XModify

As described in XML UI, Nexaweb Platform stores the state of the UI in an XML document. Depending upon the configuration of a Nexaweb-enabled application, Nexaweb platform may maintain a copy of the UI document on both the server and the client; however the client-side copy of the UI document always controls the UI. In addition, other application data may be stored in other XML documents.

These XML documents, both the UI document and application-specific documents, can be modified declaratively through the use of the following:

Service	Description
XModify	A language for modifying XML documents declaratively; can modify any existing application document.
XPath	A language for addressing parts of an XML document; used as part of the XModify syntax.

This topic contains the following sections:

XModify and XPath overview
Creating an XModify page
Using more XModify commands
Updating an XML document using Shortcut Syntax
Note: A document as referred to in this topic means an XML document object stored in the memory unless otherwise noted.

XModify and XPath Overview

XModify is an XML language for updating/modifying XML documents. The following example of an XModify page demonstrates how to create a button on the UI document:

<xm:modifications xmlns:xm="http://openxal.org/core/xmodify">
<xm:append select=/xal/rootPane">
<button text="a new button"/>
</xm:append>
</xm:modifications>

Since Nexaweb Platform 4.0, every in-memory document has a name. The Nexaweb platform reserves the name "xal" for the UI document.

XModify uses XPath expressions to specify locations within documents. The Nexaweb Platform supports the XPath 1.0 specification. In the above example, "/xal/rootpane" is an XPath expression that identifies the <rootPane> tag, a child of the document-root <xal> tag.

"/xal/rootPane" is a location path. When evaluated it returns a set of nodes relative to the context node, which is '/' in this case. In Nexaweb Platform, each UI document can only have one <rootPane> element under the single <xal'> element, therefore, "/xal/rootPane" is a short form of '/child::xal/child::rootPane[1]':

child is an example of an axis, which specifies the tree relationship between the nodes selected by the location step and the context node, xal and/or rootPane is an example of a node test, which specifies the node type and expanded-name of the nodes selected by the location step, and
[1] is a sample of predicates, which use arbitrary expressions to further refine the set of nodes selected by the location step.
For details on XPath information, please check http://www.w3.org/TR/xpath.

Creating an XModify Page

You can create an XModify page as a static file, or as a page that server pages or servlets dynamically generate. Each XModify page is a well-formed XML document that contains one or more <xm:modifications> elements. If the page contains more than one <xm:modifications> elements, you must wrap those elements in a single <xal> root node to make the page well-formed. As shown in the above example:

document - specifies the name of the document on which to perform the operations
xmlns:xm - specifies the namespace for the XModify instructions. It must be http://openxal.org/core/xmodify.
select - specifies an XPath expression that evaluates to a set of Elements, Attribute or Text objects. XModify statements with the exception of <create-document> require a select statement.

Sample 1: Using a jsp page to generate XUpdate statements for use as an event handler.

An XModify page can act as a Nexaweb event handler. The following example shows a snippet of XML code, and an event handling XML file using XModify:

The entire appendButton.jsp file could appear as follows:

<% String newButtonName = "myNewButton"; %>
<xm:modifications xmlns:xm="http://openxal.org/core/xmodify">
<xm:append select="/xal/rootPane">
<button text="<%=newButtonName%>"/>
</xm:append>
</xm:modifications>

Sample 2: How to create a fresh XML document with XModify

In this example, an XModify statement creates a "nexaweb" document with children of <name> and <address>. Then, a second XModify statement in the same modifications block adds a <phone> child. Once created, you can access this document through com.nexaweb.xml.DocumentRegistry.findDocument().

<xm:modifications xmlns:xm="http://openxal.org/core/xmodify">

<xm:create-document>
   <nexaweb>
    <name>Nexaweb</name>
    <address>Cambridge</address>
   </nexaweb>
</xm:create-document>
<xm:append select="/nexaweb">
   <phone>617-577-8100</phone>
</xm:append>
</xm:modifications>

Sample 3: MCO code

The following example looks up the root element of the created "nexaweb" document in client MCO code:

ClientSession session = getSession();
Document document = session.getDocumentRegistry().findDocument("nexaweb");
Element element = document.getRootElement();

Creating the Initial UI Page Using XModify

To create the initial UI page with an XModify document, the following special rules apply:

The first XModify statement needs to append a <rootPane> element to the "/xal" nodes
Subsequent XModify statements can append to '/xal/rootPane' node or its children

This method differs from the How to create a fresh XML document example in that, with this method, the "xal" UI document exists as soon as the application launches and before any developer code gets run. The XModify that creates the initial UI must assume that the "xal" document already exits with a single <xal> tag as the root and only element.

You can also use the ShortcutSyntax (details below) to create the initial UI description without relying on the use of XModify. You can use the ShortcutSyntax in conjunction with XModify in the same page; however, special caveats apply, described in the ShortcutSyntax section, if you want to do this. It is generally best not to mix the two; whenever possible declare the initial page solely with XModify or solely with the ShortcutSyntax.

Using XModify commands

XModify can improve your productivity in developing Nexaweb-enabled applications by allowing you to use XML documents rather than writing/compiling java code. It provides many flexible commands. This section provides a sampling of XModify commands along with some sample code. See the XModify schema reference for more information on the exact syntax and details.

insert-after

The following example shows the use of the insert-after command. Related commands include: insert-before, instert-at.

<xm:insert-after select="/xal/rootPane/window[1]/panel[1]">
<panel/>
</xm:insert-after>

append

The following example shows the use of the append command.

<xm:append select="/xal/rootPane/window[1]">
<panel/>
</xm:append>

set-attribute

The following example shows the use of the set-attribute command.

Related commands include: attribute, remove-attribute.

<xm:set-attribute select="/xal/rootPane/window[1]/panel[1]>
<xm:attribute name="myattr" value="myvalue" />
</xm:set-attribute>

replace-children

The following example shows the use of the replace-children command.

Related commands include: replace.

<xm:replace-children select="/xal/rootPane/window[1]">
<panel/>
<panel/>
<label text="mylabel"/>
</xm:replace-children>

remove-element

The following example shows the use of the remove-element command.

Related commands include: remove-attribute.

<xm:remove-element select="/xal/rootPane/window[1]/panel[1]"/>

variable, value-of

The following example shows the use of the value-of variable command.

<xm:variable name="myvar" select="/xal/rootPane/window[1]/panel[1]" clone="true"/>
<xm:append select="/nxml/rootPane/window[1]">
<xm:value-of name="myvar"/>
</xm:append>

clone

The clone command clones each of the results returned by the XPath query and returns the set of cloned elements.

The following example shows the use of the clone command.

<xm:clone select="/xal/rootPane/window[1]" deep="true" />

Updating an XML Document Using the Shortcut Syntax

The Shortcut Syntax allows you to:

Declare the initial UI for your application without relying on XModify statements
Display windows and dialogs in the <rootPane> without XModify

The Shortcut Syntax essentially provides a shorthand notation for using an XModify statement that appends to the <rootPane> tag.

A page uses shortcut syntax notation if all of the following apply:

The page has XAL tags not wrapped in XModify
The page is not being included by an <include> tag
The page is the first page of the application, or the page has a <window>, <dialog> or <messageDialog> as the root element (and is not a wrapping "xal" tag)

The Nexaweb platform uses the following rules when it processes a page in shortcut notation:

If the page does not have a <rootPane> tag and the UI document does not yet include a rootPane, Nexaweb creates the rootPane tag and adds it to the UI document under the root <xal> tag. Nexaweb then adds the contents of the page to this newly created <rootPane>. This is the only scernario under which Nexaweb automatically creates <rootPane>.
If the page does have a <rootPane> tag, Nexaweb automatically appends that tag to the root <xal> tag of the application. However, if the UI document already has a <rootPane> this will produce two root panes and lead to an error in the application.
Nexaweb considers any page with XAL not wrapped in XModify or included by an <include> tag to be shortcut syntax. The following example presents some different ways of declaring the initial UI using the shortcut notation.

java-index.xal or ajax-index.xal - the start page

or

<-- this automatically creates and appends a rootPane to the "xal" tag, then places the label and button underneath that root pane -->

or

<button text="click for hello world window" onCommand="window.xml"/>
window.xml

or