tgext.coffeescript 0.3.1
CoffeeScript middleware for TurboGears2
License: MIT
Keywords: turbogears2.extension CoffeeScript WSGI jinja2.extension

About tgext.coffeescript
------------------------------

`CoffeeScript <http://coffeescript.org/>`_ is a little language that compiles to JavaScript. Underneath all those
awkward braces and semicolons, JavaScript has always had a gorgeous object model at its heart.
`CoffeeScript <http://coffeescript.org/>`_ is an attempt to expose the good parts of JavaScript in a simple way.

`tgext.coffeescript <https://bitbucket.org/_amol_/tgext.coffeescript>`_ is a middleware aimed at making
`TurboGears2 <http://www.turbogears.org>`_ development easier, tgext.coffeescript converts regular coffee
files to javascript using the official CoffeeScript compiler.

tgext.coffeescript is based on `tgext.scss <https://bitbucket.org/_amol_/tgext.scss>`_ by Alessandro Molina and is
under the same license (MIT).

Installing
-------------------------------

tgext.coffeescript can be installed both from pypi or from bitbucket::

    easy_install tgext.coffeescript

You will also need to install the CoffeeScript compiler, for instructions on this check their website.

`CoffeeScript <http://coffeescript.org/>`_


Enabling tgext.coffeescript
----------------------------------

Using tgext.coffeescript is really simple, you edit your `config/middeware.py` and just after
the `#Wrap your base TurboGears 2 application with custom middleware here` comment wrap
`app` with `CoffeeScriptMiddleware`::

    from tgext.coffeescript import CoffeeScriptMiddleware

    make_base_app = base_config.setup_tg_wsgi_app(load_environment)

    def make_app(global_conf, full_stack=True, **app_conf):
        app = make_base_app(global_conf, full_stack=True, **app_conf)

        # Wrap your base TurboGears 2 application with custom middleware here
        app = CoffeeScriptMiddleware(app)

        return app

Now you just have to put your .coffee files inside *public/javascript* and they will be served as JavaScript.


JavaScript Compression
----------------------------------

tgext.coffeescript supports javascript output minification via slimit or jsmin as a fallback, this function is
disabled by default and can be enabled by passing the parameter minify=True on the constructor::

    app = CoffeeScriptMiddleware(app, minify=True)


Cache Backends
----------------------------------

You can change the cache backend storage into any dict like object that can serialize a dict object,
for example, you can use beaker cache by passing the cache object to the middleware constructor::

    from tgext.coffeescript import CoffeeScriptMiddleware
    from tg import cache

    make_base_app = base_config.setup_tg_wsgi_app(load_environment)
    
    def make_app(global_conf, full_stack=True, **app_conf):
        app = make_base_app(global_conf, full_stack=True, **app_conf)
        
        # CoffeeScript with beaker cache backend
        app = CoffeeScriptMiddleware(app, cache=cache)

        return app


Compiler options
----------------------------------

Currently tgext.coffeescript turns the --bare compiler option by default, this means that the resulting javascript
output will not be wrapper under a top-level function, if you want to reverse this behaviour you can tell the
middleware to disable it::

    app = CoffeeScriptMiddleware(app, bare=False)

This will disable the bare options for all files served with tgext.coffeescript, more granular control of this option
may be available later depending on the need for it.


Jinja2 Extension
----------------------------------

tgext.coffeescript provides an extension for jinja2 templates to compile CoffeeScript embedded directly on your
templates. To activate it just add to your config/app_config.py file the following::

    from tgext.coffeescript.jinja import CoffeeExtension

    base_config.jinja_extensions = [CoffeeExtension]

Now you can use the coffee tag in your templates::

    <style type="text/javascript">
    {% coffee "main" %}
        console.log state for state in ['open', 'close', 'full']
    {% endless %}
    </style>

Where "main" is a unique identifier for that CoffeeScript section, this should output nicely as::

    <style type="text/javascript">
    var state, _i, _len, _ref;

    _ref = ['open', 'close', 'full'];
    for (_i = 0, _len = _ref.length; _i < _len; _i++) {
      state = _ref[_i];
      console.log(state);
    }
    </style>