8000 docs: Improve explanation on how to use templates with django CMS (#7… · django-cms/django-cms@a88b1e8 · GitHub
[go: up one dir, main page]
Skip to content

Commit a88b1e8

Browse files
fsbraunfsbraun
committed
docs: Improve explanation on how to use templates with django CMS (#7929)
* docs: Improve docs on how to use templates * Fix typos, add `assertIn` to word list * Update setup.cfg * Remove "while" * Clarify use of CSS and JS libraries * Fix references. * Update djangocms-alias section * Update 04-templates.rst: Add missing space
1 parent 3922612 commit a88b1e8

File tree

1 file changed

+146
-3
lines changed

1 file changed

+146
-3
lines changed

‎docs/how_to/templates.rst

Lines changed: 146 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,146 @@
22
How 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

9147
static_placeholder
@@ -12,6 +150,7 @@ static_placeholder
12150
Plain :ttag:`placeholder` cannot be used in templates used by external applications,
13151
use :ttag:`static_placeholder` instead.
14152

153+
15154
.. _page_template:
16155

17156
CMS_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

Comments
 (0)
0