Release-3.3.X

django cms Documentation Release 3.3.4 Patrick Lauber Apr 25, 2017 Contents 1 Overview 3 1.1 Tutorials...............................................3 1.2 How-to guides............................................3 1.3 Key topics..............................................3 1.4 Reference...............................................3 2 Join us online 5 3 Why django CMS? 7 4 Release Notes 9 5 Table of contents 11 5.1 Tutorials............................................... 11 5.2 How-to guides............................................ 29 5.3 Key topics.............................................. 92 5.4 Reference............................................... 105 5.5 Development & community..................................... 158 5.6 Release notes & upgrade information................................ 178 5.7 Using django CMS.......................................... 226 5.8 Indices and tables.......................................... 237 Python Module Index 239 i ii django cms Documentation, Release 3.3.4 Contents 1 django cms Documentation, Release 3.3.4 2 Contents CHAPTER 1 Overview django CMS is a modern web publishing platform built with Django, the web application framework “for perfec- tionists with deadlines”. django CMS offers out-of-the-box support for the common features you’d expect from a CMS, but can also be easily customised and extended by developers to create a site that is tailored to their precise needs. Tutorials For the new django CMS developer, from installation to creating your own addon applications. How-to guides Practical step-by-step guides for the more experienced developer, covering several important topics. Key topics Explanation and analysis of some key concepts in django CMS. Reference Technical reference material, for classes, methods, APIs, commands. 3 django cms Documentation, Release 3.3.4 4 Chapter 1. Overview CHAPTER 2 Join us online django CMS is supported by a friendly and very knowledgeable community. Our IRC channel, #django-cms, is on irc.freenode.net. If you don’t have an IRC client, you can join our IRC channel using the KiwiIRC web client, which works pretty well. Our django CMS users email list is for general django CMS questions and discussion Our django CMS developers email list is for discussions about the development of django CMS 5 django cms Documentation, Release 3.3.4 6 Chapter 2. Join us online CHAPTER 3 Why django CMS? django CMS is a well-tested CMS platform that powers sites both large and small. Here are a few of the key features: • robust internationalisation (i18n) support for creating multilingual sites • virtually unlimited undo history, allowing editors to revert to a previous version • front-end editing, providing rapid access to the content management interface • support for a variety of editors with advanced text editing features. • a flexible plugins system that lets developers put powerful tools at the fingertips of editors, without over- whelming them with a difficult interface • ...and much more There are other capable Django-based CMS platforms but here’s why you should consider django CMS: • thorough documentation • easy and comprehensive integration into existing projects - django CMS isn’t a monolithic application • a healthy, active and supportive developer community • a strong culture of good code, including an emphasis on automated testing 7 django cms Documentation, Release 3.3.4 8 Chapter 3. Why django CMS? CHAPTER 4 Release Notes This document refers to version 3.3.4 Warning: Version 3.0 introduces some significant changes that require action if you are upgrading from a previous version. Please refer to Upgrading from previous versions 9 django cms Documentation, Release 3.3.4 10 Chapter 4. Release Notes CHAPTER 5 Table of contents Tutorials The pages in this section of the documentation are aimed at the newcomer to django CMS. They’re designed to help you get started quickly, and show how easy it is to work with django CMS as a developer who wants to customise it and get it working according to their own requirements. These tutorials take you step-by-step through some key aspects of this work. They’re not intended to explain the topics in depth, or provide reference material, but they will leave you with a good idea of what it’s possible to achieve in just a few steps, and how to go about it. Once you’re familiar with the basics presented in these tutorials, you’ll find the more in-depth coverage of the same topics in the How-to section. The tutorials follow a logical progression, starting from installation of django CMS and the creation of a brand new project, and build on each other, so it’s recommended to work through them in the order presented here. Installing django CMS We’ll get started by setting up our environment. Requirements django CMS requires Django 1.8, and Python 2.7, 3.3 or 3.4. Your working environment We’re going to assume that you have a reasonably recent version of virtualenv installed and that you have some basic familiarity with it. Create and activate a virtual env virtualenv env source env/bin/activate 11 django cms Documentation, Release 3.3.4 Note that if you’re using Windows, to activate the virtualenv you’ll need: env\Scripts\activate Use the django CMS installer The django CMS installer is a helpful script that takes care of setting up a new project. Install it: pip install djangocms-installer This provides you with a new command, djangocms. Create a new directory to work in, and cd into it: mkdir tutorial-project cd tutorial-project Run it to create a new Django project called mysite: djangocms-f-p. mysite This means: • run the django CMS installer • install Django Filer too (-f)- required for this tutorial • use the current directory as the parent of the new project directory (-p .) • call the new project directory mysite Note: About Django Filer Django Filer, a useful application for managing files and processing images. Although it’s not required for django CMS itself, a vast number of django CMS addons use it, and nearly all django CMS projects have it installed. If you know you won’t need it, omit the flag. See the django CMS installer documentation for more information. Warning: djangocms-installer expects directory . to be empty at this stage, and will check for this, and will warn if it’s not. You can get it to skip the check and go ahead anyway using the -s flag; note that this may overwrite existing files. Windows users may need to do a little extra to make sure Python files are associated correctly if that doesn’t work right away: assoc.py=Python.file ftype Python.File="C:\Users\Username\workspace\demo\env\Scripts\python.exe""%1"% * For the purposes of this tutorial, it’s recommended that you answer the installer’s questions as follows (where we suggest something different from the default, it’s indicated with an asterisk *). • Database configuration (in URL format): sqlite://localhost/project.db • django CMS version: stable • Django version: stable • Activate Django I18N / L10N setting: yes • Install and configure reversion support: yes 12 Chapter 5. Table of contents django cms Documentation, Release 3.3.4 • Languages to enable. Option can be provided multiple times, or as a comma separated list: en, de * • Optional default time zone: America/Chicago • Activate Django time zone support: yes • Activate CMS permission management: yes • Use Twitter Bootstrap Theme: yes * • Use custom template set: no • Load a starting page with examples after installation: yes * Create a Django admin user when invited. Start up the runserver python manage.py runserver Open http://localhost:8000/ in your browser, where you should be presented with your brand new django CMS homepage. Congratulations, you now have installed a fully functional CMS. To log in, append ?edit to the URL and hit enter. This will enable the toolbar, from where you can log in and manage your website. If you are not already familiar with django CMS, take a few minutes to run through the basics of the django CMS tutorial for users. Templates & Placeholders In this tutorial we’ll introduce Placeholders, and we’re also going to show how you can make your own HTML templates CMS-ready. Templates You can use HTML templates to customise the look of your website, define Placeholders to mark sections for managed content and use special tags to generate menus and more. You can define multiple templates, with different layouts or built-in components, and choose them for each page as required. A page’s template can be switched for another at any time. You’ll find the site’s templates in mysite/templates. If you didn’t change the automatically-created home page’s template, it’s feature.html. 5.1. Tutorials 13 django cms Documentation, Release 3.3.4 Placeholders Placeholders are an easy way to define sections in an HTML template that will be filled with content from the database when the page is rendered. This content is edited using django CMS’s frontend editing mechanism, using Django template tags. You can see them in feature.html: {% placeholder "feature" %} and {% placeholder "content" %}. You’ll also see {% load cms_tags %} in that file - cms_tags is the required template tag library. If you’re not already familiar with Django template tags, you can find out more in the Django documentation. Add a new placeholder {% placeholder "splashbox" %} to the template’s HTML structure. You can add it anywhere, for example: {% block content %} <div class="jumbotron"> {% placeholder "feature" %} </div> <div> {% placeholder "content" %} </div> <div> {% placeholder "splashbox" %} </div> {% endblock content %} If you switch to Structure mode, you’ll see the new placeholder available for use. Static Placeholders The content of the placeholders we’ve encountered so far is different for every page. Sometimes though you’ll want to have a section on your website which should be the same on every single page, such as a footer block.

Load more