cliss21
/
django-fsforms
Archivé
5
0
Bifurcation 1

[doc] Switch to markdown for the README and other files

pull/2/head
Jérôme Lebleu 2017-08-15 18:09:44 +02:00
Parent 44ee9d4c05
révision 90a9c52ddc
6 fichiers modifiés avec 111 ajouts et 112 suppressions

Voir le fichier

@ -1,11 +1,10 @@
=======
Credits
=======
Main Developers
---------------
* Jérôme Lebleu <jerome.lebleu@cliss21.org>
- Jérôme Lebleu <jerome.lebleu@cliss21.org>
Contributors
------------

6
CHANGELOG.md Normal file
Voir le fichier

@ -0,0 +1,6 @@
Changelog
---------
## [Unreleased]
### Added
- Basic ``fsfield`` tag and filter for Foundation for Sites 6.x.

Voir le fichier

@ -1,9 +0,0 @@
.. :changelog:
History
-------
6.0.0 (Unreleased)
++++++++++++++++++
* Basic ``fsfield`` tag and filter for Foundation for Sites 6.x.

96
README.md Normal file
Voir le fichier

@ -0,0 +1,96 @@
Foundation Forms for Django
===========================
A reusable Django application for rendering forms with [Foundation for Sites][].
[Foundation for Sites]: http://foundation.zurb.com/sites/docs/
Requirements
------------
- Python 3
- Django >= 1.11
- Foundation for Sites 6.x
Note that this application does not include Foundation for Sites assets so that
you can customize it as you need. Get started by reading its [documentation][]!
[documentation]: http://foundation.zurb.com/sites/getting-started.html
Features
--------
* Displays the field label as well as its help text
* Renders the Django base Widgets following the [Forms component][]'s guidelines
* Shows the field errors as needed and sets the proper CSS classes on the field
label and the input
[Forms component]: http://foundation.zurb.com/sites/docs/forms.html
Installation
------------
1. Install Foundation Forms for Django:
pip install django-fsforms
2. Add it to the `INSTALLED_APPS` in your `settings.py`:
```python
INSTALLED_APPS = (
...
'fsforms.apps.FSFormsConfig',
...
)
```
3. Change the `FORM_RENDERER` still in your `settings.py` to use the
Foundation Forms' one:
```python
FORM_RENDERER = 'fsforms.renderers.FoundationTemplates'
```
Usage
-----
In your template, you will just have to load `fsforms` then use either the
`fsfield` filter on a field for a basic usage, or the `fsfield` tag for
tunning up the output.
```django
{% load fsforms %}
<form action="/url/to/submit/" method="post">
{% csrf_token %}
<ul class="no-bullet">
<li>{{ form.simple_field|fsfield }}</li>
<li>{% fsfield form.other_field label_class="my-field" %}</li>
</ul>
<div class="button-holder">
<button type="submit" class="button">Submit</button>
</div>
</form>
```
Here are the special arguments you can pass to the `fsfield` tag:
- `label_class`: a string which contains additional CSS classes to apply to
the label element.
- `show_errors`: a boolean which turns on or off the field errors' output as
well as the CSS classes applied to the elements - e.g. `is-invalid-input`
and `is-invalid-label`. Default is `True`.
- `as_list`: a boolean which controls the rendering of choices widgets - i.e.
RadioSelect and CheckboxSelectMultiple. When set to `True` - the default,
the fields will be rendered inline and wrapped inside a fieldset as suggested
by the Forms component. Otherwise, they will be rendered as a list.
All the remaining arguments will be added to the widget attributes. As regards
the `required` one, you can alter its value too but only with client-side
effect. It means that if a field is defined as required in the form class and
you pass `required=False` to the tag, it will appear as non-required to the
user but will still be validated at the form's submission.
License
-------
You can use this under GNU AGPLv3+. See [LICENSE](LICENSE) file for details.

Voir le fichier

@ -1,98 +0,0 @@
===========================
Foundation Forms for Django
===========================
A reusable Django application for rendering forms with `Foundation for Sites`_.
.. _Foundation for Sites: http://foundation.zurb.com/sites/docs/
Requirements
------------
- Python 3
- Django >= 1.11
- Foundation for Sites 6.x
Note that this application does not include Foundation for Sites assets so that
you can customize it as you need. Get started by reading its documentation_!
.. _documentation: http://foundation.zurb.com/sites/getting-started.html
Features
--------
* Displays the field label as well as its help text
* Renders the Django base Widgets following the `Forms component`_'s guidelines
* Shows the field errors as needed and sets the proper CSS classes on the field
label and the input
.. _Forms component: http://foundation.zurb.com/sites/docs/forms.html
Installation
------------
1. Install Foundation Forms for Django::
pip install django-fsforms
2. Add it to the `INSTALLED_APPS` in your ``settings.py``:
.. code-block:: python
INSTALLED_APPS = (
...
'fsforms.apps.FSFormsConfig',
...
)
3. Change the `FORM_RENDERER` still in your ``settings.py`` to use the
Foundation Forms' one:
.. code-block:: python
FORM_RENDERER = 'fsforms.renderers.FoundationTemplates'
Usage
-----
In your template, you will just have to load ``fsforms`` then use either the
``fsfield`` filter on a field for a basic usage, or the ``fsfield`` tag for
tunning up the output.
.. code:: Django
{% load fsforms %}
<form action="/url/to/submit/" method="post">
{% csrf_token %}
<ul class="no-bullet">
<li>{{ form.simple_field|fsfield }}</li>
<li>{% fsfield form.other_field label_class="my-field" %}</li>
</ul>
<div class="button-holder">
<button type="submit" class="button">Submit</button>
</div>
</form>
Here are the special arguments you can pass to the ``fsfield`` tag:
- ``label_class``: a string which contains additional CSS classes to apply to
the label element.
- ``show_errors``: a boolean which turns on or off the field errors' output as
well as the CSS classes applied to the elements - e.g. ``is-invalid-input``
and ``is-invalid-label``. Default is ``True``.
- ``as_list``: a boolean which controls the rendering of choices widgets - i.e.
RadioSelect and CheckboxSelectMultiple. When set to ``True`` - the default,
the fields will be rendered inline and wrapped inside a fieldset as suggested
by the Forms component. Otherwise, they will be rendered as a list.
All the remaining arguments will be added to the widget attributes. As regards
the ``required`` one, you can alter its value too but only with client-side
effect. It means that if a field is defined as required in the form class and
you pass ``required=False`` to the tag, it will appear as non-required to the
user but will still be validated at the form's submission.
License
-------
You can use this under GNU AGPLv3+. See `LICENSE
<LICENSE>`_ file for details.

Voir le fichier

@ -19,9 +19,14 @@ def get_version(*file_paths):
raise RuntimeError('Unable to find version string.')
try:
import pypandoc
readme = pypandoc.convert('README.md', 'rst')
changelog = pypandoc.convert('CHANGELOG.md', 'rst')
except(IOError, ImportError):
raise RuntimeError('You must install pypandoc at first.')
version = get_version('fsforms', '__init__.py')
readme = open('README.rst').read()
history = open('HISTORY.rst').read().replace('.. :changelog:', '')
setup(
name='django-fsforms',
@ -30,7 +35,7 @@ setup(
"A reusable Django application for rendering forms with "
"Foundation for Sites."
),
long_description=readme + '\n\n' + history,
long_description=readme + '\n\n' + changelog,
author='Jérôme Lebleu',
author_email='jerome.lebleu@cliss21.org',
url='https://forge.cliss21.org/cliss21/django-fsforms',