Application Sample

Creating Documents using HDBModel

The WebTML module "tml/html/addresses/mode-new.tml" produces the following output:

mode-new.png

It shows a form to enter new address data and has two buttons "create" and "cancel" at the bottom.

Here ist the TML code from "html/addresses/mode-new.tml":

<h2>Portlet Mode '<tml:script expression="portlet.mode"/>': Create new Address ...</h2>

<tml:form id="new-address" source="none" contentclass="address">       

    <tml:include ref="::form"/>
    <hr>
    <tml:button clickaction="$store" ajax="true" portletmode="view">Create address</tml:button>
    <tml:button portletmode="view" ajax="true">Cancel</tml:button>

   
</tml:form>

The WebTML contains a <tml:form> with source="none".

Remember the source attribute we discussed in the last chapter? It is used to fill the input fields in the form from values of the "source". Because we want to create a new address we want the form to be empty. This is what source="none" accomplishes.

Next we <tml:include> a TML module "::form" that contains the form fields we want to present to the user.

It is good practice to have a separate WebTML module containing the form fields because we will use the same module (same input fields) in portlet mode "edit" (module "html/addresses/mode-edit") later.

After the ::form include we have the two <tml:button>s - the create button with clickaction="$store" and the cancel button without a clickaction. both with portletmode="view".

As described in the previous section a button without an action does nothing but refresh the portlet. The attribute. portletmode="view" ensures that after clicking this button we are back in portlet mode "view" and the module "mode-view" will be included by the portlet. This is basically what we want to do when a user cancels editing: Do nothing but return into view mode.

The create-button references default action "$store" which we also already know. It will save the form data to a new address document. But how does it know where to store this document? This is where the HDBModel framework mentioned above is involved.

The HDBModel framework

This is a framework, especially meant to be used with data-driven applications, which lets you predefine a certain document hierarchy for your data documents that will be used automatically by OpenWGA to perform the correct operations.

The heartpiece of every HDBModel-enabled application is the model definition, which is stored in a file   "files/system/hdb-model.xml". Lets have a look at the definition of this sample application:

<hdb-model>
  <storage sid="addresses">
    <content contentclass="address"/>
  </storage>
</hdb-model>

As you see, and most likely already expected from the file name, the file contains XML markup.

Without going too much into detail we can see here that the model definition defines a certain document hierarchy, which in this case only consists of two positions:

  • A"storage document" of id "addresses" which is used to collect all address documents. Think of it like some kind of "folder" for a special content class. Storage documents are automatically created by OpenWGA.
  • "Inside" the storage document there is a "content document" defined of content class "address". This means that content documents of class "address" are placed below this storage document in hierarchy when they are created. There may be unlimited numbers of address documents at this position, so all address documents become "child documents" of the "addresses" storage.

Now when the WebTML form gets stored using default action "$store", specifies source="none" and a contentclass="some-contentclass", then OpenWGA assumes that a new document should get created using HDBMOdel.

HDBModel then searches for a valid position for the document to create in its model definition. It therefor reads the attribute "contentclass" from the <tml:form> tag to determine which class of content should get stored. Then it searches for <content> tags inside the definition having the same class.

In the current case this is quite simple. The WebTML form declares content class "address", which is the only defined content position in the model. So "$store" will create a new document below the automatically created storage document "addresses".

After the document has been successfully created we return to the mode "view" - which is determined by attribute "portletmode" on <tml:button> - so we again see all address documents, now including our newly created address.


Continue on next page ...