# Installation
Edit UserFrosting `app/sprinkles.json` file and add the following to the `require` list : `"lcharette/uf_formgenerator": "^2.0.0"`. Also add `FormGenerator` to the `base` list. For example:
```
{
"require": {
"lcharette/uf_formgenerator": "^2.0.0"
},
"base": [
"core",
"account",
"admin",
"FormGenerator"
]
}
```
Run `composer update` then `php bakery bake` to install the sprinkle.
# Features and usage
Before starting with _FormGenerator_, you should read the main UserFrosting guide to familiarize yourself with _validation schemas_: (https://learn.userfrosting.com/routes-and-controllers/client-input/validation).
## Form generation
### Defining the fields in the schema
This sprinkle uses the `schemas` used by UserFrosting to validate form data to build form. To achieve this, a new `form` key is simply added to the fields found in a `schema` file.
For example, here's a simple `schema` used to validate a form used to create a `project`. The form will contain a `name`, `description` and `status` fields.
```
{
"name" : {
"validators" : {
"length" : {
"min" : 1,
"max" : 100
},
"required" : {
"message" : "PROJECT.VALIDATE.REQUIRED_NAME"
}
}
},
"description" : {
"validators" : {}
},
"status" : {
"validators" : {
"member_of" : {
"values" : [
"0", "1"
]
},
"required" : {
"message" : "PROJECT.VALIDATE.STATUS"
}
}
}
}
```
> Note: FormGenerator works with json and YAML schemas.
At this point, with typical UserFrosting setup, you would be going into your controller and Twig files to manually create your HTML form. This can be easy if you have a two or three fields, but can be a pain with a dozen fields and more. This is where FormGenerator steps in with the use of a new `form` attribute. Let's add it to our `project` form :
```
{
"name" : {
"validators" : {
"length" : {
"min" : 1,
"max" : 100
},
"required" : {
"message" : "VALIDATE.REQUIRED_NAME"
}
},
"form" : {
"type" : "text",
"label" : "NAME",
"icon" : "fa-flag",
"placeholder" : "NAME"
}
},
"description" : {
"validators" : {},
"form" : {
"type" : "textarea",
"label" : "DESCRIPTION",
"icon" : "fa-pencil",
"placeholder" : "DESCRIPTION",
"rows" : 5
}
},
"status" : {
"validators" : {
"member_of" : {
"values" : [
"0", "1"
]
},
"required" : {
"message" : "VALIDATE.STATUS"
}
},
"form" : {
"type" : "select",
"label" : "STATUS",
"options" : {
"0" : "Active",
"1" : "Disabled"
}
}
}
}
```
Let's look closer at the `name` field :
```
"form" : {
"type" : "text",
"label" : "PROJECT.NAME",
"icon" : "fa-flag",
"placeholder" : "PROJECT.NAME"
}
```
Here you can see that we define the `type`, `label`, `icon` and `placeholder` value for this `name` field. You can define any standard [form attributes](http://www.w3schools.com/html/html_form_attributes.asp), plus the `icon`, `label` and `default` attributes. `data-*` attributes can also be defined in your schema if you need them. For the `select` element, a special `options` attribute containing an array of `key : value` can be used to define the dropdown options. The select options (as any other attributes) can also be set in PHP (see further below).
And of course, the values of the `label` and `placeholder` attributes can be defined using _translation keys_.
Currently, FormGenerator supports the following form elements :
- text (and any input supported by the HTML5 standard : number, tel, password, etc.)
- textarea
- select
- checkbox
- hidden
- alert (Display a static alert box in the form)
### The controller part
Once your fields defined in the `schema` json or yaml file, you need to load that schema in your controller.
First thing to do is add FormGenerator's `Form` class to your "use" list :
`use UserFrosting\Sprinkle\FormGenerator\Form;`
Next, where you load the schema and setup the `validator`, you simply add the new Form creation:
```
// Load validator rules
$schema = new RequestSchema("schema://project.json");
$validator = new JqueryValidationAdapter($schema, $this->ci->translator);
// Create the form
$form = new Form($schema, $project);
```
In this example, `$project` can contain the default (or current value) of the fields. A data collection fetched from the database with eloquent can also be passed directly. That second argument can also be omited to create an empty form.
Last thing to do is send the fields to Twig. In the list of retuned variables to the template, add the `fields` variable:
```
$this->ci->view->render($response, "pages/myPage.html.twig", [
"fields" => $form->generate(),
"validators" => $validator->rules('json', true)
]);
```
### The Twig template part
Now it's time to display the form in `myPage.html.twig` !
```
```
That's it! No need to list all the field manually. The ones defined in the `fields` variable will be displayed by `FormGenerator/FormGenerator.html.twig`. Note that this will only load the fields, not the form itself. The `