Skip to content

Commit 0258a2a

Browse files
fsbraunfsbraun
authored
Merge 753e0d2 into 201236a 
2 parents 201236a + 753e0d2 commit 0258a2a

File tree

3 files changed

+159
-20
lines changed

3 files changed

+159
-20
lines changed

‎docs/how_to/04-templates.rst‎

Lines changed: 155 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,27 +2,169 @@
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 comes with a default template that for
43+
reasons of convenience is provided by
44+
`django CMS frontend <https://github.com/django-cms/djangocms-frontend>`_
45+
and based on Bootstrap. We encourage you to create your own templates
46+
as you would do for any Django project.
47+
48+
49+
CMS templates
50+
-------------
51+
52+
You need to configure which templates django CMS should use. You can do this by
53+
either setting the :setting:`CMS_TEMPLATES` or the :setting:`CMS_TEMPLATES_DIR`
54+
settings.
55+
56+
You can select the template by page (and language) in the page menu of django
57+
CMS' toolbar. By default, a page inherits its template from its parent page.
58+
A root page uses the first template in :setting:`CMS_TEMPLATES` if no other
59+
template is explicitly set.
60+
61+
To work seamlessly with django CMS, **your templates should include the**
62+
``{% cms_toolbar %}`` **tag right as the first item in your template's**
63+
``<body>``. This tag will render the toolbar for logged-in users.
64+
65+
.. note::
66+
67+
The toolbar can also be displayed in views independent of django CMS.
68+
To provide a consistent user experience, many projects include the toolbar
69+
in their base template and share it with the whole Django project.
70+
71+
72+
Also, you need to tell django CMS where to place the content of your pages. This
73+
is done using **placeholders**. A placeholder is a named area in your template
74+
where you can add content plugins. You can add as many placeholders as you want
75+
to your templates.
76+
77+
To add a placeholder to your template, use the
78+
``{% placeholder "name" %}`` template tag. The name is the name of the template
79+
slot. It will be shown in the structure board of the frontend editor. Typical
80+
names are "main", "sidebar", "footer", etc.
81+
82+
Finally, you need to add ``{% render_block "css" %}`` in the ``<head>`` section
83+
of your CMS templates and ``{% render_block "js" %}`` right before the closing
84+
``</body>`` tag of your CMS templates. This will render the CSS and JavaScript
85+
at the appropriate places in your CMS templates.
86+
87+
django CMS uses `django-sekizai <https://github.com/django-cms/django-sekizai>`_
88+
to manage CSS and JavaScript. To use the sekizai tags, you need to load the
89+
``sekizai_tags`` template tags in your template: ``{% load sekizai_tags %}``.
90+
91+
Example
92+
-------
93+
94+
Here is an example of a simple template that uses placeholders:
95+
96+
.. code-block:: html+django
97+
98+
{% extends "base.html" %}
99+
{% load cms_tags djangocms_alias_tags %}
100+
{% block title %}{% page_attribute "page_title" %}{% endblock title %}
101+
{% block content %}
102+
<header>
103+
{% placeholder "header" %}
104+
</header>
105+
<main>
106+
{% placeholder "main" %}
107+
</main>
108+
<footer>
109+
{% static_alias "footer" %}
110+
</footer>
111+
{% endblock content %}
112+
113+
In this example, the template extends the base template, sets the title of the
114+
page, and defines three placeholders: "header", "main", and "footer". The
115+
placeholders are then rendered in the template.
116+
117+
The underlying base template could look like this:
118+
119+
.. code-block:: html+django
120+
121+
{% load cms_tags sekizai_tags %}
122+
<!DOCTYPE html>
123+
<html>
124+
<head>
125+
<title>{% block title %}{% endblock title %}</title>
126+
{% render_block "css" %}
127+
</head>
128+
<body>
129+
{% cms_toolbar %}
130+
{% block content %}{% endblock content %}
131+
{% render_block "js" %}
132+
</body>
133+
</html>
134+
135+
136+
137+
Static aliases
138+
==============
11139

12140
.. versionadded:: 4.0
13141

14142
.. note::
15143

16-
Using ``static_alias`` requires the installation of `djangocms-alias <https://github.com/django-cms/djangocms-alias>`_ to work.
144+
Using ``static_alias`` requires the installation of
145+
`djangocms-alias <https://github.com/django-cms/djangocms-alias>`_ to work.
146+
147+
Since some content repeats on multiple pages, it is useful to create a static
148+
alias for it. This way, you can edit the content in one place and have it
149+
change on all pages where the alias is used.
150+
151+
Example uses for static aliases are the footer, the sidebar, or the header.
152+
153+
While the :ttag:`placeholder` tag cannot be used in templates outside django CMS,
154+
any application can use the :ttag:`static_alias` tag to include the content
155+
created in django CMS for an alias.
156+
157+
158+
:ttag:`render_model` allows to edit frontend-enabled Django models reusing the
159+
django CMS frontend editor. See :ref:`_placeholders_outside_cms` for more
160+
information.
17161

18162

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

22164
.. _page_template:
23165

24166
CMS_TEMPLATE
25-
------------
167+
============
26168

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

37179
.. code-block:: html+django
38180

39-
{% load cms_tags %}
181+
{% load cms_tags sekizai_tags %}
40182
<html>
183+
<head>
184+
{% render_block "css" %}
185+
</head>
41186
<body>
42187
{% cms_toolbar %}
43188
{% block main %}
44189
{% placeholder "main" %}
45190
{% endblock main %}
191+
{% render_block "js" %}
46192
</body>
47193
</html>
48194

@@ -62,10 +208,3 @@ Example: application template
62208

63209
``CMS_TEMPLATE`` memorises the path of the cms template so the application
64210
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)