Metadata-Version: 2.1
Name: nunja
Version: 0.1.0
Summary: The unified templating framework for Python x JavaScript
Home-page: https://github.com/calmjs/nunja
Author: Tommy Yu
Author-email: tommy.yu@auckland.ac.nz
License: GPL
Description: nunja
        =====
        
        A minimum framework for building reuseable templates for consumption by
        Python backends and JavaScript frontends.
        
        .. image:: https://travis-ci.org/calmjs/nunja.svg?branch=0.1.0
            :target: https://travis-ci.org/calmjs/nunja
        .. image:: https://ci.appveyor.com/api/projects/status/mfg7t8y4anh5futf/branch/0.1.0?svg=true
            :target: https://ci.appveyor.com/project/metatoaster/nunja/branch/0.1.0
        .. image:: https://coveralls.io/repos/github/calmjs/nunja/badge.svg?branch=0.1.0
            :target: https://coveralls.io/github/calmjs/nunja?branch=0.1.0
        
        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.
        
        .. _Jinja2: http://jinja.pocoo.org/
        .. _Nunjucks: http://mozilla.github.io/nunjucks/
        .. |calmjs| replace:: ``calmjs``
        .. |nunja| replace:: ``nunja``
        .. _calmjs: https://pypi.python.org/pypi/calmjs
        
        
        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:
        
        .. code:: sh
        
            $ 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:
        
        .. code:: sh
        
            $ 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:
        
        .. code:: sh
        
            $ 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.
        
        .. code:: sh
        
            $ calmjs rjs nunja --optional-advice=nunja[slim]
        
        
        Troubleshooting
        ---------------
        
        Using ``--bundle-map-method=empty`` with the ``rjs`` tool will result in
        this error message
        
        .. code:: sh
        
            $ 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.:
        
        .. code:: sh
        
            $ 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.
        
        Changelog
        =========
        
        0.1.0 (2020-09-18)
        ------------------
        
        - Initial release.
        - Provide a base registry for Python-only jinja template registry
        - Provide a base registry for nunjucks/jinja compatible template
          registry.
        - A basic rendering system for the artifacts captured by the above base
          registries.
        
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Python: >=2.7,!=3.0.*,!=3.1.*,!=3.2.*
Provides-Extra: dev
Provides-Extra: webpack
Provides-Extra: rjs
