Package: aldryn-boilerplates
The conceptAldryn 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 ausefulfrontend and creating anagnosticone.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 theAldrynplatform, aBoilerplateis 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 simplyaddthe
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 BoilerplatesAldryn Boilerplates doesn’t change the way regular files intemplatesandstaticare
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 inboilerplates/my-boilerplate-name/templates/andboilerplates/my-boilerplate-name/static/.For example, to add support for the Standard Aldryn Boilerplate (aldryn-boilerplate-bootstrap3)
to your application, place the files inboilerplates/bootstrap3/templates/andboilerplates/bootstrap3/static/.Hintdon’t forget to addboilerplatestoManifest.in, alongsidestaticandtemplateswhen creating Python packages.NoteThe convention is to prefix the github repository name withaldryn-boilerplate-. Your
Boilerplate could be called something likealdryn-boilerplate-mycompany-awesome. To use it
in a project, you’d setALDRYN_BOILERPLATE_NAME ='mycompany-awesome'and put templates
and static files intoboilerplates/mycompany-awesome/in Addons.ALDRYN_BOILERPLATE_NAMEis set automatically on Aldryn based on"identifier":"mycompany-awesome"inboilerplate.jsonwhen submitting a boilerplate to
Aldryn.InstallationNotealdryn-boilerplates comes pre-installed on the Aldryn Platform andALDRYN_BOILERPLATE_NAMEis set automatically.pip install aldryn-boilerplatesConfigurationDjango 1.8+In general configuration stays the same but you should respect changes that
were introduced by django 1.8.
In particular in Django 1.8 context processors were moved fromdjango.coretodjango.template.Be sure to includealdryn_boilerplatestoINSTALLED_APPS, adjustSTATICFILES_FINDERSand finally configureTEMPLATES.ForTEMPLATESyou need to addaldryn_boilerplates.context_processors.boilerplatetocontext_processorsand alterloadersin the same way as we do it for Django versions prior
to 1.8.Notethat in the example below we are altering the default values,
so if you are using something that is custom - don’t forget to add that too.Here is an example of a simple configuration:INSTALLED_APPS = [
    ...
    'aldryn_boilerplates',
    ...
]

STATICFILES_FINDERS = (
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'aldryn_boilerplates.staticfile_finders.AppDirectoriesFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
)

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'OPTIONS': {
            'context_processors': [
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
                'django.template.context_processors.i18n',
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.template.context_processors.media',
                'django.template.context_processors.csrf',
                'django.template.context_processors.tz',
                'sekizai.context_processors.sekizai',
                'django.template.context_processors.static',
                'cms.context_processors.cms_settings',
                'aldryn_boilerplates.context_processors.boilerplate',
            ],
            'loaders': [
                'django.template.loaders.filesystem.Loader',
                'aldryn_boilerplates.template_loaders.AppDirectoriesLoader',
                'django.template.loaders.app_directories.Loader',
            ],
        },
    },
]Adding aldryn-boilerplate support to existing packagesThe recommended approach is to add a dependency to aldryn-boilerplates and to move existingstaticandtemplatefiles to a boilerplate folder (completely removestaticandtemplates). If you’re in the process of re-factoring your existing templates with something
new, put them into thelegacyboilerplate folder and setALDRYN_BOILERPLATE_NAME='legacy'on projects that are still using the old templates.
The new and shiny project can then useALDRYN_BOILERPLATE_NAME='bootstrap3'to use the new
Aldryn Bootstrap Boilerplate (aldryn-boilerplate-bootstrap3). Or any other
boilerplate for that matter.Removingstaticandtemplateshas 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.