XUpdate

Owned by Xiaoyan Kong (Unlicensed)
Last updated: Oct 25, 2012Version comment
6 min read

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 declaritively through the use of XUpdate along with XPath.

XUpdate - A language for modifying XML documents declaratively. This can be used to modify any existing application documents.

Xpath -     A language for addressing parts of an XML document. It is used as part of the XUpdate syntax.

This topic contains the following sections:

  • XUpdate and XPath overview
  • Creating an XUpdate page
  • Using more XUpdate 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.

 
XUpdate and XPath overview

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

<xu:modifications document="nxml" version="1.0" 
    xmlns:xu="http://nexaweb.com/xupdate">
    <xu:append select="/nxml/rootPane">
        <button text="a new button"/>
    </xu:append>
</xu:modifications>

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

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

"/nxml/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 <nxml'> element, therefore, "/nxml/rootPane" is a short form of '/child::nxml/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,
  • nxml 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 XUpdate page

You can create an XUpdate page as a static file, or as a page that server pages or servlets dynamically generate. Each XUpdate page is a well-formed XML document that contains one or more <xu:modifications> elements. If the page contains more than one <xu:modifications> elements, you must wrap those elements in a single <nxml> 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:xu - specifies the namespace for the XUpdate instructions. It must be http://www.nexaweb.com/xupdate.
  • select - specifies an XPath expression that evaluates to a set of Elements, Attribute or Text objects. XUpdate 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 XUpdate page can act as a Nexaweb event handler. The following example shows a snippet of XML code, and an event handling XML file using XUpdate:

<button text="Append Button at End" onCommand="appendButton.jsp"/>

The entire appendButton.jsp file could appear as follows:

<% String newButtonName = "myNewButton"; %>
<xu:modifications document="nxml" version="1.0" 
    xmlns:xu="http://nexaweb.com/xupdate"> 
    <xu:append select="/nxml/rootPane">
        <button text="<%=newButtonName%>"/>
    </xu:append>
</xu:modifications>

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

<xu:modifications document="nexaweb" version="1.0" xmlns:xu="http://nexaweb.com/xupdate">
    <!-- the create-document command must be the first command  -->
    <xu:create-document>
        <nexaweb>
        <name>Nexaweb</name>
        <address>Cambridge</address>
        </nexaweb>
    </xu:create-document>
    <xu:append select="/nexaweb">
        <phone>617-577-8100</phone>
    </xu:append>
</xu: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 XUpdate To create the initial UI page with an XUpdate document, the following special rules apply:

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

This method differs from the How to create a fresh XML document example in that, with this method, the "nxml" UI document exists as soon as the application launches and before any developer code gets run. The XUpdate that creates the initial UI must assume that the "nxml" document already exits with a single <nxml> 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 XUpdate. You can use the ShortcutSyntax in conjunction with XUpdate 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 XUpdate or solely with the ShortcutSyntax.

Using XUpdate commands

XUpdate 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 XUpdate commands along with some sample code. See the XUpdate 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.

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

append The following example shows the use of the append command.

<xu:append select="/nxml/rootPane/window[1]">
  <panel/>
</xu:append>
<xu:append select="/nxml/rootPane/window[1]"> <panel/> </xu:append>

set-attribute The following example shows the use of the set-attribute command. Related commands include: attribute, remove-attribute.

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

replace-children The following example shows the use of the replace-children command. Related commands include: replace.

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

remove-element The following example shows the use of the remove-element command. Related commands include: remove-attribute.

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

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

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

clone The following example shows the use of the clone command.

<xu:clone select="/nxml/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 XUpdate statements
  • Display windows and dialogs in the <rootPane> without XUpdate

The Shortcut Syntax essentially provides a shorthand notation for using an XUpdate statement that appends to the <rootPane> tag. A page uses shortcut syntax notation if all of the following apply:

  • The page has NXML tags not wrapped in XUpdate
  • 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 "nxml" 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 <nxml> 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 <nxml> 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 NXML not wrapped in XUpdate 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. index.nxml - the start page

 !-- this automatically appends the rootPane to the root "nxml" tag -->

<rootPane>
  <label text="hello world"/>
  <button text="click for hello world window" onCommand="window.nxml"/>
</rootPane>

or

<-- this automatically creates and appends a rootPane to the "nxml" tag, 
    then places the label and button underneath that root pane -->
<nxml>
    <label text="hello world"/>
    <button text="click for hello world window" onCommand="window.xml"/>
</nxml>

or

<!-- this automatically creates and appends a rootPane to the "nxml" tag, 
     then places the button underneath it -->
<!-- you can only have one element in this syntax in the start page-->
<button text="click for hello world window" onCommand="window.xml"/>

window.xml

<!--  you can insert only window, dialog, messageDialog in a non-start-page when including their tags directly -->
<window caption="hello world window"/>

or

<nxml>
    <!-- you can insert only window, dialog, messageDialog in a 
    non-start-page when including their tags directly -->
    <window caption="hello world window"/>
</nxml>