This widget template provides an interface for displaying a list of items coupled with an 
interface for searching and filtering those items. It is assumed that a suitable REST API
is available for retrieving search results in XML format.

[NOTE: the XML restriction is relatively easy to work around if your REST API returns another
format such as JSON. Join us on the dev mailing list and we'll help you work it out]

* Customizing

This section describes how the template can be customised.

** Results list

The initial results list is generated by retrieving and XML document or JSON file from the 
URL defined by "browse.index.url".

This document is then transformed into HTML using a template; the template item_summary_template.html 
is used for the item summaries shows in the list, and item_template.html for the item
descriptions when an item is expanded (see below). Properties defined in the widget.properties file 
(browse.item.elements and browse.item.attributes) are read from the JSON or XML and substituted 
for tokens in these HTML files. For example, if browse.item.elements="title", then the content
of the <title> element from the results will replace ${TITLE} in the HTML template. Note that
the tokens always use uppercase.

We recommend copying item_template.html and item_summary_template.html and editing them to display data 
returned by your API. Note that the templates must use single (') instead of double (") quotes.

If a search had been performed in the form provided then the results are retrieved from the 
URL defined by "browse.search.url". Note that the variable "query" defines the search string
entered by the user.

The results are displayed in an accordion control.

*** Item identifiers

When generating the results list you need to ensure that each item has an attribute "wid" which
contains the ID of the item in question. This is later used for retrieving the details about that
item. See "item_summary_template.html" for an example of populating the wid attribute.

** Result detail

When an item is expanded an ajax request is made to retrieve the details of the item in question.
The URL used is defined by "browse.get.detail.url", you can use the variable "itemId" as the
identifier for this item.
 
The XML or JSON returned is then rendered as HTML and inserted into the expanded control using
the item_template.html HTML template in the same manner as the summaries.

** Events

You can register callbacks for events using the
WIDGETNAME_controller.register(EVENTNAME, callback function, WIDGETNAME)
method. Callbacks will recieve an event object as a parameter which
will include the following properties:

  * type: a string identifying the type of event
  * widget: a string identifying the shortname of the widget generating the event

When registering a callback you can either register it to respond to
all events of a given type or only events fired by a specific
widget. To respond to all events simply omit the WIDGETNAME in the
register method call.

Available events are:

*** ClickItem

Called whenever an item in the browse list is clicked on. 

The event object will have an "itemId" property that contains the ID for the item clicked.

**** Examples

#+BEGIN_SRC javascript
viewItem = function(event) {
    alert("Item with id " + event.itemId + " was clicked by the user");
}

${widget.shortname}_browse_controller.register("clickItem", viewItem, ${widget.shortname});
#+END_SRC

*** ExpandItem

Called whenever an item in the browse list has been expanded. The
function is passed an event object (which is generated by JQuery) and
the ID of the item being expanded.

The event object will have an "itemId" property that contains the ID
for the item expanded.

#+BEGIN_SRC javascript
${widget.shortname}_browse_controller.register("expandItem", function(event) {
    alert("expanded item with id " + event.itemId);
});
#+END_SRC