django-bs

commit

322815861a8f437230ce076094d516a779d051f4

parent

fa71b40a87ce2ef14e4359e493f318c8fda5fe4d

Author

Tobias Bengfort <tobias.bengfort@posteo.de>

Date

2020-01-26 11:42

add README

Diffstat

1 files changed, 77 insertions, 0 deletions

diff --git a/README.rst b/README.rst

@@ -0,0 +1,77 @@
   -1     1 Bootstrap 4 forms for Django
   -1     2 ============================
   -1     3 
   -1     4 Bootstrap 4 integration for django using `widget templates`_ that were
   -1     5 introduced in Django 1.11.
   -1     6 
   -1     7 Motivation
   -1     8 ----------
   -1     9 
   -1    10 This library is meant to be a drop-in replacement for
   -1    11 `django-bootstrap4`_. See below for a list of differences. I really like
   -1    12 that library, but it is hard to customize some things because everything
   -1    13 is done in python functions. By using widget templates, I hope this
   -1    14 library is more flexible.
   -1    15 
   -1    16 Installation
   -1    17 ------------
   -1    18 
   -1    19 Install with pip::
   -1    20 
   -1    21    pip install django-bs4
   -1    22 
   -1    23 After that you have to add it to ``INSTALLED_APPS``. You also need to
   -1    24 make sure that the correct ``FORM_RENDERER`` is selected and
   -1    25 ``django.forms`` is in ``INSTALLED_APPS`` (after ``django-bs4``). This
   -1    26 is required so that widget templates can be overwritten::
   -1    27 
   -1    28    INSTALLED_APPS = [
   -1    29        …
   -1    30        'django-bs4'
   -1    31        …
   -1    32        'django.forms'
   -1    33        …
   -1    34    ]
   -1    35 
   -1    36    FORM_RENDERER = 'django.forms.renderers.TemplatesSetting'
   -1    37 
   -1    38 Usage
   -1    39 -----
   -1    40 
   -1    41 The following template tags are included in the ``bootstrap4`` library:
   -1    42 
   -1    43 -  ``bootstrap_field {boundfield}`` - Render a single field.
   -1    44 -  ``bootstrap_form {form}`` - Render errors and all fields for a form.
   -1    45    The ``<form>`` element itself is not included.
   -1    46 -  ``bootstrap_messages`` - Render messages from
   -1    47    ``django.contrib.messages``.
   -1    48 -  ``bootstrap_pagination {page}`` - Render pagination. A ``<nav>``
   -1    49    element is not included.
   -1    50 
   -1    51 Please refer to the source code for additional parameters.
   -1    52 
   -1    53 Differences to django-bootstrap4
   -1    54 --------------------------------
   -1    55 
   -1    56 -  Uses widget templates instead of custom renderers. IMHO this
   -1    57    makes the code much easier to read and customize. A big downside is
   -1    58    that I had to monkey-patch ``BoundField.as_widget()`` to include some
   -1    59    information that would otherwise not be available in the widget
   -1    60    templates.
   -1    61 -  Concentrates on forms fields and does therefore not include some
   -1    62    others features.
   -1    63 -  Uses ``small.text-danger`` instead of ``.invalid-feedback`` as it
   -1    64    does not depend on DOM location. (see also `twbs/bootstrap#29439`_)
   -1    65 -  Does not use ``.is-valid`` because I find it confusing with
   -1    66    server-side rendering.
   -1    67 -  Does not include dismiss-buttons for alerts to avoid depending on
   -1    68    JavaScript.
   -1    69 -  Does not include field errors at the top of forms as they are already
   -1    70    displayed on the fields themselves.
   -1    71 -  Improved ARIA support.
   -1    72 -  You will have to load bootstrap yourself.
   -1    73 -  No configuration.
   -1    74 
   -1    75 .. _widget templates: https://docs.djangoproject.com/en/stable/ref/forms/renderers/#overriding-built-in-widget-templates
   -1    76 .. _django-bootstrap4: https://github.com/zostera/django-bootstrap4
   -1    77 .. _twbs/bootstrap#29439: https://github.com/twbs/bootstrap/issues/29439