Commits

Kirill Simonov committed 53feaeb

Updated documentation.

Comments (0)

Files changed (5)

     </strong>
 </p>
 
+<h3>Courses</h3>
+<table id="course"
+       data-htsql="/course?department_code=$department"
+       data-ref="department">
+</table>
+
 </body>
 
 </html>

doc/extensions/sphinxext_htrafdemo/static/htrafdemo.css

   display: none;
 }
 
-.demo-area h1,
-.demo-area h2,
-.demo-area h3 {
+div.body .demo-area h3 {
+  margin: 1em 0 0;
+  padding: 0;
+  font-family: inherit;
+  font-weight: bold;
+  font-size: 105%;
   color: #900;
+  background: transparent;
+  border: none;
 }
 
-.demo-area em.htraf,
-.demo-area strong.htraf {
+div.body .demo-area em.htraf,
+div.body .demo-area strong.htraf {
   color: #369;
 }
 
-.demo-area table.htraf {
+div.body .demo-area table.htraf {
 	border-collapse: collapse;
 	border-spacing: 0;
   border-left: 2px solid #ddd;
   border-bottom: 2px solid #ddd;
 }
 
-.demo-area table.htraf th,
-.demo-area table td {
+div.body .demo-area table.htraf th,
+div.body .demo-area table td {
   padding: 4px 6px;
   font-size: 90%;
   vertical-align: top;
 }
 
-.demo-area table.htraf th {
+div.body .demo-area table.htraf th {
   background: #ddd;
   font-weight: bold;
   color: #555;
 }
 
-.demo-area table.htraf td {
+div.body .demo-area table.htraf td {
   border-right: 1px solid #ddd;
   border-bottom: 1px solid #ddd;
 }
 
-.demo-area ul.htraf,
-.demo-area ol.htraf {
-  background: #ddd;
+div.body .demo-area ul.htraf,
+div.body .demo-area ol.htraf,
+div.body .demo-area dl.htraf {
+  border-left: 6px solid #ddd;
+  padding-left: 0.5em;
 }
 
-.demo-area ul.htraf li,
-.demo-area ol.htraf li {
+div.body .demo-area ul.htraf li,
+div.body .demo-area ol.htraf li,
+div.body .demo-area dl.htraf dt {
   margin: 0;
+  list-style-position: inside;
 }
 
-.demo-area .htraf-hover {
+div.body .demo-area dl.htraf dd {
+  margin: 0 0 0 1em;
+}
+
+div.body .demo-area .htraf-hover {
   background: #f6ddaf;
 }
 
-.demo-area .htraf-selected {
+div.body .demo-area .htraf-selected {
   background: #ffa43f;
 }
 
-*******************
-  HTRAF Reference
-*******************
+*****************
+  HTRAF Toolkit
+*****************
 
-HTRAF is a toolkit for embedding data into HTML pages.  HTRAF lets an
-HTML designer to associate certain HTML elements with data sources; then,
-when the page is opened in a browser, HTRAF automatically fetches the
-data from the database and populates the selected elements.
+HTRAF is a toolkit for embedding data into HTML pages.  With HTRAF, you
+can associate certain HTML elements with data sources --- when the page
+is opened in a browser, HTRAF fetches the data from the database and
+displays it on the page.
 
 HTRAF is based upon JQuery_ Javascript framework and relies on an HTSQL_
-service to retrieve data from the database.
+service to retrieve data from the database.  HTRAF is written by Oleksiy
+Golovko and Owen McGettrick and released under dual MIT/GPL license.
 
 .. _HTSQL: http://htsql.org/
 .. _JQuery: http://jquery.org/
 
-HTRAF is written by Oleksiy Golovko and Owen McGettrick and released
-under the same licenses as JQuery_.
 
+Quick Start
+===========
 
-Overview
-========
+Download HTRAF
+--------------
 
-Extracting and presenting data from a relational database is one of
-the most common tasks in web development.  The usual approach splits
-this task into several *tiers*:
+Download the latest build of HTRAF from:
 
-* a database tier that stores the data;
-* a middleware tier is a server side application that retrieves data
-  from the database and renders it into HTML;
-* a presentation tier is a web browser that displays the rendered
-  page to the users.
+    http://htsql.org/download/HTRAF-latest.zip
 
-While powerful and generic, this approach is quite heavyweight.  HTSQL
-and HTRAF radically simplify it by eliminating the middleware tier;
-instead you embed the data from the database directly to an HTML page.
+Include the framework
+---------------------
 
-Take the following use case: allow a user to select a *school* from
-a drop-down list, then, for the selected school, display associated
-*departments* together with the *number of courses* offered by each
-department.
-
-(In all examples below, we use a sample database of a student enrollment
-system in a fictional university.  The database contains schools,
-programs administered by a school, departments associated with a school,
-and courses offered by a department.)
-
-Here is how we implement this use case with HTRAF:
-
-.. demo::
-   :source:
-   :hide:
-
-    <select id="school_1"
-        data-htsql="/school{code, name}?exists(department)">
-    </select>
-
-    <table
-        data-htsql="/department{name, count(course)}?school.code=$school_1"
-        data-ref="school_1">
-    </table>
-
-This HTML fragment contains two elements: ``<select>`` and ``<table>``
-which display a drop-down list of schools and a list of associated
-departments respectively.  The elements (we call them *widgets*) are
-empty, but have some extra attributes.
-
-The ``data-htsql`` attribute contains an HTSQL query; it instructs
-HTRAF to execute the query and use the result to populate the content
-of the widget.  Take a look at the output of the query:
-
-.. htsql:: /school{code, name}?exists(department)
-   :cut: 4
-
-HTRAF renders this output into the following HTML code:
-
-.. sourcecode:: html
-
-    <select id="school_1">
-        <option value="art">School of Art and Design</option>
-        <option value="bus">School of Business</option>
-        <option value="edu">College of Education</option>
-        <option value="eng">School of Engineering</option>
-        ...
-    </select>
-
-The ``<table>`` widget is more interesting.  To indicate that the
-``<table>`` widget depends on the ``<select>`` list and should be
-updated when some row in the list is selected, we assign anchor
-``id="school_1"`` to the ``<select>`` element and add attribute
-``data-ref="school_1"`` to ``<table>``.  The selected value is available
-in HTSQL under the name ``$school_1``.
-
-For example, if the user selects *School of Engineering* in the
-drop-down list, then to update the linked table, HTRAF will execute the
-query:
-
-.. htsql::
-   :cut: 4
-
-    /department{name, count(course)}?school.code=$school_1
-     :where $school_1 := 'eng'
-
-For more information on HTSQL syntax and semantics, see `HTSQL Tutorial
-<http://htsql.org/doc/tutorial.html>`_; this document describes how to use
-HTRAF toolkit to embed results of HTSQL queries into HTML pages.
-
-Prerequisites
-=============
-
-HTRAF uses an HTSQL service to retrieve data from the database; therefore, in
-order to use HTRAF, you need to install HTSQL and deploy it as a web service
-against your database.  See `HTSQL Installation Guide
-<http://htsql.org/doc/install.html>`_ for more details.
-
-It is strongly recommended to configure the HTTP server to serve both
-HTSQL service and HTML pages from the same domain; otherwise browser
-security settings would prevent HTRAF from accessing HTSQL service.
-That could be circumvented by using CORS on the HTSQL service, but note
-that not all browsers support CORS.  For more details on CORS, see `CORS
-W3C specification`_.
-
-.. _CORS W3C specification: http://www.w3.org/TR/cors/
-
-Then download and install HTRAF.  HTRAF is a pure Javascript toolkit, so
-simply unpack the archive to where you keep other static data for your
-website.
-
-To start using HTRAF, include the script ``htraf.js`` to your HTML
-pages.
+Include the script ``htraf.js`` to your HTML pages and associate it with
+an HTSQL service:
 
 .. ifconfig:: build_website
 
     .. demo::
        :source:
-       :hide:
 
         <script type="text/javascript"
             src="/htraf/htraf.js"
 
     .. demo::
        :source:
-       :hide:
 
         <script type="text/javascript"
             src="../htraf/htraf.js"
             data-htsql-prefix="http://demo.htsql.org">
         </script>
 
-In addition to regular ``<script>`` attributes, we added two extra
-attributes:
+Select data sources
+-------------------
 
-`data-htsql-prefix` (absolute or relative URL)
-    This specifies the root of the HTSQL service; in the example above,
-    HTSQL service is located at http://htsql.org/@demo.
+Construct HTSQL queries to serve as data sources for HTML elements:
 
-    Note that the URL should not include a trailing slash.
+.. htsql::
+   :cut: 4
 
-`data-htsql-version` (``1`` or ``2``)
-    The major version of HTSQL; currently the only meaningful value
-    is ``2``.  (HTSQL 1 is used for in-house projects of `Prometheus
-    Research`_.)
+    /school{code, name}?exists(department)
 
-.. _Prometheus Research: http://prometheusresearch.com/
+.. htsql::
+   :cut: 4
 
+    /department{name, count(course)}?school.code=$school_code
+        :where $school_code := 'art'
 
-Widgets
-=======
+Attach the sources to HTML elements
+-----------------------------------
 
-HTML elements controlled by HTRAF are called *widgets*.  HTRAF supports
-a number of different widgets: drop-down and regular lists, tables,
-charts, and also provides an API to define new widget types.
-
-Widget elements should not contain any subelements since the content of
-the widget is populated and maintained by HTRAF.
-
-Linking
--------
-
-Common Attributes
------------------
-
-A widget may possess the following attributes: 
-
-`id` (a unique identifier)
-    Indicates the name of the widget, must be unique across the whole
-    HTML page.  The name is used when declaring widget dependencies,
-    see description of `data-ref` attribute for more details.
-
-`data-widget` (widget type: ``select``, ``table``, ``chart``, etc)
-    HTRAF determines the type of the widget from the value of this
-    attribute.  In the absense of `data-widget`, HTRAF assumes the type
-    coincides with the tag name.  Conveniently, commonly used widget
-    types are called ``select``, ``table``, ``ul``, etc., so often there
-    is no need to specify the widget type explicitly.
-
-`data-htsql` (an HTSQL query)
-    HTSQL query executed to populate the widget.  This is a mandatory
-    attribute since it used by HTRAF to find widgets on the page.
-
-`data-ref` (list of widget identifiers)
-    If present, indicates that the content of the widget depends on
-    other widgets. 
-
-Common Classes
---------------
-
-`htraf-selected`
-
-`htraf-hover`
-
-
-Now suppose you conjured an HTSQL query that generates the output
-you want and now you want to embed the output to the page.
-
-Let's take the query:
-
-.. htsql:: /department{name, count(course)}?school.code='eng'
-
-That produces the number of course per department in the school
-of *Engineering*.  The following code utilizes HTRAF to embed
-the output of the query as a table:
-
-.. demo::
-   :source:
-   :hide:
-
-    <table data-htsql="/department{name, count(course)}?school.code='eng'">
-    </table>
-
-In this HTML fragment, attribute ``data-htsql`` instructs HTRAF
-to execute the given query and populate the table with the query
-output.
-
-HTRAF is not limited to tables, it could also produce lists,
-charts, etc.  You can also extend HTRAF with your own widgets.
-
-For instance, the following code uses HTRAF to populate a select
-list.
-
-.. demo::
-   :source:
-   :hide:
-
-    <select data-htsql="/school{code, name}?exists(department)">
-    </select>
-
-In this case, the query
-
-.. htsql:: /school{code, name}?exists(department)
-   :cut: 3
-
-lists the code and the name of schools that have at least one
-associated department.  The first column ``code`` is used to populate
-the ``value`` of the select list, the second column ``name`` populates
-the content of the select list.
-
-HTRAF allows you to bind elements together so that selecting
-a value in one element updates another element.  For example,
-we could bind the two elements above so that a choice done
-in a select list updates the table content.
-
-Note the extra attribute `data-ref` on the table widget.  It indicates
-that the widget uses the data from another widget called ``school``
-and should be updated whenever the ``school`` widget is updated.
-
-
-Widgets
-=======
-
-HTML elements that display data are called *HTRAF widgets*.  HTRAF
-recognizes widgets by presence of attribute `data-htsql`.
-
-HTRAF supports a numerous types of widgets and allows one to extend it
-with custom widgets.  The type of a widget is determined as follows:
-
-* The value of attribute `data-widget` if it is set.
-* Otherwise, the name of the tag; if it is a valid widget name.
-* Otherwise, use *singleValue* --- the default widget.
-
-In the following example, the type of the widget is determined
-from value of ``data-widget``:
-
-.. demo::
-   :source:
-   :hide:
-
-    <div width="500" height="400"
-        data-widget="chart"
-        data-htsql="/department{name, count(course)}?school.code='eng'">
-    </div>
-
-
-HTRAF takes over the widget content, preserving the tag itself,
-but replacing the content with generated data.
-
-Some widgets (such as table or select list) allows one to select
-a row in the output.
-
-
-
-Table Widget
-============
-
-Probably the most common widget in HTRAF, *table* renders data using
-HTML ``<table>`` element.
-
-The *table* widget is selectable, when selected, it emits the value
-from the first output column.
-
-Example
--------
+Add `data-htraf` attribute to populate the element with the output of
+the query.  Add `data-ref` attribute to force an element to update when
+the linked element changes.
 
 .. demo::
    :source:
 
-    <table data-htsql="/school">
-    </table>
+    <select id="school_code"
+        data-htsql="/school{code, name}
+                           ?exists(department)"></select>
 
-Attributes
-----------
+    <table
+        data-htsql="/department{name, count(course)}
+                               ?school.code=$school_code"
+        data-ref="school_code"></table>
 
-`data-hide-column-0` (``true``)
-    Do not display the first output column.
 
-    Useful when the first column contains a value of the key to pass to
-    dependent widgets, but the the value itself is not needed in the
-    output.
-
-    Example:
-
-    .. demo::
-       :source:
-       :hide:
-
-        <h3>Select a School</h3>
-        <table id="school_2"
-            data-htsql="/school{code, name}?exists(department)"
-            data-hide-column-0="true">
-        </table>
-
-        <h3>Associated Departments</h3>
-        <table
-            data-htsql="/department{name}?school.code=$school_2"
-            data-ref="school_2">
-        </table>
-
-    Even though the query produces two columns, the first column is
-    hidden from the table.  It is still used to pass the school code to
-    the dependent widget.
-
-CSS Classes
------------
-
-`rN` (*N* is integer starting from *0*)
-    Set on *N*-th row (``<tr>``) element of the widget.
-
-`cN` (*N* is integer starting from *0*)
-    Set on each *N*-th column (``<td>``) element of the widget.
-
-`even`, `odd`
-    Set on each even/odd row element.
-
-
-Select Widget
+Documentation
 =============
 
-The *select* widget presents data in the form of a drop-down menu using
-a ``<select>`` element.
+.. toctree::
+   :maxdepth: 2
 
-The associate HTSQL query should produce two or one columns.  When the
-output has two columns, they are used to populate the value and the label
-of each option; if only one column is available, it is used to populate
-both the value and the label.
+   overview
+   widgets
 
-Example
--------
+Indices and tables
+------------------
 
-.. demo::
-   :source:
-   :hide:
+* :ref:`genindex`
+* :ref:`search`
 
-    <select data-htsql="/school{code}">
-    </select>
-
-    <select data-htsql="/school{code, name}">
-    </select>
-
-Attributes
-----------
-
-`multiple`
-    The select widget admits multiple selections.  When more then one
-    choice is selected, the values are passed to the dependent widgets
-    as a selector.
-
-    Example:
-
-    .. demo::
-       :source:
-       :hide:
-
-        <select id="school_3" size="4" multiple
-            data-htsql="/school{code, name}?exists(department)">
-        </select>
-
-        <table
-            data-htsql="/department{name}?school.code=$school_3"
-            data-ref="school_3">
-        </table>
-
-UL and OL Widgets
-=================
-
-The *ul* and *ol* widgets present data in a form of an unordered and
-ordered lists using ``<ul>`` and ``<ol>`` HTML elements.
-
-Just like select widgets, the ul and ol widgets accept input data with
-one or two columns; when two columns are given, the second column is
-used to populate the content of each entry.
-
-Example
--------
-
-.. demo::
-   :source:
-
-    <ul data-htsql="/school{code}?exists(department)">
-    </ul>
-
-    <ol data-htsql="/school{code, name}?exists(department)">
-    </ol>
-
-
-IFrame Widget
-=============
-
-The *iframe* widget embeds the response from the HTSQL server into a
-frame.  This is the only widget that does not render JSON data, but
-relies on HTSQL server to send formatted output in HTML.
-
-Example
--------
-
-.. demo::
-   :source:
-
-    <iframe width="600" height="300"
-        data-htsql="/school{code, name}?exists(department)">
-    </iframe>
-
-
-Chart Widget
-============
-
-The *chart* widget presents data in a graphical form.  The first column
-of the output specifies the chart labels, the remaining columns specify
-the respective values.
-
-Since HTML does not have a ``<chart>`` element, you need to specify the
-widget type using ``data-widget`` attribute.
-
-Example
--------
-
-.. demo::
-   :source:
-
-    <div style="width: 700px; height: 350px"
-        data-widget="chart"
-        data-yint="true"
-        data-title="Number of Departments by School"
-        data-htsql="/school{code,
-                            num_dept := count(department)}
-                           ?num_dept>0">
-    </div>
-
-Chart Types
------------
-
-The widget provides several types of charts: bar chart, pie chart and
-line chart.  The chart type is specified using `data-type` attribute.
-
-Bar Chart
-~~~~~~~~~
-
-To display a bar chart, the input data should contain two or more
-columns: the first column contains the labels, the subsequent
-columns are numeric values.  Each value is represented by the
-height of a rectangular bar.
-
-.. demo::
-   :source:
-   :hide:
-
-    <div style="width: 345px; height: 325px"
-        data-widget="chart"
-        data-type="bar"
-        data-yint="true"
-        data-title="Bar Chart"
-        data-htsql="/school{code,
-                            num_dept := count(department),
-                            num_prog := count(program)}
-                           ?num_dept>2&num_prog>2">
-    </div>
-
-Stacked Bar Chart
-~~~~~~~~~~~~~~~~~
-
-Same as the regular bar chart except that when the data contain two
-or more value columns, the respective bars are stacked in a single
-line.
-
-.. demo::
-   :source:
-   :hide:
-
-    <div style="width: 345px; height: 325px"
-        data-widget="chart"
-        data-type="stack"
-        data-yint="true"
-        data-title="Stacked Bar Chart"
-        data-htsql="/school{code,
-                            num_dept := count(department),
-                            num_prog := count(program)}
-                           ?num_dept>2&num_prog>2">
-    </div>
-
-Pie Chart
-~~~~~~~~~
-
-For a pie chart, the input data should contain two columns: the
-labels and respective numeric values.
-
-.. demo::
-   :source:
-   :hide:
-
-    <div style="width: 345px; height: 325px"
-        data-widget="chart"
-        data-type="pie"
-        data-yint="true"
-        data-title="Pie Chart"
-        data-htsql="/school{code,
-                            num_dept := count(department)}
-                           ?num_dept>2">
-    </div>
-
-Line Chart
-~~~~~~~~~~
-
-To generate a line chart, the input data should contain two or more
-columns: the first column contains (numeric or date) values for the
-*X* axis, the rest contain numeric values for the *Y* axis.
-
-.. demo::
-   :source:
-   :hide:
-
-    <div style="width: 345px; height: 325px"
-        data-widget="chart"
-        data-type="line"
-        data-yint="true"
-        data-title="Line Chart"
-        data-htsql="/(school^{num_dept := count(department)})
-                            {num_dept,
-                             num_school := count(school),
-                             num_prog := count(school.program)}">
-    </div>
-
-Attributes
-----------
-
-`style`
-
-`data-type` (``bar`` (default), ``stack``, ``pie``, ``line``)
-
-`data-legend` (``ne`` (default), ``se``, ``nw``, ``sw``, ``no``)
-
-`data-title` (a string)
-
-`data-show-title` (``true`` (default) or ``false``)
-
-`data-yint` (``true`` or ``false`` (default))
-
-`data-x-vertical` (``true`` or ``false`` (default))
-
-
-
-
-singleValue
-===========
-
-This is a fall-back widget, it is used when the actual widget type is not found.
-The widget replaces the content of the tag with the value from the first row and the
-first column of the output.
-
-Example
--------
-
-.. demo::
-   :source:
-
-    <p>The database contains
-    <strong data-htsql="/count(school)"></strong>
-    records in the <em>school</em> table and
-    <strong data-htsql="/count(department)"></strong>
-    records in the <em>department</em> table.</p>
-
-
-Common Attributes
-=================
-
-`data-htsql`
-
-`data-widget`
-
-`data-onchange`
-
-`data-onerror`
-
-`data-empty`
-
-`data-onbeforeload`
-
-`data-onafterload`
-
-
+******************
+  HTRAF Overview
+******************
+
+Introduction
+============
+
+Extracting and presenting data from a relational database is one of
+the most common tasks in web development.  The usual approach splits
+this task into several *tiers*:
+
+* a database tier that stores the data;
+* a middleware tier is a server side application that retrieves data
+  from the database and renders it into HTML;
+* a presentation tier is a web browser that displays the rendered
+  page to the users.
+
+While powerful and generic, this approach is quite heavyweight.  HTSQL
+and HTRAF radically simplify it by eliminating the middleware tier;
+instead you embed the data from the database directly to an HTML page.
+
+Take the following use case: allow a user to select a *school* from
+a drop-down list, then, for the selected school, display associated
+*departments* together with the *number of courses* offered by each
+department.
+
+.. note::
+
+   In all examples below, we use a sample database used for HTSQL
+   regression testing.  The database contains schools, programs
+   administered by a school, departments associated with a school, and
+   courses offered by a department.
+
+This is how to implement this use case with HTRAF:
+
+.. demo::
+   :source:
+
+    <select id="school_code"
+        data-htsql="/school{code, name}
+                           ?exists(department)">
+    </select>
+
+    <table
+        data-htsql="/department{name, count(course)}
+                               ?school.code=$school_code"
+        data-ref="school_code">
+    </table>
+
+This HTML fragment contains two elements: ``<select>`` and ``<table>``
+which display a drop-down list of schools and a list of associated
+departments respectively.  The elements (we call them *widgets*) are
+empty, but have some extra attributes.
+
+The ``data-htsql`` attribute contains an HTSQL query; it instructs
+HTRAF to execute the query and use the result to populate the content
+of the widget.  Take a look at the output of the query:
+
+.. htsql:: /school{code, name}?exists(department)
+   :cut: 4
+
+HTRAF renders this output into the following HTML code:
+
+.. sourcecode:: html
+
+    <select id="school_code">
+        <option value="art">School of Art and Design</option>
+        <option value="bus">School of Business</option>
+        <option value="edu">College of Education</option>
+        <option value="eng">School of Engineering</option>
+        ...
+    </select>
+
+The ``<select>`` widget is also assigned an anchor ``school_code``,
+which allows us to refer to it from other widgets.
+
+The ``<table>`` widget is more interesting as it must refresh each time
+the user selects a school from the drop-down list.  To indicate this
+dependency, we add ``data-ref="school_code"`` attribute.  Now the widget
+will be updated any time the ``school_code`` element signals a change.
+The value of the selected row is available in the HTSQL query under the
+name ``$school_code``.
+
+For example, if the user selects *School of Engineering* in the
+drop-down list, then to update the linked table, HTRAF will execute the
+query:
+
+.. htsql::
+   :cut: 4
+
+    /department{name, count(course)}?school.code=$school_code
+     :where ($school_code := 'eng')
+
+For more information on HTSQL, see http://htsql.org/; this document
+describes how to use HTRAF toolkit to embed results of HTSQL queries
+into HTML pages.
+
+
+Prerequisites
+=============
+
+Installing HTSQL
+----------------
+
+HTRAF uses an HTSQL service to retrieve data from a relational database;
+therefore, in order to use HTRAF, you need to install HTSQL and deploy
+it as a web service against your database.  See `HTSQL Installation
+Guide`_ for more details.
+
+.. _HTSQL Installation Guide: http://htsql.org/doc/install.html
+
+It is strongly recommended to configure the HTTP server to serve both
+the HTSQL service and HTML pages from the same domain; otherwise browser
+security settings would prevent HTRAF from accessing HTSQL service.
+That could be circumvented by using `Cross-Origin Resource Sharing
+(CORS)`_ on the HTSQL service, but note that not all browsers support
+CORS.
+
+.. _Cross-Origin Resource Sharing (CORS): http://www.w3.org/TR/cors/
+
+Installing HTRAF
+----------------
+
+The latest HTRAF package is available at
+http://htsql.org/download/HTRAF-latest.zip.  Unpack the archive and copy
+the content of ``htraf`` directory to where you keep static data for
+your HTML pages.
+
+HTRAF is a pure-Javascript framework that depends on JQuery_ and a
+number of JQuery plugins.  The HTRAF package includes all the
+dependencies so you don't need to install them separately.
+
+.. _JQuery: http://jquery.org/
+
+You could also download HTRAF directly from the `source repository`_:
+
+.. sourcecode:: console
+
+   $ hg clone http://bitbucket.org/prometheus/htraf
+
+.. _source repository: http://bitbucket.org/prometheus/htraf
+
+The source repository does not include any dependencies.  To build a
+packaged version of HTRAF, go to the ``htraf`` directory and type:
+
+.. sourcecode:: console
+
+   $ make
+
+The generated package will be placed into ``build`` directory.
+
+Using HTRAF
+-----------
+
+To start using HTRAF, include the script ``htraf.js`` to your HTML
+pages:
+
+.. ifconfig:: build_website
+
+    .. demo::
+       :source:
+
+        <script type="text/javascript"
+            src="/htraf/htraf.js"
+            data-htsql-version="2"
+            data-htsql-prefix="/@demo">
+        </script>
+
+.. ifconfig:: not build_website
+
+    .. demo::
+       :source:
+
+        <script type="text/javascript"
+            src="../htraf/htraf.js"
+            data-htsql-version="2"
+            data-htsql-prefix="http://demo.htsql.org">
+        </script>
+
+To include ``htraf.js``, we use the regular ``<script>`` element, but
+with two non-standard attributes:
+
+`data-htsql-prefix` (absolute or relative URL)
+    This specifies the root of the HTSQL service; in the example above,
+    HTSQL service is located at http://htsql.org/@demo or
+    http://demo.htsql.org.
+
+    Note that the URL should not include a trailing slash.
+
+`data-htsql-version` (``1`` or ``2``)
+    The major version of HTSQL; currently the only meaningful value
+    is ``2``.
+
+
+Widgets
+=======
+
+HTML elements controlled by HTRAF are called *widgets*.  HTRAF
+supports a number of widgets: drop-down and regular lists, tables,
+charts, and also prodives an API for adding new widget types.
+
+HTRAF recognizes widgets by presense of attribute ``data-htsql``.  This
+attribute specifies an HTSQL query used to populate the content of the
+widget.
+
+The type of the widget is specified by attribute ``data-widget``; when
+the attribute is not set, the type is determined by the element tag.
+
+Widgets are controlled and populated automatically by HTRAF.  HTRAF
+takes over the widget content, preserving any styles and attibutes of
+the element itself, but replacing the content of the element with
+generated data.
+
+Linking
+-------
+
+Some widgets (in particular, lists and tables) allow the user to select
+a row from the list.  It is possible to bind two widgets together so
+that selecting a row in one widget updates the content in the other.
+
+To establish a link between two widgets, assign attribute ``data-ref``
+to the dependent widget --- it should contain the ``id`` of the parent
+widget.  When the HTSQL query of the dependent widget is evaluated, the
+selected value of the parent widget is passed to the query as a
+reference.
+
+Styling
+-------
+
+In addition to existing classes, HTRAF automatically assigns some
+custom CSS classes to controlled elements:
+
+`htraf`
+    Assigned to all widget elements.  This class has no default style
+    associated with it.
+
+`htraf-hover`
+    Assigned to a selectable row when the mouse hovers over it.  The
+    default style associated with this class is:
+
+    .. sourcecode:: css
+
+       background: #888888;
+
+`htraf-selected`
+    Assigned to the currently selected row.  The default style
+    associated with this class is:
+
+    .. sourcecode:: css
+
+       background: #DDDDDD;
+
+HTRAF provides no default styling for widgets, but ``demo/css``
+directory contains several sample stylesheets which could be used as a
+starting point.
+
+Example
+-------
+
+.. demo::
+   :source:
+
+    <h3>Select a School</h3>
+    <select id="school"
+        data-htsql="/school{code, name}"></select>
+
+    <div style="width: 500px; height: 350px;"
+        data-htsql="/program{title, count(student)}
+                            ?school.code=$school
+                            &exists(student)"
+        data-ref="school"
+        data-widget="chart"
+        data-type="pie"
+        data-title="Percent of Students by Program">
+    </div>
+
+    <h3>Departments</h3>
+    <p>Filter by name: <input id="department_name"/></p>
+    <table id="department"
+        data-htsql="/department{code, name}
+                               ?school.code=$school
+                               &name~$department_name"
+        data-ref="school department_name"
+        data-hide-column-0="true">
+    </table>
+    <p>
+        The selected department:
+        <em data-htsql="/department{name}?code=$department"
+            data-ref="department"></em> <br/>
+        The number of courses in the selected department:
+        <strong
+            data-htsql="/department{count(course)}
+                                   ?code=$department"
+            data-ref="department"></strong>
+    </p>
+
+    <h3>Courses</h3>
+    <table id="course"
+        data-htsql="/course?department_code=$department"
+        data-ref="department">
+    </table>
+
+More sample dashboards are available at `HTSQL Gallery`_.
+
+.. _HTSQL Gallery: http://htsql.org/gallery/index.html
+
+********************
+  Widget Reference
+********************
+
+HTML elements controlled by HTRAF are called *HTRAF widgets*.  HTRAF
+recognizes widgets by presence of attribute ``data-htsql``.
+
+The type of the widget is determined by attribute ``data-widget``;
+if it is not set, the type is derived from the element tag.
+Conveniently, commonly used widget types are called ``select``,
+``table``, ``ul``, ``ol``, so often there is no need to specify the
+widget type explicitly.
+
+When the widget type is not recognized, the default type called
+*singleValue* is used.
+
+.. ifconfig:: build_website
+
+    .. demo::
+       :source:
+
+        <script type="text/javascript"
+            src="/htraf/htraf.js"
+            data-htsql-version="2"
+            data-htsql-prefix="/@demo">
+        </script>
+
+.. ifconfig:: not build_website
+
+    .. demo::
+       :source:
+
+        <script type="text/javascript"
+            src="../htraf/htraf.js"
+            data-htsql-version="2"
+            data-htsql-prefix="http://demo.htsql.org">
+        </script>
+
+
+Table Widget
+============
+
+Probably the most common widget in HTRAF, *table* renders data using
+HTML ``<table>`` element.
+
+Table rows are selectable; when selected, the widget emits the value
+from the first column.
+
+Example
+-------
+
+.. demo::
+   :source:
+
+    <table data-htsql="/school">
+    </table>
+
+Attributes
+----------
+
+`data-hide-column-0` (``true``)
+    Do not display the first output column.
+
+    Useful when the first column contains a value of the key that is
+    passed to dependent widgets, but should not be displayed in the
+    output.
+
+    .. demo::
+       :source:
+
+        <h3>Select a School</h3>
+        <table id="school_with_hidden_code"
+            data-htsql="/school{code, name}?exists(department)"
+            data-hide-column-0="true">
+        </table>
+
+        <h3>Associated Departments</h3>
+        <table
+            data-htsql="/department{name}
+                                   ?school.code=$school_with_hidden_code"
+            data-ref="school_with_hidden_code">
+        </table>
+
+    In this example, clicking on a row of the first widget passes the
+    code of the selected school to the second widget.
+
+CSS Classes
+-----------
+
+`rN` (*N* is integer starting from *0*)
+    Set on *N*-th row (``<tr>``) element of the widget.
+
+`cN` (*N* is integer starting from *0*)
+    Set on each *N*-th column (``<td>``) element of the widget.
+
+`even`, `odd`
+    Set on each even/odd row element.
+
+
+Select Widget
+=============
+
+The *select* widget presents data in the form of a drop-down menu using
+a ``<select>`` element.
+
+The HTSQL query associated with the widget should produce one or two
+columns.  When the output has two columns, they are used as the value
+and the label of each option respectively.  When the output has only one
+column, this column is used to populate both the option value and the
+option label.
+
+Example
+-------
+
+.. demo::
+   :source:
+
+    <select data-htsql="/school{code}">
+    </select>
+
+    <select data-htsql="/school{code, name}">
+    </select>
+
+Attributes
+----------
+
+`multiple`
+    The select widget admits multiple selections.  When more then one
+    choice is selected, the values are passed to the dependent widgets
+    using ``{...}`` list.
+
+    .. demo::
+       :source:
+
+        <select id="multiple_schools" size="4" multiple
+            data-htsql="/school{code, name}?exists(department)">
+        </select>
+
+        <table
+            data-htsql="/department{name}
+                                   ?school.code=$multiple_schools"
+            data-ref="multiple_schools">
+        </table>
+
+    In this example, you may select multiple rows in the school list;
+    the table below will show all associated departments.
+
+
+UL and OL Widgets
+=================
+
+The *ul* and *ol* widgets present data in a form of an unordered and
+ordered lists using ``<ul>`` and ``<ol>`` HTML elements.
+
+Just like the select widget, the ul and ol widgets accept input data
+with one or two columns.  When the input data contains two columns, the
+first column indicates the value emitted when an entry is selected and
+the second row specifies the entry content.
+
+Example
+-------
+
+.. demo::
+   :source:
+
+    <ul data-htsql="/school{code}?exists(department)">
+    </ul>
+
+    <ol data-htsql="/school{code, name}?exists(department)">
+    </ol>
+
+
+IFrame Widget
+=============
+
+The *iframe* widget embeds the response from the HTSQL service in a
+frame embedded in the page.  This widget displays the output as it is
+formatted by HTSQL.
+
+Example
+-------
+
+.. demo::
+   :source:
+
+    <iframe width="600" height="300"
+        data-htsql="/school{code, name}?exists(department)">
+    </iframe>
+
+
+Chart Widget
+============
+
+The *chart* widget presents data in a graphical form.  The first column
+of the output specifies the chart labels, the remaining columns specify
+the respective values.
+
+Since HTML does not have a ``<chart>`` element, you need to use a
+``<div>`` element and specify the widget type using ``data-widget``
+attribute.
+
+Example
+-------
+
+.. demo::
+   :source:
+
+    <div style="width: 700px; height: 350px"
+        data-widget="chart"
+        data-yint="true"
+        data-title="Number of Departments by School"
+        data-htsql="/school{code,
+                            num_dept := count(department)}
+                           ?num_dept>0">
+    </div>
+
+Chart Types
+-----------
+
+The widget provides several types of charts: bar chart, pie chart and
+line chart.  The chart type is specified using attribute ``data-type``:
+
+`bar` (*bar chart*)
+    To display a bar chart, the input data should contain two or more
+    columns: the first column contains the labels, the subsequent
+    columns are numeric values.  Each value is represented by the height
+    of a rectangular bar.
+
+`stacked` (*stacked bar chart*)
+    Same as the regular bar chart except that when the data contain two
+    or more value columns, the respective bars are stacked in a single
+    line.
+
+`pie` (*pie chart*)
+    For a pie chart, the input data should contain two columns: the
+    labels and respective numeric values.
+
+`line` (*line chart*)
+    To generate a line chart, the input data should contain two or more
+    columns: the first column contains (numeric or date) values for the
+    *X* axis, the rest contain numeric values for the *Y* axis.
+
+.. demo::
+   :source:
+
+    <div style="width: 345px; height: 325px; float: left"
+        data-widget="chart"
+        data-type="bar"
+        data-yint="true"
+        data-title="Bar Chart"
+        data-htsql="/school{code,
+                            num_dept := count(department),
+                            num_prog := count(program)}
+                           ?num_dept>2&num_prog>2">
+    </div>
+
+    <div style="width: 345px; height: 325px; float: left"
+        data-widget="chart"
+        data-type="stack"
+        data-yint="true"
+        data-title="Stacked Bar Chart"
+        data-htsql="/school{code,
+                            num_dept := count(department),
+                            num_prog := count(program)}
+                           ?num_dept>2&num_prog>2">
+    </div>
+
+
+    <div style="width: 345px; height: 325px; float: left; clear: both"
+        data-widget="chart"
+        data-type="pie"
+        data-yint="true"
+        data-title="Pie Chart"
+        data-htsql="/school{code,
+                            num_dept := count(department)}
+                           ?num_dept>2">
+    </div>
+
+    <div style="width: 345px; height: 325px; float: left"
+        data-widget="chart"
+        data-type="line"
+        data-yint="true"
+        data-title="Line Chart"
+        data-htsql="/(school^{num_dept := count(department)})
+                            {num_dept,
+                             num_school := count(school),
+                             num_prog := count(school.program)}">
+    </div>
+
+    <div style="clear: both"></div>
+
+Attributes
+----------
+
+`style`
+    Use CSS properties ``width`` and ``height`` to specify the size of
+    the chart.
+
+`data-type` (``bar`` (default), ``stack``, ``pie``, ``line``)
+    Indicates the chart type: *bar chart*, *stacked bar chart*, *pie
+    chart* or *line chart*.  Each chart type has specific requirements
+    for the input data.
+
+`data-legend` (``ne`` (default), ``se``, ``nw``, ``sw``, ``no``)
+    Position of the chart legend; ``no`` means no legend displayed.
+
+`data-title` (a string)
+    The chart title.
+
+`data-show-title` (``true`` (default) or ``false``)
+    Set to ``false`` to hide the chart title.
+
+`data-yint` (``true`` or ``false`` (default))
+    Set to force integer axis ticks.
+
+`data-x-vertical` (``true`` or ``false`` (default))
+    Set to swap *X* and *Y* axes.
+
+
+The Default Widget
+==================
+
+The default widget (called *singleValue*) is a fallback used when the
+actual widget type cannot be determined.  The widget replaces the
+content of the element with the value from the first row and the first
+column of the data source.
+
+Example
+-------
+
+.. demo::
+   :source:
+
+    <p>The database contains
+    <strong data-htsql="/count(school)"></strong>
+    records in the <em>school</em> table and
+    <strong data-htsql="/count(department)"></strong>
+    records in the <em>department</em> table.</p>
+
+
+Common Attributes
+=================
+
+In this section, we describe attributes that could be defined on any
+HTRAF widget:
+
+`id` (a unique identifier)
+    Indicates the name of the widget; must be unique across the whole
+    HTML page.  The name is used for declaring widget dependencies and
+    passing values between widgets.
+
+`data-htsql` (an HTSQL query)
+    HTSQL query executed to populate the widget.  This is a mandatory
+    attribute.
+
+`data-widget` (widget type: ``select``, ``table``, ``chart``, etc)
+    The type of the widget; when not present, HTRAF assumes it coincides
+    with the tag name.
+
+`data-ref` (space-separated list of parent widgets)
+    If set, indicates that the widget depends on selections on the given
+    parent widgets.  The selected values are passed to the HTSQL query
+    as references.
+
+`data-onchange` (Javascript)
+    Code to execute when the widget value changes.
+
+`data-onerror` (Javascript)
+    Code to execute when an HTSQL request produced an error.
+
+`data-empty` (Javascript)
+    Code to execute when an HTSQL request returned no rows.
+
+`data-onbeforeload` (Javascript)
+    Code to execute before making an HTSQL request.
+
+`data-onafterload` (Javascript)
+    Code to execute after the widget is rendered.
+
+In Javascript code, ``this`` refers to the DOM element of the widget.
+
+
+Adding New Widgets
+==================
+
+HTRAF provides an API for defining new widget types.  The API is based
+on `JQuery UI`_ framework; see JQuery UI documentation for details.
+
+.. _JQuery UI: http://jqueryui.com/
+
+In the following example, we create a widget called *DL* that uses HTML
+``<dl>`` element to create a definition list.  The widget requires data
+source with two columns: the first column populates the term and the
+second column populates the description of the term.
+
+.. demo::
+   :source:
+
+    <script type="text/javascript">
+        $.widget("htraf.dl", $.htraf.Base, {
+            render: function() {
+                var rows = this.data.data;
+                var element = this.element;
+                $.each(rows, function(i, row) {
+                    $("<dt/>").text(row[0]).appendTo(element);
+                    $("<dd/>").text(row[1]).appendTo(element);
+                });
+            }
+        });
+    </script>
+
+Here we create a new widget type ``htraf.dl`` using standard JQuery UI
+function ``$.widget()``.  The class ``$.htraf.Base`` is the base class
+for all HTRAF widgets; most subclasses need only to redefine method
+``render()`` which is called when the widget receives data from the data
+source and needs to render itself on the page.  In this method,
+``this.data`` refers to the output from the HTSQL request,
+``this.element`` is the widget element.
+
+Now, let's see how it works:
+
+.. demo::
+   :source:
+
+    <dl data-htsql="/school{code, name}?exists(department)"></dl>
+