<commit_before>.. _ref-configuration:

=============
Configuration
=============


Configuration and list of available settings for Pipeline


Specifying files
================

You specify groups of files to be compressed in your settings. You can use glob 
syntax to select multiples files.

The basic syntax for specifying CSS/JavaScript groups files is ::

  PIPELINE_CSS = {
      'colors': {
          'source_filenames': (
            'css/core.css',
            'css/colors/*.css',
            'css/layers.css'
          ),
          'output_filename': 'css/colors.css',
          'extra_context': {
              'media': 'screen,projection',
          },
      },
  }

  PIPELINE_JS = {
      'stats': {
          'source_filenames': (
            'js/jquery.js',
            'js/d3.js',
            'js/collections/*.js',
            'js/application.js',
          ),
          'output_filename': 'js/stats.js',
      }
  }

Group options
-------------

``source_filenames``
....................

  **Required**
  
  Is a tuple with the source files to be compressed.
  The files are concatenated in the order specified in the tuple.
  

``output_filename``
...................
 
  **Required**
 
  Is the filename of the (to be) compressed file.

``variant``
...........

  **Optional**
  
  Is the variant you want to apply to your CSS. This allow you to embed images
  and fonts in CSS with data-URI.
  Allowed values are : ``None`` and ``datauri``.
  
  Defaults to ``None``.

``template_name``
.................

  **Optional**
  
  Name of the template used to render ``<script>`` for js package or ``<link>`` for css package.
  
  Defaults to ``None``.

``extra_context``
.................

  **Optional**
  
  Is a dictionary of values to add to the template context,
  when generating the HTML for the HTML-tags with the templatetags.
  
  For CSS, if you do not specify ``extra_context``/``media``, the default media in
  the ``<link>`` output will be ``media="all"``.

``manifest``
............

  **Optional**

  Indicate if you want this group to appear in your cache manifest.

  Defaults to ``True``.


Other settings
--------------

``PIPELINE``
............

  When ``PIPELINE`` is ``True``, CSS and JavaScripts will be concatenated and filtered.
  When ``False``, the source-files will be used instead.

  Defaults to ``not DEBUG`` (compressed files will only be used when ``DEBUG`` is ``False``).

``PIPELINE_CSS_COMPRESSOR``
............................

  Compressor class to be applied to CSS files.

  If empty or ``None``, CSS files won't be compressed.
  
  Defaults to ``'pipeline.compressors.yui.YUICompressor'``.

``PIPELINE_JS_COMPRESSOR``
...........................

  Compressor class to be applied to JavaScript files.

  If empty or ``None``, JavaScript files won't be compressed.
  
  Defaults to ``'pipeline.compressors.yui.YUICompressor'``

.. note::

  Please note that in order to use YUI Compressor, you need to install YUI Compressor (see :doc:`installation` for more details).

``PIPELINE_TEMPLATE_NAMESPACE``
...............................

  Object name where all of your compiled templates will be added, from within your browser.
  To access them with your own JavaScript namespace, change it to the object of your choice.

  Defaults to ``"window.JST"``


``PIPELINE_TEMPLATE_EXT``
.........................

  The extension for which Pipeline will consider the file as a Javascript template.
  To use a different extension, like ``.mustache``, set this settings to ``.mustache``.

  Defaults to ``".jst"``

``PIPELINE_TEMPLATE_FUNC``
..........................

  JavaScript function that compiles your JavaScript templates.
  Pipeline doesn't bundle a javascript template library, but the default
  setting is to use the
  `underscore <http://documentcloud.github.com/underscore/>`_ template function.
  
  Defaults to ``"_.template"``


Embedding fonts and images
==========================

You can embed fonts and images directly in your compiled css, using Data-URI in 
modern browsers. 

To do so, setup variant group options to the method you wish to use : ::

  PIPELINE_CSS = {
      'master': {
          'source_filenames': (
            'css/core.css',
            'css/button/*.css',
          ),
          'output_filename': 'css/master.css',
          'variant': 'datauri',
      },
  }

Images and fonts are embedded following these rules :

- If asset is under **32 kilobytes** to avoid rendering delay or not rendering
  at all in Internet Explorer 8.
- If asset path contains a directory named "**embed**".
<commit_msg>updated docs with new settings<commit_after>.. _ref-configuration:

=============
Configuration
=============


Configuration and list of available settings for Pipeline


Specifying files
================

You specify groups of files to be compressed in your settings. You can use glob 
syntax to select multiples files.

The basic syntax for specifying CSS/JavaScript groups files is ::

  PIPELINE_CSS = {
      'colors': {
          'source_filenames': (
            'css/core.css',
            'css/colors/*.css',
            'css/layers.css'
          ),
          'output_filename': 'css/colors.css',
          'extra_context': {
              'media': 'screen,projection',
          },
      },
  }

  PIPELINE_JS = {
      'stats': {
          'source_filenames': (
            'js/jquery.js',
            'js/d3.js',
            'js/collections/*.js',
            'js/application.js',
          ),
          'output_filename': 'js/stats.js',
      }
  }

Group options
-------------

``source_filenames``
....................

  **Required**
  
  Is a tuple with the source files to be compressed.
  The files are concatenated in the order specified in the tuple.
  

``output_filename``
...................
 
  **Required**
 
  Is the filename of the (to be) compressed file.

``variant``
...........

  **Optional**
  
  Is the variant you want to apply to your CSS. This allow you to embed images
  and fonts in CSS with data-URI.
  Allowed values are : ``None`` and ``datauri``.
  
  Defaults to ``None``.

``template_name``
.................

  **Optional**
  
  Name of the template used to render ``<script>`` for js package or ``<link>`` for css package.
  
  Defaults to ``None``.

``extra_context``
.................

  **Optional**
  
  Is a dictionary of values to add to the template context,
  when generating the HTML for the HTML-tags with the templatetags.
  
  For CSS, if you do not specify ``extra_context``/``media``, the default media in
  the ``<link>`` output will be ``media="all"``.

``manifest``
............

  **Optional**

  Indicate if you want this group to appear in your cache manifest.

  Defaults to ``True``.


Other settings
--------------

``PIPELINE``
............

  When ``PIPELINE`` is ``True``, CSS and JavaScripts will be concatenated and filtered.
  When ``False``, the source-files will be used instead.

  Defaults to ``not DEBUG`` (compressed files will only be used when ``DEBUG`` is ``False``).

``PIPELINE_CSS_COMPRESSOR``
............................

  Compressor class to be applied to CSS files.

  If empty or ``None``, CSS files won't be compressed.
  
  Defaults to ``'pipeline.compressors.yui.YUICompressor'``.

``PIPELINE_JS_COMPRESSOR``
...........................

  Compressor class to be applied to JavaScript files.

  If empty or ``None``, JavaScript files won't be compressed.
  
  Defaults to ``'pipeline.compressors.yui.YUICompressor'``

.. note::

  Please note that in order to use YUI Compressor, you need to install YUI Compressor (see :doc:`installation` for more details).

``PIPELINE_TEMPLATE_NAMESPACE``
...............................

  Object name where all of your compiled templates will be added, from within your browser.
  To access them with your own JavaScript namespace, change it to the object of your choice.

  Defaults to ``"window.JST"``


``PIPELINE_TEMPLATE_EXT``
.........................

  The extension for which Pipeline will consider the file as a Javascript template.
  To use a different extension, like ``.mustache``, set this settings to ``.mustache``.

  Defaults to ``".jst"``

``PIPELINE_TEMPLATE_FUNC``
..........................

  JavaScript function that compiles your JavaScript templates.
  Pipeline doesn't bundle a javascript template library, but the default
  setting is to use the
  `underscore <http://documentcloud.github.com/underscore/>`_ template function.
  
  Defaults to ``"_.template"``


Embedding fonts and images
==========================

You can embed fonts and images directly in your compiled css, using Data-URI in 
modern browsers. 

To do so, setup variant group options to the method you wish to use : ::

  PIPELINE_CSS = {
      'master': {
          'source_filenames': (
            'css/core.css',
            'css/button/*.css',
          ),
          'output_filename': 'css/master.css',
          'variant': 'datauri',
      },
  }

Images and fonts are embedded following these rules :

- If asset is under **32 kilobytes** to avoid rendering delay or not rendering
  at all in Internet Explorer 8.
- If asset path contains a directory named "**embed**".

You can override these rules using the following settings:

``PIPELINE_EMBED_MAX_IMAGE_SIZE``
..........................

  Setting that controls the maximum image size (in bytes) to embed in CSS using Data-URIs.
  Internet Explorer 8 has issues with assets under 32 kilobytes.
  Defaults to ``32700``
  
``PIPELINE_EMBED_ALL_IMAGES``
..........................

  Setting that controls whether or not an asset needs to be in a directory named "**embed**" in
  order to be embedded. 
  
  Defaults to ``False``

{'fraction_non_alphanumeric': 0.1710025706940874, 'fraction_numerical': 0.0016452442159383034, 'mean_word_length': 2.3876698014629048, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7282562', 'n_tokens_mistral': 2809, 'n_tokens_neox': 2669, 'n_words': 1031}