8000 docs: Improve explanation on how to use templates with django CMS (#7… · django-cms/django-cms@d4a7526 · GitHub
[go: up one dir, main page]
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)