============================================
django-fineforms - Form rendering for Django
============================================
.. image:: https://github.com/matthiask/django-fineforms/workflows/Tests/badge.svg
:target: https://github.com/matthiask/django-fineforms
This library offers an improved replacement for Django's own form
rendering methods (``as_p``, ``as_table`` etc.) while staying simple
and extensible but without introducing a whole new framework.
django-fineforms consists of a template tag library and a few
opinionated default templates.
Goals
=====
- Stay simple and extensible
- Avoid options, settings and customizability as much as possible
Non-goals
=========
- Compete with django-crispy-forms or any of the more flexible libraries
out there
Installation
============
Simply ``pip install django-fineforms``, and add ``fineforms`` to your
``INSTALLED_APPS``.
High-level overview
===================
The template tags mostly wrap their arguments in wrapper classes that do
the real work. For example, ``{% ff_field %}`` simply wraps the passed
field in a wrapper defined in the ``FINEFORMS_WRAPPERS`` setting. All
wrappers use a template to render their output. The default wrapper
types are as follows:
.. code-block:: python
{
"errors": ErrorsWrapper,
"field": FieldWrapper,
"field-plain": PlainFieldWrapper,
"fields": FieldsWrapper,
}
The wrappers themselves mostly aren't configurable, but you can replace
individual wrappers (or all of them) by adding a ``FINEFORMS_WRAPPERS``
setting. You do not have to override all of them; if you only want to
add another wrapper for a specific field type you could just set:
.. code-block:: python
FINEFORMS_WRAPPERS = {
"specific": "app.wrappers.SpecificWrapper",
}
... and use this wrapper as ``{% ff_field some_field type='specific' %}``
somewhere in your templates.
Template tags
=============
All template tags are contained in the ``fineforms`` library.
``{% ff_field field [type=field] %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Template: ``fineforms/field.html``
Render a single field. The wrapper can be optionally overridden by
passing a different type. The key has to exist in the
``FINEFORMS_WRAPPERS`` dictionary.
The default implementation renders the label, the widget, help text and
errors related to the field. It is recommended to also set the
``error_css_class`` and ``required_css_class`` form attributes; those
classes are also added to the output.
The ``field-plain`` type can be used if the widget should be rendered
alone. A wrapping ``<span>`` tag still contains the CSS classes
mentioned above.
``{% ff_fields form [fields='a,b,c' | exclude='a,b,c'] %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Template: ``fineforms/fields.html``
Render fields of a form. ``fields`` and ``exclude`` are
comma-separated strings that can be used to only render a selection of
fields. The ``fields`` parameter takes precedence if both are given.
Hidden fields are rendered separately at the end, all other fields are
wrapped using ``FINEFORMS_WRAPPERS["field"]`` and rendered as well.
``{% ff_errors form1 [form2 ...] %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Template: ``fineforms/errors.html``
Render form errors at the top. The default implementation renders all
non-field errors, and all errors from hidden fields. Falsy parameters
(i.e. ``None``) are filtered out for you. If there aren't any errors at
all nothing is rendered.
``{% ff_hidden_fields form1 [form2 ...] %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This template tag is the outlier in that it does not use a template at
all. The return value is the concatenated result of rendering all hidden
fields of all passed forms. Falsy parameters (i.e. ``None``) are
filtered out for you.
Please note that ``{% ff_fields %}`` adds hidden fields to the output
automatically.
``{% ff_submit [_("label")] %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Template: ``fineforms/submit.html``
Show a submit button.
Raw data
{
"_id": null,
"home_page": "http://github.com/matthiask/django-fineforms/",
"name": "django-fineforms",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Matthias Kestenholz",
"author_email": "mk@feinheit.ch",
"download_url": "https://files.pythonhosted.org/packages/9f/71/ee5a1dfd014f9b39ddb07387fb7021945401f1d301e6623d9e13acb58a8c/django_fineforms-0.7.0.tar.gz",
"platform": "OS Independent",
"description": "============================================\ndjango-fineforms - Form rendering for Django\n============================================\n\n.. image:: https://github.com/matthiask/django-fineforms/workflows/Tests/badge.svg\n :target: https://github.com/matthiask/django-fineforms\n\nThis library offers an improved replacement for Django's own form\nrendering methods (``as_p``, ``as_table`` etc.) while staying simple\nand extensible but without introducing a whole new framework.\n\ndjango-fineforms consists of a template tag library and a few\nopinionated default templates.\n\n\nGoals\n=====\n\n- Stay simple and extensible\n- Avoid options, settings and customizability as much as possible\n\n\nNon-goals\n=========\n\n- Compete with django-crispy-forms or any of the more flexible libraries\n out there\n\n\nInstallation\n============\n\nSimply ``pip install django-fineforms``, and add ``fineforms`` to your\n``INSTALLED_APPS``.\n\n\nHigh-level overview\n===================\n\nThe template tags mostly wrap their arguments in wrapper classes that do\nthe real work. For example, ``{% ff_field %}`` simply wraps the passed\nfield in a wrapper defined in the ``FINEFORMS_WRAPPERS`` setting. All\nwrappers use a template to render their output. The default wrapper\ntypes are as follows:\n\n.. code-block:: python\n\n {\n \"errors\": ErrorsWrapper,\n \"field\": FieldWrapper,\n \"field-plain\": PlainFieldWrapper,\n \"fields\": FieldsWrapper,\n }\n\nThe wrappers themselves mostly aren't configurable, but you can replace\nindividual wrappers (or all of them) by adding a ``FINEFORMS_WRAPPERS``\nsetting. You do not have to override all of them; if you only want to\nadd another wrapper for a specific field type you could just set:\n\n.. code-block:: python\n\n FINEFORMS_WRAPPERS = {\n \"specific\": \"app.wrappers.SpecificWrapper\",\n }\n\n... and use this wrapper as ``{% ff_field some_field type='specific' %}``\nsomewhere in your templates.\n\n\nTemplate tags\n=============\n\nAll template tags are contained in the ``fineforms`` library.\n\n``{% ff_field field [type=field] %}``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTemplate: ``fineforms/field.html``\n\nRender a single field. The wrapper can be optionally overridden by\npassing a different type. The key has to exist in the\n``FINEFORMS_WRAPPERS`` dictionary.\n\nThe default implementation renders the label, the widget, help text and\nerrors related to the field. It is recommended to also set the\n``error_css_class`` and ``required_css_class`` form attributes; those\nclasses are also added to the output.\n\nThe ``field-plain`` type can be used if the widget should be rendered\nalone. A wrapping ``<span>`` tag still contains the CSS classes\nmentioned above.\n\n\n``{% ff_fields form [fields='a,b,c' | exclude='a,b,c'] %}``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTemplate: ``fineforms/fields.html``\n\nRender fields of a form. ``fields`` and ``exclude`` are\ncomma-separated strings that can be used to only render a selection of\nfields. The ``fields`` parameter takes precedence if both are given.\n\nHidden fields are rendered separately at the end, all other fields are\nwrapped using ``FINEFORMS_WRAPPERS[\"field\"]`` and rendered as well.\n\n\n``{% ff_errors form1 [form2 ...] %}``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTemplate: ``fineforms/errors.html``\n\nRender form errors at the top. The default implementation renders all\nnon-field errors, and all errors from hidden fields. Falsy parameters\n(i.e. ``None``) are filtered out for you. If there aren't any errors at\nall nothing is rendered.\n\n\n``{% ff_hidden_fields form1 [form2 ...] %}``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis template tag is the outlier in that it does not use a template at\nall. The return value is the concatenated result of rendering all hidden\nfields of all passed forms. Falsy parameters (i.e. ``None``) are\nfiltered out for you.\n\nPlease note that ``{% ff_fields %}`` adds hidden fields to the output\nautomatically.\n\n\n``{% ff_submit [_(\"label\")] %}``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTemplate: ``fineforms/submit.html``\n\nShow a submit button.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Form rendering for Django",
"version": "0.7.0",
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ed654a293374ba14024872af00604521f00b8167c04764cf6749ab848ebad7e7",
"md5": "7f39f01917ae2bda23c931d3854580a9",
"sha256": "4465f1157dc000e3f15a7f829b27bf75f0156723aae3b56847dc440d91bc7fd9"
},
"downloads": -1,
"filename": "django_fineforms-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7f39f01917ae2bda23c931d3854580a9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12354,
"upload_time": "2023-04-13T17:49:34",
"upload_time_iso_8601": "2023-04-13T17:49:34.391763Z",
"url": "https://files.pythonhosted.org/packages/ed/65/4a293374ba14024872af00604521f00b8167c04764cf6749ab848ebad7e7/django_fineforms-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9f71ee5a1dfd014f9b39ddb07387fb7021945401f1d301e6623d9e13acb58a8c",
"md5": "1ec4771f6ae3a43ae91b5b4b50ab695c",
"sha256": "b09dbf10dad99b84d9910d50129bc74fbb76ca127c126e5cc80538c1f95d3a4f"
},
"downloads": -1,
"filename": "django_fineforms-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "1ec4771f6ae3a43ae91b5b4b50ab695c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9407,
"upload_time": "2023-04-13T17:49:32",
"upload_time_iso_8601": "2023-04-13T17:49:32.566574Z",
"url": "https://files.pythonhosted.org/packages/9f/71/ee5a1dfd014f9b39ddb07387fb7021945401f1d301e6623d9e13acb58a8c/django_fineforms-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-13 17:49:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "matthiask",
"github_project": "django-fineforms",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-fineforms"
}
JSON
