htraf-packaging / doc / index.rst

HTRAF Reference

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 based upon JQuery Javascript framework and relies on an HTSQL service to retrieve data from the database.

HTRAF is written by Oleksiy Golovko and Owen McGettrick and released under the same licenses as JQuery.

Overview

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.

(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:

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:

HTRAF renders this output into the following HTML code:

<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:

For more information on HTSQL syntax and semantics, see HTSQL Tutorial; 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 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.

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.

In addition to regular <script> attributes, we added two extra 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.

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. (HTSQL 1 is used for in-house projects of Prometheus Research.)

Widgets

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:

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:

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.

In this case, the query

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:

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

Attributes

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:

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

The select widget presents data in the form of a drop-down menu using a <select> element.

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.

Example

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:

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

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

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

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.

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 Chart

For a pie chart, the input data should contain two columns: the labels and respective numeric values.

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.

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

Common Attributes

data-htsql

data-widget

data-onchange

data-onerror

data-empty

data-onbeforeload

data-onafterload

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.