EWD Custom Tag Development. Built-in Custom Tags for defining and manipulating Javascript

Transcription

1 EWD Custom Tag Development Built-in Custom Tags for defining and manipulating Javascript Build 790 Introduction A number of very powerful custom tags have been added to EWD. Unlike many of the built-in primitive Custom Tags, these new ones are intended for use in Custom Tag Processors and allow the Custom Tag developer to manipulate Javascript as XML tags. There are several reasons for introducing these Custom Tags into EWD: Most modern UI widgets rely on complex Javascript to control and define their behaviour EWD s parser treats anything inside <script> tags as text nodes and therefore Javascript is otherwise treated as simple strings of text. As a result, encapsulating UI widgets as EWD Custom Tags originally involved complex and tortuous string handling which ultimately was limiting and difficult to maintain. The new Javascript Custom Tags rely on the fact that EWD s compiler will repetitively re-analyse an EWD page DOM until it can no longer find any tags that it needs to process. This allows the developer to build custom tag processors that are defined using other custom tags: in this case it allows the developer to insert Javascript into the page DOM by adding Javascript-handling Custom Tags. In fact EWD s tag processing takes place in two phases, and it deals with certain Custom Tags in its second phase of processing: the Javascript Custom Tags are in this secondphase category. This is important because the Custom Tag developer needs to be sure that the Javascript custom tags remain in place until all his/her work is complete, after which they can be converted into the actual Javascript they represent. A good example of why these new Javascript Custom Tags are so powerful is the common situation where the handling of a particular UI widget will rely on not only the addition of some Javascript for each instance of that widget, but also a single instance of some other Javascript irrespective of the number of instances of those widgets. By simply adding a unique id to the one-off bit of Javascript, it is easy to later determine whether or not that chunk has already been added simply see if the getelementbyid() method returns a null or non-null value. If it returns a null value, the block cannot have been added yet. The Javascript Custom Tags also make it easy to progressively add Javascript inside other Javascript containers such as Object Constructors, Objects, Arrays or Functions: the DOM API methods make it simple and easy to embed tags inside each other and manipulate their attributes and position in the page. Tedious, tortuous and difficult to 1

2 understand string manipulation is replaced with slick, intuitive manipulation of tags within the EWD page DOM. Important: these <ewd:js*> tags are not intended to be used explicitly within an EWD page or fragment (though they could be). Their intended purpose is to be tags that are generated programmatically by tag processors, and therefore they will usually be created using DOM API methods such as addelementtodom or createelement. As such these tags will normally neither be seen in the original EWD fragment nor in the resulting compiled routine or page, but will exist only during the compilation phase as an intermediate step to the creation of the final compiled page. This, of course, means that debugging of a tag processor can be tricky, but the simplest technique is to add break commands to the tag processor at critical places and then view the state of the DOM at each break point using the outputdom() method. Generating Unique Ids within an EWD page DOM A common thing you ll need to do within an EWD Custom Tag processor is to create a unique Id for use as an id attribute within a fragment. The trick is to ensure that the Id will not clash with any other Id that might have been injected into the container page by another fragment. The recommended approach is to use the built-in uniqueid method, eg: s functionid=$$uniqueid^%zewdapi(nodeoid,filename) Note that the variable filename will automatically available to you within your Tag Processor provided you write it as an extrinsic function. filename will contain the name of the current fragment (without the.ewd file extension) 2

3 Summary of EWD Javascript Custom Tags The Javascript Custom Tags that are available in EWD are as follows: <ewd:js> <ewd:jssection> <ewd:jsline> <ewd:jsfunction> <ewd:jsconstructor> <ewd:jsmethod> <ewd:jsparameters> <ewd:jsobject> <ewd:jsnvp> <ewd:jsarray> <ewd:jsliteral> <ewd:jsvariable> <ewd:jsset> 3

4 <ewd:js> Defines an outer wrapper for the main block of Javascript within a fragment. This tag is ultimately replaced with <div id="ewdscript"> which is the container for all Javascript in a fragment.. None Most UI widget tag processors will first determine whether or not an <ewd:js> tag already exists in the page: s jsoid=$$gettagoid^%zewddom("ewd:js",docname) If jsoid returns a null value, this indicates that the tag being processed must be the first instance of a UI widget and therefore an <ewd:js> tag must be added to the page. The following is the recommended approach to creating the <ewd:js> tag: s docname=$$getdocumentname^%zewddom(docoid) s configoid=$$gettagoid^%zewddom("ewd:config",docname) s pagetype=$$getattribute^%zewddom("pagetype",configoid) i isajax!($$zcvt^%zewdapi(pagetype,"l")="rawcontent") d. n nsoid. s nsoid=$$getnextsibling^%zewddom(configoid). s jsoid=$$createelement^%zewddom("ewd:js",docoid). s jsoid=$$insertbefore^%zewddom(jsoid,nsoid) e d. n headoid. s headoid=$$gettagoid^%zewddom("head",docname). i headoid'="" s jsoid=$$addelementtodom^%zewddom("ewd:js",headoid) 4

5 <ewd:jssection> Defines a container for a chunk of Javascript. This tag doesn t actually generate or represent any Javascript per se, but is used to provide a target container into which you can later inject new Javascript Custom Tags as child nodes of the <ewd:jssection> Typically you ll uniquely identify the <ewd:jssection> by giving it a unique id attribute. This tag makes it easy to have chunks of Javascript for different purposes in your fragment, and allows you to add new lines of Javascript into that section each time you process a new instance of a UI widget. id Allows you to uniquely identify and find the jssection Most UI widget tag processors will first determine whether or not a particular <ewd:jssection> tag already exists in the page, eg: s nodeoid=$$getelementbyid^%zewddom("yui-datatable",docoid) If a null value is returned, this indicates that the jssection doesn t yet exist and probably needs to be added. The following is a typical approach to getting a pointer to a specific jssection, and creating the <ewd:jssection> tag if it doesn t yest exist. In this case we re making sure that we ve created a jssection with an id of yui-datatable which is embedded inside another jssection with an id of yuiwidgetloaders. The pointer sectionoid can then be used to manipulate the Javascript in the jssection: s sectionoid=$$getelementbyid^%zewddom("yui-datatable",docoid) i sectionoid="" d. n attr,widgetloadersoid. s widgetloadersoid=$$getelementbyid^%zewddom("yuiwidgetloaders",docoid). s attr("id")="yui-datatable". s sectionoid=$$addelementtodom^%zewddom("ewd:jssection",widgetloadersoid,,.attr) 5

6 <ewd:jsline> A very simple tag that just represents a line of Javascript. This is a lowest common denominator approach and should be used where you just want to add a line of JavaScript that won t require subsequent manipulation. The advantage is that it can represent any line of Javascript. This tag usually just has a text node that represents the line of Javascript However you can optionally add an id attribute to uniquely identify this line within the page DOM. Typically you ll use this tag to add a line of Javascript at the end of a specific jssection or jsfunction. In the following example we have a pointer to the required jssection (see <ewd:jssection> above): sectionoid. s text="ewd.yui.resourceloader.datatable() ;" s lineoid=$$addelementtodom^%zewddom("ewd:jsline",sectionoid,,,text) 6

7 <ewd:jsfunction> Defines the outer wrapper of a Javascript function. The idea is that you can subsequently add lines of Javascript into this function. Note that the current version is limited to functions that do not have any input parameters. If you need more complex functions, use a set of <ewd:jsline> tags. This tag will generate: var return = function() { }; or return = function() { }; id return addvar Allows you to uniquely identify and find the jsfunction The returnvalue for the function If set to true, the generated function call will be prefixed with var. If set to false, the var prefix will be suppressed. s functionoid=$$getelementbyid^%zewddom("myfunction",docoid) s functionpresent=0 i functionoid="" d. s functionobj="freturn"_$$uniqueid^%zewdapi(nodeoid,filename). s attr("return")=functionobj. s attr("addvar")="true". s attr("id")="myfunction". s functionoid=$$addelementtodom^%zewddom("ewd:jsfunction",sectionoid,,.attr) e d. s functionobj=$$getattribute^%zewddom("return",functionoid). s functionpresent=1 Note the use of the uniqueid method to create a unique returnvalue for the function that won t clash with any other that you create in other instances of this widget. 7

8 <ewd:jsconstructor> Defines a container that represents an object constructor. This is a particularly important and useful tag, since most Javascript-based UI widgets are defined using constructors and their input parameters can be quite complex JSON definitions. These JSON inputs are represented using a set of nested parameter tags. id object addvar Allows you to uniquely identify and find the jsconstructor The name of the object that is to be constructed If set to true, the generated constructor call will be prefixed with var. If set to false, the var prefix will be suppressed. Default if omitted is false return The returnvalue from the constructor, ie the pointer to the instance of the object that is constructed. The following is a typical approach to defining a constructor. In this case an instance of a YUI.widget.DropdownCellEditor object is being defined inside a jsfunction tag identified by functionoid. s attr("object")="yahoo.widget.dropdowncelleditor" s attr("return")="editorobj" s editorcoid=$$addelementtodom^%zewddom("ewd:jsconstructor",functionoid,,.attr) This will create the basic Constructor wrapper: editorobj = new Yahoo.widget.DropdownCellEditor() ; The parameters should be defined using the <ewd:jsparameters> tag. 8

9 <ewd:jsmethod> Defines a container that represents a Javascript method call. This is a particularly important and useful tag, since the input parameters of method calls can be quite complex JSON definitions. These JSON inputs are represented using a set of nested parameter tags. id name Allows you to uniquely identify and find the jsmethod The name of the method being invoked The following is a typical approach to defining a method call. In this case a call to the method YAHOO.util.Event.onAvailable is being added into the jssection identified by sectionoid. The method has two parameters, the first being a literal value and the second a reference to a Javascript variable: if 'functionpresent d. n methodoid. s attr("name")="yahoo.util.event.onavailable". s methodoid=$$addelementtodom^%zewddom("ewd:jsmethod",sectionoid,,.attr). s jspoid=$$addelementtodom^%zewddom("ewd:jsparameters",methodoid). s attr("value")=menuname_"div". s varoid=$$addelementtodom^%zewddom("ewd:jsliteral",jspoid,,.attr). s attr("name")=functionobj. s varoid=$$addelementtodom^%zewddom("ewd:jsvariable",jspoid,,.attr) This will create something like: YAHOO.util.Event.onAvailable( mydiv,thefunction) ; As shown above, the parameters of the method should be defined using the <ewd:jsparameters> tag. The individual parameters of the method call can be any combination of: <ewd:jsobject> defines a JSON object <ewd:jsarray> defines an array <ewd:jsvariable> defines a variable <ewd:jsliteral> defines a string literal 9

10 <ewd:jsparameters> Provides the container for the parameters of an <ewd:jsconstructor> or <ewd:jsmethod> tag This tag is appended as the first (and only) child of an <ewd:jsconstructor> or <ewd:jsmethod> tag. None The following is a typical approach to defining a constructor and its parameters tag. In this case an instance of a YUI.widget.DropdownCellEditor object is being defined inside a jsfunction tag identified by functionoid. s attr("object")="yahoo.widget.dropdowncelleditor" s attr("return")="editorobj" s editorcoid=$$addelementtodom^%zewddom("ewd:jsconstructor",functionoid,,.attr) s editorpoid=$$addelementtodom^%zewddom("ewd:jsparameters",editorcoid) The individual parameters are then defined as children of the <ewd:jsparameters> tag There are four parameter tags that you can use: <ewd:jsobject> defines a JSON object <ewd:jsarray> defines an array <ewd:jsvariable> defines a variable <ewd:jsliteral> defines a string literal You may have as many of these tags in any combination as children of the <ewd:jsparameters> tag. Furthermore, the jsobject and jsarray tags are further nestable allowing you to construct any JSON object of whatever complexity. 10

11 <ewd:jsobject> This tag is used to create the container for a Javascript object. The code it generates is {} The contents of the object that go inside the {..} are defined using <ewd:jsnvp> tags as child nodes, each <ewd:jsnvp> tag being used to define an individual name/value pair. None The following is a typical approach to defining a constructor and its parameters tag. In this case an instance of a YUI.widget.DropdownCellEditor object is being defined inside a jsfunction tag identified by functionoid. This constructor has a single object as its parameter. s attr("object")="yahoo.widget.dropdowncelleditor" s attr("return")="editorobj" s editorcoid=$$addelementtodom^%zewddom("ewd:jsconstructor",functionoid,,.attr) s editorpoid=$$addelementtodom^%zewddom("ewd:jsparameters",editorcoid) s editorooid=$$addelementtodom^%zewddom("ewd:jsobject",editorpoid) 11

12 <ewd:jsnvp> This tag is used to create the container for an individual name/value pair that belongs to an object. Each name/value pair has a declared type, the available types being: object: a Javascript object (ie JSON) array: a Javascript array literal: a string literal value variable: a Javascript variable name boolean: a name with a value of true or false If an <ewd:jsnvp> tag is defined as type array, then it will act as a container around an <ewd:jsarray> tag. This nesting can be repeated to any depth required eg: <ewd:jsnvp name= myarray type= array > <ewd:jsarray>..etc </ewd:jsarray> </ewd:jsnvp> If an <ewd:jsnvp> tag is defined as type object, then it will act as a container around an <ewd:jsobject> tag. This nesting can be repeated to any depth required eg: <ewd:jsnvp name= myobject type= object > <ewd:jsobject>..etc </ewd:jsobject> </ewd:jsnvp> If an <ewd:jsnvp> tag is defined as type literal, then it generates: name: value (where name is the value of the name attribute), eg: <ewd:jsnvp name= lastname value= Tweed type= literal /> would generate: lastname: Tweed 12

13 If an <ewd:jsnvp> tag is defined as type variable, then it generates: name:varname (where name is the value of the name attribute, and varname is the name of the variable), eg: <ewd:jsnvp name= reference value= myvar type= variable /> would generate: reference:myvar If an <ewd:jsnvp> tag is defined as type boolean, then it generates: name:value (where name is the value of the name attribute, and value is true or false), eg: <ewd:jsnvp name= hidden value= true type= boolean /> would generate: hidden:true id name value Optional lattribute that allows you to uniquely identify and find the name/value pair The name of the name/value pair The value of the name/value pair Note: this attribute is not used if the type is object or array type The type of the name/value pair: object array literal variable Boolean The following is a typical approach to defining a constructor and its parameters tag. In this case an instance of a YUI.widget.DropdownCellEditor object is being defined inside a jsfunction tag identified by functionoid. This constructor has a single object as its parameter. This object has a single boolean name/value pair. 13

14 s attr("object")="yahoo.widget.dropdowncelleditor" s attr("return")="editorobj" s editorcoid=$$addelementtodom^%zewddom("ewd:jsconstructor",functionoid,,.attr) s editorpoid=$$addelementtodom^%zewddom("ewd:jsparameters",editorcoid) s editorooid=$$addelementtodom^%zewddom("ewd:jsobject",editorpoid) i $g(ddattrs("disablebtns"))'="" d. s attr("name")="disablebtns". s attr("type")="boolean". s attr("value")=ddattrs("disablebtns"). s ddoid=$$addelementtodom^%zewddom("ewd:jsnvp",editorooid,,.attr) 14

15 <ewd:jsarray> This tag is used to create the container for a Javascript array. The code it generates is [] The elements of the array that go inside the [..] are defined using any of the following as child nodes: <ewd:jsvariable> <ewd:jsliteral> <ewd:jsobject> <ewd:jsarray> When compiled, each element that is generated from the above tags is separated by a comma. None The following is a typical approach to defining a constructor and its parameters tag. In this case an instance of a YUI.widget.DropdownCellEditor object is being defined inside a jsfunction tag identified by functionoid. This constructor has a single array as its parameter. s attr("object")="yahoo.widget.dropdowncelleditor" s attr("return")="editorobj" s editorcoid=$$addelementtodom^%zewddom("ewd:jsconstructor",functionoid,,.attr) s editorpoid=$$addelementtodom^%zewddom("ewd:jsparameters",editorcoid) s editoraoid=$$addelementtodom^%zewddom("ewd:jsarray",editorpoid) 15

16 <ewd:jsliteral> This tag is used to define a string literal value as either a member element of an array or as a parameter of an constructor or method. <ewd:jsliteral> tags are therefore always immediate children of an either an <ewd:jsarray> tag or an <ewd:jsparameters> tag. This tag simply generates the value of the name attribute wrapped in double quote, eg: <ewd:jsarray> <ewd:jsliteral name= hello /> <ewd:jsliteral name= world /> </ewd:jsarray> generates [ hello, world ] name value The value of the string literal if the <ewd:literal> is used as a child node of an <ewd:jsarray> tag The value of the string literal if the <ewd:literal> is used as a child node of an <ewd:jsparameters> tag The following is a typical approach to defining a constructor and its parameters tag. In this case an instance of a YUI.widget.DropdownCellEditor object is being defined inside a jsfunction tag identified by functionoid. This constructor has a single array as its parameter, and two array elements have been defined s attr("object")="yahoo.widget.dropdowncelleditor" s attr("return")="editorobj" s editorcoid=$$addelementtodom^%zewddom("ewd:jsconstructor",functionoid,,.attr) s editorpoid=$$addelementtodom^%zewddom("ewd:jsparameters",editorcoid) s editoraoid=$$addelementtodom^%zewddom("ewd:jsarray",editorpoid) s attr("name")= hello s varoid=$$addelementtodom^%zewddom("ewd:jsliteral",editoraoid,,.attr) s attr("name")= world s varoid=$$addelementtodom^%zewddom("ewd:jsliteral",editoraoid,,.attr) 16

17 <ewd:jsvariable> This tag is used to define a reference to a Javascript variable as either a member element of an array or as a parameter of an constructor or method. <ewd:jsvariable> tags are therefore always immediate children of an either an <ewd:jsarray> tag or an <ewd:jsparameters> tag. This tag simply generates the unquoted value of the name attribute, eg: <ewd:jsarray> <ewd:jsvariable name= hello /> <ewd:jsvariable name= world /> </ewd:jsarray> generates [hello,world] name The name of the Javascript variable The following is a typical approach to defining a constructor and its parameters tag. In this case an instance of a YUI.widget.DropdownCellEditor object is being defined inside a jsfunction tag identified by functionoid. This constructor has a single array as its parameter, and two array elements have been defined s attr("object")="yahoo.widget.dropdowncelleditor" s attr("return")="editorobj" s editorcoid=$$addelementtodom^%zewddom("ewd:jsconstructor",functionoid,,.attr) s editorpoid=$$addelementtodom^%zewddom("ewd:jsparameters",editorcoid) s editoraoid=$$addelementtodom^%zewddom("ewd:jsarray",editorpoid) s attr("name")= hello s varoid=$$addelementtodom^%zewddom("ewd:jsvariable",editoraoid,,.attr) s attr("name")= world s varoid=$$addelementtodom^%zewddom("ewd:jsvariable",editoraoid,,.attr) 17

18 <ewd:jsset> This tag is used to assigns a value of some type to a Javascript variable, object or array. By using <ewd:jsobject> and <ewd:jsarray> tags as child nodes, it is possible to build an assignment that creates a JSON object of any complexity and level of nesting. If an <ewd:jsset> tag is defined as type array, then it will act as a container around an <ewd:jsarray> tag. This nesting can be repeated to any depth required eg: <ewd:jsset return= myarray type= array > <ewd:jsarray>..etc </ewd:jsarray> </ewd:jsset> The generated code will be: myarray = [.etc ]; If an <ewd:jsset> tag is defined as type object, then it will act as a container around an <ewd:jsobject> tag. This nesting can be repeated to any depth required eg: <ewd:jsset return= myobject type= object > <ewd:jsobject>..etc </ewd:jsobject> </ewd:jsset> The generated code will be: myobject = {.etc }; 18

19 If an <ewd:jsset> tag is defined as type literal, for example <ewd:jsset return= lastname value= Tweed type= literal addvar= true /> this would generate: var lastname= Tweed ; id type Optional attribute that allows you to uniquely identify and find the jsset The type to be returned: object array literal addvar If set to true, the generated assignment call will be prefixed with var. If set to false, the var prefix will be suppressed. Default if omitted is false return The returnvalue from the assignment, ie the name of the variable, object or array that is created by the assignment The following is a typical example where an assignment is added to the DOM, the assignment instantiating a JSON object: mydatasrc.responseschema = {resultslists: records,totalrecords: 200 }; 19

20 s attr("return")=datasourceobj_".responseschema" s attr("addvar")="false" s attr("type")="object" s setoid=$$addelementtodom^%zewddom("ewd:jsset",functionoid,,.attr) s attr("name")="resultslist" s attr("value")="records" s attr("type")="literal" s nvpoid=$$addelementtodom^%zewddom("ewd:jsnvp",setoid,,.attr) s attr("name")="totalrecords" s attr("value")=200 s attr("type")="literal" s nvpoid=$$addelementtodom^%zewddom("ewd:jsnvp",mfoid,,.attr) 20