==================
Javascript helpers
==================

The javascript module has some helpers which can be used to easily get
the Javascript files from the active plugins.

Concatinated
============

With the concatinated function you can get the a single string
containing all the Javascript from each active plugin.

  >>> from kss.base.javascript import concatinated

When we run the code without activating any plugin we will get an
empty string.

  >>> concatinated()
  ''

Now if we run the code again after we activate a plugin we get
something more interesting.

  >>> from kss.base import load_plugins
  >>> load_plugins('kss-core')
  >>> concatinated()
  '/*\n* Copyright (c) 2005-2007\n* Authors: KSS Project Contributors...'

An optimization you might want to enable is concatinate the extra
dependencies along side with the plugin code. This will reduce the
number of requests a browser has to make to a website therefore making
it slightly faster (only for the first page load).

  >>> 'XPathParser' in concatinated(include_extras=True)
  True

This example was not there in the previous concatination.

  >>> 'XPathParser' in concatinated()
  False

Finally we will unregister the core plugin to clean up.

  >>> from kss.base.plugin import unload_plugins
  >>> unload_plugins('kss-core')


Packed
======

The kss.base package ships with a Javascript packer. This can reduce
the filesize of the Javascript. It will also do the concatination of
all registered plugin code.

  >>> from kss.base.javascript import packed

Like with the concatination we will get an empty string if we just run
it.

  >>> packed()
  ''

So now we activate a plugin.

  >>> load_plugins('kss-core')

By default the packed function does no packing.

  >>> no_compression = packed()
  >>> no_compression
  '/*\n* Copyright (c) 2005-2007\n* Authors: KSS Project Contributors...'

To enable compression we need to pass in a a compression level. There
are a few available options of which only `safe` is currently usable.

  >>> with_compression = packed(compression_level='safe')

Packing with `safe` should still give us smaller file sizes than with
no compression at all.

  >>> len(with_compression) < len(no_compression)
  True

We will again unregister the core plugin to clean up.

  >>> from kss.base.plugin import unload_plugins
  >>> unload_plugins('kss-core')


Extra scripts
=============

All registered extra scripts are available using one convenience
function. You can use this to get the names as well as the file data
belonging to each script.

  >>> from kss.base.javascript import extra_scripts

By default we get an empty dictionary.

  >>> extra_scripts()
  {}

If we activate a plugin we get something more interesting.

  >>> load_plugins('kss-core')
  >>> extra_scripts()
  {...'base2...js': ...}

This dictionary contains the base names of all the registered
Javascripts with their file contents as the value.

Now we can cleanup the registry again.

  >>> from kss.base.plugin import unload_plugins
  >>> unload_plugins('kss-core')
