Tutorial, and best practices, on using Ajax in templates

The simple way

The RunningQueryImpl has a number of supported parameters that, in combination with using various layouts per tab (which can also be called a "vertical"), can be used to build a rich ajax client.

Each tab/vertical has a connection to one mode. In this mode there is a list of commands to run. By default all commands are run unless they are associated to enrichments from the tab, and the enrichment's rule achieved a score meeting the enrichment's threshold. Enough about enrichments, that's a story for another day.

The commands parameter

This default behavior of which commands to run within the RunningQueryImpl can be explicitly, and per request, defined via the "commands" parameter.
For example, this search asks for only the defaultSearch command to run on sesam.no which is why you see "?" for the hit count on all the other services. The commands parameter takes a comma separate list when you want to request multiple commands within the mode to be run.

The waitFor parameter

By default the RunningQueryImpl waits until all commands have been executed. This need not be the case though if you give, in modes.xml, the command the attribute asynchronous="true". If a command is attributed such and you want to be guaranteed to see the results you must explicitly state that you are willing to wait for the command to finished by adding the parameter for example waitFor=defaultSearch.

The waitFor parameter can be used in a number of ways:

• commands=defaultSearch&waitFor=defaultSearch explicitly asks the command to be run, and presuming that it is attributed as an asynchronous command, and to wait until it is finished.
• waitFor=defaultSearch asks to wait for the command to finish. This presumes that the command is included in the default list of commands to run but is attributed as asynchronous.
• commands=&waitFor=defaultSearch disables all commands from running but asks to wait for the command to finish. This presumes that a previous request started the command. This demonstrates how commands are stored in the datamodel between requests and how asynchronous commands can be initiated by the original request, but not used in that request's output, and their results used via a second request, eg an ajax call, later on.

The layout parameter

Finally all this can be used with alternative layouts by suppling the layout parameter.
Each tab contains a default layout that is in views.xml the tab without an id attribute. With the layout parameter defined a layout with a matching id is looked for and used instead. If it can't be found the default is still used.
This allows a pseudo "portals" approach to the templating system. For example the request http://sesam.no/search/?q=sesat&commands=defaultSearch&layout=defaultSearchlayout
with the additional layout

<layout id="defaultSearchLayout" main="/fragments/layout/results/defaultSearch"/>

would render only the main results list on the page.

This above given layout doesn't have any embedded include templates. Since the result list is all rendered with just defaultSearch.vm template it can be supplied directly, in an absolute manner (see the initial / in the path), as the main template.

Examples and usages

This section won't include much code, but will explain in more detail how AJAX can be used. For these examples we'll use the following configuration:

<view id="ajax-test" key="at" mode="ajax-test" inherit="default-mode">
  <!-- default layout for normal requests -->
  <layout main="main">
    <include ...>
    [...]
  </layout>

  <!-- layout for the ajax request using the ajaxtest template-->
  <layout id="ajax" main="ajaxtest"/> 
</view>

<mode id="ajax-test" inherit="default-mode">
  <yahoo-web-command id="defaultSearch" inherit="default-yahoo-web-command" asynchronous="true"/>
  <yet-another-search-command id="yasc" inherhit="default-yasc"/>
</mode>

There's a few different ways AJAX/SESAT can be used to enhance a web page. What's probably most useful is the ability to fetch slow results using a second request.

Note: This is currently broken and probably won't work as expected until SESAT 2.18. See http://sesat.no/scarab/issues/id/SKER4737

The following steps will show a typical use of this:

1. The users browser makes a request to /search/?c=at&q=sesat
2. SESAT executes all search commands. Since defaultSearch is marked as asynchronous it's not waited for by SESAT, so if it' not finished by the time the other search commands are it's not included in the results returned to the browser.
3. The users browser executes javascript code that was returned in the first response and does an AJAX request to /search/?c=at&q=sesat&commands=&waitFor=defaultSearch&layout=ajax
4. SESAT fetches the search result for defaultSearch that was executed by the previous request and returns it to the browser using the templates associated with the layout with id ajax.
5. The users browser dynamically adds the defaultSearch result to the web page.

Another use would be to only fetch the results of specific search commands:

1. The users browser makes a request to a given web page
2. The users browser executes javascript code that was returned in the first response and does an AJAX request to to /search/?c=at&q=sesat&commands=yasc&layout=ajax
3. SESAT executes only the yasc command and wait for it to finish before returning the result to the browser.
4. The users browser dynamically adds the yasc result to the web page

The hard way

Enable DWR (the dependency and the servlet). This serialises the whole datamodel through the request so it is available in the client's javascript. This is a far more advanced approach when much more logic is required on the client side. DWR is disabled by default in Sesat as we suspect the simpler approach is well, simpler.