Add support for using Pipeline CSS/JS packages in forms and widgets. (#620)

Django allows forms and widgets to define the CSS or JavaScript files
needed on the page, automatically including those files in the
administration UI. This works fine for standalone media files, but
weren't an option for Pipeline packages.

This change introduces a branch new `PipelineFormMedia` class that a
form or widget's Media class can inherit from. The Media class can then
define `css_packages` or `js_packages` attributes that work just like
the standard `css`/`js` attributes but reference package names instead
of individual files.

Upon accessing the `css`  or `js` attributes, the files defined in the
packages will be collected/processed just like with the template tags
and the resulting filenames returned for use in the page.

Using this, any page compatible with Django's form media support will
work automatically with any form or widget that wants to use Pipeline
packages, without any modifications to templates or any other
workarounds that were needed before.

This implements issue #154.

docs/usage.rst

@@ -40,6 +40,49 @@ with the name “scripts”, you would use the following code to output them all
    {% stylesheet 'stats' %}
    {% javascript 'scripts' %}
 
+
+Form Media
+==========
+
+Django forms and widgets can specify individual CSS or JavaScript files to
+include on a page by defining a ``Form.Media`` class with ``css`` and ``js``
+attributes.
+
+Pipeline builds upon this by allowing packages to be listed in
+``css_packages`` and ``js_packages``. This is equivalent to manually including
+these packages in a page's template using the template tags.
+
+To use these, just have your form or widget's ``Media`` class inherit from
+``pipeline.forms.PipelineFormMedia`` and define ``css_packages`` and
+``js_packages``. You can also continue to reference individual CSS/JavaScript
+files using the original ``css``/``js`` attributes, if needed.
+
+Note that unlike the template tags, you cannot customize the HTML for
+referencing these files. The ``pipeline/css.html`` and ``pipeline/js.html``
+files will not be used. Django takes care of generating the HTML for form and
+widget media.
+
+
+Example
+-------
+
+.. code-block:: python
+
+    from django import forms
+    from pipeline.forms import PipelineFormMedia
+
+
+    class MyForm(forms.Form):
+        ...
+
+        class Media(PipelineFormMedia):
+            css_packages = {
+                'all': ('my-styles',)
+            }
+            js_packages = ('my-scripts',)
+            js = ('https://cdn.example.com/some-script.js',)
+
+
 Collect static
 ==============
 

pipeline/forms.py

+"""Support for referencing Pipeline packages in forms and widgets."""
+
+from __future__ import unicode_literals
+
+from django.contrib.staticfiles.storage import staticfiles_storage
+from django.utils import six
+from django.utils.functional import cached_property
+
+from .collector import default_collector
+from .conf import settings
+from .packager import Packager
+
+
+class PipelineFormMediaProperty(object):
+    """A property that converts Pipeline packages to lists of files.
+
+    This is used behind the scenes for any Media classes that subclass
+    :py:class:`PipelineFormMedia`. When accessed, it converts any Pipeline
+    packages into lists of media files and returns or forwards on lookups to
+    that list.
+    """
+
+    def __init__(self, get_media_files_func, media_cls, extra_files):
+        """Initialize the property.
+
+        Args:
+            get_media_files_func (callable):
+                The function to call to generate the media files.
+
+            media_cls (type):
+                The Media class owning the property.
+
+            extra_files (object):
+                Files listed in the original ``css`` or ``js`` attribute on
+                the Media class.
+        """
+        self._get_media_files_func = get_media_files_func
+        self._media_cls = media_cls
+        self._extra_files = extra_files
+
+    @cached_property
+    def _media_files(self):
+        """The media files represented by the property."""
+        return self._get_media_files_func(self._media_cls, self._extra_files)
+
+    def __get__(self, *args, **kwargs):
+        """Return the media files when accessed as an attribute.
+
+        This is called when accessing the attribute directly through the
+        Media class (for example, ``Media.css``). It returns the media files
+        directly.
+
+        Args:
+            *args (tuple, unused):
+                Unused positional arguments.
+
+            **kwargs (dict, unused):
+                Unused keyword arguments.
+
+        Returns:
+            object:
+            The list or dictionary containing the media files definition.
+        """
+        return self._media_files
+
+    def __getattr__(self, attr_name):
+        """Return an attribute on the media files definition.
+
+        This is called when accessing an attribute that doesn't otherwise
+        exist in the property's dictionary. The call is forwarded onto the
+        media files definition.
+
+        Args:
+            attr_name (unicode):
+                The attribute name.
+
+        Returns:
+            object:
+            The attribute value.
+
+        Raises:
+            AttributeError:
+                An attribute with this name could not be found.
+        """
+        return getattr(self._media_files, attr_name)
+
+    def __iter__(self):
+        """Iterate through the media files definition.
+
+        This is called when attempting to iterate over this property. It
+        iterates over the media files definition instead.
+
+        Yields:
+            object:
+            Each entry in the media files definition.
+        """
+        return iter(self._media_files)
+
+
+class PipelineFormMediaMetaClass(type):
+    """Metaclass for the PipelineFormMedia class.
+
+    This is responsible for converting CSS/JavaScript packages defined in
+    Pipeline into lists of files to include on a page. It handles access to the
+    :py:attr:`css` and :py:attr:`js` attributes on the class, generating a
+    list of files to return based on the Pipelined packages and individual
+    files listed in the :py:attr:`css`/:py:attr:`css_packages` or
+    :py:attr:`js`/:py:attr:`js_packages` attributes.
+    """
+
+    def __new__(cls, name, bases, attrs):
+        """Construct the class.
+
+        Args:
+            name (bytes):
+                The name of the class.
+
+            bases (tuple):
+                The base classes for the class.
+
+            attrs (dict):
+                The attributes going into the class.
+
+        Returns:
+            type:
+            The new class.
+        """
+        new_class = super(PipelineFormMediaMetaClass, cls).__new__(
+            cls, name, bases, attrs)
+
+        # If we define any packages, we'll need to use our special
+        # PipelineFormMediaProperty class. We use this instead of intercepting
+        # in __getattribute__ because Django does not access them through
+        # normal properpty access. Instead, grabs the Media class's __dict__
+        # and accesses them from there. By using these special properties, we
+        # can handle direct access (Media.css) and dictionary-based access
+        # (Media.__dict__['css']).
+        if 'css_packages' in attrs:
+            new_class.css = PipelineFormMediaProperty(
+                cls._get_css_files, new_class, attrs.get('css') or {})
+
+        if 'js_packages' in attrs:
+            new_class.js = PipelineFormMediaProperty(
+                cls._get_js_files, new_class, attrs.get('js') or [])
+
+        return new_class
+
+    def _get_css_files(cls, extra_files):
+        """Return all CSS files from the Media class.
+
+        Args:
+            extra_files (dict):
+                The contents of the Media class's original :py:attr:`css`
+                attribute, if one was provided.
+
+        Returns:
+            dict:
+            The CSS media types and files to return for the :py:attr:`css`
+            attribute.
+        """
+        packager = Packager()
+        css_packages = getattr(cls, 'css_packages', {})
+
+        return dict(
+            (media_target,
+             cls._get_media_files(packager=packager,
+                                  media_packages=media_packages,
+                                  media_type='css',
+                                  extra_files=extra_files.get(media_target,
+                                                              [])))
+            for media_target, media_packages in six.iteritems(css_packages)
+        )
+
+    def _get_js_files(cls, extra_files):
+        """Return all JavaScript files from the Media class.
+
+        Args:
+            extra_files (list):
+                The contents of the Media class's original :py:attr:`js`
+                attribute, if one was provided.
+
+        Returns:
+            list:
+            The JavaScript files to return for the :py:attr:`js` attribute.
+        """
+        return cls._get_media_files(
+            packager=Packager(),
+            media_packages=getattr(cls, 'js_packages', {}),
+            media_type='js',
+            extra_files=extra_files)
+
+    def _get_media_files(cls, packager, media_packages, media_type,
+                         extra_files):
+        """Return source or output media files for a list of packages.
+
+        This will go through the media files belonging to the provided list
+        of packages referenced in a Media class and return the output files
+        (if Pipeline is enabled) or the source files (if not enabled).
+
+        Args:
+            packager (pipeline.packager.Packager):
+                The packager responsible for media compilation for this type
+                of package.
+
+            media_packages (list of unicode):
+                The list of media packages referenced in Media to compile or
+                return.
+
+            extra_files (list of unicode):
+                The list of extra files to include in the result. This would
+                be the list stored in the Media class's original :py:attr:`css`
+                or :py:attr:`js` attributes.
+
+        Returns:
+            list:
+            The list of media files for the given packages.
+        """
+        source_files = list(extra_files)
+
+        if (not settings.PIPELINE_ENABLED and
+            settings.PIPELINE_COLLECTOR_ENABLED):
+            default_collector.collect()
+
+        for media_package in media_packages:
+            package = packager.package_for(media_type, media_package)
+
+            if settings.PIPELINE_ENABLED:
+                source_files.append(
+                    staticfiles_storage.url(package.output_filename))
+            else:
+                source_files += packager.compile(package.paths)
+
+        return source_files
+
+
+@six.add_metaclass(PipelineFormMediaMetaClass)
+class PipelineFormMedia(object):
+    """Base class for form or widget Media classes that use Pipeline packages.
+
+    Forms or widgets that need custom CSS or JavaScript media on a page can
+    define a standard :py:class:`Media` class that subclasses this class,
+    listing the CSS or JavaScript packages in :py:attr:`css_packages` and
+    :py:attr:`js_packages` attributes. These are formatted the same as the
+    standard :py:attr:`css` and :py:attr:`js` attributes, but reference
+    Pipeline package names instead of individual source files.
+
+    If Pipeline is enabled, these will expand to the output files for the
+    packages. Otherwise, these will expand to the list of source files for the
+    packages.
+
+    Subclasses can also continue to define :py:attr:`css` and :py:attr:`js`
+    attributes, which will be returned along with the other output/source
+    files.
+
+    Example:
+
+        from django import forms
+        from pipeline.forms import PipelineFormMedia
+
+
+        class MyForm(forms.Media):
+            ...
+
+            class Media(PipelineFormMedia):
+                css_packages = {
+                    'all': ('my-form-styles-package',
+                            'other-form-styles-package'),
+                    'print': ('my-form-print-styles-package',),
+                }
+
+                js_packages = ('my-form-scripts-package',)
+                js = ('some-file.js',)
+    """

tests/tests/test_forms.py

+from __future__ import unicode_literals
+
+from django.forms import Media
+from django.test import TestCase
+from django.utils import six
+
+from pipeline.forms import PipelineFormMedia
+from ..utils import pipeline_settings
+
+
+@pipeline_settings(
+    PIPELINE_COLLECTOR_ENABLED=False,
+    STYLESHEETS={
+        'styles1': {
+            'source_filenames': (
+                'pipeline/css/first.css',
+                'pipeline/css/second.css',
+            ),
+            'output_filename': 'styles1.min.css',
+        },
+        'styles2': {
+            'source_filenames': (
+                'pipeline/css/unicode.css',
+            ),
+            'output_filename': 'styles2.min.css',
+        },
+        'print': {
+            'source_filenames': (
+                'pipeline/css/urls.css',
+            ),
+            'output_filename': 'print.min.css',
+        },
+    },
+    JAVASCRIPT={
+        'scripts1': {
+            'source_filenames': (
+                'pipeline/js/first.js',
+                'pipeline/js/second.js',
+            ),
+            'output_filename': 'scripts1.min.js',
+        },
+        'scripts2': {
+            'source_filenames': (
+                'pipeline/js/application.js',
+            ),
+            'output_filename': 'scripts2.min.js',
+        },
+    })
+class PipelineFormMediaTests(TestCase):
+    """Unit tests for pipeline.forms.PipelineFormMedia."""
+
+    @pipeline_settings(PIPELINE_ENABLED=True)
+    def test_css_packages_with_pipeline_enabled(self):
+        """Testing PipelineFormMedia.css_packages with PIPELINE_ENABLED=True"""
+        class MyMedia(PipelineFormMedia):
+            css_packages = {
+                'all': ('styles1', 'styles2'),
+                'print': ('print',),
+            }
+
+            css = {
+                'all': ('extra1.css', 'extra2.css')
+            }
+
+        media = Media(MyMedia)
+
+        self.assertEqual(
+            MyMedia.css,
+            {
+                'all': [
+                    'extra1.css',
+                    'extra2.css',
+                    '/static/styles1.min.css',
+                    '/static/styles2.min.css',
+                ],
+                'print': ['/static/print.min.css'],
+            })
+        self.assertEqual(MyMedia.css, media._css)
+        self.assertEqual(
+            list(media.render_css()),
+            [
+                '<link href="%s" type="text/css" media="all" '
+                'rel="stylesheet" />' % path
+                for path in (
+                    '/static/extra1.css',
+                    '/static/extra2.css',
+                    '/static/styles1.min.css',
+                    '/static/styles2.min.css',
+                )
+            ] + [
+                '<link href="/static/print.min.css" type="text/css" '
+                'media="print" rel="stylesheet" />'
+            ])
+
+    @pipeline_settings(PIPELINE_ENABLED=False)
+    def test_css_packages_with_pipeline_disabled(self):
+        """Testing PipelineFormMedia.css_packages with PIPELINE_ENABLED=False"""
+        class MyMedia(PipelineFormMedia):
+            css_packages = {
+                'all': ('styles1', 'styles2'),
+                'print': ('print',),
+            }
+
+            css = {
+                'all': ('extra1.css', 'extra2.css')
+            }
+
+        media = Media(MyMedia)
+
+        self.assertEqual(
+            MyMedia.css,
+            {
+                'all': [
+                    'extra1.css',
+                    'extra2.css',
+                    'pipeline/css/first.css',
+                    'pipeline/css/second.css',
+                    'pipeline/css/unicode.css',
+                ],
+                'print': ['pipeline/css/urls.css'],
+            })
+        self.assertEqual(MyMedia.css, media._css)
+        self.assertEqual(
+            list(media.render_css()),
+            [
+                '<link href="%s" type="text/css" media="all" '
+                'rel="stylesheet" />' % path
+                for path in (
+                    '/static/extra1.css',
+                    '/static/extra2.css',
+                    '/static/pipeline/css/first.css',
+                    '/static/pipeline/css/second.css',
+                    '/static/pipeline/css/unicode.css',
+                )
+            ] + [
+                '<link href="/static/pipeline/css/urls.css" type="text/css" '
+                'media="print" rel="stylesheet" />'
+            ])
+
+    @pipeline_settings(PIPELINE_ENABLED=True)
+    def test_js_packages_with_pipeline_enabled(self):
+        """Testing PipelineFormMedia.js_packages with PIPELINE_ENABLED=True"""
+        class MyMedia(PipelineFormMedia):
+            js_packages = ('scripts1', 'scripts2')
+            js = ('extra1.js', 'extra2.js')
+
+        media = Media(MyMedia)
+
+        self.assertEqual(
+            MyMedia.js,
+            [
+                'extra1.js',
+                'extra2.js',
+                '/static/scripts1.min.js',
+                '/static/scripts2.min.js',
+            ])
+        self.assertEqual(MyMedia.js, media._js)
+        self.assertEqual(
+            media.render_js(),
+            [
+                '<script type="text/javascript" src="%s"></script>' % path
+                for path in (
+                    '/static/extra1.js',
+                    '/static/extra2.js',
+                    '/static/scripts1.min.js',
+                    '/static/scripts2.min.js',
+                )
+            ])
+
+    @pipeline_settings(PIPELINE_ENABLED=False)
+    def test_js_packages_with_pipeline_disabled(self):
+        """Testing PipelineFormMedia.js_packages with PIPELINE_ENABLED=False"""
+        class MyMedia(PipelineFormMedia):
+            js_packages = ('scripts1', 'scripts2')
+            js = ('extra1.js', 'extra2.js')
+
+        media = Media(MyMedia)
+
+        self.assertEqual(
+            MyMedia.js,
+            [
+                'extra1.js',
+                'extra2.js',
+                'pipeline/js/first.js',
+                'pipeline/js/second.js',
+                'pipeline/js/application.js',
+            ])
+        self.assertEqual(MyMedia.js, media._js)
+        self.assertEqual(
+            media.render_js(),
+            [
+                '<script type="text/javascript" src="%s"></script>' % path
+                for path in (
+                    '/static/extra1.js',
+                    '/static/extra2.js',
+                    '/static/pipeline/js/first.js',
+                    '/static/pipeline/js/second.js',
+                    '/static/pipeline/js/application.js',
+                )
+            ])