gajus/dora

Input generation library for value resolution, data persistence, templates, CSRF and protection from XSS.

Dora

, _(*1)

Input generation library for value resolution, data persistence, templates, CSRF and protection from XSS., _(*2)

Documentation

This document serves as Dora API documentation. If you prefer, you can learn Dora API while browsing the interactive demonstration and use this document for the API reference., _(*3)

Form

Form is a data container., _(*4)

/**
 * @param array $data Data used to populate Input generated using an instance of this Form.
 * @param null|string $template Template class name.
 */
$form = new \Gajus\Dora\Form([
    'foo' => 'Heeeere\'s...Johnny!',
    'bar' => 'Yada, yada, yada.',
    'baz' => 0,
    'qux' => ['1', 2 => '3'],
    'corge[grault]' = 'garply'
], null);

Input generated using an instance of the Form will inherit Form data., _(*5)

echo $form->input('foo');

Input with name "foo" will inherit "Heeeere's...Johnny!" value:, _(*6)

<input name="foo" type="text" value="Heeeere's...Johnny!">

Input can be any type of HTML input., _(*7)

echo $form->input('bar', ['type' => 'textarea', 'class' => 'test']);
echo $form->input('baz', null, ['options' => ['Knock, knock...', 'Come in.']]);

<textarea class="test" name="bar">Yada, yada, yada.</textarea>
<select name="baz">
    <option value="0" selected="selected">Knock, knock...</option>
    <option value="1">Come in.</option>
</select>

Input name can resolve value from an array:, _(*8)

echo $form->input('corge[grault]');

When Input is declared using variable array syntax, Input index (ie., order in which Input is generated) will be matched against the value with the respective index in the data array., _(*9)

echo $form->input('qux[]');
echo $form->input('qux[]');
echo $form->input('qux[]');

<input name="qux[]" type="text" value="1">
<input name="qux[]" type="text" value="">
<input name="qux[]" type="text" value="3">

Input

Input is a standalone entity defined with four parameters. Only the first parameter is required., _(*10)

/**
 * @param string $name Input name.
 * @param array $attributes HTML attributes.
 * @param array $properties Input properties, e.g. input name.
 * @param null|string $template Template class name.
 */
new \Gajus\Dora\Input('foo', ['type' => 'textarea'], ['name' => 'Foo'], null);

Most of the time, Form will act as a factory to produce Input (like in all the examples on this page)., _(*11)

HTML attributes

HTML attributes that are added to the generated input. All attributes will be taken literally except "type". "type" attribute will change the actual input type, e.g. "select" will make input <select>, "textarea" will make it <textarea>., _(*12)

Input Properties

Input properties are used at the time of generating the input template., _(*13)

Template

Input can be dressed using a Template. Template is utilsed when input is casted into a string. Form template will become the default template for all the Input generated using an instance of that Form:, _(*14)

$form = new \Gajus\Dora\Form([], 'Gajus\Dora\Template\Traditional');

"Gajus\Dora\Template\Traditional" is the default template. null will return input without template., _(*15)

Traditional Template

Traditional template consists of label, input and optional description., _(*16)

```html+php getInput(); $input_id = $input->getAttribute('id'); $description = $input->getProperty('description'); $class = $input->getProperty('class'); $class = $class ? ' ' . $class : ''; ob_start();?> , <sub>(*17)</sub>

        <?php if ($description):?>
        <div class="description">
            <p><?=$description?></p>
        </div>
        <?php endif;?>
    </div>
    <?php
    return ob_get_clean();
}

##### Styling

Dora or the Traditional template does not impose style. The [example of styling the Tranditional layout](http://jsfiddle.net/vac2E/1/) is for illustration purposes only.

![Traditional template example](./docs/static/image/traditional-template.png)

#### Writing a Template

Template class must extend `Gajus\Dora\Template`.

Refer to the existing templates to learn more.

### CSRF

Form generated using Dora need to be signed:

```php
$form = new \Gajus\Dora\Form();
?>
<form>
    <?=$form->sign()?>
    <input type="submit">
</form>

<input type="hidden" name="gajus[dora][uid]" value="2953768934">
<input type="hidden" name="gajus[dora][csrf]" value="d0be2dc421be4fcd0172e5afceea3970e2f3d940">

// $form from the preceding example.

if ($form->isSubmitted()) {
    // This will be triggered if CSRF passed.
}

if ($_SERVER['REQUEST_METHOD'] === 'POST') {}
if (isset($_POST['gajus'])) {}
if (isset($_POST['your']['input'])) {}

{
    "require": {
        "gajus/dora": "0.1.*"
    }
}