Refactor (#2)

Author: michael-yin

.github/assets/formify-demo.jpg

@@ -1 +1,35 @@
-# README
+<div align="center">
+
+<h1>Django Formify</h1>
+
+<p>Django-Formify seamlessly integrates Tailwind CSS styles into your Django forms for a modern look.</p>
+
+<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>
+
+<p><a href="https://pypi.org/project/django-formify/"><img src="https://badge.fury.io/py/django-formify.svg" alt="Pypi version"></a>
+<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>
+
+</div>
+
+```html
+{% load formify %}
+
+<form method="post">
+
+    {% csrf_token %}
+
+    {% render_form form %}
+
+    {% render_submit text='Hello Formify!' variant="primary" %}
+
+</form>
+```
+
+![Django Formify Demo](.github/assets/formify-demo.jpg)
+
+## Documentation
+
+## FAQ
+
+### Django-Formify vs Crispy-Tailwind
+

README.md

@@ -0,0 +1,96 @@
+# Formify Helper
+
+## Workflow
+
+Unlike other form rendering packages, below template tags
+
+```bash
+{% render_form %}
+{% render_submit %}
+{% render_field %}
+{% render_form_errors %}
+```
+
+Just accept arguments from the templates, and pass the arguments to the `formify_helper` to render them.
+
+So core logic is in the `formify_helper`
+
+The benefit of this approach is it can be easy to customize the logic.
+
+## Global Formify Helper
+
+The default formify helper is `django_formify.tailwind.formify_helper.FormifyHelper`
+
+We can create a class to inherit and override some methods to change the rendering logic.
+
+To change the default global formify helper, just add below code to your Django settings
+
+```python
+FORMIFY = {
+    "formify_helper": "xxxx",
+}
+```
+
+Leveraging Python OOP, you can override some methods of the formify helper to customize the rendering behavior.
+
+```bash
+{% render_form %}            -> formify_helper.render_form
+{% render_submit %}          -> formify_helper.render_submit
+{% render_field %}           -> formify_helper.render_field
+{% render_form_errors %}     -> formify_helper.render_form_errors
+```
+
+## Field Dispatcher
+
+To make logic of rendering field more clean, there is a field dispatcher in the `render_field` method.
+
+For example, if a field is using `TextInput` widget, it will try to use below methods to render
+
+```
+text_input
+fallback
+```
+
+Notes:
+
+1. If `text_input` method is not found in the `formify_helper` instance, `fallback` method will be used to render the field.
+2. This can help developers to control rendering behavior of the specific widgets.
+
+If you have built some custom widgets, just add a method to the `formify_helper` and make the final result look well, this is much cleaner.
+
+## Formify Helper Variables
+
+Formify Helper have some variables such as:
+
+```python
+form_show_errors = True
+form_show_labels = True
+field_wrapper_class = "field-wrapper mb-3"
+```
+
+Developers can override or add more variables to change the behavior.
+
+In the final Django html, just access the variable using ``{{ formify_helper.form_show_errors }}``
+
+For example, to control if rendering field label or not
+
+```html
+{% if field.label and formify_helper.form_show_labels %}
+
+{% endif %}
+```
+
+## Formify Helper in Form
+
+You can also create formify helper for the form to override the global formify helper.
+
+```python
+from django_formify.tailwind.formify_helper import FormifyHelper
+
+class ExampleForm(forms.Form):
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.formify_helper = FormifyHelper()
+        self.formify_helper.field_wrapper_class = "another-field-wrapper"
+```

docs/source/formify_helper.md

@@ -0,0 +1,89 @@
+# Get Started
+
+## Simple Form Rendering
+
+Let's assume you already have Django forms.
+
+To render the form with good style in the template
+
+```html
+{% load formify %}
+
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Form</title>
+  <script src="https://cdn.tailwindcss.com?plugins=forms"></script>
+</head>
+<body>
+
+<div class="w-full max-w-3xl mx-auto px-4">
+  <form method="post">
+    
+    {% csrf_token %}
+
+    {% render_form form %}
+    
+    {% 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" %}
+    
+  </form>
+</div>
+
+</body>
+</html>
+```
+
+Notes:
+
+1. We `{% load formify %}` at the top to use relevant tags.
+2. We use `<script src="https://cdn.tailwindcss.com?plugins=forms"></script>` to import Tailwind CSS and the `form` plugin, this is for testing purpose only.
+3. `{% render_form form %}` is to iterate form fields and display all the fields with their labels and errors.
+4. `{% render_submit %}` is to help render submit button with custom text and CSS class.
+
+![](./images/simple_form.jpg)
+
+It will also help display form non-field errors and form field errors as well.
+
+![](./images/simple_form_errors.jpg)
+
+## Render Fields Manually
+
+If you want more control of the form layout, you can render fields manually.
+
+```html
+{% load formify %}
+
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Form</title>
+  <script src="https://cdn.tailwindcss.com?plugins=forms"></script>
+</head>
+<body>
+
+<div class="w-full max-w-3xl mx-auto px-4">
+  <form method="post">
+
+    {% csrf_token %}
+
+    <div class="grid grid-cols-12 gap-3">
+      <div class="col-span-12 md:col-span-6">
+        {% render_field form.name %}
+      </div>
+      <div class="col-span-12 md:col-span-6">
+        {% render_field form.email %}
+      </div> 
+    </div>
+    
+    {% 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" %}
+
+  </form>
+</div>
+
+</body>
+</html>
+```
+
+Notes:
+
+You can use `{% render_field form.email %}` to render specific form field.

docs/source/get_started.md

@@ -1,12 +1,15 @@
 django-formify
 =====================
 
-A set of tools to help simplify your Django templates.
+Django-Formify seamlessly integrates Tailwind CSS styles into your Django forms for a sleek, modern look.
 
 Topics
 ------
 
 .. toctree::
    :maxdepth: 2
 
-   getting_started.md
+   install.md
+   get_started.md
+   formify_helper.md
+   layout.md

docs/source/getting_started.md

@@ -0,0 +1,42 @@
+# Installation
+
+```shell
+$ pip install django-formify
+```
+
+Then add the app into `INSTALLED_APPS` in settings.py
+
+```python
+INSTALLED_APPS = [
+    ...,
+    'django_viewcomponent',       # new
+    'django_formify',             # new
+]
+```
+
+`django_formify` has some components build by `django_viewcomponent`, to make it work, please also update `TEMPLATES` by following the instruction below.
+
+Modify `TEMPLATES` section of settings.py as follows:
+
+1. Remove `'APP_DIRS': True,`
+2. add `loaders` to `OPTIONS` list and set it to following value:
+
+```python
+TEMPLATES = [
+    {
+        ...,
+        'OPTIONS': {
+            'context_processors': [
+                ...
+            ],
+            'loaders':[(
+                'django.template.loaders.cached.Loader', [
+                    'django.template.loaders.filesystem.Loader',
+                    'django.template.loaders.app_directories.Loader',
+                    'django_viewcomponent.loaders.ComponentLoader',
+                ]
+            )],
+        },
+    },
+]
+```