Skip to content

Commit

Permalink
Update the README.md file
Browse files Browse the repository at this point in the history
  • Loading branch information
@nicksagona
nicksagona committed Jul 23, 2015
1 parent b6b2836 commit 941a79f
Showing 1 changed file with 232 additions and 41 deletions.
273 changes: 232 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,51 +28,38 @@ Install `pop-form` using Composer.

## BASIC USAGE

* [Using field configurations](#using-field-configurations)
* [Using field element objects](#using-field-element-objects)
* [Using field configurations](#using-field-configurations)
* [Templates](#templates)
* [Filtering](#filtering)
* [Validation](#validation)
* [Dynamic fields from a database table](#dynamic-fields-from-a-database-table)

### Using field configurations

The form object will default to 'post' as the method and the current request URI as
the action otherwise changed by the user.
### Using field element objects

```php
use Pop\Form\Form;
use Pop\Form\Element\Input;
use Pop\Validator;

$fields = [
'username' => [
'type' => 'text',
'label' => 'Username:',
'required' => true,
'attributes' => [
'size' => 40
],
'validators' => [
new Validator\AlphaNumeric()
]
],
'email' => [
'type' => 'email',
'label' => 'Email:',
'required' => true,
'attributes' => [
'size' => 40
]
],
'submit' => [
'type' => 'submit',
'value' => 'SUBMIT'
]
];

$form = new Form($fields);
$form = new Form();
$form->setAttribute('id', 'my-form');

$username = new Input\Text('username');
$username->setLabel('Username:')
->setRequired(true)
->setAttribute('size', 40)
->addValidator(new Validator\AlphaNumeric());

$email = new Input\Email('email');
$email->setLabel('Email:')
->setRequired(true)
->setAttribute('size', 40);

$submit = new Input\Submit('submit', 'SUBMIT');

$form->addElements([$username, $email, $submit]);

if ($_POST) {
$form->setFieldValues($_POST);
if (!$form->isValid()) {
Expand All @@ -85,14 +72,20 @@ if ($_POST) {
}
```

So a few different things are going on in the above example:

1. We set a `$fields` configuration array first, defining the field type, name, label, attributes, validators, etc.
2. We created the form object, passed it the `$fields` config and gave it an 'id' attribute.
3. We checked for a $_POST submission. If not detected, we just render the form for the first time.
4. If a $_POST submission is detected:
1. Set the field values with the values in the $_POST array (a bad idea without any [filtering](#filtering))
2. Check if the form object passes validation. If not, re-render the form with the errors. If it does pass, then you're good to go.
So a few things are going on in the above example:

1. We created the form object and gave it an 'id' attribute.
2. We created the individual field elements setting their name, label, attributes, validators, etc.
3. We added the field elements to the form object
4. We checked for a $_POST submission. If not detected, we just render the form for the first time.
5. If a $_POST submission is detected:
1. Set the field values with the values in the $_POST array
(a bad idea without any [filtering](#filtering))
2. Check if the form object passes validation. If not, re-render the form with the errors.
If it does pass, then you're good to go.

Just as a note, the form object will default to 'post' as the method and the
current request URI as the action otherwise changed by the user.

On the first pass, the form will render like this:

Expand Down Expand Up @@ -145,12 +138,210 @@ If it fails validation, it will render with the errors. In this case, the userna

[Top](#basic-usage)

### Using field element objects
### Using field configurations

We can do the same thing as above with a field configuration array,
which helps streamline the process a bit:

```php
use Pop\Form\Form;
use Pop\Validator;

$fields = [
'username' => [
'type' => 'text',
'label' => 'Username:',
'required' => true,
'attributes' => [
'size' => 40
],
'validators' => [
new Validator\AlphaNumeric()
]
],
'email' => [
'type' => 'email',
'label' => 'Email:',
'required' => true,
'attributes' => [
'size' => 40
]
],
'submit' => [
'type' => 'submit',
'value' => 'SUBMIT'
]
];

$form = new Form($fields);
$form->setAttribute('id', 'my-form');

if ($_POST) {
$form->setFieldValues($_POST);
if (!$form->isValid()) {
echo $form; // Has errors
} else {
echo 'Valid!';
}
} else {
echo $form;
}
```

[Top](#basic-usage)

### Templates

By default, the form object will render using a DL element with a 1:1 matching DT and DD
elements for field labels and elements. However, you can easily expand your control over
the rendering and display of the form object by using templates.

#### Using a stream template

Consider the following stream template for the above example `form.html`:

```html
<table>
<tr>
<td>
[{username_label}]
</td>
<td>
[{username}]
</td>
</tr>
<tr>
<td>
[{email_label}]
</td>
<td>
[{email}]
</td>
</tr>
<tr>
<td>
&nbsp;
</td>
<td>
[{submit}]
</td>
</tr>
</table>
```

We can then set the template for the form object like this:

```php
$form->setTemplate('form.html');
```

And it will render like this:

```html
<form action="/" method="post" id="my-form">
<table>
<tr>
<td>
<label for="username" class="required">Username:</label>
</td>
<td>
<input type="text" name="username" id="username" value="" required="required" size="40" />
</td>
</tr>
<tr>
<td>
<label for="email" class="required">Email:</label>
</td>
<td>
<input type="email" name="email" id="email" value="" required="required" size="40" />
</td>
</tr>
<tr>
<td>
&nbsp;
</td>
<td>
<input type="submit" name="submit" id="submit" value="SUBMIT" />
</td>
</tr>
</table>
</form>
```

#### Using a file template

Similarly, you could use a PHP file template. Consider the PHTML file `form.phtml`:

```php
<form action="<?php echo $action; ?>" method="<?php echo $method; ?>">
<table>
<tr>
<td>
<?php echo $username_label . PHP_EOL; ?>
</td>
<td>
<?php echo $username . PHP_EOL; ?>
</td>
</tr>
<tr>
<td>
<?php echo $email_label . PHP_EOL; ?>
</td>
<td>
<?php echo $email . PHP_EOL; ?>
</td>
</tr>
<tr>
<td>
&nbsp;
</td>
<td>
<?php echo $submit . PHP_EOL; ?>
</td>
</tr>
</table>
</form>
```

Set that as the template:

```php
$form->setTemplate('form.phtml');
```

and it would render like this:

```html
<form action="/" method="post">
<table>
<tr>
<td>
<label for="username" class="required">Username:</label>
</td>
<td>
<input type="text" name="username" id="username" value="" required="required" size="40" />
</td>
</tr>
<tr>
<td>
<label for="email" class="required">Email:</label>
</td>
<td>
<input type="email" name="email" id="email" value="" required="required" size="40" />
</td>
</tr>
<tr>
<td>
&nbsp;
</td>
<td>
<input type="submit" name="submit" id="submit" value="SUBMIT" />
</td>
</tr>
</table>
</form>
```

[Top](#basic-usage)

### Filtering
Expand Down

0 comments on commit 941a79f

Please sign in to comment.