FormSearch

Search form builder. To render highly flexible and customizable forms
Creates/renders HTML forms for searching model data. This form builder extracts the informations it needs (e.g. widget types, search operators, data validation info) from the model's property definitions.
Processes the submitted search form data and creates an SQL string for querying the data, it can return this SQL or injects it into the model. As making the proper data package to be submitted from the form is not so easy it is highly recommended to uses the "artaengine.js" for submitting search forms created by this class.
Source
FormSearch.php
Depends on
Session , Form , Widget , Utils , IModel , Arta , Model
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 = 70726

Search operator group name for type text. Each operator group is a set of search operator types.

BETWEEN = 'B'

Search operator query type. Query numbers or dates between the search key.

CHAR = 70721

Search operator group name for type char. Each operator group is a set of search operator types.

CONTAIN = 'C'

Search operator query type. Query text that contain the search key.

CONTAIN_ALL = 'A'

Search operator query type. Query text that contain all search keys.

CONTAIN_ONE = 'O'

Search operator query type. Query text that contain at least one of the search keys.

DATE = 70723

Search operator group name for type date/datetime. Each operator group is a set of search operator types.

DROPDOWN = 70724

Search operator group name for drop-downs and selects. Each operator group is a set of search operator types.

EQUAL = 'E'

Search operator query type. Query data that is exactly the same as the search key.

EQUAL_NOT = 'N'

Search operator query type. Query data that do not match the search key.

EXACT = 70725

Search operator group name for type which have only equal compare. Each operator group is a set of search operator types.

GREATER = 'G'

Search operator query type. Query numbers or dates greater than the search key.

IN = 'I'

Search operator query type. Query data which contain at least one of the search keys.

LESS = 'L'

Search operator query type. Query numbers or dates less than the search key.

NUMBER = 70722

Search operator group name for type number. Each operator group is a set of search operator types.

STRING = 70720

Search operator group name for type string. Each operator group is a set of search operator types.

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.

operator = 'AND'

$obj->operator = 'AND'

SQL operator which will be used between each "col op data" when creating the search SQL query.

operators = array

$obj->operators = array(
        self::STRING   => array('C', 'A', 'O', 'E',),
        self::CHAR     => array('I',),
        self::NUMBER   => array('E', 'G', 'L', 'N', 'I', 'B',),
        self::DATE     => array('B', 'E', 'G', 'L',),
        self::TEXT     => array('C',),
        self::EXACT    => array('E',),
        self::DROPDOWN => array('I',),
    )

This property defines search operator groups. You can change the sets to customize the operators available for each search item.

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

FormSearch $obj = new FormSearch(string formName='search')

Create a search form instance.

Arguments

    formName='search' (string)
    If a value is assigned it will be added to all element ids

Returns

void

__tostring

string $obj->__tostring()

Get the form as HTML.

Returns

string
HTML

bind

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

Reads the search data pack from a source(request) then creates an SQL string and injects it into the model. Other conditions may be added to the model. Calling "model.query()" will query the data.

Arguments

    model (IModel)
    IModel instance to inject the SQL query into
    source=post (array | string | const)
    Source to find the search data pack inside it. array=the data source array, string=PHP request array name: '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
    configs=true (bool | array)
    true=validate form's security token, false=ignore form's security token, array=configs
    {
        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 added to both the form and session,
    }
    

Returns

bool
false=if security token had to be validated and was not valid

getSql

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

Reads the search data pack from a source(request) then creates an SQL string and returns it. (the model will remain untouched).

Arguments

    model (IModel)
    IModel instance to make the SQL query based on
    source=post (array | string | const)
    Source to find the search data pack inside it. array=the data source array, string=PHP request array name: '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
    configs=true (bool | array)
    true=validate form's security token, false=ignore form's security token, array=configs
    {
        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 added to both the form and session,
    }
    

Returns

bool
State of success

render

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

Render the form as HTML.

Arguments

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

Returns

string
HTML