Skip to content

Commit d4a7526

Browse files
fsbraunfsbraun
authored
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 f06afa1 commit d4a7526

File tree

3 files changed

+179
-20
lines changed

3 files changed

+179
-20
lines changed

‎docs/how_to/04-templates.rst

Lines changed: 175 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,27 +2,189 @@
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.
76

7+
Django's Template System
8+
========================
89

9-
static_alias
10-
------------
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 djangocms_alias_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_alias "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+
145+
146+
Static aliases
147+
==============
11148

12149
.. versionadded:: 4.0
13150

14151
.. note::
15152

16-
Using ``static_alias`` requires the installation of `djangocms-alias <https://github.com/django-cms/djangocms-alias>`_ to work.
153+
Using ``static_alias`` requires the installation of
154+
`djangocms-alias <https://github.com/django-cms/djangocms-alias>`_ to work.
155+
156+
The package `djangocms-alias <https://github.com/django-cms/djangocms-alias>`_
157+
provides an admin page in Django admin where special types of placeholders
158+
called "static aliases" can be managed and its contents edited.
159+
160+
Frequent Use Cases:
161+
162+
1. Editors wish to manage repeated content centrally (DRY - don't repeat
163+
yourself)
17164

165+
2. Developers wish to add CMS functionality to their custom application's
166+
templates
167+
168+
**Repeated content**: Often, content areas such as a footer, a header or a
169+
sidebar have identical content across all pages of a website.
170+
`djangocms-alias <https://github.com/django-cms/djangocms-alias>`_ provides
171+
a Django admin page for editors to manage such general site-wide content in
172+
one place.
173+
174+
**Custom applications**: Templates in custom applications usually follow some
175+
well-defined business logic which is normally hard-coded in the template.
176+
However the same templates might include areas of "static" content, i.e.
177+
content that editors wish to manage. As the django CMS :ttag:`placeholder` tag
178+
only work in templates attached to the django CMS
179+
:class:`~cms.models.pagemodel.Page` model,
180+
`djangocms-alias <https://github.com/django-cms/djangocms-alias>`_
181+
closes the gap by providing editors central access to such custom content areas.
18182

19-
Plain :ttag:`placeholder` cannot be used in templates used by external applications,
20-
use :ttag:`static_alias` instead.
21183

22184
.. _page_template:
23185

24186
CMS_TEMPLATE
25-
------------
187+
============
26188

27189
``CMS_TEMPLATE`` is a context variable available in the context; it contains
28190
the template path for CMS pages and application using apphooks, and the default
@@ -36,13 +198,17 @@ Example: cms template
36198

37199
.. code-block:: html+django
38200

39-
{% load cms_tags %}
201+
{% load cms_tags sekizai_tags %}
40202
<html>
203+
<head>
204+
{% render_block "css" %}
205+
</head>
41206
<body>
42207
{% cms_toolbar %}
43208
{% block main %}
44209
{% placeholder "main" %}
45210
{% endblock main %}
211+
{% render_block "js" %}
46212
</body>
47213
</html>
48214

@@ -62,10 +228,3 @@ Example: application template
62228

63229
``CMS_TEMPLATE`` memorises the path of the cms template so the application
64230
template can dynamically import it.
65-
66-
67-
render_model
68-
------------
69-
70-
:ttag:`render_model` allows to edit the django models from the frontend by
71-
reusing the django CMS frontend editor.

‎docs/introduction/01-install.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -223,7 +223,7 @@ template. It performs the following five steps in one simple go:
223223
- `djangocms_admin_style <https://github.com/django-cms/djangocms-admin-style>`_ for
224224
a consistent user experience with django CMS and Django admin.
225225

226-
3. It changes into the project directory and runs the ``migrate`` command to create the
226+
3. It changes into the project directory and runs the ``migrate`` command to create the
227227
database:
228228

229229
.. code-block::
@@ -273,7 +273,7 @@ We suggest to use pip-compile to freeze your requirements as, for example, discu
273273
Spin up your Django development server (Step 3)
274274
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
275275

276-
Now you are ready to spin up Django's development server by first changing directory into
276+
Now you are ready to spin up Django's development server by first changing directory into
277277
the project folder and then spinning up the development server:
278278

279279
.. code-block::
@@ -295,7 +295,7 @@ CMS to any Django project. It will require some settings to be modified, however
295295
Minimally-required applications and settings
296296
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
297297

298-
To run djanog CMS you will only need to modify the ``settings.py`` and ``urls.py``
298+
To run django CMS you will only need to modify the ``settings.py`` and ``urls.py``
299299
files.
300300

301301
Open the new project's ``settings.py`` file in your text editor.

‎setup.cfg

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,5 +67,5 @@ bcrypt = bcrypt
6767
universal=1
6868

6969
[codespell]
70-
ignore-words-list = cant,statics,groupe,manuel,uptodate
70+
ignore-words-list = cant,statics,groupe,manuel,uptodate,assertIn
7171
skip = package-lock.json,*.js,*.js.html,*.po,./node_modules/*,./.idea/*,./docs/env/*,./docs/build/*,./.env/*,./.venv/*,./build/*,./django_cms.egg-info/*,./.git,./cms/test_utils/project/sampleapp/models.py,./venv/*,./docs/spelling_wordlist

0 commit comments

Comments
 (0)