Skip to content

Commit b685dfb

Browse files
fsbraunfsbraun
committed
add docs
1 parent 17fc6e5 commit b685dfb

File tree

6 files changed

+224
-10
lines changed

6 files changed

+224
-10
lines changed

‎.github/workflows/codecov.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,9 @@ jobs:
3232
uses: actions/setup-python@v5
3333
with:
3434
python-version: ${{ matrix.python-version }}
35-
- name: Intall dependencies
35+
- name: Install dependencies
3636
run: |
37-
pip install -r tests/requirements/${{ matrix.requirements-file }}
37+
pip install -U -r tests/requirements/${{ matrix.requirements-file }}
3838
- name: Run coverage
3939
run: |
4040
coverage run -m pytest

‎docs/source/how-to/add-frontend-plugins.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _how-to-add-frontend-plugins:
2+
13
How to add your own frontend plugin
24
===================================
35

‎docs/source/tutorial/components.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,8 @@ Configuration
5959

6060
1. **Add Installed Apps**
6161

62-
Open your Django project's ``settings.py`` and add the following applications to ``INSTALLED_APPS``:
62+
Open your Django project's ``settings.py`` and add the following applications to ``INSTALLED_APPS`` -
63+
you only need (and should) add the components you want content editors to use:
6364

6465
.. code-block:: python
6566

‎docs/source/tutorial/custom_components.rst‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,23 @@ require additional listing in the ``INSTALLED_APPS`` setting.
3131
either keep components together in one theme app, or keep them with where
3232
they are used in different custom apps.
3333

34+
Directory Structure
35+
-------------------
36+
37+
Custom components live in the ``cms_componenty`` module of any of your apps.
38+
Ensure your app has the following structure::
39+
40+
theme/
41+
cms_components.py
42+
migrations/
43+
models.py
44+
templates/
45+
components/
46+
hero.html
47+
views.py
48+
admin.py
49+
50+
3451
Let's go through this by creating a theme app::
3552

3653
python manage.py startapp theme
@@ -83,7 +100,7 @@ The template could be, for example:
83100

84101
.. code-block:: html
85102

86-
<!-- theme/components/hero.html -->
103+
<!-- theme/templates/components/hero.html -->
87104
{% load cms_tags frontend sekizai_tags %}
88105
<section class="bg-white dark:bg-gray-900">
89106
<div class="grid max-w-screen-xl px-4 py-8 mx-auto lg:gap-8 xl:gap-0 lg:py-16 lg:grid-cols-12">

‎docs/source/tutorial/index.rst‎

Lines changed: 37 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,48 @@
11
.. index::
22
single: Tutorial
33

4-
##########
5-
Tutorial
6-
##########
4+
#################
5+
Getting Started
6+
#################
7+
8+
When working with components in djangocms-frontend, you can choose from different
9+
approaches depending on your needs. These range from using pre-built Bootstrap 5
10+
components, over quick and simple methods to create your own custom components to
11+
more flexible but complex solutions. We recommend staying with the simplest approach
12+
that gets the job done for your project.
13+
14+
1. **Pre-Built Components** – The easiest way to **get started** with djangocms-frontend.
15+
Pre-built components are ready to use and require no additional configuration.
16+
They are perfect for quickly setting up a website with a variety of components
17+
that are compatible with Bootstrap 5. Pre-built components need to be explicitly
18+
added to your project's ``INSTALLED_APPS``.
19+
20+
2. **Template-Based Components** – The easiest approach creating or porting your own
21+
**custom components**, allowing you define components by their HTML templates. Special
22+
djangocms-frontend tags are used to provide the additional declarative information
23+
needed. This is the fastest approach to create djangocms-frontend components.
24+
Template-based (or auto) components are auto-detected.
25+
26+
3. **Custom Component Development** – A more advanced method that lets you create
27+
custom components with **minimal code**. This approach is more flexible than the
28+
template-based method, but requires some Python coding providing more control over
29+
the components add and change forms, for example.
30+
31+
4. **Custom Plugin Development** – The most advanced option, where you create fully-fledged
32+
custom plugins, giving you maximum control over functionality, rendering, and
33+
integration with other parts of your project. This approach is the most flexible,
34+
but also the most complex, since template, plugin, and forms need to be created.
35+
For custom plugin development, see the :ref:`how-to-add-frontend-plugins` guide.
36+
37+
38+
Tutorials
39+
#########
740

8-
The first tutoral shows how to quickly build a website using Bootstrap 5, django CMS frontend and
9-
its pre-built components.
1041

11-
The second tutorial guides you through creating custom components with minimal code.
1242

1343
.. toctree::
1444
:maxdepth: 1
1545

1646
components
47+
template_components
1748
custom_components

‎docs/source/tutorial/template_components.rst‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
.. _template_components:
2+
3+
############################
4+
Building Template Components
5+
############################
6+
7+
.. index::
8+
single: Template Components
9+
single: Auto Components
10+
11+
.. versionadded:: 2.1
12+
13+
Custom components are a powerful tool for content editors, allowing them to build pages without needing
14+
in-depth knowledge of design, HTML, or nested structures. Editors can simply add content to pre-defined
15+
components, creating visually cohesive pages with ease.
16+
17+
When working with `Tailwind CSS <https://tailwindcss.com>`_, for example, you
18+
either create your custom components or customize components from providers,
19+
e.g. `Tailwind UI <https://tailwindui.com>`_,
20+
`Flowbite <https://flowbite.com>`_, or the community
21+
`Tailwind Components <https://tailwindcomponents.com>`_.
22+
23+
With django CMS you make your components available to the content editors to
24+
simply add them to a page by a click **and** frontend developers for use in templates from a single
25+
source.
26+
27+
Custom components are part of the djangocms-frontend root package and do not
28+
require additional listing in the ``INSTALLED_APPS`` setting.
29+
30+
djangocms-frontend allows developers to extend its functionality by creating
31+
template components**. In this tutorial, we will create an **Hero component**
32+
with the following fields:
33+
34+
- ``title``: A required text field.
35+
- ``slogan``: A required text area field.
36+
- ``hero_image``: A required image field.
37+
38+
This component will be stored in a template directory named ``<app_name>/cms_components``,
39+
as required for djangocms-frontend template components.
40+
41+
Directory Structure
42+
-------------------
43+
44+
The templte component lives in the template directory of any of your apps.
45+
Ensure your DjangoCMS app has the following structure::
46+
47+
theme_app/
48+
migrations/
49+
models.py
50+
templates/
51+
theme_app/
52+
cms_components/
53+
hero.html
54+
views.py
55+
admin.py
56+
57+
Creating the Template Component
58+
--------------------------------
59+
60+
The **template component** must be stored in the ``cms_components`` directory
61+
inside your app. djangocms-frontend expects you to follow Django's template
62+
namespace convention. Create a new file at::
63+
64+
theme_app/templates/theme_app/cms_components/hero.html
65+
66+
.. note::
67+
No python code is required to create the component. The component is
68+
defined in the template itself.
69+
70+
Then, add the following code::
71+
72+
<!-- theme_app/templates/theme_app/cms_components/hero.html -->
73+
{% load frontend cms_component %}
74+
75+
{# Declare component - template tags are evaluated at project startup and will render empty #}
76+
{% cms_component "Hero" name=_("My Hero Component") %}
77+
{% field "title" forms.CharField required=True name=_("Title") %}
78+
{% field "slogan" forms.CharField required=True name=_("Slogan") widget=forms.Textarea %}
79+
{% field "hero_image" ImageFormField required=True name=_("Image") help_text=_("At least 1024px wide image") %}
80+
81+
{# Actual template - when rendering, declared fields are available in the context #}
82+
<section class="bg-white dark:bg-gray-900">
83+
<div class="grid max-w-screen-xl px-4 py-8 mx-auto lg:gap-8 xl:gap-0 lg:py-16 lg:grid-cols-12">
84+
<div class="mr-auto place-self-center lg:col-span-7">
85+
<h1 class="max-w-2xl mb-4 text-4xl font-extrabold tracking-tight leading-none md:text-5xl xl:text-6xl dark:text-white">
86+
{{ title }}
87+
</h1>
88+
<p class="max-w-2xl mb-6 font-light text-gray-500 lg:mb-8 md:text-lg lg:text-xl dark:text-gray-400">
89+
{{ slogan }}
90+
</p>
91+
{% childplugins %}{% endchildplugins %}
92+
</div>
93+
<div class="hidden lg:mt-0 lg:col-span-5 lg:flex">
94+
<img src="{{ hero_image.url }}">
95+
</div>
96+
</div>
97+
</section>
98+
99+
Understanding the Code
100+
----------------------
101+
102+
Component Declaration
103+
^^^^^^^^^^^^^^^^^^^^^
104+
105+
::
106+
107+
{% cms_component "Hero" name=_("My Hero Component") %}
108+
109+
This tag **declares** the component and assigns it a name (``Hero``). This is used internally
110+
by django CMS to identify the plguin later. The ``name`` parameter is used to display the
111+
component in the CMS admin interface. Internally the command declares a ``CMSFrontendComponent``
112+
class. All named arguments are added to the component's Meta class.
113+
114+
Defining Fields
115+
^^^^^^^^^^^^^^^
116+
117+
::
118+
119+
{% field "title" forms.CharField required=True name=_("Title") %}
120+
{% field "slogan" forms.CharField required=True name=_("Slogan") widget=forms.Textarea %}
121+
{% field "hero_image" ImageFormField required=True name=_("Image") help_text=_("At least 1024px wide image") %}
122+
123+
Each ``{% field %}`` tag defines a form field that content editors can use when configuring the component in the CMS.
124+
The first parameter is the field name which is then available in the rest of the template. The second parameter is the
125+
form field class to use. The remaining parameters are passed to the form field constructor.
126+
127+
By default, Django's ``django.forms`` module is available as ``forms`` in the template context. If the relevant apps are
128+
installed, additional fields available are ``HTMLFormField`` for rich text, ``LinkFormField`` for links, and ``ImageFormField``
129+
for images.
130+
131+
Rendering the Component
132+
^^^^^^^^^^^^^^^^^^^^^^^
133+
134+
After the fields are declared, the remaining part of the template is dedicated to rendering the component.
135+
The fields declared earlier (``title``, ``slogan``, and ``hero_image``) are now available as template variables::
136+
137+
<h1>{{ title }}</h1>
138+
<p>{{ slogan }}</p>
139+
<img src="{{ hero_image.url }}">
140+
141+
The ``{% childplugins %}`` block allows additional CMS plugins (like buttons) to be added inside the component
142+
in the structure editor.
143+
144+
Make the component avialabvle in django CMS
145+
-------------------------------------------
146+
147+
Template components are discovered automatically - no more coding is required. If you change the declarative
148+
content, i.e. add/remove ``{% field %}`` tags, or change the ``{% cms_component %}`` tag, you need to restart
149+
the Django server to apply the changes.
150+
151+
1. Restart your Django server.
152+
2. Create a new page end edit it.
153+
3. Add a new **Hero component** to a page from the plugin picker.
154+
4. Fill in the **title**, **slogan**, and **hero image** fields.
155+
5. Save and publish the page.
156+
157+
Conclusion
158+
----------
159+
160+
You have successfully created a **djangocms-frontend template component** using ``cms_component``!
161+
This structure allows editors to easily customize hero sections while maintaining a reusable
162+
and structured design.
163+

0 commit comments

Comments
 (0)