First, you have to write your code in HTML, for instance:, (*6)
<!-- forms/example.html -->
<form method="post">
Enter your name:
<input type="text" name="name" /><br />
<input type="submit" />
</form>
Step 3: Give it to Formidable
In your PHP code, give your form to Formidable:, (*7)
handle(function() {
echo "Form OK!";
}, function($errors) {
echo "Errors: ";
foreach ($errors as $error) {
echo "$error ";
}
});
echo $form;
```
Simple, right?
### Step 4: Enjoy the magic
You can then use the Formidable API to play with your form:
```php
name = "Bob";
// Will get the value of the field
$name = $form->name;
// Adds a constraint on the name
$form->addConstraint('name', function($value) {
if (strlen($value) addConstraint(function($form) {
if ($form->getValue('pass1') != $form->getValue('pass2')) {
return 'The passwords are different';
}
});
```
You can also try to change your form and add constraint directly in
the HTML code:
```html
```
This will force the text to be at least 10 characters long when the
server-side constraints will be checked.
Want a CAPTCHA to secure your form?
```html
```
This will generate an image and an input field on the client-side, and use
session on the server-side to check that the code is correct.
Note that this will use the dependency with [Gregwar/Captcha](https://github.com/Gregwar/Captcha/)
library (you will have to install dependencies using composer).
## Types
The following input types are supported:
* `input` tags, with types:
* `text`
* `number` or `numeric`, see `min` and `max` attributes
* `int` or `integer`, see `min` and `max` attributes
* `file`
* `checkbox`
* `radio`
* `hidden`
* `password`
* `captcha`, will automatically generate an image
* `date`, will generate three selects, and return a `DateTime` as data
* `multiradio` and `multicheckbox` (see the source section)
* `textarea`
* `select`
## Attributes
Note that some attributes are not HTML-valid, like `maxlength`:
```html
```
It will not be rendered in the HTML form, but will be used to check integrity.
Here is the list of available attributes:
* `minlength`: the minimum length of the value
* `maxlength`: the maximum length of the value
* `regex`: the regexp that the value should respect
* `min` (for numbers): the minimum value
* `max` (for numbers): the maximum value
* `required`: tell that the field is required
* `readonly`: the field is readonly and should not be modifier
* `value`: the default value for the field
* `min-entries`: specify the minimum number of
entries that you should provide for a multiple (see below)
* `max-entries`: specify the maximum number of
entries that you can provide for a multiple (see below)
* `entries`: specify both minimum and maximum number of entries
for a multiple (see below)
## API
You can call these method on your `$form` object:
* `posted()`: return true if the form was posted
* `check()`: check the form and return an array of validity errors
* `handle($callback, $errorCallback)`, this shortcut method call posted
and check(), and will call `$callback` if the form is valid, `$errorCallback`
else
* `setAttribute($field, $attr, $value)`: sets an extra attribute on a field
* `getAttribute($field, $attr)`: gets an extra attribute on a field
* `source($source, $values)`: feed a source (see the "Source" section)
* `setPlaceholder($name, $value)`: sets a placeholder value (see below)
* `addConstraint($field, $callback)`: adds a custom constraint on a field, the
`callback` will be called with the field value and should return false if no
problem, or an error string. If you just pass a closure to it, the closure will
be called with the form passed as argument and can then do some tests involving
multiple fields or form information.
* `setValue($field, $value)`: set the value of a field
* `getValue($field)`: gets the value of a field
* `setValues(array $values)`: set the values for some fields
* `getValues()`: get the values of all fields
## CSRF protection
An additional CSRF token is automatically inserted in the form and checked
when it's submitted. Thus, all your forms will be secured.
The presence and validity of CSRF token is used to check that a form was
posted when calling `posted` method (it's used internally in `handle`)
If you specify the `name` attribute in the `form`, the CSRF token will be
different for this specific form, this will allow Formidable to make the
difference of which form is submitted if there is multiple form on the same
page.
## Languages
The language for the errors can be set with `setLanguage()`:
```php
setLanguage(new Gregwar\Formidable\Language\French);
```
Check that your language is supported in the `Language` directory, don't hesitate
to participate!
## Source
You can use the sourcing system to populate dynamically a `select`, a `multiradio` or
a `multicheckbox`:
```html
```
Then populate it with `source`:
```php
source('colours', array('red', 'yellow', 'blue'));
```
This will be rendered by some checkboxes.
You can do it this way with `select`:
```html
```
And then source it with the same method
## Creating form from string
You can create form from a file or from a string, this will be detected automatically:
```php
');
echo $form->getValue('colour') . "\n";
// red
// Sets the color to blue
$form->setValue('colour', 'blue');
echo $form;
/* Will display:
*/
```
## Mapping
You can also use `mapping` attribute to populate your form or to get back the form data in an array or
in an object, for instance:
```php
name; }
public function setName($name) {
$this->name = $name;
}
}
$person = new Person;
$person->setName('Jack');
$form = new Gregwar\Formidable\Form('');
$form->setData($person);
echo $form;
/*
Will output something like:
*/
```
Note that the mapping uses the [Symfony PropertyAccessor](https://github.com/symfony/PropertyAccess),
you can then use accessor as in the example above to populate properties.
You can use:
* `getData($entity = array())`: populate and return entity with data populated
* `setData($entity)`: populate the form with the entity attributes
## Creating multiple sub-forms
You can add multiple sub-forms to a page using the `` tag:
```html
```
With this, the `` can be used exactly like a field, but it will
contains an array of elements.
Some JS will be injected in the page and allow you to add/remove some
elements.
You can use `min-entries` and `max-entries` constraint to set limits on the
number of entries in a multiple.
If you specify the same value for `min-entries` and `max-entries`, or specify
a value for `entries` (which is actually an alias to do it), the number ofr inputs
will be fixed and no javascript will be required.
## Adding dynamic data into the form
In some case, you'll want to add custom data into the form, there is two way to do this.
### First way: using the placeholders
The `{{ something }}` syntax allow you to simply inject data from the code, like this:
```php
Hello {{ name }}!
');
$form->setPlaceholder('name', 'Bob');
echo $form;
```
In the example above, the `{{ name }}` will be rendered as `Bob`.
Note that placeholders may be used anyway excepted in the `');
$form->setPlaceholder('color', 'red');
echo $form;
```
### Second way: using PHP form
You can also write your form using PHP, like a template, for instance:
```php
Wallogit.com
