22How to work with templates
33##########################
44
5- Application can reuse cms templates by mixing cms template tags and normal django
6- templating language.
5+ django CMS uses Django's template system to manage the layout of the CMS pages.
6+
7+ Django's Template System
8+ ========================
9+
10+ Django’s template language is designed to strike a balance between power and
11+ ease. It’s designed to feel comfortable to those used to working with HTML.
12+ If you have any exposure to other text-based template languages, such as Smarty
13+ or Jinja2, you should feel right at home with Django’s templates.
14+
15+ The template system, out of the box, should be familiar to those who have
16+ worked with desktop publishing or web design. Tags are surrounded by {% and %}
17+ and denote the actions like loops and conditionals. Variables are surrounded by
18+ {{ and }} and get replaced with values when the template is rendered.
19+
20+ Learn more about Django's template system in the
21+ `Django documentation <https://docs.djangoproject.com/en/dev/topics/templates/ >`_.
22+
23+
24+ Django CMS and Django's Template System
25+ =======================================
26+
27+ Django templates
28+ ----------------
29+
30+ You are totally free on how to name your templates, but we encourage you
31+ to use the general Django conventions, including letting all templates inherit
32+ from a base template by using the ``extends `` template tag or putting templates
33+ in a folder named after the application providing it.
34+
35+ .. note ::
36+
37+ Some django CMS apps, like django CMS Alias, assume the base template is
38+ called ``base.html ``. If you happen to prefer a different name for the base
39+ template and need to use such apps, you can create a ``base.html `` template
40+ that just consists of the ``{% extends "your_base_template.html" %} `` tag.
41+
42+ A fresh installation of django CMS using the quickstarter project or the
43+ ``djangocms `` command comes with a default template that for reasons of
44+ convenience is provided by
45+ `django CMS frontend <https://github.com/django-cms/djangocms-frontend >`_
46+ and based on Bootstrap. We encourage you to create your own templates
47+ as you would do for any Django project.
48+
49+ Generally speaking, django CMS is wholly frontend-agnostic. It doesn’t care
50+ what your site’s frontend is built on or uses: You are free to decide which
51+ CSS framework or JS library to use (if any).
52+
53+ When editing, the frontend editor will replace part of the current document's
54+ DOM. This might require some JS widgets to be reinitialized.
55+ See :ref: `frontend-integration ` for more information.
56+
57+
58+ CMS templates
59+ -------------
60+
61+ You need to configure which templates django CMS should use. You can do this by
62+ either setting the :setting: `CMS_TEMPLATES ` or the :setting: `CMS_TEMPLATES_DIR `
63+ settings.
64+
65+ You can select the template by page (and language) in the page menu of django
66+ CMS' toolbar. By default, a page inherits its template from its parent page.
67+ A root page uses the first template in :setting: `CMS_TEMPLATES ` if no other
68+ template is explicitly set.
69+
70+ To work seamlessly with django CMS, **your templates should include the **
71+ ``{% cms_toolbar %} `` **tag right as the first item in your template's **
72+ ``<body> ``. This tag will render the toolbar for logged-in users.
73+
74+ .. note ::
75+
76+ The toolbar can also be displayed in views independent of django CMS.
77+ To provide a consistent user experience, many projects include the toolbar
78+ in their base template and share it with the whole Django project.
79+
80+
81+ Also, you need to tell django CMS where to place the content of your pages. This
82+ is done using **placeholders **. A placeholder is a named area in your template
83+ where you can add content plugins. You can add as many placeholders as you want
84+ to your templates.
85+
86+ To add a placeholder to your template, use the
87+ ``{% placeholder "name" %} `` template tag. The name is the name of the template
88+ slot. It will be shown in the structure board of the frontend editor. Typical
89+ names are "main", "sidebar", "footer", etc.
90+
91+ Finally, you need to add ``{% render_block "css" %} `` in the ``<head> `` section
92+ of your CMS templates and ``{% render_block "js" %} `` right before the closing
93+ ``</body> `` tag of your CMS templates. This will render the CSS and JavaScript
94+ at the appropriate places in your CMS templates.
95+
96+ django CMS uses `django-sekizai <https://github.com/django-cms/django-sekizai >`_ 97+ to manage CSS and JavaScript. To use the sekizai tags, you need to load the
98+ ``sekizai_tags `` template tags in your template: ``{% load sekizai_tags %} ``.
99+
100+ Example
101+ -------
102+
103+ Here is an example of a simple template that uses placeholders:
104+
105+ .. code-block :: html+django
106+
107+ {% extends "base.html" %}
108+ {% load cms_tags %}
109+ {% block title %}{% page_attribute "page_title" %}{% endblock title %}
110+ {% block content %}
111+ <header>
112+ {% placeholder "header" %}
113+ </header>
114+ <main>
115+ {% placeholder "main" %}
116+ </main>
117+ <footer>
118+ {% static_placeholder "footer" %}
119+ </footer>
120+ {% endblock content %}
121+
122+ In this example, the template extends the base template, sets the title of the
123+ page, and defines three placeholders: "header", "main", and "footer". The
124+ placeholders are then rendered in the template.
125+
126+ The underlying base template could look like this:
127+
128+ .. code-block :: html+django
129+
130+ {% load cms_tags sekizai_tags %}
131+ <!DOCTYPE html>
132+ <html>
133+ <head>
134+ <title>{% block title %}{% endblock title %}</title>
135+ {% render_block "css" %}
136+ </head>
137+ <body>
138+ {% cms_toolbar %}
139+ {% block content %}{% endblock content %}
140+ {% render_block "js" %}
141+ </body>
142+ </html>
143+
144+
7145
8146
9147static_placeholder
@@ -12,6 +150,7 @@ static_placeholder
12150Plain :ttag: `placeholder ` cannot be used in templates used by external applications,
13151use :ttag: `static_placeholder ` instead.
14152
153+
15154.. _page_template :
16155
17156CMS_TEMPLATE
@@ -29,13 +168,17 @@ Example: cms template
29168
30169.. code-block :: html+django
31170
32- {% load cms_tags %}
171+ {% load cms_tags sekizai_tags %}
33172 <html>
173+ <head>
174+ {% render_block "css" %}
175+ </head>
34176 <body>
35177 {% cms_toolbar %}
36178 {% block main %}
37179 {% placeholder "main" %}
38180 {% endblock main %}
181+ {% render_block "js" %}
39182 </body>
40183 </html>
41184
0 commit comments