The JsonWeb Module

Description

The JsonWeb module allows to create websites directly using json data. Using templates we can specify the structure of the website, and then JsonWeb automatically create a corresponding website with data extracted from json files.

Installation

This module has been built for portability and ease of use, so it is composed by a stand-alone Python program. All you need is to have Python 3 installed on your system, then you can just download the code and run it. The behavior of the module can be tuned by using some command options that are described below. Being a Python program, it is also easy to inspect the code, see how it works, and possibly modify it if you want so.

Quick Usage

Command line: jsonweb
The JsonWeb module can be directly launched without any parameters: if so, it will proceed by using default locations for the input, templates and output directories (see below).

Options

The JsonWeb behaviour can be modified via the following command line options (shorter or longer formats):


  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        the input json directory (default: google/results)
  -t TEMPLATES, --templates TEMPLATES
                        the templates directory (default: templates)
  -o OUTPUT, --output OUTPUT
                        the output web directory (default: website)
  -b BASE, --base BASE  base directory for relative directory paths (default: .)
  -l LEFT, --left LEFT  left delimiter of JsonWeb command activator (default: [[[)
  -r RIGHT, --right RIGHT
                        right delimiter of JsonWeb command activator (default: ]]])
  -a [ALLOWED [ALLOWED ...]], --allowed [ALLOWED [ALLOWED ...]]
                        allowed file extensions: files are processed (default: ['.html', '.htm'])
  -d [DISALLOWED [DISALLOWED ...]], --disallowed [DISALLOWED [DISALLOWED ...]]
                        disallowed file extensions: files are ignored (default: ['~'])
  -c, --copy            copy all other files (not in allowed+disallowed) (default: False)
  -g, --gzip            compress allowed output pages with gzip (adds .gz suffix) (default: False)

Some more information about the options:

-i, --input: This option allows to modify the location of the input app json files from the current default (the relative directory google/results). Note that the directory location can be absolute or relative.
-t, --templates: This option allows to modify the location of the directory containing the generator templates. The directory location can be absolute or relative.
-o, --output: This option allows to modify the location of the output directory, where the produced (html or other format) files are stored. Again, the directory location can be absolute or relative.
-b, --base: This option allows to modify the base directory that is used to eventually produce the absolute paths of the input and output directory. Note that this is effective only when the input or output directory is a relative path, otherwise it is ignored. The default base directory is the one containing the JsonWeb program.
-l, --left: This option allows to modify the left delimiter of the Json command activator. This can be helpful in case the chosen default sequence interferes with the language of the template.
-r, --right: Similarly, this option allows to modify the closing (right) delimiter. Note that the left and right delimiters, if so desired, can also be equal.
-a, --allowed: This option specifies the extension of the files to process. The default is for html files (prefixes .htm and .html) but any prefix can be specified, given that JsonWeb actually works on any textual format, not just html (for instance, you can automatically insert json data inside javascript files).
-d, --disallowed: Dually to the -a option, this option allows to specify (by extension) what files should never be processed. The default disallowed extension is ~. This option works also in combination with option -c, disabling copy. So, every file whose extension is specified by this option will never be copied to the output directoy.
-c, --copy: This option specifies that all the remaining source files (neither allowed nor disallowed) should be directly copied to the output directory. This is helpful, for instance, for static files that do not contain JsonWeb commands (like static css files, images and so on) that are also needed in the generated output. So, this allows to test a site directly using the templates in the input directory, and also to then recreate a fully operative site in the output directory.
-g, --gzip: This option compresses every produced files in the output directory, so to save space (this is useful for web servers that support compressed file sources).

Note that JsonWeb, when generating the output files and copying, also automatically replicates the directory structure present in the templates. Thus, this allows for complete nested structures to be generated, not only flat lists of pages.

Details

As said, JsonWeb generates a web site using templates and json data. The templates are constituted by the pages of the web site, with the added condition that they can contain special JsonWeb commands that are processed and that produce corresponding pages with values extracted from the json data. The commands are contained within the delimiters [[[ and ]]] (that can also be changed via the appropriate command line option, so not to interfere with the language of the page). In order to extact data, we use json paths, that is to say key values that are dot-separated (so, for example, using the Mobosearch App Interchange Format writing "app.developer.name" corresponds to enter the json with key "app", then with key "developer", and finally extracting the value corresponding to the key "name").

The basic JsonWeb commands are three, defined as follows:

The Context Command: This command specifies the context from where to extract the json data. The format is [[[context:path]]], where path is the json path corresponding to the data to consider. For instance, if we have data in the MoboSearch app interchange format and we want to tell JsonWeb that the data to extract must come from all the app data structures therein, we can use [[[context:app]]]: this is telling JsonWeb to process the json files and to consider the json substructures within the app key.
The Filename Command: This command sets the name of the generated output file. For instance, using Mobosearch data with a [[[context:app]]] as described above, inserting [[[filename:id]]] tells the JsonWeb generator to produce a file that has as name the json value of app.id (the store id of the app).
The Path Command: This command is activated by simply writing a json path: [[[path]]]. This tells the JsonWeb generator to use the json value corresponding to the specific path (always within the specified context). Going on with the example before, writing [[[name]]] (within a context [[[context:app]]]) tells JsonWeb to insert the json value corresponding to the app.name path, that is to say the name of the app.

So, for example, if we were using json app data in AIF format we could have in the template the following web page describing an app:

<!DOCTYPE html>
<html>
<body>
[[[context:app]]][[[filename:id]]]
<script>
  <!-- as an example, here we also insert the raw json into a variable mydata, that can be used by the js -->
 mydata=[[[.]]]
 (other js code...)
</script>
<h1>The App: [[[name]]]</h1>
<p>Here you can find the info for the app <q>[[[name]]]</q>.</p>
 <p>First of all, the number of total reviews for this app is: <strong>[[[reviews.total]]]</strong>.</p>
 (other html code...)
</body>

This single page template would then, via JsonWeb, automatically generate description pages for all the apps.

The Code

The source code of the module can be directly downloaded here (note that at public launch we will also provide a GitHub link).