DOCSEARCHbyAlgolia
Submit Docs

django-bootstrap5

repository·main·Indexed 19 days ago

https://github.com/zostera/django-bootstrap5

A library for integrating Bootstrap 5 styling into Django applications via template tags. It provides tools to render Bootstrap 5 CSS, JavaScript, forms, buttons, and Django messages as alerts. Key features include support for floating labels, horizontal form layouts, input groups, and a customizable BOOTSTRAP5 settings dictionary for asset URLs and layout configurations.

Tokens
11.1K
Snippets
44
Records
55
Agent score
65%

What's inside django-bootstrap5

  1. Use Input Groups for complex fields

    main

    Bootstrap 5 Input groups allow you to combine fields with add-ons (text or buttons) placed either before or after the input.

    django-bootstrap5 supports:

    • Separate rendering of labels, fields, help texts, and errors to allow for custom input group construction.
    • Support for addon_before and addon_after as part of bootstrap_field.
    • Defining add-ons via Python code in the form, field, or widget definition.

    Note: When using input groups, ensure the parent container has the has-validation class as required by Bootstrap 5.

  2. Handle jQuery and Popper.js dependencies

    main

    Bootstrap 5 no longer depends on jQuery, and django-bootstrap5 has removed all tags and functions referencing it.

    • jQuery: If your project requires jQuery, you must include it manually in your templates.
    • Popper.js: django-bootstrap5 uses the bundled version of Bootstrap 5 JavaScript which includes Popper. If you require a separate Popper.js file, do not use the {% bootstrap_javascript %} tag; instead, load the JavaScript files manually.

  3. Understand the structure of a rendered field

    main

    When using django-bootstrap5 to render form fields, each field is composed of several components rendered in a specific order (which may vary by widget type). A standard rendered field includes:

    • wrapper: A container (typically with a class like mb-3).
    • label (optional): Rendered with the form-label class.
    • field: The actual input element (e.g., with form-control).
    • help text (optional): Rendered with the form-text class.
    • validation texts (optional): Rendered with classes like valid-feedback or invalid-feedback.

    This structure is managed through bootstrap_formset, bootstrap_form, and bootstrap_field to ensure a sensible default Bootstrap 5 layout.

    <div class="mb-3"> <!-- wrapper start -->
    <label for="name" class="form-label">Email address</label> <!-- label -->
    <input type="text" class="form-control" id="name" aria-describedby="nameHelp"> <!-- field -->
    <div id="nameHelp" class="form-text">An alias is fine.</div> <!-- help text -->
    <div class="valid-feedback">Looks good!</div> <!-- validation text -->
</div>

  6. Customize field help text and errors template

    main

    You can override the default rendering of field help text and errors by providing your own template at django_bootstrap5/field_help_text_and_errors.html.

    When writing this template, the variable help_text_and_errors is available as an array of strings containing the relevant messages.

  7. Install django-bootstrap5 via pip

    main

    The preferred method for installing django-bootstrap5 is using pip. It is recommended to use a virtualenv for your Python development environment.

    To install the package, run:

    $ pip install django-bootstrap5

    If you have cloned the repository locally, you can install it in editable mode from the project folder:

    $ pip install -e .

    Ensure you add django-bootstrap5 to your project's requirements.txt file.

  8. Customize Django messages template

    main

    You can customize the rendering of Django messages by overriding django_bootstrap5/messages.html.

    The template has access to the messages variable. By default, the library applies the following three built-in Django filters to the messages:

    • safe
    • urlize
    • linebreaksbr

  9. Integrate django-bootstrap5 into Django templates

    main

    To use django-bootstrap5 in your templates, you must first load the tag library using {% load django_bootstrap5 %}.

    Once loaded, you can use the following tags to include necessary assets and UI components:

    • {% bootstrap_css %}: Renders the Bootstrap 5 CSS link tag.
    • {% bootstrap_javascript %}: Renders the Bootstrap 5 JavaScript script tag.
    • {% bootstrap_messages %}: Automatically renders Django's django.contrib.messages as Bootstrap alerts.
    • {% bootstrap_form form %}: Renders a Django form using Bootstrap 5 styling and classes.
    • {% bootstrap_button button_type="..." content="..." %}: Renders a Bootstrap-styled button.
    {# Load the tag library #}
{% load django_bootstrap5 %}

{# Load CSS and JavaScript #}
{% bootstrap_css %}
{% bootstrap_javascript %}

{# Display django.contrib.messages as Bootstrap alerts #}
{% bootstrap_messages %}

{# Display a form #}
<form action="/url/to/submit/" method="post" class="form">
  {% csrf_token %}

  {% bootstrap_form form %}

  {% bootstrap_button button_type="submit" content="OK" %}
  {% bootstrap_button button_type="reset" content="Cancel" %}
</form>

  12. Migrate from django-bootstrap4 to django-bootstrap5

    main

    When upgrading from django-bootstrap4 to django-bootstrap5, you must update all references to the application name. This includes:

    1. Updating INSTALLED_APPS in your settings.py.
    2. Updating template tag loading references.
    3. Updating template inheritance/extension references.
    4. Updating widget usage references.
    # settings.py
INSTALLED_APPS = [
    ...
    'django_bootstrap5',  # Changed from 'bootstrap4'
    ...
]