Wiki: Topnew Form Helper

Wiki: CMS Form Helper v 2018.09.09

Topnew Form helper generates html form, with data validation. It also generates SQL based on input values. Let's start with an example:

Let's start with a quick Example:

/* Define all form fields in array or json */
$cols = [
    'form' => [
        'class' => 'formH',
    ],
    'name' => [
        //'type' => 'text', // default no need to specify
    ],
    'gender' => [
        'type' => 'radio',
        'list' => ['M' => 'Male', 'F' => 'Female'],
    ],
    'status' => [
        'type' => 'cbox', // or checkbox
        'list' => 'Active'
    ],
    'groups' => [
        //'type' => 'sele', // default list for select no need to specify
        'list' => [10 => 'Admin', 11 => 'Sales', 12 => 'Support'],
    ],
    'cmd' => [
        'type' => 'submit',
        'value' => 'Search',
    ],
];

$form = new Form($cols);
echo $form->form(); // output the whole form html code according to above definition.

1 - $form->form()

1a - If you defined $cols, above will output the whole html form.

1b - If you do not defined $cols, it will only output <form ...>

1c - You can also do each form field output in the following way, without definition of $cols, or if $cols defined, the following will over-write $cols:

echo $form->form($name, $data, $type); // eg ->form('name', $name, 'text');
echo $form->form($name, $data, $attr); // eg ->form('gender', $gender, ['type' => 'radio', 'list' => [...]]);

1d - Deprecated: output part of $cols eg // ->form('form,name,gender,end');

2 - $type : all valid and invalid html form input types are supported. eg <b>form, text, select, checkbox, radio, password, submit, hidden, reset, number, date, ...</b>

There are additional 5 special types:

2a - <b>boot1</b> - to produce all html code before a form field eg input

2b - <b>boot2</b> - to produce all html code after a form field eg input

The purpose of <b>boot1, boot2</b> is that you can easily insert any html into a bootstrap form element group.

2c - <b>html</b> - to produce html text instead of a form field eg input

2d - <b>end</b> - output <b></form></b> - $form() will automatically add this to the end of each form.

2e - <b>ajax</b> - will call ajax to generate html code based on other form field is updated etc

3 - Name of a form field

$cols = [
    'status' => [...], // without name, status is the name
    'add' => [
        'type' => 'submit',
        'name' => 'cmd',
    ],
    'cmd' => [
        'type' => 'submit',
        'value' => 'Delete',
    ],
]

Above will output:

4 - Default value of a form field

$cols = [
    'name' => [
        'value' => 'Origin',
    ]
]

Once you changed the value and submit the form, the value submitted will be the changed value, instead original.

5 - Attributes of a form field

$cols = [
    'region' => [
        'type' => 'select',
        'list' => [
            'North America' => [1 => 'USA', 'Canada', ...],
            'Europe' => [5 => 'UK', ...],
        ],
        'multiple',
        'data-src' => 'some value',
        'class' => 'css class',
        'label' => 'Label Text',
        'label_class' => 'label class',
    ],
];

<div class="row">
  <label class="label class">Label Text</label>
  <select name="region" multiple data-src="some value" class="css class">
    <optgroup label="North America">
      <option value="1">USA</option>
    </optgroup>
    ...
  </select>
</div>

6 - Form layout, vertical, horizontal, label-less

$cols = [
    'form' => [
        'class' => 'formH',
        'data-label' => 'col-3',
        'data-kid' => 'col-9',
    ]
]

Above setting will produce a horizontal form, each line has a label and form field, and you do not need to specify bootstrap css class, as any css class in <b>data-label, data-kid</b> will be applied to any row like the following:

<div class="row">
    <label>First Name</label>
    <input type="text" name="first_name">
</div>

As a result each row will be matched for <b>col-3</b> for the labels and <b>col-9</b> for the input etc.

6a - Vertical form, which means the label will occupy a whole row followed by a whole row of input etc. In this case you just specify:

$cols = [
    'form' => [
        'data-label' => 'col-12'
    ]
]

6b - horizontal form without label:

$cols = [
    'form' => [
        'class' => 'formH label-0',
    ]
]

There are 3 ways to turn off label:

cols.form.class = label-0
cols.form.global.label = -1
cols.name.label = -1

7 - Ajax

$cols = [
    'status' => [ ... ],
    'sub_status' => [
        'type' => 'ajax',
        'data-src' => 'status', // when id="status" changed, ajax will be called
        //'ajax' => '/ajax', // default url to call ajax
        //'ajax_controller' => 'App.Controller.AjaxController', // default ajax controller
        //'data-cmd' => 'change', // default event trigger
        //'ajax' => ['func' => 'sub_status'], // if not specified, ajax will call ajaxController@subStatus()
    ],
];

8 - Some advanced features

cols.name.prefix = 'Some html code after </label> and before <input>'
cols.name.postfix = 'some html code after input and before </div>'
cols.name.acs = 'R' // this field is read only for all user
cols.form.global.role = 'Admin' // role for current session user, used for acs
cols.email.acs = ['All' => 'R', 'Admin' => 'W'] // Admin can write else read only
cols.name.clean = 'int' // this field is int for data validation
cols.name.box_ = 'html attribute or style for row'
cols.name.label_ = 'html attribute or style for label'
cols.name.defa = 'Please select' // default select option for <select>
cols.name.defa = [''=>'Please select', -1 => '...']
cols.name.style = 'some css styles'
cols.name.id = 'id_otherwise_name'
cols.name.valid = 'req' // required
cols.name.valid = ['req', 'int' => 'customer Err msg: only int allowed', ...]
cols.form.global.all_req = 1 // all fields required
Shorthand types:

cbox = checkbox
pass = password
sele = select

For the full list of features, please check docs on code page.

9 - SQL

cols.a.sql = 'like'
cols.b.sql = 'first_name'
cols.c.sql = '!='
cols.d.sql = ['status', '=', 123]
cols.e.sql = ['status', 'start']
cols.f.sql = -1 // ignore SQL for this field

It will be used for a search form, where sql will be produced like:

$sql = $form->search('my customer SQL');

WHERE 1
  AND a LIKE :a // :a = '%' . $a . '%'
  AND first_name = :b // :b = $b
  AND c != :c
  AND status = 123
  AND status like :e // :e = $e . '%'
  AND my customer SQL

SQL will automatically skip field type form, submit, reset, html

Wiki: Topnew Form Helper

Wiki: CMS Form Helper v 2018.09.09

Category