Skip to content

Commit 4e2be20

Browse files
michael-yinmichael-yin
committed
Merge remote-tracking branch 'origin/main'
2 parents 3686c40 + 560c8cc commit 4e2be20

29 files changed

+307
-118
lines changed

‎.github/assets/formify-demo.jpg

277 KB
Loading

‎README.md

+35-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,35 @@
1-
# README
1+
<div align="center">
2+
3+
<h1>Django Formify</h1>
4+
5+
<p>Django-Formify seamlessly integrates Tailwind CSS styles into your Django forms for a modern look.</p>
6+
7+
<p><strong><a href="https://django-formify.readthedocs.io/en/latest/">Documentation</a> &nbsp;|&nbsp; <a href="https://saashammer.com/lookbook/inspect/form_component/form_fields/">Demo site</a></strong></p>
8+
9+
<p><a href="https://pypi.org/project/django-formify/"><img src="https://badge.fury.io/py/django-formify.svg" alt="Pypi version"></a>
10+
<a href="https://github.com/rails-inspire-django/django-formify/actions/workflows/runtests.yml"><img src="https://github.com/rails-inspire-django/django-formify/actions/workflows/runtests.yml/badge.svg" alt="CI status"></a></p>
11+
12+
</div>
13+
14+
```html
15+
{% load formify %}
16+
17+
<form method="post">
18+
19+
{% csrf_token %}
20+
21+
{% render_form form %}
22+
23+
{% render_submit text='Hello Formify!' variant="primary" %}
24+
25+
</form>
26+
```
27+
28+
![Django Formify Demo](.github/assets/formify-demo.jpg)
29+
30+
## Documentation
31+
32+
## FAQ
33+
34+
### Django-Formify vs Crispy-Tailwind
35+

‎docs/source/component_design.md

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Component Design
2+
3+
## Field Rendering
4+
5+
In field rendering, Django-Formify use components to render the HTML:
6+
7+
```
8+
Field Wrapper formify.tw.field_wrapper
9+
Label formify.tw.field_label
10+
Field
11+
Error And Help Text formify.tw.field_error_help_text
12+
Error formify.tw.field_error
13+
Help Text formify.tw.field_help_text
14+
```
15+
16+
Notes:
17+
18+
1. Except `Field`, other parts are rendered using components, and each has its own logic.
19+
2. During the rendering, components can read variable from the `formify_helper` to control the rendering behavior.
20+
21+
For example:
22+
23+
```python
24+
form.formify_helper = FormifyHelper()
25+
form.formify_helper.field_wrapper_class = "md:flex md:items-center mb-6"
26+
form.formify_helper.label_container_class = "md:w-1/3"
27+
form.formify_helper.field_container_class = "md:w-2/3"
28+
```
29+
30+
After we set the above class, `formify.tw.field_wrapper` will use the above class to render something like this:
31+
32+
```html
33+
<div class="md:flex md:items-center mb-6">
34+
<div class="md:w-1/3">
35+
<label for="id_email">Email</label>
36+
</div>
37+
<div class="md:w-2/3">
38+
<input type="text" name="email" id="id_email">
39+
</div>
40+
</div>
41+
```
42+
43+
We just easily changed the form layout to horizontal form, in clean way.
44+
45+
## Customize
46+
47+
All the field rending components are build using [django-viewcomponent](https://github.com/rails-inspire-django/django-viewcomponent), you can easily build your own components to fit your needs.
48+
49+
For example, after you build your own `field wrapper` component, just override `field_wrapper_component` of the `formify_helper`, then it should work.
50+
51+
## Layout
52+
53+
The components in `django_formify.tailwind.layout` are all also built using `django-viewcomponent`.
54+
55+
You can also build custom components to fit your needs, for example, if you want to use `Accordion` to generate complex form, you can build `Accordion` and `AccordionSection` components using `django-viewcomponent`.
56+
57+
And then you can use them like this:
58+
59+
```python
60+
class ExampleForm(forms.Form):
61+
62+
def __init__(self, *args, **kwargs):
63+
super().__init__(*args, **kwargs)
64+
self.formify_helper = FormifyHelper()
65+
self.formify_helper.layout = Layout(
66+
Accordion(
67+
AccordionSection(
68+
...
69+
),
70+
AccordionSection(
71+
...
72+
),
73+
AccordionSection(
74+
...
75+
),
76+
dom_id="accordion-1"
77+
),
78+
)
79+
```
80+
81+
What is more, after creating `Accordion` component, you can also use them in normal web pages as well (not just in form rendering), which is convenient.
82+
83+
## Django-ViewComponent
84+
85+
`django-viewcomponen` provides solution for developer to build reusable components in Django, the biggest advantage in this case is that: **developers can use it to create components, which are used in both Django Templates and Python Code**
86+
87+
In field rendering, we can use component in the django template:
88+
89+
```html
90+
{% load viewcomponent_tags %}
91+
92+
{% component formify_helper.field_wrapper_component as field_component %}
93+
94+
{% call field_component.label %}
95+
{% component formify_helper.label_component field=field formify_helper=formify_helper %}{% endcomponent %}
96+
{% endcall %}
97+
98+
{% call field_component.input %}
99+
{{ field_html }}
100+
{% endcall %}
101+
102+
{% call field_component.field_helper_text_and_errors %}
103+
{% component formify_helper.field_error_help_text_component field=field formify_helper=formify_helper %}{% endcomponent %}
104+
{% endcall %}
105+
106+
{% endcomponent %}
107+
```
108+
109+
In form layout, we can use component in the python code:
110+
111+
```python
112+
self.formify_helper.layout = Layout(
113+
Div(
114+
Div(Field("email"), css_class="col-span-12 md:col-span-6"),
115+
Div(Field("password"), css_class="col-span-12 md:col-span-6"),
116+
Div(Field("address"), css_class="col-span-12"),
117+
Div(Field("address2"), css_class="col-span-12"),
118+
Div(Field("city"), css_class="col-span-12 md:col-span-6"),
119+
Div(Field("state"), css_class="col-span-12 md:col-span-4"),
120+
Div(Field("zip_code"), css_class="col-span-12 md:col-span-2"),
121+
Div(Field("check_box"), css_class="col-span-12"),
122+
Div(Submit(text="Sign in"), css_class="col-span-12"),
123+
css_class="grid grid-cols-12 gap-3",
124+
),
125+
)
126+
```
127+
128+
Since `django-viewcomponent` solve problem very well, `django-formify` use it instead of creating another component solution.

‎docs/source/get_started.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -86,4 +86,4 @@ If you want more control of the form layout, you can render fields manually.
8686

8787
Notes:
8888

89-
You can use `{% render_field form.email %}` to render specific form field.
89+
1. You can use `{% render_field form.email %}` to render specific form field.

‎docs/source/index.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
django-formify
22
=====================
33

4-
Django-Formify is designed to enhance the styling and rendering of forms within your Django projects
4+
Django-Formify seamlessly integrates Tailwind CSS styles into your Django forms for a sleek, modern look.
55

66
Topics
77
------
@@ -13,3 +13,4 @@ Topics
1313
get_started.md
1414
formify_helper.md
1515
layout.md
16+
component_design.md

‎docs/source/install.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,9 @@ INSTALLED_APPS = [
1414
]
1515
```
1616

17-
`django_formify` has some components build by `django_viewcomponent`, to make it work, please also update `TEMPLATES` by following the instruction below.
17+
```{note}
18+
`django_formify` contains some components build using `django_viewcomponent`, to make it work, please also update `TEMPLATES` by following the instruction below.
19+
```
1820

1921
Modify `TEMPLATES` section of settings.py as follows:
2022

‎docs/source/layout.md

+10-78
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ The layout is to help control the form layout in Python code.
77
This feature is inspired from `django-crispy-forms`
88

99
```python
10+
from django_formify.tailwind.formify_helper import FormifyHelper
1011
from django_formify.tailwind.layout import Div, Field, Layout, Submit
1112

1213

@@ -17,42 +18,15 @@ class ExampleForm(forms.Form):
1718
self.formify_helper = FormifyHelper()
1819
self.formify_helper.layout = Layout(
1920
Div(
20-
Div(
21-
Field("email"),
22-
css_class="col-span-12 md:col-span-6",
23-
),
24-
Div(
25-
Field("password"),
26-
css_class="col-span-12 md:col-span-6",
27-
),
28-
Div(
29-
Field("address"),
30-
css_class="col-span-12",
31-
),
32-
Div(
33-
Field("address2"),
34-
css_class="col-span-12",
35-
),
36-
Div(
37-
Field("city"),
38-
css_class="col-span-12 md:col-span-6",
39-
),
40-
Div(
41-
Field("state"),
42-
css_class="col-span-12 md:col-span-4",
43-
),
44-
Div(
45-
Field("zip_code"),
46-
css_class="col-span-12 md:col-span-2",
47-
),
48-
Div(
49-
Field("check_box"),
50-
css_class="col-span-12",
51-
),
52-
Div(
53-
Submit(text="Sign in"),
54-
css_class="col-span-12",
55-
),
21+
Div(Field("email"), css_class="col-span-12 md:col-span-6"),
22+
Div(Field("password"), css_class="col-span-12 md:col-span-6"),
23+
Div(Field("address"), css_class="col-span-12"),
24+
Div(Field("address2"), css_class="col-span-12"),
25+
Div(Field("city"), css_class="col-span-12 md:col-span-6"),
26+
Div(Field("state"), css_class="col-span-12 md:col-span-4"),
27+
Div(Field("zip_code"), css_class="col-span-12 md:col-span-2"),
28+
Div(Field("check_box"), css_class="col-span-12"),
29+
Div(Submit(text="Sign in"), css_class="col-span-12"),
5630
css_class="grid grid-cols-12 gap-3",
5731
),
5832
)
@@ -71,48 +45,6 @@ The `django_formify.tailwind.layout` current contains below classes for develope
7145
- Field
7246
- Fieldset
7347

74-
## Django-ViewComponent
75-
76-
The layout classes from `django-crispy-forms` is built tightly with `django-crispy-forms` project itself, if I want to use them to render HTML from Python code, then it would be hard to get it work.
77-
78-
So I want to choose a robust component solution:
79-
80-
1. The solution can let developers build custom components as they like.
81-
2. `Django-Formify` just pass `context` to the components, and use the components to render HTML.
82-
83-
[django-viewcomponent](https://github.com/rails-inspire-django/django-viewcomponent) is the component solution I chose, it provides easy way to let developer build custom components.
84-
85-
The components in `django_formify.tailwind.layout` are all built using `django-viewcomponent`.
86-
87-
You can also build custom components to fit your needs, for example, if you want to use `Accordion` to generate complex form, you can build `Accordion` and `AccordionSection` components using `django-viewcomponent`.
88-
89-
And then you can use them like this:
90-
91-
```python
92-
class ExampleForm(forms.Form):
93-
94-
def __init__(self, *args, **kwargs):
95-
super().__init__(*args, **kwargs)
96-
self.formify_helper = FormifyHelper()
97-
self.formify_helper.layout = Layout(
98-
Accordion(
99-
AccordionSection(
100-
...
101-
),
102-
AccordionSection(
103-
...
104-
),
105-
AccordionSection(
106-
...
107-
),
108-
dom_id="accordion-1"
109-
),
110-
)
111-
```
112-
113-
What is more, after creating `Accordion` component, you can also use them in normal web pages as well (not just in form rendering), which is convenient.
114-
115-
11648
## Horizontal Form
11749

11850
Some people might have heard of a horizontal form, where the field labels and fields are arranged side by side

‎pyproject.toml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[tool.poetry]
22
name = "django-formify"
33
version = "0.0.4"
4-
description = "Django-Formify is designed to enhance the styling and rendering of forms within your Django projects"
4+
description = "Django-Formify seamlessly integrates Tailwind CSS styles into your Django forms for a sleek, modern look."
55
authors = ["Michael Yin <[email protected]>"]
66
license = "MIT"
77
homepage = "https://github.com/rails-inspire-django/django-formify"

‎src/django_formify/components/formify/tw/field_error.html

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{% if self.should_render %}
2+
<div class="mt-1">
3+
{% for error in self.field.errors %}
4+
<p id="error_{{ forloop.counter }}_{{ self.field.auto_id }}" class="text-red-600 text-xs">{{ error }}</p>
5+
{% endfor %}
6+
</div>
7+
{% endif %}

‎src/django_formify/components/formify/tw/field_error.py

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
from django_viewcomponent import component
2+
3+
4+
@component.register("formify.tw.field_error")
5+
class FieldErrorComponent(component.Component):
6+
def __init__(self, field, formify_helper, **kwargs):
7+
self.field = field
8+
self.formify_helper = formify_helper
9+
10+
@property
11+
def should_render(self):
12+
return self.field.errors and self.formify_helper.form_show_errors
13+
14+
template_name = "formify/tw/field_error.html"

‎src/django_formify/components/formify/tw/field_error_help_text.html

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{% load viewcomponent_tags %}
2+
3+
{% component self.formify_helper.field_error_component field=self.field formify_helper=self.formify_helper %}{% endcomponent %}
4+
5+
{% component self.formify_helper.field_help_text_component field=self.field formify_helper=self.formify_helper %}{% endcomponent %}

‎src/django_formify/components/formify/tw/field_error_help_text.py

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
from django_viewcomponent import component
2+
3+
4+
@component.register("formify.tw.field_error_help_text")
5+
class FieldErrorHelpTextComponent(component.Component):
6+
def __init__(self, field, formify_helper, **kwargs):
7+
self.field = field
8+
self.formify_helper = formify_helper
9+
10+
template_name = "formify/tw/field_error_help_text.html"

‎src/django_formify/components/formify/tw/field_help_text.html

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{% if self.should_render %}
2+
<div class="mt-1">
3+
<small {% if self.field.id_for_label %}id="{{ self.field.id_for_label }}_helptext" {% endif %} class="text-gray-600">{{ self.field.help_text|safe }}</small>
4+
</div>
5+
{% endif %}

‎src/django_formify/components/formify/tw/field_help_text.py

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
from django_viewcomponent import component
2+
3+
4+
@component.register("formify.tw.field_help_text")
5+
class FieldHelpTextComponent(component.Component):
6+
def __init__(self, field, formify_helper, **kwargs):
7+
self.field = field
8+
self.formify_helper = formify_helper
9+
10+
@property
11+
def should_render(self):
12+
return self.field.help_text
13+
14+
template_name = "formify/tw/field_help_text.html"

‎src/django_formify/components/formify/tw/field_label.html

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{% if self.should_render %}
2+
<label for="{{ self.field.id_for_label }}" class="{{ self.formify_helper.label_class }}">
3+
{{ self.field.label|safe }} {{ self.asterisk_if_required|safe }}
4+
</label>
5+
{% endif %}

0 commit comments

Comments
 (0)