Projects structure

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 script in Django. django-instance is located into the project/bin directory and is aware of installed eggs from buildout.

Git ignore

Project embeds many .gitignore files to avoid to commit some files into your repository.

Principle 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.

  • install to proceed to a new install of this project. Use clean command before if you want to reset a current install;
  • clean to clean your local repository from all stuff created by buildout and instance usage;
  • delpyc to remove all *.pyc files, this is recursive from the current directory;
  • assets to minify all assets and collect static files;
  • scss to compile all SCSS stuffs with Compass;
  • tar_data to dump applications datas to json files and copying medias then put them all in a tarball;
  • import_db to import dumped datas, this will use syncdb so remove/drop your database before;


Default SCSS are made for Foundation (version 5.4.7) and compiled with Compass (version >= 0.12, <1.0).

Shipped templates are integrated using Foundation components and created project embeds css compiled with the SCSS sources from the compass directory.

Adding application

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 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 buildout.cfg.

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 and a to enable the app (using settings.INSTALLED_APPS) in the project and potentially its settings and urls;
  • The and files 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 runserver command, 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.

Available mods


Enable Django registration and everything you need to allow users to request registration and to connect/disconnect. The views and forms are added so this part can be used.

It includes:

  • 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.

In the 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 (to be configured in the 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 use a dummy profile model linked to User object. This profile is dummy because it implement fields for sample but you may not need all of them or you can even may not need about a Profile model, the User object could be enough for your needs. So before to use the syncdb, be sure to watch for the model to change it, then apply your changes to forms.RegistrationFormAccounts, views.RegistrationView and eventually templates.


Enable djangocms-admin-style to enhance the administration interface. Also enable django-admin-shortcuts.

admin-style better fit with DjangoCMS than admin_tools.


This mod cannot live with admin_tools, you have to choose only one of them.


Enable django-admin-tools to enhance the administration interface. This enables three widgets to customize certain elements and link to filebrowser module (that should allready be enabled).


This mod cannot live with admin_style, you have to choose only one of them.


Enable django-assets to combine and minify your assets (CSS, JS). The minification library used, yuicompressor, requires the installation of Java (the OpenJDK installed by default on most Linux systems is sufficient).

In general, this component 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/ and some apps can defined their own file but our main file does not use them.

Our file is divised in three parts :

  • BASE BUNDLES: Only for app bundle like Foundation Javascript files or RoyalSlider files;
  • MAIN AVAILABLE BUNDLES: Where you defined main bundles for the frontend, use app bundles previously defined;
  • ENABLE NEEDED BUNDLE: Bundle you effectively want to use. Bundle that are not defined here will not be reachable from templates and won’t be compiled;


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 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.

By default, it uses the recaptcha 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-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 project.utils.


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 painful to manage files with Filebrowser and django-filer enabled in the same project.


Enable the use of Django flatpages app in your project. Once it has been enabled, go to the 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 display a gallery of all your defined Icomoon webfonts. It won’t work with a webfont not generated on Icomoon site because it depends on a JSON manifest file.

Default behavior is to search for the JSON manifest file at project/webapp_statics/fonts/selection.json, so when you deploy an icomoon webfont you have to put there the selection.json file given into the download ZIP archive.

If you have more than one Icomoon webfont in your project, you can define more manifest to search for, read the documentation for more details.

Once the JSON manifest installed, along the webfont files, you can reach the gallery at :


Default behavior is to required to be authenticated to access to the gallery.


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.

N.B. Neither django_pdb nor 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 project/protected_medias directory.

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 sendfile.backends.nginx).

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:

  • Current Site entry name;
  • SITE.domain: Current Site entry domain;
  • SITE.web_url: The Current Site entry domain prefixed with the http protocol like 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 project.utils.context_processors.get_site_metas.


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.


Enable the emencia-django-socialaggregator app to manage social contents.


This app require to fill some API keys settings (like for Twitter API, Facebook API, etc..) to work correctly.


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.


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.