Projects are created with the many components that are available for use. These components are called mods and these mods are already installed and ready to use. You can enable or disable them, as needed.
This is the command installed to replace the old
manage.py script in Django.
django-instance is located into the
project/bin directory and is aware of installed eggs from buildout.
Project embeds many
.gitignore files to avoid to commit some files into your repository.
Aim is to never commit files created from buildout (installed packages, app development sources, etc..), compiled static files, project media files and database.
Project embeds a
Makefile file that contains some usefull commands to build your project.
- to proceed to a new install of this project. Use clean command before if you want to reset a current install
- to proceed to a new install of this project with additional sources for development
- to install (or re-install) Foundation sources
- to clean your local repository from all stuff created by buildout and instance usage
- to remove all
*.pycfiles, this is recursive from the current directory
- to minify all assets and collect static files
- to compile all SCSS stuffs with compass
- to update staticfiles with Foundation sources (use this is you upgrade Foundation sources)
- to dump applications datas to json files then put them in a tarball
- to import dumped datas, you should empty the database before
- to reload uwsgi instance (for integration and production only)
Produced project contain a SASS structure ready to use and contains Foundation and Bourbon libraries. You should find a structure like this:
sass/ ├── bourbon ├── foundation5 └── scss
scss directory is where live your SASS sources to compile to CSS. SASS sources and libraries must be compatible with any compiler which implement SASS >= 3.2.x references.
Included HTML templates was done using Foundation, so you will need to change them if you plan to use another SASS framework.
We strongly advise you to use Boussole to avoid messing with some Ruby or Node.js installation. Compass 1.x is still supported. In the SASS sources directory a default configuration is available for both of them.
Compass include also a SASS framework. It’s most important feature is vendor prefix for many CSS3 properties but this is not needed anymore with recent browsers.
If you use still use Compass compiler, never use any Compass mixin or stuff in your SASS sources, it will break compatibility for people using another compiler.
For CSS3 properties requiring vendor prefix, we include Bourbon framework instead. If you are not sure about vendor prefix needs, search in Can I Use database.
If you plan to integrate a new app into a project, always use the buildout system to ensure its portability (pip requirements file is not used in our system).
To do this, just open and edit the
buildout.cfg file to add the new egg name to be installed. For more details, read the buildout documentation.
Also it is always preferable to use the mods system to configure new added apps and keep the
settings.py only for Django owned settings.
Project contains a
version.cfg file that define exact version to use for listed eggs in
buildout.cfg. All existing mods have their eggs defined in this file, if you need to enable a mod that you skipped during project creation, just find its egg name in
version.cfg and add it to the eggs in
How the Mods work¶
The advantage of centralizing app configurations in their mods is to safely gather together them distinctly from the Django basic settings (like SMTP config, database access, middlewares, etc..). Furthermore it is easier to enable or disable apps.
To create a new mods:
- Create a directory in
project/mods_available/that contains at least one empty
settings.pyto enable the app (using
settings.INSTALLED_APPS) in the project and potentially its settings and urls;
urls.pyfiles in this directory will be executed automatically by the project (the system loads them after the project ones so that a mods can overwrite the project initial settings and urls);
- N.B. With the Django
runservercommand, a change to these files does not reload the project instance; you need to relaunch it yourself manually;
To enable a new mods, you need to create its symbolic link (a relative path to the available mod) in
project/mods_enabled. To disable it, simply delete the symbolic link.
Since Django 1.8, every template settings are contained in their backend entry in
settings.TEMPLATES. We actually assume to only use the default Django template backend in our project. So mods will be able to manipulate template settings using the default backend that will be the index 0 of the backends list:
TEMPLATES['OPTIONS']['context_processors'] = ....
Trying to use the old template settings will result in an error.
Enable Django registration and everything you need to allow users to register and to connect/disconnect. Sample views and forms are include so it can be easily used.
- A view for the login and one for the logout;
- All the views for the registration request (request, confirmation, etc.);
- A view to ask for the reinitialization of a password;
- Email sending;
skeleton.html template, a partial HTML code is commented. Uncomment it to display the logout button when the user is connected.
The registration process consists in sending an email (sender/destination emails have to be configured in settings) with the registration request to an administrator responsible for accepting them (or not). Once validated, an email is sent to the user to confirm his registration by way of a link. Once this step has been completed, the user can connect.
Also, note that this app extend the user model with a profile model.
This profile is naive because it implement some comon additional fields for sample but you may not need all of them, if you change it you will need to do some changes also in registration view, forms and email senders.
Included forms and templates depends on crispy_forms mod.
Enable djangocms-admin-style to enhance the administration interface. Also enable django-admin-shortcuts.
admin-style is an enhancement for Django admin that have been developed by Django CMS team.
Enable django-assets to combine and minify your assets (CSS, JS).
There are two used minification libraries:
- yuicompressor for CSS;
Both of them requires the installation of Java (OpenJDK installed on most Linux systems is sufficient), they are installed through some Python meta package from Pypi.
In general, this mod is required. If you do not intend to use it, you will need to modify the project’s default templates to remove all of its occurrences.
Assets are defined in
project/assets.py and some apps can defined their own
asset.py file but our main file does not use them.
assets.py file is divised in three parts :
- MAIN AVAILABLE BUNDLES: Where you defined main bundles for the frontend, use app bundles previously defined;
- ENABLE NEEDED BUNDLE: Leading bundles you effectively want to use and expose in your templates. Bundle that are not defined here will not be reachable from templates and won’t be minified;
Enable and define customization for the CKEditor editor. It is enabled by default and used by Django CKEditor in the cms mod, and also in zinnia.
Note that DjangoCMS use it’s own app named “djangocms_text_ckeditor”, a djangocms plugin to use CKEditor (4.x).
But Zinnia (and some other generic app) use “django_ckeditor” that ship the same ckeditor but without cms addons.
This mod contains configuration for all of them.
And some useful patches/fixes :
- the codemirror plugin that is missing from the ckeditor’s django apps;
- A system to use the “template” plugin (see views.EditorTemplatesListView for more usage details);
- Some overriding to have content preview and editor more near to Foundation;
Django CMS allows for the creation and management of the content pages that constitute your site’s tree structure. By default, this component enables the use of filebrowser, Django CKEditor and emencia-cms-snippet (a clone of the snippets’ plugin with a few improvements).
By default it is configured to use only one language. See its
urls.py to find out how to enable the management of multiple languages.
Enable Django Codemirror to apply the editor with syntax highlighting in your forms (or other content).
It is used by the snippet’s CMS plugin.
A simple contact form that is more of a standard template than a full-blown application. You can modify it according to your requirements in its
apps/contact_form/ directory. Its HTML rendering is managed by crispy_forms based on a customized layout.
Depends on recaptcha and crispy_forms mods.
Enable the use of django-crispy-forms and crispy-forms-foundation.
crispy_forms is used to manage the HTML rendering of the forms in a finer and easier fashion than with the simple Django form API.
crispy-forms-foundation is a supplement to implement the rendering with the structure (tags, styles, etc.) used in Foundation.
Add `_django-datadownloader`_ to your project to manage data (media/db).
Add django-debug-toolbar to your project to insert a tab on all of your project’s HTML pages, which will allow you to track the information on each page, such as the template generation path, the query arguments received, the number of SQL queries submitted, etc.
This component can only be used in a development or integration environment and is always disabled during production.
Note that its use extends the response time of your pages and can provokes some bugs (see the warning at end) so for the time being, this mods is disabled. Enable it locally for your needs but never commit its enabled mod and remember trying to disable it when you have a strange bug.
Never enable this mod before the first database install or a syncdb, else it will result in errors about some table that don’t exist (like “django_site”).
Group together some common and various utilities from
Add Django Filebrowser to your project so you can use a centralized interface to manage the uploaded files to be used with other components (cms, zinnia, etc.).
The version used is a special version called no grappelli that can be used outside of the django-grapelli environment.
Filebrowser manage files with a nice interface to centralize them and also manage image resizing versions (original, small, medium, etc..), you can edit these versions or add new ones in the settings.
Don’t try to use other resizing app like sorl-thumbnails or easy-thumbnails, they will not work with Image fields managed with Filebrowser.
Mod for django-filer and its DjangoCMS plugin
Only enable it for specific usage because this can be painful to manage files when Filebrowser and django-filer are enabled in the same project.
Enable the use of Django flatpages app in your project. Once it has been enabled, go
urls.py in this mod to configure the map of the urls to be used.
Add django-google-tools to your project to manage the tags for Google Analytics and Google Site Verification from the site administration location.
The project is filled with a custom template
project/templates/googletools/analytics_code.html to use Google Universal Analytics, remove it to return to the old Google Analytics.
Django Icomoon help you to manage your webfonts with Icomoon service. It won’t work with a webfont not generated on Icomoon site because it depends on a JSON manifest file (you could make it yourself but it’s a little bit complicated).
This mod can handle many webfonts if you need, you just have to define them in the mod settings, at least one webfont is required.
Once one or more webfonts are defined, Django Icomoon can help you to automatically deploy them in your project from downloaded Zip on Icomoon using a command line
Also when deployed and the webfonts are loaded in your templates, you can visualize every icons from a gallery located at
Enable django-logentry-admin to browse all admin log entries at contrary to default Django admin behavior that only display the last entries.
Add Django PDB to your project for more precise debugging with breakpoints.
pdb are installed by buildout. You must install
them manually, for example with pip, in your development environment so you do not
disrupt the installation of projects being integrated or in production. You must also
add the required breakpoints yourself.
See the the django-pdb Readme for more usage details.
Make sure to put django_pdb after any conflicting apps in INSTALLED_APPS so that they have priority.
So with the automatic loading system for the mods, you should enable it with a name like “zpdb”, to ensure that it is loaded at the end of the loading loop.
Add Django Porticus to your project to manage file galleries.
There is a DjangoCMS plugin for Porticus, it is not enabled by default, you will have to uncomment it in the mod settings.
Enable the Django reCaptcha module to integrate a field of the captcha type via the Service reCaptcha. This integration uses a special template and CSS to make it responsive.
If you do in fact use this module, go to its mods setting file (or that of your environment) to fill in the public key and the private key to be used to transmit the data required.
By default, these keys are filled in with a fake value and the captcha’s form field therefore sends back a silent error (a message is inserted into the form without creating a Python Exception).
Enable django-sendfile that is somewhat like a helper around the X-SENDFILE headers, a technic to process some requests before let them pass to the webserver.
Commonly used to check for permissions rights to download some private files before let the webserver to process the request. So the webapp can execute some code on a request without to carry the file to download (than could be a big issue with some very big files).
django-sendfile dependancy in the buildout config is commented by default, so first you will need to uncomment its line to install it, before enabling the mod. Then you will need to create the directory to store the protected medias, because if you store them in the common media directory, they will public to everyone.
This directory must be in the project directory, then its name can defined in the
PROTECTED_MEDIAS_DIRNAME mod setting, default is to use
protected_medias and so you should create the
Your webserver need to support this technic, no matter on a recent nginx as it is allready embeded in, on Apache you will need to install the Apache module XSendfile (it should be availabe on your distribution packages) and enable it in the virtualhost config (or the global one if you want), see the Apache module documentation for more details. Then remember to update your virtualhost config with the needed directive, use the Apache config file builded from buildout.
The nginx config template allready embed a rule to manage
project/protected_medias with sendfile, but it is commented by default, so you will need to uncomment it before to launch buildout again to build the nginx config file.
By default, the mod use the django-sendfile’s backend for development that is named
sendfile.backends.development. For production, you will need to use the right backend for your webserver (like
Finally you will need to implement it in your code as this will require a custom view to download the file, see the django-sendfile documentation for details about this. But this is almost easy, you just need to use the
sendfile.sendfile method to return the right Response within your view.
Enable a module in
settings.TEMPLATE_CONTEXT_PROCESSORS to show a few variables linked to Django sites app in the context of the project views template.
Common context available variables are:
SITE.name: Current Site entry name;
SITE.domain: Current Site entry domain;
SITE.web_url: The Current Site entry domain prefixed with the http protocol like
http://mydomain.com. If HTTPS is enabled ‘https’ will be used instead of ‘http’;
Some projects can change this to add some other variables, you can see for them in
This mod use the Django’s Sitemap framework to publish the
sitemap.xml for various apps. The default config contains ressources for DjangoCMS, Zinnia, staticpages, contact form and Porticus but only ressource for DjangoCMS is enabled.
Uncomment ressources or add new app ressources for your needs (see the Django documentation for more details).
Enable the emencia-django-slideshows app to manage slide animations (slider, carousel, etc.). This was initially provided for Foundation Orbit and Royal Slider, but can be used with other libraries if needed.
This mod uses emencia-django-staticpages to use static pages with a direct to template process, it replace the deprecated mod prototype.
Mod for easy-thumbnails a library to help for making thumbnails on the fly (or not).
Generally this is not recommended, because by default we allready enable Filebrowser that allready ships a thumbnail system.
django-urls-map is a tiny Django app to embed a simple management command that will display the url map of your project.
Mod to define Django-xiti settings to load Xiti HTML code into templates
Since Xiti usage is not common, this mod is not installed or enabled on default install, you will need to enable it’s egg in buildout, enable its mod and finally update
marketing_tags.html to load it.
Django Blog Zinnia allows for the management of a blog in your project. It is well integrated into the cms component but can also be used independently.