Forms

(Required modules: core,sql)

The first objective of the forms module is automated build of html forms and format sql queries. Although the sql query formatter is the part of the forms module the documentation is located under different page.

Note: The automated view/save/edit/delete of entities are achieved by Node module which is heavy based on this module.

The two main part of this page is:

Simple HTML form generation

Let's see the generation of this easy form:

The corresponding html code:

<form method="POST" action="handlerurl" enctype="multipart/form-data">
 <input type="text" name="city" value=""/>
 <select name="size">
  <option value="1">Small</option>
  <option value="2">Medium</option>
  <option value="3">Big</option>
 </select>
 <input type="checkbox" name="capital" />
 <input type="submit" name="add" value="Add" />
</form>

You can generate this form with the following codes:

 $f = new HtmlForm();
 $f->action_post('handleurl');
 $f->input('text','city','');
 $f->select('select','size','',[
                      '1' => 'Small',
                      '2' => 'Medium',
                      '3' => 'Big',
                    ]);
 $f->input('checkbox','capital');
 $f->input('submit','add','Add');
 print $f->get();

The HtmlForm object stores every settings and data in it's internal sate. As seen above the html generation is done by get() method. The following functions can be used to define the form:

Definition methods of HtmlForm class:

The code generation methods of HtmlForm class:

Using of form formatters

The HtmlForm object can receive a HtmlFormFormatter descendant object which can format/specify the output mode of the form. You can write own form formatter class to display custom forms. (Later the SpeedForm class will use it's own formatter to achieve the special functionalities)

Let's see an example of creating a custom form formatter putting everything into divs:

class MyFormatter extends HtmlFormFormatter
{
    public function __construct()
    {
        $this->name = 'MyFormatter';
    }
    function begin_form($txt)
    {
        return '<div class="myform-whole">'.$txt;
    }
    function end_form($txt)
    {
        return $txt.'</div>';
    }
    function item($txt,$name)
    {
        return '<div class="myformitem-'.$name.'">'.$txt.'</div>';
    }
}

You can set this form formatter to arbitrary form:

$f = new HtmlForm('myfirstform');
...
$f->set_formatter(new MyFormatter());
...
print $f->get();

Form checker method

The HtmlForm class automatically appends a hidden value to the form which is regularly change. It's recommended to check this values in case of parameter loading to make harder to do CSRF attacks.

form_source_check($disable_auto_redirect = false)
Check the form source value through the CodKep's parameter system and do automatic redirection to an error location if difference detected.

Note: The SpeedForm do this check automatically on parameter load.

The SpeedForm

There is a more versatile form generation class which can build more styled forms and can handle sql operations too. This class is the SpeedForm. The SpeedForm improve the functionality of HtmlForm.

The SpeedForm connects the HTML side data with the database backend, and handle both together. The SpeedForm is a html form from the html side. While from database side it represents a record of an sql table.

You have to define a complex data definition structure when creating a SpeedForm. This definition structure can specify the field names, database related features, the look & feel, form customisations, data validations and everything which needed to build and use a complex form.
This data definition structure is a big associative array, which have to passed to the constructor of SpeedForm. You can write it by hand or build with SpeedForm builder. The documentation is located under different chapter.

The SpeedForm contains fields, and the fields have a type which specify both the html side appearance and the database types/features. The main goal of the data definition structure to specify this fields. There is an important expectation of SpeedForm is that a key typed field is mandatory, you always have to define one. (It's can be a keyn or keys type in SpeedForm)

The SpeedForm object can achieve the following main operations:

Simple example of using SpeedForm (it's only show an empty form):

// $def is contains the data definition, see next code block below
$sf = new SpeedForm($def);
$form = $sf->generate_form(); //Generating a HtmlFrom object
$form->action_post('formsubmitlocation'); //Set the handle url of the form
print $form->get(); //Generate & print the concrete html codes

This code above can show a complete styled form looks like this way:

sf_example_ftable.png

The definition structure of this form is the following (It was built by SpeedForm builder):

$def =
  [
      "name" => "people_spec",
      "table" => "people",
      "show" => "table",
      "color" => "#88ff88",
      "fields" => [
          10 => [
              "sql" => "uid",
              "type" => "keyn",
              "text" => "Identifier",
          ],
          20 => [
              "sql" => "name",
              "type" => "smalltext",
              "text" => "Name",
              "color" => "#44cc44",
          ],
          30 => [
              "sql" => "birth",
              "type" => "date",
              "text" => "Birthdate",
          ],
          40 => [
              "sql" => "sex",
              "type" => "txtradio",
              "text" => "Gender",
              "color" => "#f8f888",
              "values" => [
                  "m" => "Male",
                  "f" => "Female",
              ],
          ],
          50 => [
              "sql" => "hair",
              "text" => "Hair color",
              "type" => "txtselect",
              "optional" => "yes",
              "values" => [
                  "b" => "Brown",
                  "l" => "Blonde",
                  "e" => "Black",
                  "r" => "Red",
                  "o" => "Other",
              ],
              "default" => "b",
          ],
          60 => [
              "sql" => "note",
              "type" => "largetext",
              "text" => "Note",
              "col" => 30,
              "row" => 3,
          ],
          70 => [
              "sql" => "active",
              "text" => "Account activated",
              "type" => "check",
              "default" => true,
              "suffix" => "yes",
          ],
          80 => [
              "sql" => "add_btn",
              'in_mode' => 'insert',
              "type" => "submit",
              "default" => 'Add',
              "centered" => true,
          ],
          90 => [
              "sql" => "save_btn",
              'in_mode' => 'update',
              "type" => "submit",
              "default" => 'Save',
              "centered" => true,
          ],
      ],
  ];

Methods of SpeedForm

Let's see some real word example which uses SpeedForm in various situations.

function addform_page()
{
    $d = get_data_definition();

    $sf = new SpeedForm($d);
    if($sf->in_action('insert')) //If the user click on "Add" button
    {
        $sf->load_parameters(); //Load values as POST parameters
        $sf->do_insert();  //Validate & Save its to the database
        return 'The item is inserted';
    }

    $form = $sf->generate_form('insert'); //Generate an empty "insert" form
    $form->action_post(current_loc()); //Set the handler to this page callback
    ob_start();
    print $form->get(); //Generate the html codes of the form
    return ob_get_clean();
}
function editform_page()
{
    $d = get_data_definition();

    par_def('id','number0'); //define the "id" parameter
    $id = par('id'); //get the value of "id" parameter
    $sf = new SpeedForm($d);
    $sf->set_key($id); // Set the key of the item to edit
    if($sf->in_action('update')) //If the user click on "Save" button
    {
        $sf->load_parameters(); //Load values as POST parameters
        $sf->do_update(); //Validate & Save its to the database
        print 'The item is SAVED!<br/>';
        //You can optionally return here or run load_loc('somewhere');
        // ...without that we will stay here and display the saved form again
    }

    $sf->do_select(); //Query the "old" values from the database
    $form = $sf->generate_form('update');
    $form->hidden('id',$id); //Add the key value to the form as hidden parameter
    $form->action_post(current_loc()); //Set the handler to this page callback

    ob_start();
    print $form->get(); //Generate the html codes of the form
    return ob_get_clean();
}
function addform_page()
{
    $d = get_data_definition();

    $sf = new SpeedForm($d);
    if($sf->in_action('insert')) //If the user click on "Add" button
    {
        $sf->load_parameters(); //Load values as POST parameters
        if($sf->do_validate(false))
        {
            // Validation failed: We print out the validation error text,
            //  but does not stop the execution here because
            //  the form generation will use this validation highlights
            //  to sign the bad data
            print '<pre>'.$sf->validate_errortext.'</pre>';
            print '</br>';
        }
        else
        {
            $sf->do_insert();  //Validate & Save its to the database
            return 'The item is inserted';
            //You can optionally return here or run load_loc('somewhere');
        }
    }

    $form = $sf->generate_form('insert'); //Generate an empty "insert" form
    $form->action_post(current_loc()); //Set the handler to this page callback
    ob_start();
    print $form->get(); //Generate the html codes of the form
    return ob_get_clean();
}

Note: The highlighting is signed by a big red border, but can be changed to something else by using CSS class validation_highlighted.

Data definition structure

The data definition array is php associative array structure to driven SpeedForm object features, specify fields, data validators, look and feel, and other features of the generated form or database values.

You can write this data definition structure by hand or you can use a builder page built-in CodKep. This builder page is called SpeedForm builder and located under speedformbuilder url.

The SpeedForm builder is disabled by default. You have to set $site_config->enable_speeformbuilder=true to use the builder page and even set $site_config->enable_speeformbuilder_preview=true to use preview function in site settings.

This is a full javascript builder so does not modify anything on server side. You have to copy out the final result and insert into your code to use it.

speedformbuilder.png

The structure : Top level attributes

List of top level attributes/features:

Index nameDescriptionNecessityValue
nameIdentifier name of the form object. It will be used in classes names, hooks.Mandatorystring
tableThe SQL table name in the databaseMandatorysql table name
showThe formatter mode of the form. Html table or divs. Read details here.Mandatory"table" or "div"
fieldsDefinition of data fields itselfMandatorydefinition of fields
classnameIn case you specify a node type you can tell a php class name here. If you do this, all this typed node object will be created with the specified class. You have to reach many customisation of node type this way. See the specific node documentation here.Optionalphp class name (Subclass of Node)
view_callbackIn case you specify a node type you can tell a php function name here to redirect the standard view of node to the given functionOptionalphp function name
view_phpfileIn case you specify a node type you can tell a php file name here to redirect the standard view of the node to the given php fileOptionalphp file name
colorThe background color of the entire table (Each field can redefine it.)OptionalA html color code. Example: #aa8888
beforeThis text is printed before the whole formOptionalstring (Can contains html codes)
afterThis text is printed after the whole formOptionalstring (Can contains html codes)
table_classThe CSS class of the generated html table (If show=table)Optionalstring
table_styleThe "style" attribute of the generated html table (If show=table)Optionalstring
table_borderThe "border" attribute of the generated html table (If show=table)Optionalstring
div_classThe CSS class of the form's main div (If show=div)Optionalstring
div_c_aftervPut an empty "clear:both;" css styled div block after the value's div (If show=div)Optionaltrue or false
div_c_afterlPut an empty "clear:both;" css styled div block after the data block's div (line) (If show=div)Optionaltrue or false

Sample of top level attributes:

  $d = [
        "name" => "people_spec",
        "table" => "people",
        "show" => "table",
        "color" => "#88ff88",
        "fields" => [
            ...
        ],
  ];

Field types

Following field types exists in CodKep (May be extend by hooks)

Type nameForm appearanceDatabase
keynStatic textSERIAL
keysStatic textVARCHAR UNIQUE
smalltexttype_smalltext.pngVARCHAR
numbertype_number.pngNUMERIC
largetexttype_largetext.pngLONGTEXT/TEXT
txtselecttype_select.png
type_select2.png(If optional=yes)
type_select3.png(If optional=yes)
VARCHAR
numselecttype_select.png
type_select2.png(If optional=yes)
type_select3.png(If optional=yes)
NUMERIC
floattype_float.pngNUMERIC(15,5)
passwordtype_password.pngVARCHAR
statictype_static.png
rotexttype_rotext.pngVARCHAR
txtselect_intrangetype_numselect_intrange.pngVARCHAR
numselect_intrangetype_numselect_intrange.pngNUMERIC
txtradiotype_radio.pngVARCHAR
numradiotype_radio.pngNUMERIC
checktype_check.pngBOOLEAN
datetype_date.pngDATE NOT NULL
dateutype_dateu.pngDATE
timestamp_createStatic textTIMESTAMP
timestamp_modStatic textTIMESTAMP
modifier_userStatic textVARCHAR
sqlnchoosetype_select.png
type_select2.png(If optional=yes)
type_select3.png(If optional=yes)
NUMERIC
sqlschoosetype_select.png
type_select2.png(If optional=yes)
type_select3.png(If optional=yes)
VARCHAR
fileThe filename and the browse buttonNUMERIC (CodKep ufi)
submittype_submit.png

keyn

This field is the primary key of the sql table which identifies the record. (Numeric variant) You can hide this field, if not a simple text will show in form. The set_key() function change the value of this field.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"keyn"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe value is show before the user will send the formstring
linkOptionalMakes clickable html link from the key.string where the "<key>" token is replaced to the key value
sql_sequence_nameOptionalSome database system does not return correct value after insert with PDO::lastInsertId() when the key is generated by a sequence (Pgsql). That case you have to put the sequence name here to determine which sequence provides the generated key.string

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 10 => [
    "sql" => "id",
    "type" => "keyn",
    "text" => "Identifier",
    "hide" => true,
 ],

See all field types...

keys

This field is the primary key of the sql table which identifies the record. (Varchar variant) You can hide this field, if not a simple text will show in form. The set_key() function change the value of this field.

Note: Some databases like postresql can achieve the automatic key value generation with sequences. This case it's recommended to set sql_sequence_name attribute to that sequence name to work codes properly.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"keys"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe value is show before the user will send the formstring
linkOptionalMakes clickable html link from the key.string where the "<key>" token is replaced to the key value
sql_sequence_nameOptionalSome database system does not return correct value after insert with PDO::lastInsertId() when the key is generated by a sequence (Pgsql). That case you have to put the sequence name here and may use keyprefix,keysuffix options to determine the generated key.string
keyprefixOptionalThis text will be automatically prepended to the sql sequence generated number returned by PDO::lastInsertId() Only use if you have special id field.string
keysuffixOptionalThis text will be automatically appended to the sql sequence generated number returned by PDO::lastInsertId() Only use if you have special id field.string

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 10 => [
    "sql" => "mid",
    "type" => "keys",
    "text" => "Identifier",
    "color" => "#ff8888",
    "centered" => "yes",
    "sql_sequence_name" => "mtab_seq", // useful on postresql where the keys
                                       //  are generated with a sequence
 ],

See all field types...

smalltext

This is a simple one lined text field, can hold names email addresses and many other textual data.

Hint: You can use regex to validate input data

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"smalltext"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldstring

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 11 => [
    "sql" => "name",
    "type" => "smalltext",
    "text" => "Name",
    "par_sec" => "text5",
    "check_noempty" => "Do not leave it empty",
    "form_options" => [
        'size' => 30,
    ],
    "check_regex" => [
        '/\s/' => "Have to contains a space",
        '/^\p{Lu}/' => "Have to start with uppercase letter",
    ],
 ],

See all field types...

number

This field is an integer number field appears as single line edit in form.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"number"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldinteger
minimumOpt.ValidatorThe minimum value of the field (user input validator)integer
maximumOpt.ValidatorThe maximum value of the field (user input validator)integer

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 20 => [
    "sql" => "length",
    "text" => "Length",
    "type" => "number",
    "default" => "55",
    "suffix" => "cm",
    "color" => "#aaaacc",
 ],

See all field types...

largetext

This field is a large text edit area with adjustable edit area size. On the database side it's an unlimited data field. You can even attach CKEditor (with css classes) to create html content.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"largetext"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldstring
rowMandatorySpecifies the row number of the html textarea boxinteger
colMAndatorySpecifies the column number of the html textarea boxinteger

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 30 => [
    "sql" => "note",
    "text" => "Note",
    "type" => "largetext",
    "col" => 50,
    "row" => 6,
    "par_sec" => "free", // caution: only enable if necessary!
    "form_options" => [
        "class" => "use-ck",
    ],
 ],

See all field types...

txtselect

This field is a frequent used select input with fix key-value pairs, where the database store one of the selected textual keys. You can set the selection to "optional". If set the user can select "nothing" between the values. This case the database will contains NULL value.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"txtselect"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldone of key of the possible keys
valuesMandatoryThe possible values of the fieldAn associative array of keys and values
optionalOptionalIf the optional = "yes" is set the field can accept empty value. The user can reset the value with a button. This case the sql value will NULL. Otherwise only a select box will appears so the user have to select a value."yes" or "no"

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 40 => [
    "sql" => "hairc",
    "type" => "txtselect",
    "text" => "Hair color",
    "optional" => "yes", //You can choose "nothing", that case the database value is NULL
    "values" => [
        "b" => "Brown",
        "l" => "Blonde",
        "e" => "Black",
        "r" => "Red",
        "o" => "Other",
    ],
    "default" => "b",
 ],

See all field types...

numselect

This field is a frequent used select input with fix key-value pairs, where the database store one of the selected integer keys. You can set the selection to "optional". If set the user can select "nothing" between the values. This case the database will contains NULL value.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"numselect"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldone integer of key of the possible keys
valuesMandatoryThe possible values of the fieldAn associative array of keys and values
optionalOptionalIf the optional = "yes" is set the field can accept empty value. The user can reset the value with a button. This case the sql value will NULL. Otherwise only a select box will appears so the user have to select a value."yes" or "no"

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 41 => [
    "sql" => "car",
    "text" => "Car",
    "type" => "numselect",
    "color" => "#aaaaff",
    "values" => [
        1 => "Suzuki",
        2 => "Mitsubishi",
        3 => "Volkswagen",
        4 => "Ford",
    ],
    "default" => '2',
    "form_options" => [
        "class" => "selulize",
        "id" => "cselect",
    ],
 ],

See all field types...

float

This field contains numeric value.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"float"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldstring
minimumOpt.ValidatorThe minimum value of the field (user input validator)integer
maximumOpt.ValidatorThe maximum value of the field (user input validator)integer

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 50 => [
    "sql" => "height",
    "text" => "Height",
    "type" => "float",
    "default" => "1.78",
    "suffix" => "m",
    "maximum" => "0.5",
    "minimum" => "2.5",
 ],

See all field types...

password

This field is similar to simple text field (smalltext) but the entered characters displayed as dots.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"password"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldstring

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 60 => [
    "sql" => "pwd",
    "text" => "Password",
    "type" => "password",
    "color" => "#ff9999",
    "form_options" => [
        "maxlength" => 50,
        "size" => 30,
    ],
    "converter" => "pwd_scatter_func",
 ],

See all field types...

static

This field is a static text which not present in SQL. You can use it to make titles, separators or other visual elements in the form.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"static"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe value of this fieldstring

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 70  => [
    "sql" => "ttext",
    "type" => "static",
    "default" => "User data",
    "centered" => "yes",
    "prefix" => "<strong>",
    "suffix" => "</strong>",
 ],

See all field types...

rotext

This field is a simple text field which shows a database value as a readonly text.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"rotext"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
linkOptionalMakes clickable html link from the field.string where the "<key>" token is replaced to the key value
defaultOptionalThe value of this fieldstring

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 80  => [
    "sql" => "pobjid",
    "type" => "rotext",
    "text" => "Parent object ID",
    "link" => "edit-parent/<key>",
 ],

See all field types...

txtselect_intrange

This field represents an integer value where the select mode is a dropdown styled. You have to specify the start and the end of the possible values appears in drowdown list.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"txtselect_intrange"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
startMandatoryThe first possible value of this fieldinteger value
endMandatoryThe last possible value of this fieldinteger value
defaultOptionalThe default value of this fieldstring of a possible value
minimumOpt.ValidatorThe minimum value of the field (user input validator)integer
maximumOpt.ValidatorThe maximum value of the field (user input validator)integer

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 90 => [
    "sql" => "weight",
    "type" => "txtselect_intrange",
    "text" => "Weight",
    "suffix" => "kg",
    "start" => 30,
    "end" => 130,
    "default" => "70",
 ],

See all field types...

numselect_intrange

This field represents an integer value where the select mode is a dropdown styled. You have to specify the start and the end of the possible values appears in drowdown list.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"numselect_intrange"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
startMandatoryThe first possible value of this fieldinteger value
endMandatoryThe last possible value of this fieldinteger value
defaultOptionalThe default value of this fieldinteger of a possible value
minimumOpt.ValidatorThe minimum value of the field (user input validator)integer
maximumOpt.ValidatorThe maximum value of the field (user input validator)integer

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 91 => [
    "sql" => "weight",
    "type" => "numselect_intrange",
    "text" => "Weight",
    "suffix" => "kg",
    "start" => 30,
    "end" => 130,
    "default" => 70,
 ],

See all field types...

txtradio

This field is a frequent used radio input with fix key-value pairs, where the database store one of the selected textual keys.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"txtradio"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldone string of the possible keys
valuesMandatoryThe possible values of the fieldAn associative array of keys and values

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 100 => [
    "sql" => "shape",
    "text" => "Shape",
    "type" => "txtradio",
    "values" => [
        "s" => "Skinny",
        "p" => "Pretty",
        "c" => "Chubby",
        "f" => "Fat",
    ],
    "default" => "p",
 ],

See all field types...

numradio

This field is a frequent used radio input with fix key-value pairs, where the database store one of the selected integer keys.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"numradio"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldone integer of the possible keys
valuesMandatoryThe possible values of the fieldAn associative array of keys and values

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 101 => [
    "sql" => "repeat",
    "text" => "Repeat",
    "type" => "numradio",
    "values" => [
        1 => "One",
        2 => "Two",
        3 => "Three",
    ],
    "default" => 2,
 ],

See all field types...

check

This is a classic checkbox field.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"check"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this field"true" or "false"

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 110 => [
    "sql" => "active",
    "type" => "check",
    "text" => "Account activated",
    "default" => true,
    "suffix" => "yes",
 ],

See all field types...

date

This is a date selection field with year, month and day selector dropdown. The user have to select a value here.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"date"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldAn isodate string to set an exact date.
Give "now" for set the current date.
Example: "2016-10-27"

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 120 => [
    "sql" => "birth",
    "text" => "Birthdate",
    "type" => "date",
    "default" => "2000-01-01",
    "color" => "#bbbbbb",
 ],

See all field types...

dateu

This is a date selection field with year, month and day selector dropdown where the unknown option is also accepted. You can use this field that cases where the date is not required to set. If the date is unknown the database holds the NULL value.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"dateu"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldAn isodate string to set an exact date.
Empty string or "u" if unknown.
Give "now" for set the current date.
Example: "2016-10-27"

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 121 => [
    "sql" => "deadl",
    "text" => "Deadline",
    "type" => "dateu",
    "default" => "u", //Means the "unknown"
    "color" => "#bbbbee",
    "form_options" => [
        "class" => "deadline",
    ],
 ],

See all field types...

timestamp_create

This is a timestamp typed field which value is automatically set to the current timestamp on INSERT, and not updated later.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"timestamp_create"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this field (shown in form when no data)string

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 130 => [
    "sql" => "created",
    "type" => "timestamp_create",
    "hide" => true,
 ],

See all field types...

timestamp_mod

This is a timestamp typed field which value is automatically set to the current timestamp on INSERT and every UPDATE.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"timestamp_mod"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this field (shown in form when no data)string
autoupdateOptionalYou can disable the automatic update of this field"disable"

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 131 => [
    "sql" => "mod",
    "type" => "timestamp_mod",
    "text" => "Last modification",
    "prefix" => "<i>",
    "suffix" => "</i>",
    "color" => "#999999",
 ],

See all field types...

modifier_user

This is a special readonly varchar field which hold the user identifier who done the last update of the record. It means that this record is updated on every UPDATE. It can hold user name or login name.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"modifier_user"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
userdataOptionalSets the field is store the user's full name or login name"fullname" or "login"

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 140 => [
    "sql" => "moduser",
    "text" => "Modifier user",
    "type" => "modifier_user",
    "userdata" => "fullname",
    "color" => "#999999",
 ],

See all field types...

sqlnchoose

This field is similar to numselect dropdown select, the only difference is that the values comes from a different SQL table. You can even use optional attribute to make possible to the user not to select any values.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"sqlnchoose"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldone of intiger key value represents in referenced table
connected_tableMandatoryThe sql table name which provides the keys and values for the field.string (sql table name)
keynameMandatorySpecifies a row of the connected sql table. The value of this row will be the key of the fieldstring (row name)
showpartMandatorySpecifies a row or an sql expression. The result of this expression will be used as value of the field. This will shown in a html dropdown list.string (row name or sql expression)
where_orderby_partMandatoryYou can restrict and/or order the result by give this part to the end of the sql selectstring (sql)
optionalOptionalIf the optional = "yes" is set the field can accept empty value. The user can reset the value with a button. This case the sql value will NULL. Otherwise only a select box will appears so the user have to select a value."yes" or "no"

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 150 => [
    "sql" => "owner",
    "text" => "Owner user",
    "type" => "sqlnchoose",
    "default" => 1,
    "connected_table" => "users",
    "keyname" => "uid",
    "showpart" => "name",
    "where_orderby_part" => "WHERE NOT lindis ORDER BY name",
    "sqlcreatetype" => 'BIGINT(20) UNSIGNED',
 ],

See all field types...

sqlschoose

This field is similar to txtselect dropdown select, the only difference is that the values comes from a different SQL table. You can even use optional attribute to make possible to the user not to select any values.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"sqlschoose"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
defaultOptionalThe default value of this fieldone of varchar key value represents in referenced table
connected_tableMandatoryThe sql table name which provides the keys and values for the field.string (sql table name)
keynameMandatorySpecifies a row of the connected sql table. The value of this row will be the key of the fieldstring (row name)
showpartMandatorySpecifies a row or an sql expression. The result of this expression will be used as value of the field. This will shown in a html dropdown list.string (row name or sql expression)
where_orderby_partMandatoryYou can restrict and/or order the result by give this part to the end of the sql selectstring (sql)
optionalOptionalIf the optional = "yes" is set the field can accept empty value. The user can reset the value with a button. This case the sql value will NULL. Otherwise only a select box will appears so the user have to select a value."yes" or "no"

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 151 => [
    "sql" => "tool",
    "text" => "Selected tool",
    "type" => "sqlschoose",
    "optional" => "yes",
    "connected_table" => "tools",
    "keyname" => "tid",
    "showpart" => "toolname",
    "where_orderby_part" => "WHERE available ORDER BY toolname",
    "color" => "#8888dd",
    "form_options" => [
            "class" => "selulize toolsel",
        ],
 ],

See all field types...

file

This field is achieve a file upload/store possibility. (indirectly) In fact it stores an UFI (numeric) value in the database which is an UniqueFileIdentifier value of CodKep. It is a reference to the file through the CodKep's file manage system. In case a file is uploaded the SpeedForm creates a File object and store the file to the appropriate way, and save the UFI to the database field.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"file"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
textOptionalThe describe text of the field. This will be displayed to the user in formsstring
filetypesOptionalThe allowed mime types of file separated by ; sign.string
containerMandatorySpecify the container type of the uploaded file. Read this for details."public" or "secure"
subdirOptionalSpecify a subdirectory where the file is uploadedstring
ondeleteOptionalYou can set the CodKep should keep the file even if unselected/deleted in this field."keep"

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 160 => [
    "sql" => "photo",
    "text" => "Student photo",
    "type" => "file",
    "container" => "secure",
    "filetypes" => "image/jpeg;image/png",
    "subdir" => "studentfaces",
 ],

See all field types...

submit

This field is a submit input which dedicated to send/close the form to further processing. It does not appear in database. You can put more instance of this field into a SpeedForm to makes different buttons to Save,Insert or Delete operations.

Attributes of the field

Index nameNecessityDescriptionValue
typeMandatoryThe type specification string"submit"
sqlMandatoryThe name of the sql row holds this data field + The identifier of the data fieldstring
defaultOptionalThe default value of this fieldstring
in_modeOptionalRestrict the appearance of the field for specified typed function"insert" or "update" or "delete" or "select"

You can use more attributes here which are common and usable in all field definitions.

A sample definition of this kind of field:

 170 => [
    "sql" => "save_btn",
    'in_mode' => 'update',
    "type" => "submit",
    "default" => 'Save',
    "centered" => true,
 ],

See all field types...

Common field attributes

There is a lot attribute which usable in all field definition array to change features or look & feel of the field or do data validation etc.

This optional attributes can:

Change features of the fields:

Index nameDescriptionValues
par_secSet the security class of the parameter, which controls the possible values of the fieldA security class name
sqlcreatetypeYou can redefine the default SQL TYPE of the field type in case of sql table creation. If you set a string here, the field will be placed into CREATE TABLE with this type string.sql string
readonlySet the field to read-only. This option can turn every editable field to a simple read only text.true or false
skipIf this option is set the SpeedForm completely skip the field in the specified situation.all, modify, select, update, insert
skipIf this option is set to visual the SpeedForm completely skip the field's visual side. The sql part is stay working but the field is skipped out in the form.visual
skipIf this option is set to sql the SpeedForm completely skip the field's sql side. The field still appear in form.sql
formattersThis option can control the form formatter garnish. The form formatter html tags are only placed to the specified locations. This option can meld together two or more field visually if the first set to before the last to after and all intermediate fields to none.all(default), before, after, none
converterIf you set a php callback function name here the loaded html value will send trough this function before saved into the database.php function name
scriptYou can add arbitrary javascript code to the field, which inserted after the data between srcipt tags.javascript code
hideIf this option is true the field will hided out in form.true or false

Change appearance of the fields:

Index nameDescriptionValues
colorSets the color of the table backgroundHTML color code
Sample: #ffaa99
beforePrints the text before the whole field codes.text (Can contains html codes)
prefixPrints the text before the field value.text (Can contains html codes)
suffixPrints the text after the field value.text (Can contains html codes)
afterPrints the text after the whole field codes.text (Can contains html codes)
centeredIf this option is set true and the text is empty the value will centered in the table celltrue, false
form_optionsThis is an associative array which directly passed to the HtmlForm element generated by the field. It will be the $opts parameter. To see possible values see the HtmlForm field options. (class, id, size, maxlength, readonly, onclick, style, etc...)Associative array

Associate CSS to fields:

Index nameDescriptionValues
line_classSet CSS classes of the field's whole line.String contains CSS classes
title_classSet CSS classes of the field's title text.String contains CSS classes
value_classSet CSS classes of the field's value part.String contains CSS classes

Adds data validations:

Index nameDescriptionValues
check_regexYou can set the regex based validations of the field's value. You have to set an associative array here, where the key is the regex and the value is the error text to show in case the value does not match to the regex. (See the sample code of smalltext to see how to use it.)An associative array with key-value pairs
check_noemptyIf you set this attribute, the SpeedForm does not allow to save the empty value. In that case the error message printed which set as value.Error message

Output format of SpeedForm

The SpeedForm's data definition array have a top level attribute show which basically influence the appearance of the generated form. The generated HtmlForm object is built with HtmlFormFormatter descendant object set.

Two base types are available as output format:

Note: Both output format has the possibility to generate the final form codes by field to field and put arbitrary codes between the field this way. See HtmlFrom's get_start,get_part and get_end functions. Read here.

Query and Add field types

You can query the available field types of SpeedForm with the following function:

speedform_available_types()

You can create new field types in SpeedForm with the HOOK_custom_formtypes hook.

If you intend to create a new field type you have to implement the HOOK_custom_formtypes hook, and create a special associative array with the appropriate fields and return it. The returned array have to contains the following values:

Sample code which define the "gpscoordinate" type:

function hook_mymodule_custom_formtypes()
{
  $r = [];
  $r['gpscoordinate'] = [
      'sqlname'   => 'sfh_name_gps',
      'sqlvalue'  => 'sfh_value_gps',
      'directval' => false,
      'dispval'   => 'sfh_dispval_gps',
      'form'      => 'sfh_gps_form',
      'loadpar'   => 'sfh_phs_loadpar',
      'par_sec'   => 'number1ns',
      'sqltype'   => 'VARCHAR(64)',
      'validator' => 'sfh_gps_validator',
  ];
  return $r;
}

function sfh_name_gps($field_def,$op)
{
    ... //return the sql name here
}

function sfh_value_gps($strip,$field_def,$op,$value)
{
    ... //returns the sql value here
}

function sfh_gps_form($field_def,$form,$value,$opts)
{
    ... //generate the field's related form data here
}

function sfh_phs_loadpar($field_def,$tablename)
{
    ... //load the parameter(s) here
}
function sfh_dispval_gps($field_def,$value)
{
    ... //return the nice looking html codes of the value
}

function sfh_gps_validator($field_def,$value)
{
    ... //validate the data here
}

Data definition structure repository

A data definition structure is usually used to specify a Node. This case the structure are stored in CodKep's node subsystem. You can also load this structures into the SpeedFormBuilder to make further edit of this (Load is located under the "state" button)

Other data definition structures (Which are not acts as node definition) can add into a global repository which store this definitions and makes it possible to get this definitions anywhere by datadef_from_repository($name) function. This definition will also available by speedformbuilder just as node definitions.

Note: Using of data field repository subsystem is fully optional. The SpeedForm class does not require it.

Adding data definitions to the repository:

Get the data from the repository:

datadef_from_repository($name));

function hook_mymodule_datadef_repository()
{
    return [
        'album_pictures_def' => 'generate_album_pictures_def',
    ];
}

function generate_album_pictures_def()
{
    return
    [
     ... //May generated/and re-loaded by SpeedFormBuilder
    ];
}

...

//using of the structure somewhere in the code:
$sf = new SpeedForm(datadef_from_repository('album_pictures_def'));

Hooks

The following hooks can be implement to interact with forms module.

Note: Many of this hooks has an $obj parameter which is a container object holding references to the object and other data structures which are modifiable by the hook.

HookDescription
HOOK_table_get($obj)This hook runs before the HtmlTable object is rendered. It can modify the table data and settings.
HOOK_form_get_start($obj)This hook runs before the HtmlForm object rendering is start. It can modify the forms data.
HOOK_form_get_item($obj)This hook runs every time when HtmlForm item is started to render. It can modify the item's data and settings.
HOOK_custom_formtypes()You can add your own field type to SpeedForm with this hook.
HOOK_speedform_created($obj)This hook is run after a SpeedForm is created and got the definition. It can modify definition and initial values of SpeedForm.
HOOK_speedform_set_key($obj)This hooks run when a SpeedForm's key is set. It can modify the value of the set key itself.
HOOK_speedform_parameters_loaded($obj)This hook run immediately after a SpeedForm is loaded the values from page parameters. (POST/GET) It receives the definition and the loaded values.
HOOK_speedform_values_loaded($obj)This hook run immediately after a SpeedForm is loaded the values from function which is usually means that the values are loaded from database. (SELECT) It receives the definition and the loaded values.
HOOK_speedform_before_validate($obj)This hook is runs immediately before the SpeedForm validation process. In can raise a validation error or can modify values, highlights.
HOOK_speedform_form_generated($obj)This hook runs immediately after the SpeedForm is generate the HtmlForm object. It can modify the SpeedForm and the form data too.
HOOK_field_repository($obj)You can define global field types with this hook, which can be used and reused in to_table() function anywhere to build nice and well formatted tables. See this chapter.
HOOK_datadef_repository()You can add one or more data definition structure to a global repository by this hook and receive its when needed. (By datadef_from_repository($name) function) This data definition are accessible by speedform builder, if the settings makes it possible.
Page generated in 0.1029 seconds.