Here’s a step-by-step tutorial to get you started with djangocms-frontend, a versatile plugin bundle for django CMS that provides a suite of frontend components compatible with various CSS frameworks, including Bootstrap 5.
For this tutorial we will be using the built-in Boostrap 5 components that come with djangocms-frontend.
To install djangocms-frontend, follow these steps:
Install the package using pip:
pip install djangocms-frontend
Alternatively, you can add djangocms-frontend to your requirements.txt file and install it via:
pip install -r requirements.txt
Install optional dependencies (if needed):
Depending on your project’s requirements, you may need additional dependencies:
For icon support with djangocms-icon and not the build-in icon plugin:
pip install djangocms-frontend[djangocms-icon]
To include the Ace code editor in static files (if, e.g., your project does not have access to the internet where django CMS loads static ace from a CDN):
pip install djangocms-frontend[static-ace]
To install multiple optional dependencies at once:
pip install djangocms-frontend[static-ace,djangocms-icon]
Add Installed Apps
Open your Django project’s settings.py and add the following applications to INSTALLED_APPS - you only need (and should) add the components you want content editors to use:
INSTALLED_APPS = [
# Optional dependencies
'djangocms_icon',
'easy_thumbnails',
'djangocms_link', # Required if djangocms_frontend.contrib.link is used
# Main frontend components
'djangocms_frontend',
'djangocms_frontend.contrib.accordion',
'djangocms_frontend.contrib.alert',
'djangocms_frontend.contrib.badge',
'djangocms_frontend.contrib.card',
'djangocms_frontend.contrib.carousel',
'djangocms_frontend.contrib.collapse',
'djangocms_frontend.contrib.component',
'djangocms_frontend.contrib.content',
'djangocms_frontend.contrib.grid',
'djangocms_frontend.contrib.icon',
'djangocms_frontend.contrib.image',
'djangocms_frontend.contrib.jumbotron',
'djangocms_frontend.contrib.link',
'djangocms_frontend.contrib.listgroup',
'djangocms_frontend.contrib.media',
'djangocms_frontend.contrib.tabs',
'djangocms_frontend.contrib.utilities',
]
Apply Migrations
Run the following command to create the necessary database tables:
djangocms-frontend does not automatically include CSS or JavaScript files. You need to manually add them to your templates.
Using Bootstrap 5 templates (recommended to get started quickly)
The package is designed to work with Bootstrap 5 by default. If you want to use Bootstrap 5, extend the default template like this:
{% extends "bootstrap5/base.html" %}
{% block brand %}<a href="/">My Site</a>{% endblock %}
This will load Bootstrap 5 CSS and JS from a CDN.
Note
We recommend developing your own base.html for your projects. The example templates load CSS and JS files from a CDN. Good reasons to do so are
djangocms-frontend does not contain CSS or JS files from Bootstrap or any other framework for that matter. The example templates load CSS and JS from a CDN.
It is considered safer to host CSS and JS files yourself. Otherwise you do not have control over the CSS and/or JS that is delivered.
It is a common practice to customize at least the CSS part, e.g. with brand colors.
You might have a totally different build process for your styling assets, especially if you use other frameworks, such as Tailwind CSS.
Custom Templates
If you prefer to manage assets locally, download Bootstrap 5, customize as needed, and include it in your template:
<!DOCTYPE html>
<html lang="en">
<head>
<link rel="stylesheet" href="{% static 'css/bootstrap.min.css' %}">
</head>
<body>
<script src="{% static 'js/bootstrap.bundle.min.js' %}"></script>
</body>
</html>
djangocms-frontend’s built-in templates allow for extensive customization through Django template blocks. Some key blocks you can override:
The example template is customisable by a set of template blocks:
{% block title %}
Renders the page title. Defaults to {% page_attribute "page_title" %}
{% block content %}
Here goes the main content of the page. The default setup is a <section> with a placeholder called “Page Content”:
{% block content %}
<section>
{% placeholder "Page Content" %}
</section>
{% endblock content %}
{% block navbar %}
This block renders a navigation bar using the Bootstrap 5 navbar classes and django CMS’ menu system. If you need to add additional navigation on the right hand side of the nav bar populate the block searchbar (which can include a search function but does not have to). Also, the block brand is rendered in the navigation bar.
{% block base_css %}
Loads the framework’s CSS. Replace this block if you prefer to include your the CSS from your server.
{% block base_js %}
Loads the framework’s JS. Replace this block if you prefer to include your the JS from your server. JS is loaded before {% render_block 'js' %}.
{% block end_js %}
Loads additional JS at the end of the page. Currently empty. This block is loaded after {% render_block 'js' %}.
{% block bottom_css %}
Additional CSS placed just before the end of the <body>. Currently empty.
{% block meta %}
Contains the meta description of the page. Defaults to:
<meta name="description" content="{% page_attribute meta_description %}"/>
<meta property="og:type" content="website"/>
<meta property="og:title" content="{% page_attribute "page_title" %}"/>
<meta property="og:description" content="{% page_attribute meta_description %}"/>
{% block canonical_url %}
Contains the canonical url of the page. Defaults to:
<link rel="canonical" href="{{ request.build_absolute_uri }}"/>
<meta property="og:url" content="{{ request.build_absolute_uri }}"/>
If you have restricted rights for users our groups in your projects make sure that editors have the right to add, change, delete, and - of course - view instances of all djangocms_frontend UI items:
Accordion
Alert
Badge
Card
Carousel
Collapse
Content
Forms
Grid
Icon
Image
Jumbotron
Link
Listgroup
Media
Tabs
Utilities
Otherwise the plugins will not be editable and will not appear in the editors’ plugin selection when adding a plugin in the frontend.
Since changing them for each of the plugins manually can become tiresome a management command can support you.
First manually define the permissions for the model FrontendUIItem of the app djangocms_frontend. Then you can synchronize all permissions of the installed UI items by typing
./manage.py frontend sync_permissions users ./manage.py frontend sync_permissions groups
These commands transfer the permissions for FrontendUIItem to all installed plugins for each user or group, respectively.
The first command is only necessary of you define by-user permissions. Depending on the number of users it may take some time.
Limitations of built-in components¶Built-in components are a powerful tool for content editors, especially if they are used to using the Bootstrap CSS framework. Those components are both portable to other frameworks and extensible (see How to extend built-in components) But they have some limitations:
Deep nesting: The Bootstrap 5-based components will require some nesting, e.g., a text inside a card inner inside a card inside a column inside a row inside a container will be a regular example. For some editors this might be confusing, or at least something to get used to. Also, large plugin trees in the structure board are more difficult to navigate.
So even if you are working with the Bootstrap 5 framework you might consider using a template component to cover typical use cases.
“Bootstrappyness”: Bootstrap is a powerful framework, but contains certain potentially oppinionated design decisions which reflect in the type of built-in components are included with djangocms-frontend.
Need for customization: Most websites will require some customization of the design. To use the built-in components as a starting point is a good idea, but you will need to customize Bootstrap to fit your design. See the Bootstrap documentation for more information.
Now that you have installed and configured djangocms-frontend, explore additional features such as:
Creating template components or custom frontend components.
Using advanced layout features.
Integrating with third-party frameworks.
For more details, refer to the official documentation: https://djangocms-frontend.readthedocs.io/en/latest/
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4