nunja

A minimum framework for building reuseable templates for consumption by Python backends and JavaScript frontends.

Features

nunja is a framework that offers developers a way to build templates in Jinja that can be easily used from within Python and from the web browser using JavaScript for the frontend user facing UI components. This is achieved by making use of Jinja2 templates that can be rendered using Jinja2 for the Python side, and the Nunjucks JavaScript package for the rendering on the client side.

The package leverages upon the calmjs framework for the management of access to Jinja templates with associated JavaScript front-end libraries embedded inside Python packages.

Installation

Currently under development; to begin, please clone this repository first.

Requirements

As this package interoperates with a number of software libraries, a number of prerequisites are required for all the features to function correctly. At the minimum, Python 2.7 or 3.3+ must be available; for the JavaScript/Node.js integration side, Node.js v4 or higher is highly recommended, though testing shows that the core parts should run even under Node.js v0.10. However, the goal is to also make Node.js optional for users of downstream libraries if they include the generated JavaScript artifacts. Tools to make this easy to do so will need to be done for nunja. For the web browser, only modern web browsers are supported, please refer to the continuous integration configurations (in brief: Firefox 31, Chrome 40, IE 11, Safari 9; alternatively, run the tests against a target browser, if the tests passes it should work).

Before the installation, please have calmjs installed first so that when python setup.py develop is executed at the root of this package's repository, the appropriate metadata files defined by the Calmjs framework will also be installed. Failing that, calmjs should also be installed automatically through setuptools, however the egg- info metadata will need to be regenerated by running python setup.py egg_info.

Usage

A tutorial will need to be made.

Guidelines will be added as the system is formalized, and they follow:

• Similar to the standard calmjs system, with the difference being the molds system is optimised for the AMD framework as implemented by require.js, and so the option to build packages as AMD modules is permitted, though the standard CommonJS structure should work.

Shared templates

These are exposed through the nunja.molds registry as a complete set that includes client side scripts.

Server-side only templates

These are exposed through the nunja.tmpl registry, and is intended for templates that generate the skeletal markup from which the molds may be nested.

A more formal set of keywords may be developed in the future to better facilitate the above process.

Currently, declaring templates under this registry will be useful for providing static templates across Python package boundaries.

Deployment

Generally, this involves building a standalone static requirejs AMD artifact file which is then sent to the browsers used by the end-users to be used in conjunction with the packages that provide the molds. Such an artifact that has none of the default nunja.molds that are provided as examples should be generated like so through this invocation of the calmjs command:

$ calmjs rjs --source-registry=calmjs.module nunja

The above command will produce a nunja.js in the current directory that can be included in a <script> tag with the other AMD artifacts that may contain the actual molds.

If one wishes to generate a complete artifact, and assuming the package to be deployed also lists nunja as a Python dependency (here nunja is simply used as an example), the following command can be invoked:

$ calmjs rjs nunja

This will simply build the same thing but the raw template strings will be included as is. If they are to be compiled into JavaScript code, the optional advice should be applied like so:

$ calmjs rjs nunja --optional-advice=nunja

Alternatively, the nunjucks slim library can be bundled instead, which will decrease the size of the final output, but the ability for dynamic template compilation will be disabled on the client side.

$ calmjs rjs nunja --optional-advice=nunja[slim]

Troubleshooting

Using --bundle-map-method=empty with the rjs tool will result in this error message

$ calmjs rjs nunja --bundle-map-method=empty

Tracing dependencies for: /tmp/nunja/nunja.testing.js
Error: TypeError: Cannot read property 'normalize' of undefined
    at Object.<anonymous> (/tmp/nunja/node_modules/requirejs/bin/r.js:1221:35)

This is caused by the provided templates done through the text plugin which is not being provided. To work around this, either ensure the templates registries are NOT provided, or apply the optional advice nunja[slim] to precompile the template and not include the raw source template strings. Alternatively, if the text module is to be made available through a different artifact bundle for a given deployment, the --empty flag may be employed to stub out the missing modules completely, i.e.:

$ calmjs rjs --empty nunja --bundle-map-method=empty

Contribute

• Issue Tracker: https://github.com/calmjs/nunja/issues
• Source Code: https://github.com/calmjs/nunja

Legal

The nunja package is part of the calmjs project.

The calmjs project is copyright (c) 2016 Auckland Bioengineering Institute, University of Auckland. nunja is licensed under the terms of the GPLv2 or later.