Creating a New Page

With the object model and service in place, we're ready to provide interaction. Dynamic pages are XSL templates which sit within the html/ directory. XSL knowledge is required for page editing. XSL is somewhat obscure, and so you might never have used it. It takes input XML and reformats it according to XSL instructions, selecting data from elements, iterating through elements, and dumping content (ie HTML). The main advantage of XSL is the separation of processing and formatting. Basically, the java that does the work is all together, and the XSL which does the formatting is all together. This means that each piece can be best managed by separate tools, and that changes are located close together. In practice, it leads to quicker development and lessened maintenance. If this is your first time encountering XSL, you should read the XSL Overview tutorial.

How Pages are Constructed

Dynamic pages are constructed in the following manner by the web framework:
  1. Input XML is formulated for the page. This XML contains the specifics for the page request, including the requested url, the specified parameters, the user, the session and the current menu state.
  2. The XML is used as input to the requested page, which spits out HTML. This HTML is a bare HTML snippet (no html tag, no head, no body), just the content snippet for the current request.
  3. The same XML is then used as input to the theme XSL, which creates the overall layout of the page, including the HTML header, the body tag, the menu and page title, and various site-wide content. The default theme is 'default' and may be found as var/site/page.xsl within the benow-web.jar or as var/site/page.xsl, if overriden. The theme page spits out a <!--page--> tag which is located and used as the insertion point for the current page snippet (as generated in the previous step). The HTML now contains the dynamic content amid the theme page.

    The theme can be customized to your application, and might spit out a different menu, title bar or page layout. More on the theme system and customisation can be found in Theme Customisation page within the advanced section of this walkthru.

  4. The HTML produced to this point is then scanned for post-processing. The web framework provides certain tags which cause further processing and substitution, such as the <svc> tag, which will be discussed in Calling services from a page
  5. The HTML is now complete and is delivered to the requesting client, is rendered and seen by the visitor.

Creating a new page

The easiest way to create a new page is to go to the development page, select pages from the dropdown, specify a full page name (including path, but excluding the html/ prefix) and hit 'Create New...': The new page template is copied to the specified file, and is ready to be customised. This template is found in var/templates/page.template within benow-web.jar, but may be overriden by specifying a var/templates/page.template within the project filesystem. You now have the boilerplate for a new page. As can be seen in the screenshot, the new page from the template already contains information. It defines a stylesheet, includes some XSL libraries, has some parameters, and defines a template. So, we now have a new page that is ready to be edited. Remove the comments and add some text in the index template, and hit save: hit 'View' and a new window/tab will open to the edited page: Isn't it pretty... but perhaps still a bit unclear as to how it was done. XSL reformats XML, and we've seen no XML yet. As outlined above, the XML is created for each page request, and serves as the input to the XSL. The XML for the page request can be shown by clicking the XML link in the top left (or the shortcut Alt-Shift-X). The full xml for the page request was: 
<index uri="/walkthru/hello.page">
  <params>
    <pagePath>walkthru/hello.page</pagePath>
  </params>
  <url>http://localhost:8420/walkthru/hello.page</url>
  <headers>
    <Host>localhost:8420</Host>
    <User-Agent>Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.1.7pre) Gecko/20091210 Ubuntu/9.10 (karmic) Shiretoko/3.5.7pre</User-Agent>
    <Accept>text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8</Accept>
    <Accept-Language>en-us,en;q=0.5</Accept-Language>
    <Accept-Encoding>gzip,deflate</Accept-Encoding>
    <Accept-Charset>ISO-8859-1,utf-8;q=0.7,*;q=0.7</Accept-Charset>
    <Keep-Alive>300</Keep-Alive>
    <Connection>keep-alive</Connection>
    <Referer>http://localhost:8420/admin/dev/index.page?op=view&type=page&item=walkthru/hello.page</Referer>
    <Cookie>userInfo=admin  92668751; userInfo=admin  92668751; wdk_pref_cookie_0=eJyNkctKQzEQhl/F7uXQikIrzbLo5mjBLhSRME3GdmiSCZlp63l7o1WoR7wsB/7L9zOuoMekBEFsBpE9F2/w+ua+PZOL29l4f3clk+nAccycqvCRvAm8ovTUbAVLgojGO43TwY6ElgELZhZSLoRiLkfn48mpj9Zj5JpyVNZzQ86BHChxasA5lBpGgbRrZM1F3VYT7Gj1LsAEtcib55qDv1khqOKL9vQuUIVIqHXrJvDBaaydtfPFw2Lezqw9+crq2S1BKurnkJ8rN9gtGYr/H+1W128dH6fnCPSd5NjhSXKArnGh/oqcGQ2HfdRDBsasnf2jrrfqFRPUx5M.; JSESSIONID=1exiiote7y814</Cookie>
  </headers>
  <session>
    <headers>{}</headers>
    <addCookies>[javax.servlet.http.Cookie@16e14f9]</addCookies>
    <pagexml>[org.benow.web.path.page.XMLChunk@22ed4b]</pagexml>
    <xslParams>{}</xslParams>
    <params>pagePath{walkthru/hello.page} </params>
    <user key="1" type="org.benow.repository.security.UserImpl">
      <name>admin</name>
      <description><![CDATA[Administrative user.]]></description>
      <validated>true</validated>
      <validation-code>1260832613816</validation-code>
      <needs-password>false</needs-password>
      <confirmed>true</confirmed>
    </user>
    <url>http://localhost:8420/walkthru/hello.page</url>
    <userStamp>Thu Dec 17 17:03:02 MST 2009</userStamp>
  </session>
  <menu key="1">
    <name>/</name>
    <href>/</href>
    <description>root</description>
    <pos>0</pos>
    <canned>false</canned>
    <children type="org.benow.repository.mapping.JSQLArrayList">
      <item key="3" type="org.benow.web.menu.MenuItemImpl">
        <path>/Administration</path>
        <name>Administration</name>
        <href>/admin/index.page</href>
        <on-click/>
        <description>Administer the site</description>
        <pos>1</pos>
        <canned>false</canned>
        <children type="org.benow.repository.mapping.JSQLArrayList">
          <item key="4" type="org.benow.web.menu.MenuItemImpl">
            <path>/Administration/menu</path>
            <name>menu</name>
            <href>/admin/dev/menu.page</href>
            <on-click/>
            <description>Configure the menu</description>
            <pos>1</pos>
            <canned>false</canned>
          </item>
          <item key="5" type="org.benow.web.menu.MenuItemImpl">
            <path>/Administration/development</path>
            <name>development</name>
            <href>/admin/dev/index.page</href>
            <on-click/>
            <description>Edit web items</description>
            <pos>2</pos>
            <canned>false</canned>
          </item>
          <item key="6" type="org.benow.web.menu.MenuItemImpl">
            <path>/Administration/security</path>
            <name>security</name>
            <href>/admin/security/index.page</href>
            <on-click/>
            <description>Manage users, roles and permissions</description>
            <pos>3</pos>
            <canned>false</canned>
          </item>
          <item key="7" type="org.benow.web.menu.MenuItemImpl">
            <path>/Administration/services</path>
            <name>services</name>
            <href>/svc/</href>
            <on-click/>
            <description/>
            <pos>4</pos>
            <canned>false</canned>
          </item>
        </children>
      </item>
    </children>
  </menu>
  <styles>
    <item link="/css/index.css"/>
  </styles>
</index>
The XML begins with an index element, and contains a bunch of data, most of which is only useful to the page template. The index is matched by <xsl:template match="index">. We can further edit the page to dump some of this info: This now gets the user name from the user parameter, and displays the current url from the <url> element: And so, that is the basics of dynamic web page design. The whole dynamic part is still missing. The data is still relatively static, but we'll soon be fetching data from the services, as described in the next section.

Operations

For the previous example, the index element was matched. The index element is the root element when no op parameter is specified. The op parameter can be used to present other functionality within the page. If another template were defined, then it can be matched by passing the associated value for op. For example: When the page is accessed as /walkthru/hello.page?op=goodbye, then <goodbye> becomes the top element and matches the goodbye template, causing: By using different values for the op parameter, different templates within the page can be used. This centralizes behaviour and makes sites simpler and more appropriate. We'll be using this behaviour, as we move to calling services from a page.