Metadata-Version: 1.1
Name: aldryn-boilerplates
Version: 0.7.2
Summary: An extension that allows re-usable apps to provide sets of templates and staticfiles for different boilerplates.
Home-page: https://github.com/aldryn/aldryn-boilerplates/
Author: Stefan Foulis
Author-email: stefan@foulis.ch
License: BSD
Description: ###################
        aldryn-boilerplates
        ###################
        
        .. image:: https://travis-ci.org/aldryn/aldryn-boilerplates.svg?branch=develop
            :target: https://travis-ci.org/aldryn/aldryn-boilerplates
        
        .. image:: https://img.shields.io/coveralls/aldryn/aldryn-boilerplates.svg
          :target: https://coveralls.io/r/aldryn/aldryn-boilerplates
        
        
        ***********
        The concept
        ***********
        
        Aldryn Boilerplates aims to solve a familiar Django problem. Sometimes re-usable applications need
        to provide their own templates and staticfiles, but in order to be useful, these need to commit
        themselves to particular frontend expectations - thereby obliging the adopter to override these
        files in order to adapt the application to other frontends, or create a new fork of the project
        aimed at a different frontend setup.
        
        It's especially difficult to provide a rich and complete frontend for a re-usable application,
        because there's a conflict between creating a *useful* frontend and creating an *agnostic* one.
        
        The solution is to build in provision for different, switchable, frontend expectations into the
        re-usable application, and this is what Aldryn Boilerplates does.
        
        On the `Aldryn <http://aldryn.com>`_ platform, a *Boilerplate* is a complete set of frontend
        expectations, assumptions, opinions, conventions, frameworks, templates, static files and more - a
        standard way of working for frontend development.
        
        Many developers do in fact work with their own preferred standard sets of frontend tools and code
        for all their projects; in effect, with their own Boilerplates, even if they don't use that name.
        Aldryn Boilerplates is intended to make it easier to provide support for multiple Boilerplates in
        res-usable applications, and to switch between them.
        
        If users of a particular frontend framework or system would like to use it with a certain re-usable
        application, they now no longer need to rip out and replace the existing one, or override it at the
        project level every single time. Instead with Aldryn Boilerplates they can simply *add* the
        frontend files to the application, alongside the ones for existing supported Boilerplates.
        
        A simple setting in the project tells applications that support Aldryn Boilerplates which one to
        use.
        
        
        *************************
        Using Aldryn Boilerplates
        *************************
        
        Aldryn Boilerplates doesn't change the way regular files in ``templates`` and ``static`` are
        discovered - a re-usable application that supports Aldryn Boilerplates can also work perfectly well
        in a project that doesn't have it installed.
        
        However, to support Aldryn Boilerplates, your application should place Boilerplate-specific
        frontend files in ``boilerplates/my-boilerplate-name/templates/`` and
        ``boilerplates/my-boilerplate-name/static/``.
        
        For example, to add support for the Standard Aldryn Boilerplate (`aldryn-boilerplate-bootstrap3`_)
        to your application, place the files in ``boilerplates/bootstrap3/templates/`` and
        ``boilerplates/bootstrap3/static/``.
        
        .. hint::
            don't forget to add ``boilerplates`` to ``Manifest.in``, alongside ``static`` and ``templates``
            when creating Python packages.
        
        .. note::
            The convention is to prefix the github repository name with ``aldryn-boilerplate-``. Your
            Boilerplate could be called something like ``aldryn-boilerplate-mycompany-awesome``. To use it
            in a project, you'd set ``ALDRYN_BOILERPLATE_NAME = 'mycompany-awesome'`` and put templates
            and static files into ``boilerplates/mycompany-awesome/`` in Addons.
            ``ALDRYN_BOILERPLATE_NAME`` is set automatically on Aldryn based on
            ``"identifier": "mycompany-awesome"`` in ``boilerplate.json`` when submitting a boilerplate to
            Aldryn.
        
        
        ************
        Installation
        ************
        
        .. note::
            aldryn-boilerplates comes pre-installed on the Aldryn Platform and
            ``ALDRYN_BOILERPLATE_NAME`` is set automatically.
        
        ::
        
            pip install aldryn-boilerplates
        
        
        *************
        Configuration
        *************
        
        ::
        
            INSTALLED_APPS = [
                ...
                'aldryn_boilerplates',
                ...
            ]
        
            TEMPLATE_CONTEXT_PROCESSORS = [
                ...
                'aldryn_boilerplates.context_processors.boilerplate',
            ]
        
            STATICFILES_FINDERS = [
                'django.contrib.staticfiles.finders.FileSystemFinder',
                # important! place right before django.contrib.staticfiles.finders.AppDirectoriesFinder
                'aldryn_boilerplates.staticfile_finders.AppDirectoriesFinder',
                'django.contrib.staticfiles.finders.AppDirectoriesFinder',
            ]
        
            TEMPLATE_LOADERS = [
                'django.template.loaders.filesystem.Loader',
                # important! place right before django.template.loaders.app_directories.Loader
                'aldryn_boilerplates.template_loaders.AppDirectoriesLoader',
                'django.template.loaders.app_directories.Loader',
            ]
        
        Now set the name of the Boilerplate you want to use in your project::
        
            ALDRYN_BOILERPLATE_NAME = 'bootstrap3'
        
        
        ******************************************************
        Adding aldryn-boilerplate support to existing packages
        ******************************************************
        
        The recommended approach is to add a dependency to aldryn-boilerplates and to move existing
        ``static`` and ``template`` files to a boilerplate folder (completely remove ``static`` and
        ``templates``). If you're in the process of re-factoring your existing templates with something
        new, put them into the ``legacy`` boilerplate folder and set ``ALDRYN_BOILERPLATE_NAME='legacy'``
        on projects that are still using the old templates.
        The new and shiny project can then use ``ALDRYN_BOILERPLATE_NAME='bootstrap3'`` to use the new
        Aldryn Bootstrap Boilerplate (`aldryn-boilerplate-bootstrap3`_). Or any other
        boilerplate for that matter.
        
        Removing ``static`` and ``templates`` has the benefit of removing likely deprecated templates
        from the very prominent location, that will confuse newcomers. It also prevents having not-relevant
        templates and static files messing up your setup.
        
        
        .. _aldryn-boilerplate-bootstrap3: https://github.com/aldryn/aldryn-boilerplate-standard
        
Platform: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
