This document covers the following topics:
Inside a tag handler, a protocol item is passed in the called methods. There are some mandatory tasks that you have to do with a protocol item:
You must tell the protocol item every property you are referencing from your control.
This information is required because only these properties are transferred from the server to the client at runtime which are referenced inside the page.
You must tell the protocol item every text ID you are referencing from your control.
Again this information is used to send the right text IDs to the client processing.
In case of using macro controls, one macro control is rendered into many normal controls. Each normal control is treated in the way that it generates corresponding HTML/JavaScript and in the way that it itself tells to which properties it binds; that is, each normal control adds its properties/text IDs itself: when your macro control contains some FIELD controls, then each FIELD control will tell during generation the adapter properties to which it binds - there is no necessity for you to re-tell on macro control level.
But: you might tell on macro control level that all the contained adapter properties are
not provided via one-by-one implementation but by implementing a server-side class already
providing all sub-properties. In this case, you can use the protocol
item in the following way:We call these classes
"binding classes", see also Creating Macro Controls Out of Existing
Controls. To add a binding class
ADDRESSInfo, you use the protocol item in the following way:
Call addProperty('nameOfProperty','serverSideClass'). For
example:
addProperty(m_addressprop,'ADDRESSInfo')
Tell that all property definitions made by internally contained controls are not
relevant for implementation by calling the method
suppressFurtherCodeGenEntries().
Call IXSDGenerationHandler xga =
protocolItem.findXSDGenerationHandler(); to get access to an object which
implements the IXSDGenerationHandler interface. This object is
responsible for the generation of the corresponding data bindings for NATPAGE layouts.
Call the method addControlInfoClass and pass your binding
class as the third parameter. The second parameter is the name of the complex property
to which you apply the binding: xga.addControlInfoClass(protocolItem,
myproperty, ADDRESSInfo.class);.
For more information, see the corresponding Javadoc files of your Natural for Ajax or NaturalONE installation.
The Layout Painter is configured via a file editor.xml inside the <installdir>/cis/config/ directory. This file contains information about all controls which are available inside the editor. For each control, the list of attributes and the list of possible subnodes is listed.
Have a look at the file - the structure is self-explaining.
With early versions, you had to bring own controls into the editor.xml file by editing it accordingly. The disadvantage was that every time Application DesignerApplication ComposerNatural for Ajax changed the editor.xml file, you had to reapply your changes. Application DesignerApplication ComposerNatural for Ajax now offers a dynamic way of adding own controls into the logical structure of the editor.xml.
Write an editor_xyz.xml file and place it into the same directory as editor.xml. "xyz" should be the same name as the one you chose as the prefix for your control library. Each editor_xyz.xml file holds information about the controls of the xyz control library:
data types of a tag
name of control tags
attributes of tags
subnodes a tag may have
subnode extensions for existing Application DesignerApplication ComposerNatural for Ajax tags - this means, you define below which Application DesignerApplication ComposerNatural for Ajax controls your new tags should be positioned
The following definition shows the usage of the editor_xyz.xml file:
<!--
Dynamic extension of editor.xml file.
-->
<controllibrary>
<editor>
<!-- datatype TEXT -->
<datatype name="demo:count">
<value id="1st" name="First"/>
<value id="2nd" name="Second"/>
<value id="3rd" name="Third"/>
</datatype>
<!-- control DEMOCONTROL -->
<tag name="demo:democontrol">
<attribute name="text" datatype="demo:count"/>
</tag>
<tagsubnodeextension control="itr" newsubnode="demo:democontrol"/>
<tagsubnodeextension control="tr" newsubnode="demo:democontrol"/>
<!-- control DEMOCONTROLDYN -->
<tag name="demo:democontroldyn">
<attribute name="textprop"/>
</tag>
<tagsubnodeextension control="itr" newsubnode="demo:democontroldyn"/>
<tagsubnodeextension control="tr" newsubnode="demo:democontroldyn"/>
<!-- control ADDRESSROWAREA -->
<tag name="demo:addressrowsarea">
<attribute name="addressprop"/>
</tag>
<tagsubnodeextension control="pagebody" newsubnode="demo:addressrowarea"/>
</editor>
</controllibrary>
Note that the structure of the file directly corresponds to the structure of the original editor.xml file. The data is an add-on that is logically added to the information from the editor.xml file.
Note also that both new data types and new control tags are named together with their prefix - in order not to mix up with standard Application DesignerApplication ComposerNatural for Ajax controls or with controls of other control library providers.
In a previous section, you learned how to integrate controls into the Layout Painter (see Integrating Controls into the Layout Painter). In addition to the basic concepts described in that section, you can also apply data-type definitions to your control attributes.
The following example shows how to apply data types to an attribute editor_nadc.xml file:
<!--
Dynamic extension of editor.xml file.
-->
<controllibrary>
<editor>
<!-- datatype TEXT -->
<datatype name="nadc:count">
<value id="1st" name="First"/>
<value id="2nd" name="Second"/>
<value id="3rd" name="Third"/>
</datatype>
<!-- control MYCONTROL -->
<tag name="nadc:mycontrol">
<attribute name="fixedtext" datatype="nadc:count"/>
</tag>
....
Note that both new data types and new control tags are named together with their prefix - in order not to mix them up with standard Application Designer controls or with controls of other control library providers.
As shown in the CUSTC2-P example of the Natural for Ajax demos, you can
create controls with repeated data structures without having to deal with all the details
of array bindings. The control NADC:ADDRESSLIST is an example for this. The idea is to
have your own custom controls and simply reuse the repeated concepts and array bindings of
the framework together with your own custom controls. We recommend to use this approach
whenever possible.
If you really need to implement your own repeated data binding, you will find some
details for generating and implementing your own array binding in the description of the
CUST2-P example and the corresponding Natural for Ajax demos.
Please contact Software AG in case you create new controls with language-dependent information - and if you want to use the same translation methods as Application Designer does for these controls.