Metadata-Version: 2.0
Name: django-systemjs
Version: 1.1.2
Summary: Brings SystemJS to Django staticfiles
Home-page: https://github.com/sergei-maertens/django-systemjs
Author: Sergei Maertens
Author-email: sergeimaertens@gmail.com
License: MIT
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django :: 1.8
Classifier: Framework :: Django :: 1.9
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
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: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Dist: django-appconf (>=0.6)
Requires-Dist: semantic-version
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: mock; extra == 'test'

Django SystemJS
=====================

.. image:: https://travis-ci.org/sergei-maertens/django-systemjs.svg?branch=master
    :target: https://travis-ci.org/sergei-maertens/django-systemjs


.. image:: https://coveralls.io/repos/sergei-maertens/django-systemjs/badge.svg
  :target: https://coveralls.io/r/sergei-maertens/django-systemjs

.. image:: https://img.shields.io/pypi/v/django-systemjs.svg
  :target: https://pypi.python.org/pypi/django-systemjs


Django SystemJS brings the Javascript of tomorrow to Django, today.

It leverages JSPM (https://jspm.io) to do the heavy lifting for your
client side code, while keeping development flow easy and deployment
without worries. In DEBUG mode, your Javascript modules are loaded
asynchronously. In production, your app is nicely bundled via JSPM
and ties in perfectly with `django.contrib.staticfiles`.


Installation
------------
You will need to add 'systemjs' to your `INSTALLED_APPS` to be able
to use the templatetag and management command.

JSPM has to be installed and configured correctly - you will need npm for
that. Refer to the JSPM installation documentation.

Some notable configuation options:

* set the base url to your `STATIC_URL`.
* set the base path to your `STATIC_ROOT`.

Usage
-----

Template tag
************

Usually, in your template you would write something like::

    <script src="/path/to/system.js"></script>
    <script src="/path/to/config.js"></script>
    <script>System.import('my/awesome/app');</script>

With Django SystemJS you can replace this with::

    {% load system_tags %}
    <script src="/path/to/system.js"></script>
    <script src="/path/to/config.js"></script>
    {% systemjs_import 'my/awesome/app' %}


If ``SYSTEMJS_ENABLED`` is ``False`` (default value is `not DEBUG`),
the tag will output the previous ``System.import`` statement. Otherwise,
it will output something like::

    <script src="/static/SYSTEMJS/my/awesome/app.js"></script>

This url is generated by the configured static files backend, so if you
use the ``CachedStaticFilesStorage``, all will be well. Django-storages is
untested, if you run into any issues, raise an issue and support will probably
be added.

.. note::

    Added in version 1.1

    If you want to use ``django.contrib.staticfiles.storage.ManifestStaticFilesStorage``,
    you need to use the systemjs-version:
    ``systemjs.storage.SystemJSManifestStaticFilesStorage``. This storage ensures
    that during bundling the collected staticfiles (from ``collectstatic``)
    aren't removed from the manifest file.


Management command
******************

Django SystemJS comes with a management command to create all the
bundles. It does so by checking all your template files and
extracting the ``{% systemjs_import '...' %}`` template tags.::

    python manage.py systemjs_bundle


By default it will look at all templates in your app directories, and
additionally the additional template dirs for the vanilla Django
template engine.

.. note::

    The default bundling mechanism changed in 0.2. Before 0.2, all bundles would
    by default be created as self-executing (``jspm bundle-sfx <app>``). This
    was changed to the default ``jspm bundle <app>`` command. Self-executing
    bundles include the entire SystemJS library and your ``config.js``, leading
    to 1MB+ bundle files. This is painful if you have multiple bundles.

    A better strategy is to leverage the JSPM CDN (see jspm docs), and then
    don't forget to include your ``config.js`` (which you would probably do in
    development mode anyway).

    Self-executing bundles can still be generated with the ``--sfx`` management
    command option::

        python manage.py systemjs_bundle --sfx


Example workflow
----------------
Django SystemJS is designed as a non-intrusive library in development mode,
so that it won't sit in your way too much. Simply using the template tag
will be all you have to do as long as you're running with `DEBUG=True`.

Assuming nothing is installed, what follows is an example step-by-step
to deploy your application.

Install npm dependencies from package.json. This should pull in `jspm`::

    npm install

Install ``jspm`` dependencies from package.json::

    jspm install

Run collectstatic so all files can be found by the webserver. This
must be done before you run `systemjs_bundle`, because (with the
proposed ``config.js``) jspm will look for the modules in ``STATIC_ROOT``.::

    python manage.py collectstatic --link --noinput

(Re)generate the bundles::

    python manage.py systemjs_bundle

That's it! It should work!

Available settings
------------------

``SYSTEMJS_ENABLED``: defaults to ``not settings.DEBUG``. If disabled, the loading
of modules will happen in the 'standard' jspm way.

``SYSTEMJS_JSPM_EXECUTABLE``: path to the ``jspm-cli`` executable. Defaults to
``jspm``, which should be available if installed globally with ``npm``.

``SYSTEMJS_OUTPUT_DIR``: name of the subdirectory within ``settings.STATIC_ROOT``.
Bundled files will end up in this directory, and this is the place the
templatetag will point static files to.

Contact
-------
If you run into any issues, miss certain features or want to contribute,
the central point is the github repo: https://github.com/sergei-maertens/django-systemjs


