<div class="notebook">

<div class="nb-cell markdown">
# Result rendering

SWISH allows for _rendering_ a Prolog answer in a domain specific way.  This
can be compared to the Prolog _hook_ portray/1, although it currently only applies to the answer as a whole and *not* recursively on terms embedded in an answer.  A renderer is selected using use_rendering/1 or use_rendering/2,
for example:
</div>

<div class="nb-cell program">
:- use_rendering(table).
</div>

<div class="nb-cell markdown">
The [table renderer](example/render_table.swinb) recognises a table and renders it as an HTML table.  Press the _play_ button to run the simple example below.
</div>

<div class="nb-cell query">
X = [ [ 'Amsterdam', 'The Netherlands' ],
      [ 'London', 'United Kingdom' ],
      [ 'Paris', 'France' ]
    ].
</div>

<div class="nb-cell markdown">
## Provided renderers

The following rendering plugins are currently supported.  Please visit the linked notebook for more documentation and examples exploiting these renderers.

  - General purpose renderers
    - [table](example/render_table.swinb) renders tables
    - [svgtree](example/render_svgtree.swinb) renders Prolog terms as trees
    - [graphviz](example/render_graphviz.swinb) render graphs using
      [Graphviz](http://www.graphviz.org/).
    - [c3](example/render_c3.swinb) renders =c3= dicts as charts (line, bar, pie
      etc.) using [C3.js](http://www.c3js.org)
    - [codes](example/render_codes.swinb) renders lists of code-points as text.
  - Domain specific renderers
    - [bdd](example/render_bdd.swinb) renders CLP(B) residual goals as Binary Decision Diagrams (BDDs)
    - [chess](example/render_chess.swinb) renders chess positions (currently only
      N-queen boards).
    - [sudoku](example/render_sudoku.swinb) renders sudoku puzzles.
</div>

<div class="nb-cell markdown">
## Adding a new render plugin

The rendering infrastructure is specialized using a series of _plugins_ provided as Prolog libraries in the directory =lib/render= of the SWISH sources.  A render plugin is a _module_ that performs these steps:

  1. Registering the renderer using register_renderer/2
  2. Define a rule for term_rendering//3, which
     - Identifies the Prolog term as suitable for the plugin.  For
       example, a _table_ renderer requires a datastructure that can be
       interpreted as a table.
     - Define the translation to an HTML fragment using
       library(http/html_write).  The HTML fragment can include _style_
       and (JavaScript) scripts.

### Embedded JavaScript

Embedded JavaScript is executed explicitly after the provided HTML DOM node has been added to the document.  The infrastructure sets =|$.ajaxScript|= to a `jQuery` object that refers to the script element.  This can be used to find the inserted DOM node without generating an `id` attribute.  The typical
JavaScript skeleton that avoids poluting the namespace and ensures executing if the node is properly embedded is given below.

```
(function() {
  if ( $.ajaxScript ) {
  // do the work
  }
})();
```

SWISH uses [RequireJS](http://requirejs.org/) for dependency tracking.  This functionality can be exploited to load JavaScript only once.  For example, the [svgtree](example/render_svgtree.swinb) uses this fragment.

```
  require(["render/svg-tree-drawer", "jquery"], function(svgtree) {
  // setup the tree
  });
```

The RequireJS paths `c3` and `d3` are preconfigured to load [D3.js](http://www.d3js.org) and [C3.js](http://www.c3js.org)
</div>

</div>