From 941a79f4d396cfb65162e6603c4bd27218623ba2 Mon Sep 17 00:00:00 2001 From: Nick Sagona Date: Wed, 22 Jul 2015 22:08:42 -0500 Subject: [PATCH] Update the README.md file --- README.md | 273 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 232 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index eb5ac42..baff415 100644 --- a/README.md +++ b/README.md @@ -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()) { @@ -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: @@ -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 + + + + + + + + + + + + + +
+ [{username_label}] + + [{username}] +
+ [{email_label}] + + [{email}] +
+   + + [{submit}] +
+``` + +We can then set the template for the form object like this: + +```php +$form->setTemplate('form.html'); +``` + +And it will render like this: + +```html +
+ + + + + + + + + + + + + +
+ + + +
+ + + +
+   + + +
+
+``` + +#### Using a file template + +Similarly, you could use a PHP file template. Consider the PHTML file `form.phtml`: + +```php +
+ + + + + + + + + + + + + +
+ + + +
+ + + +
+   + + +
+
+``` + +Set that as the template: + +```php +$form->setTemplate('form.phtml'); +``` + +and it would render like this: + +```html +
+ + + + + + + + + + + + + +
+ + + +
+ + + +
+   + + +
+
+``` + [Top](#basic-usage) ### Filtering