> ## Documentation Index
> Fetch the complete documentation index at: https://www.ghostwriter.wiki/llms.txt
> Use this file to discover all available pages before exploring further.
# Form Layouts & Design
> Creation and layout of forms
## Introduction
The Ghostwriter project uses the *django-crispy-forms* library (Crispy) to layout forms. At a basic level, this library provides template tags for rendering form fields that are more visually appealing than the regular Django form fields.
[GitHub - django-crispy-forms/django-crispy-forms](https://github.com/django-crispy-forms/django-crispy-forms)
Ghostwriter leverages the library's more advanced features to create `FormHelper()` and `Layout()` objects to design reusable forms in code. This requires some additional work upfront, but the end result should be a form that can be modified in one location (the *forms.py* file) and reused in multiple views and templates.
If created correctly, the form can be added to a template with two lines:
```json theme={"system"}
{% load crispy_forms_tags %}
{% crispy form form.helper %}
```
Read about Crispy's `FormHelper()` and `Layout()` objects:
## Creating a Form
Most forms should be instances of Django's `models.ModelForm` class. This makes it simpler to create a form for most, if not all, of Ghostwriter's use cases for a form.
The name of the form should identify the related model and include an appropriate docstring.
```json theme={"system"}
class ClientContactForm(forms.ModelForm):
"""
Create an individual :model:`rolodex.ClientContact` for a :model:`rolodex.Client`.
"""
class Meta:
model = ClientContact
exclude = ("client",)
```
Avoid naming forms with adjectives like "create" (ex: `ClientContactCreate`) because the forms should be reusable. A form used to create a new model entry should be reusable to update that same entry.
The `Meta` class of every instance of `ModelForm` must declare the model as the variable`model` and then provide values for either `fields` or `exclude`. Use `exclude` to declare which fields should not be included in the form.
If the form applies to a specific scenario where `exclude` would be a bigger list than `fields`, then use `fields` to declare which fields to include.
Finally, if the form will include all fields, explicitly state this by setting `fields = "__all__"`.
### Forms.py
Forms should be added to the application's *forms.py* file and then imported using a line like `from .forms import FORM_NAME`.
When form files become large (like when dealing with multiple parent forms and child formsets), the files become difficult to navigate., so there is one exception to this rule:
If the *forms.py* file grows into an excessively large file, split the file into two or more files organized by model.
The Rolodex application's form files are a good example of this situation. All of the forms related to the `Client` and `Project` models and their associated child models pushed the single *forms.py* file beyond 1,000 lines. To make it easier to maintain each set of forms, the project moved them into files named \_forms.*client.py* and *forms\_project.py*.
Name the new files with the *forms*\_ prefix followed by the model's name.
## Basic Form Design
The Django form attributes control field attributes. The Crispy `FormHelper()` and `Layout()` objects control the `` tags and the layout of the fields, respectively.
### Setting Field Attributes
Django allows for field attributed to be configured in the form class. For `ModelForm` instances, this is done in the form's `__init__` method. Attributes should be set at the top of the `__init__` method, like so:
```json theme={"system"}
def __init__(self, *args, **kwargs):
super(ClientContactForm, self).__init__(*args, **kwargs)
self.fields["name"].widget.attrs["placeholder"] = "David McQuire"
self.fields["name"].widget.attrs["autocomplete"] = "off"
self.fields["email"].widget.attrs["placeholder"] = "info@specterops.io"
self.fields["email"].widget.attrs["autocomplete"] = "off"
self.fields["job_title"].widget.attrs["placeholder"] = "CEO"
self.fields["job_title"].widget.attrs["autocomplete"] = "off"
self.fields["phone"].widget.attrs["placeholder"] = "(800) 444-4444"
self.fields["phone"].widget.attrs["autocomplete"] = "off"
self.fields["note"].widget.attrs[
"placeholder"
] = "Additional notes for the contact"
```
A `placeholder` attribute should be set for all fields. The placeholder text should provide an example of the intended content or an example of the proper input format. In more freeform fields, the placeholder should identify the field and guide the user towards its intended purpose (e.g., the `note` field in the above example).
All fields should set `autocomplete` to `off` unless it is explicitly needed. Otherwise, autocomplete behavior can negatively impact user experience (e.g., autocomplete lists appearing and covering datepickers) or display non-public information when clicking on the field. The latter is mostly an issue for demonstrations of Ghostwriter.
### FormHelper Object
Every form should have a `FormHelper()` object named `self.helper`. Create a `FormHelper()` object named in the form's `__init__` method. At a minimum, Ghostwriter form helpers set several values. These values ensure the form appears correctly in the content of the rendered webpage.
```json theme={"system"}
# Design form layout with Crispy FormHelper
self.helper = FormHelper()
# Explicitly turn on/off