The initial implementation is extremely simple (some would say simplistic), but it already provides a good starting point. With a good stylesheet, and accompanied syntax highlighting, this provides, in my opinion, a convincing proof of concept.
The example provided here shows the usage of the code, combined with the usage of bootstrap for formatting and highlight.js for syntax highlighting.
Playing Well With Standards
In order to use this in your file, simply reference the
css/LitJS.css files in your HTML file.
<pre> <code> tags:
<pre> <code> var power = 5; var upperBound = 355000; </code> </pre>
Combined with Highlight.JS this should also take care of syntax highlighting.
<code> tag, with an
The upper bound is <code class="inline">upperBound</code>
Upon loading the page, simply invoke the
LitJS.eval() function, this should take care of the rest.
See the attached example to get a better idea.
You can wrap a code block in a panel with a title simply by providing a title attribute to the
<pre title="Solution"> <code> ... </code> </pre>
This will result in a panel with a title, using the value of the
title attribute provided.
This method uses bootstrap classes to render the resulting HTML.
You can of course use any other valid HTML to produce the title directly. The example shows both methods.
When providing a title, you also have the option to designate the block as a collapsible block. If you do that, a small text "button" will appear near the title, allowing the user to collapse and expand the title at will. For example:
<pre title="Solution" collapsible> <code> ... </code> </pre>
As previously, you have the option to do it yourself, with different styles/characters.
You also have the option to start the block as collapsed, when the page is loaded. Simply replace 'collapsible' with 'collapsed', like so:
<pre title="Solution" collapsed> <code> ... </code> </pre>
And the annotated block will be collapsed when the page loads. Otherwise, the behavior is like 'collapsible'.
If an error is raised in one of the blocks, LiterateJS will raise an error, by default using
It will report the id of the code block. LiterateJS will provide a default id if none is provided by you.
For an example of this, refer to the error example.
Interactive Literate Blocks
Blocks can also reference values that are given by in-page input elements. For example, given an input element:
<input type=number id=y class="lit-value" />
Another code block in the same page can now reference
y as a variable, with the value given in the input.
var x = y + 2;
This is also bound to the inputs' change events, so code blocks will get re-evaluated, and inline code snippets will be updated. See the interactive example for a more complete example.
Also, tooltips, with the given variable name will be added to the inputs marked as lit-value. So the user may hover over specific inputs, and learn their variable names as they appear in code.
Ignoring Specific PRE CODE Element
As a rule, LitJS searches for
code elements within
pre elements, and evaluates them.
In case you want to have such an element, but not have it evaluated by LitJS, simply add the
litjs-ignore class to the
<pre class="litjs-ignore"> <code> ... </code> </pre>
This element will be simply ignored by LitJS - it won't be evaluated, nor any other treatment, e.g. adding headers, will be added to it.
Embedding Code Blocks
The code depends on JQuery. Other than that, the example uses Bootstrap and Highlight.JS, but the literate programming doesn't rely on that. Some examples use other libraries, the rights to those libraries the property of their respective owners, as designated by their respective licenses.
Markdown Support in LiterateJS
The functionality is available using a separate optional extension to LiterateJS - litjs-md. Using this extension allows one to write simple markup documents, with code blocks, and using these as regular text documents. See the extension's documentation for more details.
Literate JS documents can be used as live documents. Meaning: changing values in them, and reloading at a later time. Using the optional Auto Save extension, values can be saved in the browser's local storate (automatically), and reloaded when the page is loaded later, in the same browser.