JAVASCRIPT ENGINE FOR GUIXML USERS' GUIDE
Users’ Guide
Compiled by Solaris_navi on Apr. 2008
Engine Version: 0.97
Document Version: 0.97_Modify_1
Abstract
The goal of this guide is to introduce how to use this JavaScript Engine Beta Version for GUIXML correctly to create a basic web application.
CONTENTS
Chapter 1 A GUIXML file......................................................................................................................... 2
1.1 Structure of GUIXML.................................................................................................................. 2
1.1.1 Main Body Containers.................................................................................................... 2
1.1.2 Solution.......................................................................................................................... 2
1.1.3 Forms............................................................................................................................. 3
1.1.4 Reaction......................................................................................................................... 5
1.2 A well-formed GUIXML file.......................................................................................................... 5
Chapter 2 Properties of Components.................................................................................................... 7
Chapter 3 Preload HTML file................................................................................................................. 9
3.1 Preload Codes............................................................................................................................. 9
3.2 Custom Codes........................................................................................................................... 10
3.2.1 in the scope of <head>................................................................................................. 10
3.2.2 in the scope of <body>................................................................................................. 10
Chapter 4 Custom events.................................................................................................................... 11
4.1 Function Naming....................................................................................................................... 11
4.2 Engine Interfaces....................................................................................................................... 12
In this section, you can understand how to create a correct GUIXML file, which is supported by current JS Engine Beta Version.
Note: JS Engine Current Version only supports WELL-FORMED GUIXML File now.
1.1 Structure of GUIXML
Here is to introduce the basic structure of a GUIXML file.
1.1.1 Main Body Containers
All the GUIXML file start with the tag <guixml> and end with </guixml>. In the body of <guixml>, there are three tags: <solution>, <forms> and <reaction>. GUIXML file similar to the one shown below appear (Code 1.1):
Code 1.1 the sample of simple structure of GUIXML file.
<guixml>
<solution>
<datamodel>
</datamodel>
<flavor>
</flavor>
<forms>
</forms>
<reaction>
</reaction>
</solution>
</guixml>
1.1.2 DataModel and Flavor In Solution
The engine currently version only support two tags of Solution: Datamodel and Flavor.
You can define some data model by add a tag <model> with its value of id as a DOM table identity, and add the tag <instance> with its source xml file, in the container <datamodel>, sample code as the Code 1.2. Then you can use these data model by referencing.
Code 1.2 Structure of Datamodel:
<datamodel>
<model id="modelid">
<instance src="guixml file path"/>
</model>
</datamodel>
The container <flavor> is similar to the Class in Java. It defines default component styles and values. It means that if you don’t configure your component styles or values in the custom way, the styles and values will be replaced by these default styles and values you defined in <flavor>. <flavor> contains tag <attributes>, which define the name or the identity of default styles and values set, as Class Name in Java, you can set the attribute type of <attributes> to define the name of this set. <attributes> contains one tag <attribute> or more, tag <attribute> will define every styles and values according to your definition. Each <attribute> has an attribute name, which is the name of this attribute, and the value of <attribute> is the value of this attribute. Attribute name can be two types: one is text, another is CSS Style. Type text defines the default value and type CSS Style defines the default style of the component. The sample code shows below as Code 1.3.
Code 1.3 Structure of Flavor
<flavor>
<attributes type="labeltype">
<attribute name="text">Default Label</attribute>
<attribute name="color">red</attribute>
<attribute name="size">5</attribute>
</attributes>
</flavor>
This sample shows that, it defines an attribute set named labeltype and it contains three attributes in two types: the default value and style, which is the text Default Label and the style “color = red; size = 5”.
1.1.3 Forms in Solution
All components are defined in the scope of the container <forms>. Please follow the instructions below to create a frame with components, or controllers:
- Create a frame
All components except frame need a parent component. A frame should be defined like this:
Code 1.4 Structure of Component Frame
<component class="frametype" id="frameName">
<flavor>
<attribute name="rendering">Frame</attribute>
<attribute name="text"> (Optional) frameName</attribute>
</flavor>
<component>
…..
</component>
</component>
Note: Frame needs at least one component.
- Add components
Component should be defined like this:
Code 1.5 Structure of General Component
<component class="component type" id="component name">
<flavor>
<attribute name="rendering">Component Type</attribute>
<attribute name="text"> (Optional) type text value</attribute>
<attribute name="style name"> (Optional) type style value</attribute>
</flavor>
</component>
Every component contains an attribute named rendering, engine current version supports: Label, TextField, TextArea, Button, Submit, Reset, DataPanel, Password, Image, RadioButton, CheckBox, ComboBox, List and Link. Component has its own default or custom text value, which is the required property and it help the engine defined the shown-out text. If there is a RadioButton, CheckBox, ComboBox or List, you can define the options split by “|”. There is an RadioButton example shown below:
Code 1.6 Example of a RadioButton
<component class="combotype" id="radiodemo1">
<flavor>
<attribute name="rendering">RadioButton</attribute>
<attribute name="text">option1|option2|option3|option4</attribute>
</flavor>
</component>
- Link Data if need
In the Solution, if you defined a datamodel, then you would have a datamodelid as a identity name of a path of a xml file.
Note: the xml file should be well-formed, otherwise, error(s) will be caused.
If you really have a datamodel now, you can reference data from the xml file.
Code 1.7 Link data Demo
<reference type="xml" datamodelid="datamodelid" idref="xpath"></reference>
You can insert a reference similar to Code 1.7 to tag <attribute name= “text”></attibute>.
And if you define a DataPanel, you can show all data in the xml file with a configuration schema.
There is a example shows that how to define a DataPanel with referenced Data.
Code 1.8 Example of a well-formed Data XML file: “Stduent.xml”
<students>
<student no="1">
<name>Mike</name>
<dept>Computer Science</dept>
<age>21</age>
</student>
<student no="2">
<name>Jane</name>
<dept>Computer Science</dept>
<age>22</age>
</student>
<student no="3">
<name>Jack</name>
<dept>Computer Engineering</dept>
<age>20</age>
</student>
<student no="4">
<name>Daniel</name>
<dept>Computer Engineering</dept>
<age>21</age>
</student>
<student no="5">
<name>Juliet</name>
<dept>Information Science</dept>
<age>21</age>
</student>
</students>
And if we want to use this xml file, we should have a definition in <solution>.
Code 1.9 DataModel Definitions in Solution
<datamodel>
<model id="showstudent">
<instance src=" Student.xml"/>
</model>
</datamodel>
Then add a component in <forms>.
Code 1.10 DataPanel Example
<component class="datapaneltype" id="datapanelName">
<flavor>
<attribute name="rendering">DataPanel</attribute>
<attribute name="datamodelid">showstudent</attribute>
<attribute name="xmldatastructure">student|@no,name,dept,age</attribute>
</flavor>
</component>
Now, you have a DataPanel with the data from “Student.xml”.
1.1.4 Reaction in Solution
Reaction is the scope that defines buttons behaviors. The Engine currently supports only the Button with behaviors. The structure of <Reaction> shows as below:
Code 1.11 Structure of Reaction
<reaction>
<if>
<condition>
<trigger class="action" idref="Component (button) Name"/>
</condition>
<callback>
<adapter name="actionName" class="JavaScript Function"/>
</callback>
</if>
</reaction>
The attribute idref of trigger is the name of the button or other component support further, and the attribute class of adapter is the JavaScript Function which defined in Custom events (incident.js). You can define a 1 to 1, 1 to N, N to N action here. It means that you can define one or more components to one function, or one component to more than one function.
The engine now cannot parse a broken or incomplete GUIXML file, so a well-formed GUIXML file is need to create a application by using this engine. A well-formed GUIXML file should contain similar tags as the follow example (Code 1.12):
Code 1.12 A well-formed GUIXML File
<guixml>
<solution>
<datamodel>
<model id="showstudent">
<instance src="data_test.xml"/>
</model>
<model id="showstudent_2">
…………
</datamodel>
<flavor>
<attributes type="labeltype">
<attribute name="text">Default Label</attribute>
<attribute name="color">red</attribute>
…………
</attributes>
<attributes type="frametype">
…………
</flavor>
<forms>
<component class="frametype" id="frame1">
<flavor>
<attribute name="rendering">Frame</attribute>
<attribute name="text">Instruction</attribute>
</flavor>
<component class="labeltype" id="ilabel1">
<flavor>
<attribute name="rendering">Label</attribute>
<attribute name="text">
<reference type="xml" datamodelid="instruction" idref="/instruction/title/text()">
</reference>
</attribute>
<attribute name="color">blue</attribute>
<attribute name="font-size">18</attribute>
</flavor>
</component>
<component class="labeltype" id="ilabel2">
…………
</component>
<component class="frametype" id="frame2">
…………
</forms>
<reaction>
<if>
<condition>
<trigger class="doClick" idref="button1exit"/>
<trigger class="doClick" idref="button2exit"/>
………..
</condition>
<callback>
<adapter name="closeme" class="hideUpOneLevel(this.parentNode)"/>
………..
</callback>
</if>
<if>
............
</reaction>
</solution>
</guixml>
Exception or broken xml error rising may be supported in the Engine further versions.
Chapter 2 Properties of Components
There are 2 types of properties. One is Type Text, another is Type Styles. Property Text is required for every component. It configures components’ shown text. Properties Type Styles are optional, and it configures components’ shown styles. It means that if you define a component, there must be one attribute at least in your <attributes> scope: <attribute name = “text”>…. </attribute>.
All Styles properties are referred from CSS Styles. All styles are supposed to be supported in the engine of current version shows in the table below (Table 2.1):
Table 2.1 CSS Styles’ Table
|
Text Properties |
|
|
text-indent |
text-autospace |
|
text-overflow |
test-kashida-space |
|
vertical-align |
text-justify |
|
text-align |
ruby-align |
|
layout-flow |
ruby-position |
|
writing-mode |
ruby-overhang |
|
direction |
ime-mode |
|
unicode-bidi |
layout-grid |
|
Word-break |
layout-grid-char |
|
line-break |
layout-grid-char-spacing |
|
White-space |
layout-grid-line |
|
Word-wrap |
|
|
Table Properties |
|
|
border-collapse |
empty-cells |
|
border-spacing |
table-layout |
|
caption-side |
speak-header |
|
Paddings Properties |
|
|
padding |
padding-bottom |
|
padding-top |
padding-left |
|
padding-right |
|
|
Outlines Properties |
|
|
outline |
outline-style |
|
outline-color |
outline-width |
|
Margins Properties |
|
|
margin |
margin-bottom |
|
margin-top |
margin-left |
|
margin-right |
|
|
Lists Properties |
|
|
list-style |
list-style-type |
|
list-style-image |
marker-offset |
|
list-style-position |
|
|
Layout Properties |
|
|
Clear |
overflow-x |
|
Float |
overflow-y |
|
Clip |
display |
|
overflow |
visibility |
|
Font Properties |
|
|
font |
text-underline-position |
|
Color |
text-shadow |
|
font-family |
font-variant |
|
font-size |
text-transform |
|
font-size-adjust |
line-weight |
|
font-stretch |
letter-spacing |
|
font-style |
word-spacing |
|
font-weight |
text-decoration |
|
Dimensions Properties |
|
|
height |
Width |
|
max-height |
max-width |
|
min-height |
min-width |
|
Borders Properties |
|
|
border |
border-style |
|
border-color |
border-bottom |
|
border-width |
border-bottom-color |
|
border-top |
border-bottom-style |
|
border-top-color |
border-bottom-width |
|
border-top-style |
border-left |
|
border-top-width |
border-left-color |
|
border-right |
border-left-style |
|
border-right-color |
border-left-width |
|
border-right-style |
border-right-width |
|
Background Properties |
|
|
background |
background-position-x |
|
background-attachment |
background-position-y |
|
background-color |
background-repeat |
|
background-image |
layer-background-color |
|
background-position |
layer-background-image |
How to add attributes please see 1.1.2 and 1.1.3.
Chapter 3 Preload HTML file
First, let’s see the sample code below (Code 3.1):
Code 3.1 Preload HTML file sample
<html>
<head>
<meta name="GUIXMLFILE" content="test_frame1.xml"/>
<script language="javascript" type="text/javascript" src="xml_parser_V2.js"></script>
<script language="javascript" type="text/javascript" src="basic_comp.js"></script>
<script language="javascript" type="text/javascript" src="preload.js"></script>
<script language="javascript" type="text/javascript" src="incident.js"></script>
<script language="javascript" type="text/javascript" src="hidendisplay.js"></script>
<script language="javascript" type="text/javascript" src="dragndrop.js"></script>
<script language="javascript" type="text/javascript" src="xml.js"></script>
<link rel="stylesheet" type="text/css" href="div-css.css" />
</head>
<body onload="preload(div1);">
<div id="div2">
<h1> This is a GUIXML Test File</h1>
<br/>
<b>Click the Link below to run the test.</b>
</div>
<div id="div1"></div>
</body>
</html>
3.1 Preload Codes
There are some codes in this HTML file that should not be removed (Code 3.2):
Code 3.2 Kernel Codes
<script language="javascript" type="text/javascript" src="xml_parser_V2.js"></script>
<script language="javascript" type="text/javascript" src="basic_comp.js"></script>
<script language="javascript" type="text/javascript" src="preload.js"></script>
<script language="javascript" type="text/javascript" src="incident.js"></script>
<script language="javascript" type="text/javascript" src="hidendisplay.js"></script>
<script language="javascript" type="text/javascript" src="dragndrop.js"></script>
<script language="javascript" type="text/javascript" src="xml.js"></script>
<link rel="stylesheet" type="text/css" href="div-css.css" />
These codes contain parser, loading scripts, static behaviors, data process and translator, also a CSS style for the default style value. If there are any of them missing or removed, engine may cause errors because browser cannot understand a broken code written in JavaScript, such as undefined errors and missing object errors. Keep its process integrity so that the engine can run without any unexpected errors.
3.2 Custom Codes
You can edit codes in the scope of <head> and <body>.
3.2.1 in the scope of <head>
Here is only one tag that you can edit is the properties of tag <meta>:
Code 3.3
<meta name="GUIXMLFILE" content="test_frame1.xml"/>
This
Property content supports absolute and relative path
3.2.2 in the scope of <body>
You can add or edit any of these codes in the scope of <body> by using HTML codes. Please notice:
- tag <body onload>
<body> event onload refers a function called preload(). The parameter of this function is the name of the container <div>. It means that you can change the parameter to select which container you want to use.
- container <div>
Every tag has a property named id, you should edit tag <div> and set the id property, then you can run the function correctly.
- other codes
You can add other HTML codes in the scope of <body>, such as the code shown below (Code 3.4):
Code 3.4 Custom Code in Preload HTML file
<div id="div2">
<h1> This is a GUIXML Test File</h1>
<br/>
<b>Click the Link below to run the test.</b>
</div>
………………………………..
Chapter 4 Custom events
You can add new functions to the engine current version; codes must be added in the JavaScript file incident.js.
4.1 Function Naming
JavaScript didn’t have any Code Naming Scope, so functions should have an exclusive name. So user custom name should be begin with: func_, then the description of the function. For example: function func_alert(). Here are the codes of the functions referred from student management demo (Code4.1):
Code 4.1 Events of Student Management Demo
function func_clear(obj)
{
//alert(obj.innerHTML);
obj.innerHTML = "";
}
function func_show_table(obj , xmlname)
{
var exDOM2;
//alert(xmlname);
for(var fid1=0;fid1<global_reference_model_name.length;fid1++)
{
if(global_reference_model_name[fid1] == xmlname)
{
exDOM2 = global_xmldoc_DOM[fid1];
break;
}
}
var schema = "student|@no,name,dept,age";
obj.innerHTML = makeTable_V2(exDOM2, schema);
}
function func_add_a_student_DOM(xmlname,no,name,age,dept)
{
var exDOM2;
var exid;
//alert(xmlname);
for(var fid1=0;fid1<global_reference_model_name.length;fid1++)
{
if(global_reference_model_name[fid1] == xmlname)
{
exDOM2 = global_xmldoc_DOM[fid1];
exid = fid1;
break;
}
}
var root = exDOM2.documentElement;
newstudent=exDOM2.createElement("student");
newstudent.setAttribute("no",no.value);
newname=exDOM2.createElement("name");
newtext=exDOM2.createTextNode(name.value);
newname.appendChild(newtext);
newage=exDOM2.createElement("age");
newtext=exDOM2.createTextNode(age.value);
newage.appendChild(newtext);
newdept=exDOM2.createElement("dept");
newtext=exDOM2.createTextNode(dept.value);
newdept.appendChild(newtext);
newstudent.appendChild(newname);
newstudent.appendChild(newdept);
newstudent.appendChild(newage);
root.appendChild(newstudent);
//alert(root.xml);
global_xmldoc_DOM[exid] = exDOM2;
}
function func_del_a_student_DOM_from_top(xmlname)
{
var exDOM2;
var exid;
//alert(xmlname);
for(var fid1=0;fid1<global_reference_model_name.length;fid1++)
{
if(global_reference_model_name[fid1] == xmlname)
{
exDOM2 = global_xmldoc_DOM[fid1];
exid = fid1;
break;
}
}
var root = exDOM2.documentElement;
y=exDOM2.getElementsByTagName("student")[0];
root.removeChild(y);
//alert(root.xml);
}
4.2 Engine Interfaces
Engine also has some interfaces to the users. But in this version, the engine provides one function: makeTable_V2().
This function makeTable_V2 (exDOM2, schema) provides two parameters (or you can call it interfaces): DOM as a object and schema as a String, and then return a HTML code string, so that to return a table with the data related with the data xml file and a table structure defined by schema.
This feature may be completed in the further version of engine.
