by Jorge Tapia

After a thorough and extensive review of LiveServer code on the current project I'm working on, I have decided to write this post. LiveServer back-end development is very complex, not in terms of difficulty, but in the sense that learning and actually getting results from it falls in the tedious write, test, fail, change, rewrite cycle. The product documentation is not complete and in some cases is almost useless.

I had the privilege to work on one of the finest LiveServer implementations where I really got to know and to tweak, tune, fix and extend its capabilities and features. This post collects all the knowledge acquired through many, many hours and code lines written to achieve the exceptional results our clients now enjoy.

Dynaments can REALLY be your friends! It is a matter of organization and structural thinking to write code that will do EXACTLY what you want. To do this, there are a few points to consider. For example, many may not notice but every Dynament that resides in LiveServer is translated into a Java Iolet and every Java Iolet residing in LiveServer is a Singleton instance of the Iolet class.

-Dynament basic structure-

<?xml version="1.0" encoding="UTF8"?>
<rde-dm:dynaments>
<rde-dm:attribute mode="write" attribute="request:helloText" value="Hello from LS" />
<rde-dm:dynaments>

Always start your code with a generic XML declaration:

<?xml version="1.0" encoding="UTF8"?>

Enclose your Dynament code in a "Dynament" block:

<rde-dm:dynaments>
<!--Your code goes here-->
<rde-dm:dynaments>

-Reading and writing attributes-

<?xml version="1.0" encoding="UTF8"?>
<rde-dm:dynaments>
<rde-dm:attribute mode="write" attribute="request:helloText" value="Hello from LS" />
<rde-dm:attribute mode="read" attribute="request:helloText" />
<rde-dm:dynaments>

When reading and writing attributes using the attribute Dynament you can always specify explicitly the source from/where you will be reading/writing your attributes. Attributes can be considered as "variables" that have their respective scope (source). The traditional Dynament call to write an attribute named "helloText" into the request source is:

<rde-dm:attribute mode="write" source="request" attribute="helloText" value="Hello from LS" />

But you can always use the abbreviated call by removing the source attribute and including it inside the "attibute" attribute followed by a colon (:):

<rde-dm:attribute mode="write" attribute="request:helloText" value="Hello from LS" />

This can be done to read/write attributes into LiveServer's request, session, user, content and all other LiveServer sources.

-Validating simple conditions and constraints-
If you need to validate simple conditions then the attribute Dynament is your best choice and the correct way to call it is the following:

<rde-dm:attribute mode="condition" attribute="request:helloText" op="eq" value="Hello" tag="notag" />
<!--Code to execute if condition evaluates true-->
</rde-dm:attribute>

In this example we determine if the request:helloText attribute value equals "Hello". In the "op" attribute we set the operator of the condition. There are more operators and LiveServer documentation provides the complete list under the attribute Dynament section.

As you can see, there is no need to explicitly write an "if" block. The "if" block is only necessary when you have to execute another piece of code if the condition is not satisfied ("else" block required). The correct structure to do this is the following:

<rde-dm:attribute mode="condition" attribute="request:helloText" op="eq" value="Hello" tag="notag" />
<rde-dm:if>
<!--Code to execute if condition evaluates true-->
</rde-dm:if>
<rde-dm:else>
<!--Code to execute if condition evaluates false-->
</rde-dm:else>
</rde-dm:attribute>

If you need to evaluate more complex conditions, then you need to use LiveServer constraints. The correct use of a constraint is the following:

<rde-dm:attribute mode="condition" attribute="request:helloText" op="eq" value="Hello" tag="notag" />
<rde-dm:constraint>
(request:helloText eq 'Hello') or (request:helloText eq 'Hello from LS')
</rde-dm:constraint>
<rde-dm:if>
<!--Code to execute if constraint evaluates true-->
</rde-dm:if>
<rde-dm:else>
<!--Code to execute if constraint evaluates false-->
</rde-dm:else>
</rde-dm:attribute>

What I've learned when writing constraints:
- ALWAYS group your statements using parenthesis "(statement)".
- NEVER break a large constraint into several lines. Apparently when you do that LiveServer will only evaluate the expression(s) on the first line and completely ignore the expression(s) on the conscutive lines.

-Reading and writing multi-valued attributes-
There is not much science in reading and writing these attributes. The extra step to achieve this is to define a "value separator" which will tell LiveServer how to divide several attribute values. The most common is the comma (,) but I personally prefer the semi-colon (;). So, to create our multi-valued attribute we call the attribute Dynament this way:

<rde-dm:attribute mode="write" op="set" attribute="session:countries" value="Ecuador;Italy;USA" value-separator=";" />

This is not the only way to write a multi-valued attribute. You can increasingly add values to the attribute, and to do this there are some steps to follow:

- Write the initial value of the attribute using "set" as the operator "op" option:

<rde-dm:attribute mode="write" op="set" attribute="session:countries" value="Ecuador" value-separator=";" />

- Call the same Dynament again where needed but the operator "op" must be changed to "add" for the rest of values:

<rde-dm:attribute mode="write" op="add" attribute="session:countries" value="Italy" value-separator=";" />
<rde-dm:attribute mode="write" op="add" attribute="session:countries" value="USA" value-separator=";" />

This is another useful way to write multi-valued attributes.

Reading and making multiple values from a multi-valued attribute available:
Now that you know how to write multi-valued attributes it is time to use them. Here comes the magic of the "for-each" mode of the attribute Dynament in our aid. The correct and simple way to read our session:countries attribute is the following:

<rde-dm:attribute mode="for-each" attribute="session:countries" alias="country" />
<rde-dm:attribute mode="read" attribute="context:country" />
</rde-dm:attribute>

When this is executed you will get the following XML result ready for you to manipulate with XPath expressions or to transform using XSL stylesheets:

<countries>
<country>Ecuador</country>
<country>Italy</country>
<country>USA</country>
</countries>

As you have noticed, the "alias" attribute defines the element for each of the values in a multi-valued attributes.

With these basic suggestions, your Dynaments will be cleaner, and easier to understand and maintain. The rest of LiveServer Dynaments behave pretty much the same as the attribute Dynament so the same principles depicted on this post apply perfectly (source shortcut, constrint evaluation and reading/writing).