Form

Form builder. To render highly flexible and customizable forms.
Creates/renders HTML forms for inputting data. Specially to render forms for inputting model data. This form builder extracts the informations it needs (e.g. widget types, data validation info) from the model's property definitions.
Binds submitted form data into a model. Uses class "Binder" for this functionality.
Source
Form.php
Depends on
Session , Widget , Utils , IModel , NoIModelInstanceToBind , Binder , IForm
Extends
FormBase

Constants

ANCHOR = 0xF

To address form widget or HTML element: anchor

BUTTON = 0x7

To address form widget or HTML element: button

CHECKBOX = 0x4

To address form widget or HTML element: input type checkbox

DIV = 0xE

To address form widget or HTML element: div

DIVH3 = 2

Param for "addSection()" to render the section with div and h3.

FIELDSET = 1

Param for "addSection()" to render the section with fieldset.

FILE = 0x3

To address form widget or HTML element: input type file

FORM_LABEL_LAYOUT_H = true

Render parameter: place form labels and form widgets in blocks which are above each other.

FORM_LABEL_LAYOUT_V = false

Render parameter: place form labels and form widgets on in blocks on the same row.

HIDDEN = 0xD

To address form widget or HTML element: input type hidden

IBUTTON = 0x10

To address form widget or HTML element: input type button

IMAGE = 0xA

To address form widget or HTML element: img

IMG = 0x6

To address form widget or HTML element: input type image

INPUT = 0x1

To address form widget or HTML element: input

LABEL = 0xB

To address form widget or HTML element: label

PASSWORD = 0xC

To address form widget or HTML element: input type password

RADIO = 0x5

To address form widget or HTML element: input type radio

RESET = 0x9

To address form widget or HTML element: input type reset

SUBMIT = 0x8

To address form widget or HTML element: input type submit

TEXT = 0x2

To address form widget or HTML element: text area

Properties

index = null

$obj->index = null

This value will be added to the id attribute of all input elements/widgets as a postfix of an index to e.g. '[0]' can be set to this property. This may be useful when more than one forms are being created and put on the same page from the same model.

jsValidate = true

$obj->jsValidate = true

true=put hints in class attributes to make automated JavaScript validations possible. "arta.js" "Arta.validate()" can validate the form using this hints.

confirmPassword = null

$obj->confirmPassword = null

When form has a password input, setting this property to a string will display a second password confirm input and the label for the confirm input will be the string set to this property.

Static Methods

bindTo

bool Form::bindTo(
    IModel model,
    object | array | string | const source=post,
    bool | array configs=true
)

This method uses "Binder::bind()" to fill model's data properties with form's submitted data. This method is static, it is usable only if you did not create a form with a name (you can supply a name for a form: "Form.__construct(name)", default=no name) otherwise use "Form.bind()" to consider the form settings. The source array keys or object property names may be as "PREFIX-model-property-name-POSTFIX". By default the model properties which are already set to a value will only be overwritten if a keys represents them in source with values not null. To force model properties to be saved NULL in database add a "__nulls" key to the source and set a list of property names or a string of property names separated by coma. If the form is posted by "arta.js", the "__nulls" will be taken care of.

Arguments

    model (IModel)
    The model object to be filled
    source=post (object | array | string | const)
    array=data source array to set it's data to model's properties, string=PHP request array name to set it's data to model's properties: 'post' or 'get' or 'cookie' or 'session' or 'request', const=request array constant: INPUT_GET or INPUT_POST or INPUT_COOKIE or INPUT_SESSION or INPUT_REQUEST, object=data source to set it's properties data to model's properties.
    configs=true (bool | array)
    true=validate the token and proceed only if token is valid, false=ignore token, array=configs to change default behavior
    {
        string prefix :
            to compensate matching keys with model's property name; when keys
            are not exactly the same as the model's property names and have an
            extra prefix,
        string postfix :
            to compensate matching keys with model's property name; when keys
            are not exactly the same as the model's property names and have an
            extra postfix,
        bool   token : false
            true=protect against XSRF attracts. proceed only if a token key exists
            in the source and session and matches. This is what will be checked:
            "$_SESSION[Arta.Form][token-key] === $source[token-key]"
            when a forms is created by an Artaengine form generator a such token
            is dded to both the form and session,
        bool   default : false
            when no key in source matches with a model property name then if this
            is false=leave the property value as it is (don't do anything)
            true=set the property value to default_val or Binder::DEFAULT_VALUE,
        mixed  default_val : Binder::DEFAULT_VALUE
            if default=true and property value=null set the property value to this,
        string check :
            proceed only if this key or prefix-key-postfix exists in the source,
    }
    

Returns

bool
true=model was successfully filled, false=source is invalid or token (if must check) is invalid or configs "check" (if specified) does not exists in source

checkSpamBarriers

bool Form::checkSpamBarriers(
    object | array | string | const source=post,
    int minTime=3,
    string classTr=form-tr,
    string nameEmpty=address,
    string nameFilled=user-first-name
)

Check a submitted form for robots and spams.

Arguments

    source=post (object | array | string | const)
    array=data source array to set it's data to model's properties, string=PHP request array name to set it's data to model's properties: 'post' or 'get' or 'request', const=request array constant: INPUT_GET or INPUT_POST or INPUT_REQUEST, object=data source to set it's properties data to model's properties.
    minTime=3 (int)
    min number of seconds that submitting a form must take (robots submit is quick)
    classTr=form-tr (string)
    the class attribute value for tr tags containing the inputs, to be set to invisible
    nameEmpty=address (string)
    id and name for the input which should remain empty
    nameFilled=user-first-name (string)
    id and name for the input with a value which should maintain the value

Returns

bool
true=not spam

Methods

add

void $obj->add(IModel model, array | [string] properties=null)

Add IModel's data properties to the form. You can pass an IModel instance and a list of data properties to be put in the form. The widget for each property is chosen based on the properties definition automatically, thought you can explicitly set a widget to a property in it's definition to the "widget" key.

Arguments

    model (IModel)
    An IModel instance to add it's data properties to the form
    properties=null (array | [string])
    The IModel properties to be added to the model, null=add all properties

Returns

void

add

IForm $obj->add(string label, const type, array atts=null, array params=null)

Add a simple widget (An HTML tag such as an input) to the form.

Arguments

    label (string)
    Row label
    type (const)
    Widget type Form::WIDGET-NAME
    atts=null (array)
    Attributes for the widget HTML tag e.g. {class:my-class,}
    params=null (array)
    Params for the widget

Returns

IForm
For method chaining

addForm

IForm $obj->addForm(
    array | string atts=array,
    string action=null,
    string method='post'
)

Add a form HTML element.

Arguments

    atts=array (array | string)
    string=value of the onsubmit attribute, array=attributes for the form element {attr: value,}
    action=null (string)
    string=URL, null=current URL if "action" is not set in "atts"
    method='post' (string)
    Form submit method can be either 'post', 'get' or 'upload'

Returns

IForm
For method chaining

addSection

IForm $obj->addSection(
    string label='',
    array atts=array,
    const style=FormBase::FIELDSET
)

Add a section. Creates using "fieldset" or "h3" and "div" HTML tags.

Arguments

    label='' (string)
    Section title
    atts=array (array)
    Attributes for the HTML element {attr:value,}
    style=FormBase::FIELDSET (const)
    "FormBase::FIELDSET" or "FormBase::DIVH3"

Returns

IForm
For method chaining

addWidget

IForm $obj->addWidget(string label, string widget, string key=null)

To manually add a row of HTML to the form, opposed to the "add()" method that automatically adds appropriate rows for the give model properties.

Arguments

    label (string)
    Row label
    widget (string)
    Widget HTML to be put in the row
    key=null (string)
    A unique key across form rows, this key will be used in the if/name attribute values of tags related to the form row

Returns

IForm
For method chaining

anchor

IForm $obj->anchor(
    string contents=null,
    string href=null,
    string onclick=null,
    string class=null
)

Add an a (HTML tag) to the form.

Arguments

    contents=null (string)
    Contents/text of the tag
    href=null (string)
    Value to be set to the "href" attribute
    onclick=null (string)
    Value to be set to the "onclick" attribute
    class=null (string)
    Value to be set to the "class" attribute

Returns

IForm
For method chaining

attributes

IForm $obj->attributes(array atts=null)

To manually set HTML attributes for form elements.

Arguments

    atts=null (array)
    You can address the form HTML elements to assign attributes as shown below: [@FormBase.attributes.atts]

Returns

IForm
For method chaining

button

IForm $obj->button(
    string value=null,
    string onclick=null,
    string name=null,
    string type=null,
    string class=null
)

Add a button (HTML tag) to the form.

Arguments

    value=null (string)
    Value to be set to the "value" attribute
    onclick=null (string)
    Value to be set to the "onclick" attribute
    name=null (string)
    Value to be set to the "name" attribute
    type=null (string)
    Value to be set to the "type" attribute
    class=null (string)
    Value to be set to the "class" attribute

Returns

IForm
For method chaining

buttons

IForm $obj->buttons(array buttons)

Add a bunch of buttons (HTML tag) to the form.

Arguments

    buttons (array)
    To add more buttons to a form row [{value, onclick, name, class},]

Returns

IForm
For method chaining

captcha

IForm $obj->captcha(string label=null, string name=captcha, string path=null)

Adds a captcha row to the form.

Arguments

    label=null (string)
    Row label to be displayed beside captcha picture and input
    name=captcha (string)
    Captcha input element id attribute
    path=null (string)
    URL to the captcha generator, null=BASE_URL/captcha.jpeg

Returns

IForm
For method chaining

closeForm

IForm $obj->closeForm()

Close opened form element. The last opened form will be closed automatically without the need to use this method.

Returns

IForm
For method chaining

closeSection

object $obj->closeSection()

Close an opened section element. The last opened form will be closed automatically without the need to use this method.

Returns

object
this - for method chaining

div

IForm $obj->div(
    string label=null,
    string name=null,
    string contents=null,
    string class=null
)

Add a div (HTML tag) to the form.

Arguments

    label=null (string)
    Label text to be shown beside the widget
    name=null (string)
    Value to be set to the "name" attribute
    contents=null (string)
    Contents/text of the tag
    class=null (string)
    Value to be set to the "class" attribute

Returns

IForm
For method chaining

group

IForm $obj->group(string label, array cols, bool labelized=false, string key=null)

Group two or more form rows into one row. By default each widget is put in one row, using this method it is possible to put more widgets in the same row.

Since
Artaengine 1.2.0

Arguments

    label (string)
    Row label
    cols (array)
    Columns to be put in a row [column-or-model-property-name,]
    labelized=false (bool)
    true=put original row label of each col beside it
    key=null (string)
    A unique key across form rows, this key will be used in the if/name attribute values of tags related to the form row

Returns

IForm
For method chaining

hidden

IForm $obj->hidden(string name=null, string value=null)

Add a hidden input (HTML tag) to the form.

Arguments

    name=null (string)
    Value to be set to the "name" attribute
    value=null (string)
    Value to be set to the "value" attribute

Returns

IForm
For method chaining

img

IForm $obj->img(string src=null, string alt=null, string class=null)

Add an img (HTML tag) to the form.

Arguments

    src=null (string)
    Value to be set to the "src" attribute
    alt=null (string)
    Value to be set to the "alt" attribute
    class=null (string)
    Value to be set to the "class" attribute

Returns

IForm
For method chaining

input|password|image|checkbox|radio|file|text

IForm $obj->input|password|image|checkbox|radio|file|text(
    string label=null,
    string name=null,
    string value=null,
    string class=null
)

Add an input (HTML tag) to the form.

Arguments

    label=null (string)
    Label text to be shown beside the widget
    name=null (string)
    Value to be set to the "name" attribute
    value=null (string)
    Value to be set to the "value" attribute
    class=null (string)
    Value to be set to the "class" attribute

Returns

IForm
For method chaining

label

IForm $obj->label(
    string label=null,
    string contents=null,
    string name=null,
    string class=null
)

Add a label (HTML tag) to the form.

Arguments

    label=null (string)
    Label text to be shown beside the widget
    contents=null (string)
    Contents/text of the tag
    name=null (string)
    Value to be set to the "name" attribute
    class=null (string)
    Value to be set to the "class" attribute

Returns

IForm
For method chaining

params

IForm $obj->params(array params=null)

Set form widget parameters with this method. Note that for instances of the "IModel" the best fitting parameters are chosen automatically, however parameters to override the default configs may be set using this method.

Arguments

    params=null (array)
    You can set parameters for the model data properties as: [@FormBase.params.params]

Returns

IForm
For method chaining

raw

array $obj->raw()

Returns an array of form rows and data about rendering the form. Use this method instead of "IForm.render()" when you want to manually render the form.

Returns

array
{row-or-property-name: {render-data},}

reset

IForm $obj->reset(string formName=null)

To reset all configs to default, this can be useful when creating multiple forms with the same "IForm" object.

Arguments

    formName=null (string)
    This value will be added to all HTML id attributes related to the form e.g. id="AAA-formName"

Returns

IForm
For method chaining

submit|reset

IForm $obj->submit|reset(
    string value=null,
    string name=null,
    string class=null,
    string onclick=null
)

Add an input button (HTML tag) to the form.

Arguments

    value=null (string)
    Value to be set to the "value" attribute
    name=null (string)
    Value to be set to the "name" attribute
    class=null (string)
    Value to be set to the "class" attribute
    onclick=null (string)
    Value to be set to the "onclick" attribute

Returns

IForm
For method chaining

__construct

Form $obj = new Form(string formName=null)

Create a form instance.

Arguments

    formName=null (string)
    If value is provided it will be added to all form HTML element id attributes as a prefix

Returns

void

__tostring

string $obj->__tostring()

Get the form as HTML.

Returns

string
HTML

addSpamBarriers

IForm $obj->addSpamBarriers(
    string classTr=form-tr,
    string nameEmpty=address,
    string nameFilled=user-first-name
)

Adds few barriers for robots and spams (to be used instead of CAPTCHA thought CAPTCHA would be a safer solution). Adds an empty input (expected to be submitted empty). Adds an input with a random value (expected to be submitted with the same value). Adds form generation timestamp (form is expected to be submitted after few seconds). Note that this method must be called before any data binding.

Arguments

    classTr=form-tr (string)
    the class attribute value for tr tags containing the inputs, to be set to invisible
    nameEmpty=address (string)
    id and name for the input which should remain empty
    nameFilled=user-first-name (string)
    id and name for the input with a value which should maintain the value

Returns

IForm
For method chaining

bind

bool $obj->bind(
    IModel model,
    object | array | string | const source=post,
    bool | array configs=true
)

Fill model's data properties with form's submitted data. The source array keys or object property names may be as "PREFIX-model-property-name-POSTFIX". By default the model properties which are already set to a value will only be overwritten if a keys represents them in source with values not null. To force model properties to be saved NULL in database add a "__nulls" key to the source and set a list of property names or a string of property names separated by coma. If the form is posted by "arta.js", the "__nulls" will be taken care of.

Arguments

    model (IModel)
    The model object to be filled
    source=post (object | array | string | const)
    array=data source array to set it's data to model's properties, string=PHP request array name to set it's data to model's properties: 'post' or 'get' or 'cookie' or 'session' or 'request', const=request array constant: INPUT_GET or INPUT_POST or INPUT_COOKIE or INPUT_SESSION or INPUT_REQUEST, object=data source to set it's properties data to model's properties.
    configs=true (bool | array)
    true=validate the token and proceed only if token is valid, false=ignore token, array=configs to change default behavior
    {
        string prefix :
            to compensate matching keys with model's property name; when keys
            are not exactly the same as the model's property names and have an
            extra prefix,
        string postfix :
            to compensate matching keys with model's property name; when keys
            are not exactly the same as the model's property names and have an
            extra postfix,
        bool   token : false
            true=protect against XSRF attracts. proceed only if a token key exists
            in the source and session and matches. This is what will be checked:
            "$_SESSION[Arta.Form][token-key] === $source[token-key]"
            when a forms is created by an Artaengine form generator a such token
            is dded to both the form and session,
        bool   default : false
            when no key in source matches with a model property name then if this
            is false=leave the property value as it is (don't do anything)
            true=set the property value to default_val or Binder::DEFAULT_VALUE,
        mixed  default_val : Binder::DEFAULT_VALUE
            if default=true and property value=null set the property value to this,
        string check :
            proceed only if this key or prefix-key-postfix exists in the source,
    }
    

Returns

bool
true=model was successfully filled, false=source is invalid or token (if must check) is invalid or configs "check" (if specified) does not exists in source

Throws

bind

bool $obj->bind(
    object | array | string | const source=post,
    bool | array configs=true
)

Fill model's data properties with form's submitted data. The model object must already been set inside the form object context. The source array keys or object property names may be as "PREFIX-model-property-name-POSTFIX". By default the model properties which are already set to a value will only be overwritten if a keys represents them in source with values not null. To force model properties to be saved NULL in database add a "__nulls" key to the source and set a list of property names or a string of property names separated by coma. If the form is posted by "arta.js", the "__nulls" will be taken care of.

Arguments

    source=post (object | array | string | const)
    array=data source array to set it's data to model's properties, string=PHP request array name to set it's data to model's properties: 'post' or 'get' or 'cookie' or 'session' or 'request', const=request array constant: INPUT_GET or INPUT_POST or INPUT_COOKIE or INPUT_SESSION or INPUT_REQUEST, object=data source to set it's properties data to model's properties.
    configs=true (bool | array)
    true=validate the token and proceed only if token is valid, false=ignore token, array=configs to change default behavior
    {
        string prefix :
            to compensate matching keys with model's property name; when keys
            are not exactly the same as the model's property names and have an
            extra prefix,
        string postfix :
            to compensate matching keys with model's property name; when keys
            are not exactly the same as the model's property names and have an
            extra postfix,
        bool   token : false
            true=protect against XSRF attracts. proceed only if a token key exists
            in the source and session and matches. This is what will be checked:
            "$_SESSION[Arta.Form][token-key] === $source[token-key]"
            when a forms is created by an Artaengine form generator a such token
            is dded to both the form and session,
        bool   default : false
            when no key in source matches with a model property name then if this
            is false=leave the property value as it is (don't do anything)
            true=set the property value to default_val or Binder::DEFAULT_VALUE,
        mixed  default_val : Binder::DEFAULT_VALUE
            if default=true and property value=null set the property value to this,
        string check :
            proceed only if this key or prefix-key-postfix exists in the source,
    }
    

Returns

bool
true=model was successfully filled, false=source is invalid or token (if must check) is invalid or configs "check" (if specified) does not exists in source

Throws

render

string $obj->render(const layout=Form::FORM_LABEL_LAYOUT_H)

Render the form as HTML.

Arguments

    layout=Form::FORM_LABEL_LAYOUT_H (const)
    Form row layout can be "Form::FORM_LABEL_LAYOUT_H" or "Form::FORM_LABEL_LAYOUT_V"

Returns

string
HTML