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. 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 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.
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.