tuum/form

form generator and other template helpers.

Tuum/Form

Various helper classes for generating Html tags and managing data., _(*1)

• Status: Alpha release.
• Psr-1, Psr-2, and Psr-4.

Licence

MIT Licence, _(*2)

Getting Started

Installation

composer require "tuum/form: 0.2.*"

code

The DataView object is the master of all other services. For instance,, _(*3)

use Tuum\Form\DataView;

$view = new DataView();
$view->setInputs([
    'name' => 'value',
    'more' => [
        'key' => 'val'
    ]
]);
echo $view->inputs->get('name'); // 'value'
echo $view->inputs->get('more[key]'); // 'val'
echo $view->forms->text('name', 'default'); // text input form

The forms helper generates an html tag for input[type=text] with the value attribute (not 'default' but) 'value' which is set in the $inputs, like;, _(*4)

<input type="text" name="name" value="value" />

Helpers

These helpers help to manage data to be viewed in a template. There are,, _(*5)

• Escape,
• Data,
• Inputs,
• Errors,
• Message,
• Forms, and
• Dates,

helpers., _(*6)

Escape Helper

Use Escape class to manage escape method when redering a string inside a template. As a default, strings will be escaped using htmlspecialchars function for HTML files., _(*7)

$esc = new Escape();
echo $esc('<danger>safe</danger>'); // or
echo $esc->escape('<danger>safe</danger>');

You can specify another escape method at the construction or using withEscape method:, _(*8)

$esc = new Escape('addslashes');
// or
$esc = $esc->withEscape('rawurlencode');

The helpers registered in DataView will use the escape object;, _(*9)

$view = new DataView(new Escape('addslashes'));
$view->inputs->get('with-slash'); // escaped with addslashes.

Data Helper

Use Data class to display strings and values to template while escaping the values., _(*10)

$data = Data::forge(['view'=>'<i>val</i>'], $esc);
// or 
$view = new DataView();
$view->setData(['some'=>'value']);
$data = $view->data;

to access data, any of the following works., _(*11)

echo $data['view'];      // escaped
echo $data->view;        // escaped
echo $data->get('view'); // escaped
echo $data->raw('view'); // raw value
echo $data->get('none', 'non\'s'); // show escaped default value

iteration

the Data object implements IteratorAggregate interface., _(*12)

$data1 = [
    'text' => 'testing',
    'more' => '<b>todo</b>',
];
$data2 = [
    'text' => 'tested',
    'more' => '<i>done</i>',
];
$data = Data::forge([$data1, $data2]);
foreach($data as $key => $val) {
    echo "$key: ", $val->text;
    echo "$key: ", $val->more; // escaped. 
}

caution when using the iteration..., _(*13)

$data = Data::forge([
      'text' => 'tested',
      'more' => '<i>done</i>',
  ]);
  foreach($data as $key => $val) {
      echo "$key: ", $val->get(null); // won't work!
  }
  

hidden tag

a simple method to show a hidden tag:, _(*14)

$data = Data::forge(['_method'=>'put']);
echo $data->hiddenTag('_method');  
// <input type="hidden" name="_method" value="put" />

extract by key

use extractKey method to create a subset of Data object if the data is an array of another array (or object)., _(*15)

$data = Data::forge(['obj'=>new ArrayObject['type' => 'object']);
$obj = $data->extractKey('obj');
echo $obj->type;  // object

Inputs Helper

The Inputs class introduces a convenient way to access array of data using names of HTML form elements. (think Laravel's Input::old values are populated in Form class)., _(*16)

<?php
$input = Inputs::forge([
    'name' => '<my> name',
    'gender' => 'male',
    'types' => [ 'a', 'c' ],
    'sns' => [
        'twitter' => 'example@twitter.com',
        'facebook' => 'example@facebook.com',
    ],
], $esc);
echo $input->get('name'); // escaped '<my> name'
echo $input->checked('gender', 'male');   // ' checked'
echo $input->checked('gender', 'female'); // empty
vardump($input->get('types')); // ['a', 'c']
echo $input->checked('types', 'a'); // ' checked'
echo $input->checked('types', 'b'); // empty
echo $input->get('sns[twitter]'); // 'example@twitter.com'

Errors Helper

The Errors maybe used as conjunction with Inputs, where as Errors for invalidated message for input data., _(*17)

<?php
$errors = Errors::forge([
    'name' => 'message for name',
    'gender' => 'gender message',
    'types' => [ 2 => 'message for type:B' ],
    'sns' => [
        'facebook' => 'love messaging facebook?',
    ],
], $esc);
// default format is: <p class="text-danger">%s</p>
echo $errors->get('name'); // message for name
echo $errors->get('gender');   // gender message
echo $errors->get('types[2]'); // message for type:B
echo $errors->get('sns[facebook]'); // love messaging facebook?

Notice that the message for type:B has specific index number. In order for generic array input to work with error messages, you have to specify the index., _(*18)

To change the format of the error message, just do:, _(*19)

$errors->format = '<div>(*_*) %s</div>';

Message Helper

This helper may not be that generic. Message class is for general message to be displayed in a main contents of a web page., _(*20)

$message = new Message;
$message->add('hello');
$message->add('whoops', Message::ERROR);
echo $message->onlyOne(); 
// <div class="alert alert-danger">Whoops</div>

The onlyOne method shows only one first message that is most severe., _(*21)

Forms Helper

generates html form tags., _(*22)

$form = new Form();

// or using DataView
$view = new DataView();
$form = $view->forms;

input elements

Creates various form input element. The most generic method is input., _(*23)

<?= $form->input('text', 'name', 'default value'); ?>

will generate, _(*24)

<input type="text" name="name" value="default value" />

Already various methods exists for html's input tags, such as: text, hidden, email, password, radio, and checkbox., _(*25)

The extra html attribute can be added by method as follows., _(*26)

<?= $form->date('date')->class('form')->placeholder('date'); ?>

open/close forms

To start a form;, _(*27)

<?= $form->open()->action('to')->method('post')->uploader(); ?>
<?= $form->close(); ?>

if a non-standard method is given, it will generate a hidden tag with the method in the open() method, as;, _(*28)

<input type="hidden" name="_method" value="some-method" />

label

can output label as;, _(*29)

$form->label('label string', 'for-id');

buttons

currently, two buttons are supported., _(*30)

$form->submit('button name');
$form->reset('cancel me');

textArea

text-area is supported., _(*31)

$form->textArea('area-name', 'default value');

select list

it's easy to create a select box., _(*32)

$list = [
    '1' => 'selecting',
    '2' => 'is',
    '3' => 'easy',
];
$form->select('name', $list, '2');

checkbox and radio list

Often you want to generate a list of checkbox or radio buttons. You can build it a bit like a select box., _(*33)

$list = [
    '1' => 'checkbox',
    '2' => 'radio',
];
echo $form->checkList('checks', $list, '1');

will output;, _(*34)

<ul>
  <li><label><input type="checkbox" name="checks" value="1" />checkbox</label></li>
  <li><label><input type="checkbox" name="radio" value="1" /> radio </label></li>
</ul>

but you might not like the output above. then,, _(*35)

$list = $form->checkList('radio', $list, '2');
foreach(array_keys($list->getList()) as $key) {
   echo $key, ': ', $list->getInput($key), '<br/>';
}

will show how to construct html., _(*36)

ugly usage. need method like getKeys() method here., _(*37)

Dates Helper

a helper to create select box list style date fields. For instance,, _(*38)

echo $form->dates->dateYMD('day', '2015-06-18');

will generate html like (options are omitted);, _(*39)

<select name="day_y"></select>
<select name="day_m"></select>
<select name="day_d"></select>

to-be-written...., _(*40)