Skip to content

Commit 560c8cc

Browse files
michael-yinmichael-yin
authored
Update doc (#3)
1 parent da7cbbf commit 560c8cc

File tree

5 files changed

+144
-81
lines changed

5 files changed

+144
-81
lines changed

‎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

+2-2
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ To render the form with good style in the template
2424

2525
{% render_form form %}
2626

27-
{% render_submit text='Hello Formify!' css_class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded focus:outline-none focus:shadow-outline" %}
27+
{% render_submit text='Submit' css_class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded focus:outline-none focus:shadow-outline" %}
2828

2929
</form>
3030
</div>
@@ -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

+1
Original file line numberDiff line numberDiff line change
@@ -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

0 commit comments

Comments
 (0)