What is this ?

The preview server watches Stog files and recomputes the documents when there is a change. This is useful to have a preview as you modify your web site or article.

Have a look at stog server in action on a video here.

How does it work ?

When launched, the server computes the documents a first time. It then handles HTTP connections. All documents are accessed under the path /preview/. For example, the /foo/bar.html document will be browsed, by default, at address http://localhost:8080/preview/foo/bar.html.

When a browser queries a document preview, the server returns a simple page with some javascript code to load. This javascript code opens a websocket connection, by default to http://localhost:8081, and queries the document. The server sends the whole document preview and the javascript code fills the DOM with the document.

When a source file is modified, the server recomputes the corresponding documents and sends a patch to the browser, through the websocket connection. The javascript code applies the patch to the DOM.

Applying patches rather than reloading the whole document is better when some parts of the document are changed by some other code (I'm looking at you, Mathjax). By now, this case is not fully handled yet, but this is work in progress. The javascript part of the Xmldiff library allows to specify some nodes to ignore when applying a patch.

By now, only documents which exist when the server is launched are watched for changes. This means that if you add a new document source file, you have to click on the ↺ button at the top of the preview page.

Usage

To run the server, simply run stog-server[.byte] instead of stog[.byte], with the same parameters.

You can use mk-stog[.byte] to create your own server. To do so, just use --package stog.server in addition to other packages.

The --http and --ws command line options can be used to specify a url defining the host and port to listen on, for the HTTP and websocket servers respectively. Defaults are http://localhost:8080 and ws://localhost:8081.

If the server must be run behind a proxy, you must also give the --pub-http and --pub-ws options to indicate the "public" base urls, i.e. the ones that the proxy will handle to send queries to the server.

For information you can see the source code of the page.

<page title="Preview server"
with-contents="true"
navbar-doc="active"
>
<contents>
<toc/>
<section id="whatis" title="What is this ?">
<p>
The preview server watches Stog files and recomputes
the documents when there is a change. This is useful to have
a preview as you modify your web site or article.
</p>
<p>Have a look at stog server in action on a video
<doc href="2014-10-27-video.html">here</doc>.
</p>
</section>

<section id="how" title="How does it work ?">
<p>
When launched, the server computes the documents a first time.
It then handles HTTP connections. All documents are accessed
under the path <icode>/preview/</icode>. For example, the <icode>/foo/bar.html</icode>
document will be browsed, by default, at address
<icode>http://localhost:8080/preview/foo/bar.html</icode>.
</p>
<p>
When a browser queries a document preview, the server returns
a simple page with some javascript code to load. This javascript code
opens a websocket connection, by default to <icode>http://localhost:8081</icode>,
and queries the document. The server sends the whole document preview and
the javascript code fills the DOM with the document.
</p>
<p>
When a source file is modified, the server recomputes
the corresponding documents and sends a patch to the browser,
through the websocket connection.
The javascript code applies the patch to the DOM.
</p>
<p>
Applying patches rather than reloading the whole document is better
when some parts of the document are changed by some other code
(I'm looking at you, Mathjax). By now, this case is not fully handled yet,
but this is work in progress. The javascript part of
the <ext-a href="http://zoggy.github.io/xmldiff">Xmldiff</ext-a>
library allows to specify some nodes to ignore when applying a patch.
</p>
<p class="alert alert-warning">
By now, only documents which exist when the server is launched are
watched for changes. This means that if you add a new document source file,
you have to click on the ↺ button at the top of the preview page.
</p>
</section>

<section id="usage" title="Usage">
<p>
To run the server, simply run <icode>stog-server[.byte]</icode> instead of
<icode>stog[.byte]</icode>, with the same parameters.
</p>
<p>
You can use <icode>mk-stog[.byte]</icode> to create your own server. To do
so, just use <icode>--package stog.server</icode> in addition to other packages.
</p>
<p>
The <icode>--http</icode> and <icode>--ws</icode> command line options can be
used to specify a url defining the host and port to listen on, for the HTTP
and websocket servers respectively. Defaults are <icode>http://localhost:8080</icode>
and <icode>ws://localhost:8081</icode>.
</p>
<p>If the server must be run behind a proxy, you must also give the
<icode>--pub-http</icode> and <icode>--pub-ws</icode> options to indicate
the "public" base urls, i.e. the ones that the proxy will handle to send
queries to the server.
</p>
</section>

</contents>
</page>