{"id":17086065,"url":"https://github.com/smileychris/django-forms","last_synced_at":"2025-04-12T21:37:17.853Z","repository":{"id":66063958,"uuid":"987901","full_name":"SmileyChris/django-forms","owner":"SmileyChris","description":"A Django template-based form api.","archived":false,"fork":false,"pushed_at":"2011-07-05T04:51:25.000Z","size":319,"stargazers_count":24,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T10:06:11.918Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SmileyChris.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-10-14T19:16:59.000Z","updated_at":"2022-10-23T14:07:30.000Z","dependencies_parsed_at":"2023-02-19T21:55:16.904Z","dependency_job_id":null,"html_url":"https://github.com/SmileyChris/django-forms","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmileyChris%2Fdjango-forms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmileyChris%2Fdjango-forms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmileyChris%2Fdjango-forms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmileyChris%2Fdjango-forms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SmileyChris","download_url":"https://codeload.github.com/SmileyChris/django-forms/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248637773,"owners_count":21137537,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-14T13:27:01.339Z","updated_at":"2025-04-12T21:37:17.834Z","avatar_url":"https://github.com/SmileyChris.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"============\r\nDjango Forms\r\n============\r\n\r\nA designer-focused forms control library which works as a layer over the\r\nstandard Django forms API.\r\n\r\n\r\nTags\r\n====\r\n\r\n.. _form-tag:\r\n\r\n``{% form %}``\r\n--------------\r\n\r\nRender one or more forms. A basic example of rendering a standard form using\r\nHTML paragraphs for rows would be\r\n``{% form some_form using \"forms/p.html\" %}``.\r\n\r\nUsage::\r\n\r\n    {% form some_form [form2 form3 ...] %}\r\n\r\nAny of the standard `tag arguments`_ can be used.\r\n\r\nContext:\r\n\r\n    ``forms``\r\n        List of forms to render.\r\n\r\n    ``errors``\r\n        Set to ``True`` if any of the forms contain errors.\r\n\r\n    ``non_field_errors``\r\n        List of non-field errors.\r\n\r\n\r\n.. _row-tag:\r\n\r\n``{% row %}``\r\n-------------\r\n\r\nUsed to render a row template with one or more fields with the currently\r\ndefined template.\r\n\r\nUsage is either::\r\n\r\n    * ``{% row field_list %}``\r\n    * ``{% row some_form.field [some_form.field ...] %}``\r\n\r\nAny of the standard `tag arguments`_ can be used.\r\n\r\nContext:\r\n\r\n    ``fields``\r\n        List of fields to render.\r\n\r\n    ``errors``\r\n        List of errors relating to any of the fields in this row.\r\n\r\n    ``required``\r\n        The number of fields that are required.\r\n\r\n\r\n.. _field-tag\r\n\r\n``{% field %}``\r\n---------------\r\n\r\nUsed to render a specific field with the currently defined field template.\r\n\r\nUsage::\r\n\r\n    {% field some_field %}\r\n\r\nRequires a context variable named ``form`` to exist (and be a\r\n`django.forms.forms.BaseForm`` instance).\r\n\r\nAny of the standard `tag arguments`_ can be used.\r\n\r\nContext:\r\n\r\n    ``value``\r\n        The value of this field.\r\n\r\n    ``errors``\r\n        A list of errors relating to this field.\r\n\r\n    ``label``\r\n        The label text for this field.\r\n    \r\n    ``help_text``\r\n        The help text for this field.\r\n\r\n    ``form``\r\n        The form this field belongs to.\r\n    \r\n    ``field``\r\n        The underlying form field being rendered.\r\n        \r\n    ``id``\r\n        The id for this field (or an empty string).\r\n\r\n    ``id_for_label``\r\n        The id which should be assigned to the field's label\r\n\r\n    ``name``\r\n        The name of this field.\r\n\r\n    ``html_name``\r\n        The prefixed name of this field\r\n\r\n\r\n.. _formconfig-tag\r\n\r\n``{% formconfig %}``\r\n--------------------\r\n\r\nUsed to configure rows and fields, as specified by the first tag argument.\r\nReuse of this tag overrides previously defined matching configurations.\r\n\r\nUsage, either::\r\n\r\n    * ``{% formconfig row ... %}``, or\r\n    * ``{% formconfig field ... %}``\r\n\r\n    Any of the standard `tag arguments`_ can be used.\r\n\r\nTo limit the configuration of rows for one or more specific fields, use the\r\n``for`` argument. For example::\r\n\r\n    {% formconfig row for form.first_name form.last_name using \"forms/rows/pretty.html\" %}\r\n\r\nThe ``for`` argument also accepts strings::\r\n\r\n    {% formconfig field for \"email\" with help_text=\"Your email address\" %}\r\n\r\nUse the ``priority`` argument to `change the default order of form fields`_.\r\nThis can only be used if the configuration is limited to specific fields. For\r\nexample::\r\n\r\n    {% formconfig field for form.first_name priority 1 %}\r\n    {% formconfig field for form.last_name priority 2 %}\r\n\r\n\r\nTag Arguments\r\n=============\r\n\r\nThese arguments can be used on any form-related tag.\r\n\r\nAdd to the context (``with``)\r\n-----------------------------\r\n\r\n`` with key=value [key=value key=value ...]``\r\n\r\nAdds to the context of the template which will be rendered.\r\n\r\nExclude the current context (``only``)\r\n--------------------------------------\r\n\r\nIf this argument is part of the tag, the current context will not be available\r\nto the template that will be rendered.\r\n\r\n.. note::\r\n\r\n    There is one exception: any context variable named ``form`` will still be\r\n    available (also any variable starting with ``_formconfig``, but they aren't\r\n    available from templates anyway).\r\n\r\n\r\nChoose the template (``using`` or ``extends``)\r\n----------------------------------------------\r\n\r\nThere are two arguments that allow configuration of which template should be\r\nused to render the template:\r\n\r\n`` using some_template`` or `` using`` (as the final tag argument)\r\n    Specify the template to use.\r\n\r\n`` extends some_template`` or `` extends`` (as the final tag argument)\r\n    Extends an existing template (via the use of ``{% block %}`` tags).\r\n    See the `Extend form-related templates inline`_ section.\r\n\r\nThe ``using`` argument without a template or either form of the ``extends``\r\nargument means that the template is being defined inline until a closing\r\n``{% end-`` tag is reached (matching the opening tag, for example, \r\n``{% form extends \"forms/custom.html\" %}...{% endform %}``).\r\n\r\n\r\nOther Tags\r\n==========\r\n\r\n``{% get_ordered_fields %}``\r\n--------------------------\r\n\r\nUsed by form templates to retrieve an ordered list of form fields.\r\n\r\nUsage::\r\n\r\n    {% get_ordered_fields forms_list as var_name %}\r\n\r\nAdds a context variable containing a list of fields.\r\n\r\n\r\n``{% ifcontent %}``\r\n-------------------\r\n\r\nNot specific to forms, a useful tag which allows wrapping text if the content\r\ncontains non-whitespace. For example, conditionally showing the help text div\r\ninside of the field template::\r\n\r\n    {% ifcontent %}\r\n        \u003cdiv class=\"helptext\"\u003e\r\n            {% content %}\r\n                {% block help %}{{ help_text }}{% endblock %}\r\n            {% endcontent %}\r\n        \u003c/div\u003e\r\n    {% endifcontent %}\r\n\r\n\r\nExamples of extending form-related templates inline\r\n===================================================\r\n\r\nHere are some basic examples::\r\n\r\n    {% form form1 form2 extends \"forms/p.html\" %}\r\n\r\n        {% block config %}\r\n            {% formconfig field using \"forms/fields/booleanselect.html\" for form1.accept_tos %}\r\n        {% endblock %}\r\n\r\n    {% endform %}\r\n\r\n\r\n    {% form form1 extends \"forms/p.html\" %}\r\n\r\n        {% block config %}\r\n            {### Set all rows to use a special \"p\", except for the TOS #}\r\n            {% formconfig row using \"forms/rows/special-p.html\" %}\r\n            {% formconfig row using \"forms/rows/p.html\" for form1.accept_tos %}\r\n        {% endblock %}\r\n\r\n    {% endform %}\r\n\r\nAnd here's one more slightly more complex example that extends both the form\r\nand a field's template::\r\n\r\n    {% form extends \"forms/p.html\" %}\r\n\r\n        {% block config %}\r\n            {% formconfig field for form.is_manager extends %}\r\n                {% block help %}{% blocktrans with site=site.name %}Can this person manage {{ site }}?{% endblocktrans %}{% endblock %}\r\n            {% endformconfig %}\r\n        {% endblock %}\r\n        \r\n        {% block fields %}\r\n            {% row form.first_name form.last_name %}\r\n            {% row form.email with class=\"email\" %}\r\n            {% row form.is_manager %}\r\n        {% endblock fields %}\r\n\r\n    {% endform %}\r\n\r\n\r\nChange the default order of form fields\r\n=======================================\r\n\r\nUse the ``priority`` argument of :ref:`formconfig-tag` to order fields without\r\nthe need to manually redefine all fields in the form.\r\nTo give fields a priority to the top of the form, use positive integers (the\r\nlower the number, the higher priority).\r\n\r\nUse negative integers to give fields a low priority (i.e. occuring after both\r\nthose with a positive priority and those without a priority set at all).\r\n\r\nIf multiple fields are given the same priority, the fields configured first\r\nwill have the highest priority::\r\n\r\n    {% form form1 form2 extends \"forms/p.html\" %}\r\n\r\n        {% block config %}\r\n            {### Put these three fields to the top, in this order #}\r\n            {% formconfig field for \"first_name\" priority 1 %}\r\n            {% formconfig field for \"last_name\" priority 1 %}\r\n            {% formconfig field for \"email\" priority 1 %}\r\n            {### And put this one to the bottom #}\r\n            {% formconfig field for \"accept_tos\" priority -1 %}\r\n        {% endblock %}\r\n\r\n    {% endform %}\r\n\r\nIf you are creating an entire form template, use this tag to initiate the\r\nreordering of a form's fields::\r\n\r\n    {% formreorder form %}\r\n\r\nThis is done in all the built-in form templates.\r\n\r\n\r\nExample of a form template\r\n==========================\r\n\r\n``forms/p.html``::\r\n\r\n    {% block allconfig %}\r\n        {% formconfig row using \"forms/rows/p.html\" %}\r\n        {% block config %}{% endblock %}\r\n    {% endblock %}\r\n    \r\n    {% if non_field_errors %}\r\n    \u003cul class=\"errors\"\u003e\r\n        {% for errors in form.non_field_errors %}\r\n        \u003cli\u003e{{ errors }}\u003c/li\u003e\r\n        {% endfor %}\r\n    \u003c/ul\u003e\r\n    {% endif %}\r\n    \r\n    {% get_rows_ordered forms as rows %}\r\n    {% block rows %}\r\n    {% for fields in rows %}\r\n        {% row fields %}\r\n    {% endfor %}\r\n    {% endblock %}\r\n\r\n\r\n``forms/rows/base.html``::\r\n\r\n    {% block row_start %}{% endblock %}\r\n    {% for form, field in fields %}\r\n        {% block start %}{% endblock %}\r\n        {% field field %}\r\n        {% block end %}{% endblock %}\r\n    {% endfor %}\r\n    {% block row_end %}{% endblock %}\r\n\r\n\r\n``forms/rows/p.html``::\r\n\r\n    {% extends \"forms/rows/base.html\" %}\r\n    {% block start %}\u003cp{% if errors or required %} class=\"{% if errors %}errors{% if required %} {% endif %}{% endif %}{% if required %}required{% endif %}\"{% endif %}\u003e{% endblock %}\r\n    {% block end %}\u003c/p\u003e{% endblock %}\r\n\r\n\r\n``form/fields/base.html``::\r\n\r\n    {% if label %}\r\n        \u003clabel{% if id_for_label %} for=\"{{ id_for_label }}\"\u003e{% block label %}{{ label }}{% endblock %}\u003c/label\u003e\r\n    {% endif %}\r\n    \u003cinput type=\"text\" value=\"{{ value }}\" id=\"{{ id }}\" /\u003e\r\n    {% if errors %}\r\n    \u003cul class=\"errors\"\u003e\r\n    {% for error in errors %}\r\n        \u003cli\u003e{{ error }}\u003c/li\u003e\r\n    {% endfor %}\r\n    \u003c/ul\u003e\r\n    {% endif %}\r\n    {% ifcontent %}\r\n        \u003cspan class=\"helptext\"\u003e\r\n            {% content %}\r\n                {% block help %}{{ help_text }}{% endblock %}\r\n            {% endcontent %}\r\n        \u003c/span\u003e\r\n    {% endifcontent %}\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmileychris%2Fdjango-forms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmileychris%2Fdjango-forms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmileychris%2Fdjango-forms/lists"}