Wiki: CMS Form Helper v5.5.3 - 2017.03.03

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

/* 0 - define all form fields: either in array or json */
$cols = [
    'form' => [
        'class' => 'page p btn bg-gold',
        'global'=> ['label' => -1, 'class'=>'span2']
    ],
    'name' => [
        'sql' => 'like',
    ],
    'office' => [
        'list' => ['AU', 'CN', 'UK', 'US'],
    ],
    'dob' => [
        'class' => 'datepicker span2',
    ],
    'male' => [
        'type' => 'checkbox',
        'list' => 'Male',
    ],
    'cmd' => [
        'type' => 'submit',
        'defa' => 'Search',
    ],
];
/* 1 - Register all form fields */
cms_form_cols($cols);
/* 2 - validate data or clean data */
$data = cms_form_data();
/* 3 - Build an html form */
echo cms_form();
/* 4 - Build a search SQL */
$sql = [
    'select'=> 'id,name,office,male,dob',
    'from'  => 'users',
    'where' => cms_form_search(),
];
/* 5 - Return pagination of search result */
$pgno = $data['pgno'];
$grid = cms_pgno($sql, $pgno);
/* 6 - Display pagination and data grid for current page */
echo $pgno;
cms_grid($grid);

Above cms_form() will output the following HTML:

If you do not register $cols, you can do manually one by one:

echo cms_form('form', '', '', ['class'=>'page btn bg-gold']);
echo cms_form('text', 'name', $name, ['class'=>'span2']);
echo cms_form('sele', 'office', $office, ['AU'=>'AU', ...]);
echo cms_form('date', 'dob',  $dob,  [...]);
echo cms_form('cbox', 'male', $male, 'Male');
echo cms_form('submit','cmd', 'Search');
echo cms_form('end');

The following is an example of search result: (in real world pagination will be clickable)

  1. «
  2. 1
  3. 2
  4. 3
  5. ...
  6. 168
  7. »

ID Name Office Male DOB
1 Tom Hanks US 1 1956-07-09
145 Tom Jerry US 1 1950-07-09
452 Lee Atom UK 0 2010-07-09

Now let's study how cms_form() actually works

1 - cms_form()

Once you registered all form fields attributes, you can simply call above one line to generate the whole form.

The benefit to register all form fields is that this info can be re-used later on when you do data validation, access control, search and pagination.

You can also customize how to print the whole form, eg cms_form('form;name;cmd;end') will only print the fields specified.

If $cols not defined, cms_form() == cms_form('form')

2 - cms_form($type, $name, $data, $attr)

You can always echo one form field at a time, and you can pass in field attributes to overwite those if already registered previously.

eg. echo cms_form('text', 'name', $name, ['class' => 'bg-red'])

3 - Types of a form field

Any valid or invalid html form types. eg. form, text, select, checkbox, radio, password, submit, hidden, reset, number, date, ...

if (!$cols[name][type]) {
    $cols[name][type] = isset($cols[name][list]) ? 'select' : (
        isset($cols[name][ajax]) ? 'ajax' : 'text'
    );
}

There are additional 6 special types:

boot1 to produce all html code for the starting part of an html form field including labels etc. eg cms_form('boot1', 'label-name', '', $attr);

boot2 to produce all html code for the ending part of an html form field. eg cms_form('boot2');

You can use boot1 + field1 + field2 + ... + boot2 when you need to have multiple form fields under one group.

html to insert html code as a form field. eg cms_form('hmtl', 'label-name', 'html text', $attr);

cms_form('end') same as </form>

ajax will call cms_ajax(...)

err to produce validation errors

eg echo cms_form('err') -- to produce $cols[form][err]
eg echo cms_form('err', $err) -- to show customized $err msg

4 - Name of a form field

Used for a form field name eg <input name="name" ... >

You can also modify name via $cols[$name][name] = 'new name';

eg $cols = [
    'add' => [
        'type' => 'submit',
        'name' => 'cmd',
    ],
    'del' => [
        'type' => 'submit',
        'name' => 'cmd',
    ]
];

5 - data: value of a form field

Used for a form field value eg <input value="data" ... >
For a select / checkbox / radio, data can be an array

$cols[$name][defa] = $default_value; // to set a default value

$cols[$name][val] = $fixed_value; // to set a fixed value

6 - Attributes of a form field

You can put as many key => value pairs as you want into $attr. It can be string or array, which will be used as html tag attributes.

eg $attr = 'id="user_id" class="className" placeholder="User ID" data-abc="some data" disabled ...';

eg $attr = ['id' => 'user_id', 'class' => 'css class', 'selected', 'data-form' => '...', ...];

These $cols[$name][keys] will be auto moved to $cols[$name][attr][keys]: id, name, label, list, defa, class, class_*, style, placeholder

eg $cols[$name][class] = $cols[$name][attr][class] = 'css class'

This is very straight forward as long as you know how to write valid html codes. The following is a list of special attributes which control additional form behaviours:

6.1 - global attribute in $cols[form][attr]

6.1.1 - cols.form.(attr.)url = 'action.php'; if not set default to self url

6.1.2 - cols.form.(attr.)method = 'get'; if not set default to post

6.1.3 - cols.form.(attr.)token = -1; turn off a POST form security token

6.1.4 - cols.form.global.class = 'global class for any fields in this form'

6.1.5 - cols.form.global.class_label = 'global class for any labels in this form'

6.1.6 - cols.form.global.id_prefix = 'form_'; will add this prefix to any id inside this form

6.1.7 - cols.form.global.inline = 'page'; or 'row' will add this class to each form field group. If not set, field label and form field will be in seperate lines. The difference is that row will be dispayed in responsive grid, while page will be always in one line. Check css/all.css for details.

6.1.8 - cols.form.global.label = -1; will turn off all labels inside this form

6.1.9 - cols.form.valid.stop_at_err = 1; stop at one error otherwise get all validation errors

6.1.10 - cols.form.valid.valid_when = '';
GET will do validation when $_GET is true;
URL validate when page is loaded even when form not submitted;
otherwise default to validate when _POST is true

6.2 - option list for a select|sele, checkbox|cbox or radio

Option list can be in cols.colName.list or cols.colName.attr.list

$cols['group'] = [
    // 'type' => 'select', // no need to declare if 'list' is declared
    'class' => 'css className',
    'attr' => [
        'multiple', // if it allows multiple options
    ],
    'list' => cms_list('select id,group from groups'),
    'defa' => 'Please Select', // or ['' => 'Select', 'US' => 'Group USA', ...]
];

If default not set, it will default to placeholder, if placeholder not set, it will default to field name

If neither cols.field.list nor cols.field.attr.list is set, option list will default to cols.field.attr

If list is string, it will be converted to [1 => list]

eg echo cms_form('sele', 'status', $status, $attr);
$attr = 'Active' => ['list' => 'Active'] => ['list' => [1 => 'Active']]

6.3 - form style: default, inline, or no label

6.3.1 - Default form will be displayed as two lines for each form field: label in a line followed by form field in next line.

eg echo cms_form('text', 'name', $name, ['label' => 'What is your name?'])

What is your name?

6.3.2 - You can also display an inline form:

$cols = [
    'form' => [
        'attr' => [
            //'inline',//default inline style is row
            //'inline' => 'row',//'row' is responsive, 'page' is non-responsive
        ],
        'class' => 'inline ...',//you can also define inline in a class
    ],
    //inline defined in form fields will overwrite in global form
    'field_name' => [
        'attr' => [
            'inline',
            //'inline' => 'page',//you can also define inline style
        ],
        //class => 'inline ...',//you can not define inline here
    ],
];

If you define inline in cols.form, all fields inside this form will be inline.

What is your name?

Inline mean lable and field are displayed in one line, the default control is that label takes span3 (3/12 = 25% width) and field takes span9 (9/12 = 75%), you can also overwite it either in cols.form or cols.field:

$cols = [
    'form' => [
        'global' => [
            'class_label' => 'span5',
            'class' => 'span7',
        ],
    ],
    // if define in field, it will overwrite cols.form.global
    'field_name' => [
        'class_label' => 'span4',
        'class' => 'span8',
    ],
];

6.3.3 - You can also turn off labels:

$cols = [
    'form' => [
        'global' => [
            'label' => -1,
        ],
    ],
    // if define in field, it will overwrite cols.form.global
    'field_name' => [
        'label' => -1,
    ],
];

6.4 - Disable an attribute

If you set an attribute value as -1, it will not output to html, eg:

$cols['field']['attr']['id'] = -1;

By default each field will have an ID default to cols.form.global.id_prefix + cols.field.name

6.5 - Label, name and placeholder

If field lable is not set, it will default to field name.

Field name will be same as cols.field_name, unless set by: cols.field_name.attr.name | cols.field_name.name = 'new_name'

If placeholder is not set, it will default to label.

6.6 - class_cbox for checkbox or radio

It is used to seperate options of checkbox or radio, default space

$cols['male'] = [
    'type' => 'radio',
    'class_cbox' => '<br>', // default to SPACE
];

6.7 - Add class for optgroup and option value:

$cols['name'] = [
    'list' => [
        'grp1' => ['a'=>'Group A', 'b'=>'Group B'],
        'grp2' => 'Group 2',
    ],
    'class_grp1' => 'class_for_optgroup_grp1',
    'class_b' => 'class_for_option_value_b',
];

6.8 - Attribute value precedence

cms_form($type, $name, $data, $attr): $attr will overwrite cols.name.attr if found

cols.name.attr will again overwrite cols.form.global

7 - SQL search attributes

If not defined, any fields will be treated as = eg. if you input 'Tom' in user_name field, it will produce this SQL to search: where user_name = 'Tom'

The following is a list of examples of search attributes:

SQL will only be produced when there is a value input.

$cols = [
    'id' => [
        'sql' => '=', // default no need to declare here: id = 12345
    ],
    'user_name' => [
        'sql' = 'like', // user_name like '%'. $user_name .'%'
        // 'sql' => 'start' : like 'abc%'; 'end' : like '%abc'
    ],
    'exlude_this_field_in_search' => [
        'sql' => -1, // form cmd pgno reset by default no search
    ],
    'pgno' => [
        'sql' => '=', // turn on this field in search as it is disabled by default
    ],
    'salary' => [
        'sql' => '>', // salary > $salary
    ],
    'date_from' => [
        'sql' => ['created', '>'], // created > $date_from
    ],
    'has_sales' => [
        'sql' => ['id', 'in', 'select id from sales where ...'], // id in (select id ...)
    ],
];
$sql = array(
    'select'=> 'id,name,office,male,dob',
    'from'  => 'users',
    'where' => cms_form_search(),
);
// You can also manually insert an SQL:
$sql = array(
    'select'=> 'id,name,office,male,dob',
    'from'  => 'users',
    'where' => cms_form_search(['field_a' => $special_sql, ...]),
);

8 - Form data sanitization and validation

Please refer Topnew CMS Clean Helper for details.

9 - Access control

Unless specified, anyone can read and write any form field. However you can specify whether a field can R(ead), W(rite), or N(one access) by certain user-roles:

User role = Admin can always write read any form field.

$cols = [
    'id' => [
        'acs' => 'R', // any one can read only
    ],
    'password' => [
        'acs' => 'N', // no one has access
    ],
    'email' => [
        'acs' => [
            'sales' => 'R', // sales staff can only read
            'manager' => 'W', // Admin or manager can read write
            'support' => 'N', // support staff can not read
            'marketing' => 'R', // marketing staff can read
        ],
    ],
];

10 - A tiny form util: cms_form_arr

This tiny function is to produce key/value for an option list:

$years = cms_form_arr(2000, 2020); will produce:

$years = [2000=>2000, 2001, 2002, ... 2020];

$years = cms_form_arr(2000, 2000, 5, 'pref ', ' post'); will produce

$years = [2000=>'pref 2000 post', 2005=>'pref 2005 post', ... 2020=>'pref 2020 post'];

$years = cms_form_arr([2000,2005], '', '', 'pref ', ' post'); // same as above

$years = cms_form_arr('2000;2005', ';','', 'pref ', ' post'); // same as above

Projects - 其他项目:

bank BenSon Bank
Cash Manager

blog Blog Forum
Blog BBS Ticket

chart SVG Chart
PHP SVG Chart

save Page Maker
Page Maker

topnew SIDU DB GUI
Database tool