Wiki: Topnew\Util\Form v 2026.04.04
Topnew Form is a view helper class used to generate HTML form elements programmatically.
Sample Usage:
<?= Form::text('email') ?>
This will generate the following HTML:
<input type="text" name="email">
You can also use the global helper function to achieve the same result:
<?= form('text', 'email') ?>
function form($type = null, $name = null, $css = null, $attr = null, $list = null)
Let's walk through a complete form example step by step.
For brevity, the following examples use the shorthand syntax:
[?= form(...) ?]
In actual usage, you should use:
<?= form(...) ?>
or (depending on your template engine):
{!! form(...) !!}
1. form('form', $url = '', $css = '', $attr = [ ], $method = '')
[?= form('form') ?]
HTML:
[form method="POST"]
[input value="b664686f26308c3321e33f0f" name="csrf" type="hidden"]
By default, a form uses the POST method. A CSRF token is automatically added to all POST forms for security.
$url = form action url eg /save.php $css = any css class for this form $attr = any html attr for this form eg ['id' => 'myForm', ...] $method = 'GET', otherwise by default POST
2. form('text', $name = '', $css = '', $attr = [])
[?= form('text', 'email', 'css', ['required', 'placeholder' => 'Email*']) ?]
HTML:
[input type="text" name="email" class="css" required placeholder="Email*"]
You can set 'value' => 'some value' in $attr, if no value is set in $attr, the Form will try to pre-fill with _POST or _GET or old() values in previous page redirect (e.g. after form submission). For the very first time of page loading, if you need a default value, you can set via $attr['value']
3. form('hidden', $name = '', $css = '', $attr = [])
[?= form('hidden', 'token', '', ['value' => 'abc']) ?]
HTML:
[input type="hidden" name="token" value="abc"]
4. form('email', $name = '', $css = '', $attr = [])
This is just an alias of form('text', ...) with different input type. HTML5 supports various specialized input types, such as: email, number, tel, date, datetime, url, color, file, ... etc
[?= form('number', 'amt', 'ar', ['step' => 0.01]) ?]
HTML:
[input type="number" name="amt" class="ar" step="0.01"]
5. form('textarea', $name = '', $css = '', $attr = [])
[?= form('textarea', 'info', 'cell-12', ['style' => 'height:150px']) ?]
HTML:
[textarea name="info" class="cell-12" style="height:150px"][/textarea]
6. form('checkbox', $name = '', $css = '', $attr = [], $list = [])
A shortcut alias is available as cbox.
[?= form('cbox', 'groups', '', [], [1 => 'Group A', 'Group B']) ?]
HTML:
[label][input type="checkbox" name="groups[]" value="1"] Group A[/label]
[label][input type="checkbox" name="groups[]" value="2"] Group B[/label]
When multiple options are provided, the helper automatically appends [] to the name attribute so that the submitted values are collected as an array.
$list is an associative or indexed array where keys become the checkbox values and values become the labels.
Sometimes if there is only one option, you can pass in $list as string eg
[?= form('cbox', 'active', '', [], 'Active member') ?]
HTML:
[label][input type="checkbox" name="active" value="1"] Active member[/label]
7. form('radio', $name = '', $css = '', $attr = [], $list = [])
[?= form('radio', 'gender', '', [], ['M' => 'Male', 'F' => 'Female']) ?]
HTML:
[label][input type="radio" name="gender" value="M"] Male[/label]
[label][input type="radio" name="gender" value="F"] Female[/label]
For checkbox and radio inputs, you may need to specify a glue string to control how individual options are joined together when rendered. For example:
$attr['glue'] = '<br>';
This would display each option on a new line. By default, the glue value is a single space (' ').
8. form('select', $name = '', $css = '', $attr = [], $list = [])
[?= form('select', 'status', '', [], [1 => 'Active', 2 => 'Closed']) ?]
HTML:
[select name="status"]
[option value=""]Please select[/option]
[option value="1">Active[/option]
[option value="2">Closed[/option]
[/select]
For checkbox, radio, and select inputs, you may sometimes want the $list keys to be the same as their values. In this case, you can enable this behavior by setting:
$attr['kv'] = 1;
Then you can define your list as a simple array:
$list = ['Open', 'Closed'];
[?= form('select', 'status', '', ['kv' => 1], ['Open', 'Closed']) ?]
HTML:
[select name="status"]
[option value=""]Please select[/option]
[option value="Open">Open[/option]
[option value="Closed">Closed[/option]
[/select]
For select inputs, a default first option is automatically included:
[option value=""]Please select[/option]
If you want to remove this default entry, set:
$attr['defa'] = -1;
You can replace the default text by providing a string:
$attr['defa'] = 'Please select your group';
This will render:
[option value=""]Please select your group[/option]
You can also define multiple options at the top of the list by passing an associative array:
[?php $defa = ['' => 'Please select', 'CN' => 'China', 'AU' => 'Australia']; ?]
[?= form('select', 'country', '', compact('defa'), $countries) ?]
HTML:
[select name="country"]
[option value=""]Please select[/option]
[option value="CN">China[/option]
[option value="AU">Australia[/option]
... rest loop via $countries
[/select]
If $list is a nested array, it will be rendered as [optgroup] elements in a select input.
[?php
$list = [
'Label A' => [1 => 'ABC', 3 => 'XYZ'],
'Group B' => [5 => 'BBB', 8 => 'EEE'],
];
?]
[?= form('select', 'hobby', '', 'multiple', $list) ?]
HTML:
[select multiple name="hobby[]"]
[option value=""]Please select[/option]
[optgroup label="Label A"]
[option value="1"]ABC[/option]
[option value="3"]XYZ[/option]
[/optgroup]
[optgroup label="Group B"]
[option value="5"]BBB[/option]
[option value="8"]EEE[/option]
[/optgroup]
[/select]
When $list contains nested arrays, each top-level key becomes an [optgroup] label
If $attr includes 'multiple', the name attribute will automatically be suffixed with [] (e.g. hobby[]).
If $attr contains only a single value, it can be passed as a string instead of an array (e.g. 'multiple')
9. form('button', $name = '', $css = '', $attr = [], $label = '')
[?= form('button', 'cmd', 'btn bg-red', [], 'Save') ?]
HTML:
[button name="cmd" value="Save" class="btn bg-red" type="submit"]Save[/button]
he default button type is submit.
You can override the type via $attr, for example:
$attr['type'] = 'reset';
If $label is not provided, it will default to the value of $name.
You can also create a submit button using an [input type="submit"] instead of a [button]:
[?= form('submit', 'cmd', 'btn bg-red', ['value' => 'Save']) ?]
10. form('close')
[?= form('close') ?]
HTML:
[/form]
11. form($type, $name, $css, $attr, ...)
As shown in the examples above, the 3rd parameter $css is used to add a class="..." attribute to form elements such as [input], [select], [button] and [textarea].
However, checkbox and radio inputs behave differently:
For most input types:
$css → applied to the input element
$attr['class'] → also applied to the input element
Both are merged into class="..."
For checkbox and radio:
$css and $attr['class'] → applied to the label, not the input
To style the actual input element, use:
$attr['input.class'] $attr['input.style']
Additional label styling:
$attr['label.style'] → applies inline styles to the label
12. form type alias
open = form, cbox = checkbox, pass = password, sele = select
13. form('label', $text = '', $css = '', $attr = [], $for = '')
[?= form('label', 'Some text', 'red', ['id' => 'xId'], 'abc') ]
HTML:
[label id="xId" class="red" for="abc"]Some text[/label]
14. form([]) — Build a Complete Form in One Go
You can generate an entire form using a single form([]) call. This allows you to define all form elements in a structured array.
form('html', $html) and form('csrf', $csrf) are rarely needed when using this approach, as they are handled automatically.
[?= form([
'form' => ['url.php', 'css'],
'name' => ['text'],
'email' => 'email', // shorthand for single element
'pass' => 'pass',
'male' => ['cbox', '', '', 'Male'],
'x' => ['html', 'some html code here ...'],
'status' => ['sele', '', ['kv' => 1], ['Active', 'Pending']],
'close',
]) ?]
HTML:
[form class="css" action="url.php" method="POST"]
[input value="ac5639ee97dcd7e235aec6c5" name="csrf" type="hidden"]
[label for="name"]Name[/label]
[input name="name" type="text"]
[label for="email"]Email[/label]
[input name="email" type="email"]
[label for="pass"]Pass[/label]
[input name="pass" type="password"]
[label for="male"]Male[/label]
[label][input type="checkbox" name="male" value="1"] Male[/label]
some html code here ...
[label for="status"]Status[/label]
[select name="status"]
[option value=""]Please select[/option]
[option value="Active"]Active[/option]
[option value="Pending"]Pending[/option]
[/select]
[/form]