Widget

This is the default Artaengine widget generator class. Artaengine form generators use this class by default to render widgets for inputting data for the model data properties. The Widget constants of this class can be used inside the model's data property definitions to explicitly assign a widget. The value assigned to each constant points to widget renderer class and method. e.g: "Widget::DROPDOWN" This class can be used to manually render widgets outside the model context.
Note that some of the widgets require JavaScript libs to be included to the page, the methods of this class will automatically add the required libs to the factory "js", "css" and "jsx" properties.
Some widgets depend on css, JavaScript libraries and codes to be loaded and executed, this dependencies will be automatically added to the factory's "css", "js" and "jsx" properties. This values will be available in the templates so you can load them in the page. If the factory is responding to an ajax request then the dependencies will be added to the response and if the ajax request was done by the "artaengine.js" then the dependencies will be send and loaded (you don't have to do anything).
Custom Widget classes may be used by the models if their method's arguments and return values are strictly consistent with the ones in this class.
Source
Widget.php
Depends on
Arta , Utils , Localization

Constants

AUTO_COMPLETE = 'Widget.autoComplete'

To identify widget and widget renderer for jQueryUI auto complete.

CK = 'Widget.ckEditorW'

To identify widget and widget renderer for ck editor.

COMBO = 'Widget.combo'

To identify widget and widget renderer for jQueryUI combo.

DATE_PICKER = 'Widget.datePickerW'

To identify widget and widget renderer for date picker (jQueryUI).

DATE_TIME = 'Widget.dateTimeW'

To identify widget and widget renderer for date-time (drop-downs).

DROPDOWN = 'Widget.dropDown'

To identify widget and widget renderer for drop-down.

DROPDOWN_TIME = 'Widget.timeW'

To identify widget and widget renderer for time.

MULTI_CHECKBOX = 'Widget.multiCheckbox'

To identify widget and widget renderer for multi check-boxes.

MULTI_OPTION = 'Widget.multiOption'

To identify widget and widget renderer for multi options (radio-boxes).

MULTI_SELECT = 'Widget.multiSelect'

To identify widget and widget renderer for multi selects.

Methods

autoComplete

string $obj->autoComplete(
    array | IDbAbstract | string source,
    array atts=null,
    array params=null
)

Render a drop-down input widget. List items come from a database or an array data source. This widget depends on jQueryUI and will be turned into a jQueryUI auto-complete widget.
This method adds the "jquery" and "jquery/autocomplete" keys to the factory class "js" property and "jquery/autocomplete" to the "css" property and the JavaScript source codes for initializing the widget to the "jsx" property. The keys must be set to the appropriate library and template URLs in the applications front-end dictionary and the resources and JavaScript source codes to be loaded and executed in the page.

See also
http://artaengine.com/tutorials/browser-dictionary

Arguments

    source (array | IDbAbstract | string)
    data source
    IDbAbstract
        a query must have been executed with the object, the method will iterate
        over the query result to render widget items from the queried rows
    .............................................................................
    the method will create and execute a query on the database then iterates over
    the query result to render widget items from the queried rows
    [
        IDbAbstract database object to execute query with,
        string      database table or view name to be queried
    ]
    .............................................................................
    widget will be rendered from array items
    { string|int item-key : item-value, }
    .............................................................................
    widget will be rendered from array items. the item values can be an array where
    the first item is the value and the second item is an array of HTML attributes
    to be set to the HTML tag that wraps around the value 
    {
        string|number item-key :
            [
                string item-value,
                { string attribute-name : attribute-value, }
            ],
    }
    .............................................................................
    string
        'Class-name::static-property' which is set to an array
        'Class-name::static-method'   which returns an array
    
    atts=null (array)
    widget HTML attributes plus "selected" and "default" values
    {
        mixed selected :
            the widget item key or keys to be selected,
        mixed default :
            to be displayed in the widget when no option is selected
            false  display nothing
            true   add and display an item with no key and value
            string add and display an item with no key but this value
            array  (key, value) add and display an item with this key and value
        string attribute-name :
            attribute-value
            the attributes will be set to the main widget tag e.g. select or input
            when the attribute "name" is set and attribute "id" does not exists
            then "id" will be added and set to the same value as "name",
    }
    
    params=null (array)
    parameters for tweaking the widget
    {
        string id : id
            for database data-sources - name of a table/view column (primary-key)
            name of the column that it's values will be used as widget item keys,
        string|array text : name>description>title>text>id
            for database data-sources - name of a table/view column or columns
            the value of the column or columns will be displayed in the widget
            items. by default the first of column names ("name" or "description"
            or "title" or "text" or "id") that is found will be used for this
            purpose,
        string separator : -
            if param "text" is set to an array then the values will be displayed
            separated by this string,
        string selected : params[id]
            for database data-sources - name of a table/view column
            the selected item (atts[selected]) will be checked against values of
            this column. by default this column is the same as the id column,
        string where :
            for database data-sources - database WHERE condition,
        string|array sort :
            for database data-sources - column name or names for database ORDER BY,
        string alias : -
            when data-source is empty(has no items) this string will be shown
            instead of the widget. the empty widget will still exist but will
            be set hidden,
        array dictionary :
            {text-value: new-text-value,} before putting texts inside widget items
            if the text exists as a key in this array then the array value will be
            put inside the item,
    }
    

Returns

string
Widget HTML

ckEditor

string $obj->ckEditor(array atts=null, array params=null)

Render a CK Editor widget (version 4 or later). This method adds the "ckeditor" key to factory's "js" property and the required JavaScript source codes to the "jsx" property. It is expected that the "ckeditor" key is set to the appropriate URL pointing to CK Editor library and the resources and JavaScript source codes are loaded and executed in the page.

See also
http://artaengine.com/tutorials/browser-dictionary

Arguments

    atts=null (array)
    widget HTML attributes plus "selected" and "default" values
    {
        mixed selected :
            the widget item key or keys to be selected,
        mixed default :
            to be displayed in the widget when no option is selected
            false  display nothing
            true   add and display an item with no key and value
            string add and display an item with no key but this value
            array  (key, value) add and display an item with this key and value
        string attribute-name :
            attribute-value (only "name" and "id" will be used)
            the attributes will be set to the main widget tag e.g. select or input
            when the attribute "name" is set and attribute "id" does not exists
            then "id" will be added and set to the same value as "name",
    }
    
    params=null (array)
    parameters CK Editor configs and settings

Returns

string
Widget HTML

combo

string $obj->combo(
    array | IDbAbstract | string source,
    array atts=null,
    array params=null
)

Render a drop-down input widget. List items come from a database or an array data source. This widget depends on jQueryUI and will be turned into a jQueryUI combo widget.
This method adds the "jquery" and ("jquery/combobox" or "jquery/ui") keys to the factory class "js" property and ("jquery/combobox" or "jquery/ui") to the "css" property and the JavaScript source codes for initializing the widget to the "jsx" property. The keys must be set to the appropriate library and template URLs in the applications front-end dictionary and the resources and JavaScript source codes to be loaded and executed in the page.

See also
http://artaengine.com/tutorials/browser-dictionary

Arguments

    source (array | IDbAbstract | string)
    data source
    IDbAbstract
        a query must have been executed with the object, the method will iterate
        over the query result to render widget items from the queried rows
    .............................................................................
    the method will create and execute a query on the database then iterates over
    the query result to render widget items from the queried rows
    [
        IDbAbstract database object to execute query with,
        string      database table or view name to be queried
    ]
    .............................................................................
    widget will be rendered from array items
    { string|int item-key : item-value, }
    .............................................................................
    widget will be rendered from array items. the item values can be an array where
    the first item is the value and the second item is an array of HTML attributes
    to be set to the HTML tag that wraps around the value 
    {
        string|number item-key :
            [
                string item-value,
                { string attribute-name : attribute-value, }
            ],
    }
    .............................................................................
    string
        'Class-name::static-property' which is set to an array
        'Class-name::static-method'   which returns an array
    
    atts=null (array)
    widget HTML attributes plus "selected" and "default" values
    {
        mixed selected :
            the widget item key or keys to be selected,
        mixed default :
            to be displayed in the widget when no option is selected
            false  display nothing
            true   add and display an item with no key and value
            string add and display an item with no key but this value
            array  (key, value) add and display an item with this key and value
        string attribute-name :
            attribute-value
            the attributes will be set to the main widget tag e.g. select or input
            when the attribute "name" is set and attribute "id" does not exists
            then "id" will be added and set to the same value as "name",
    }
    
    params=null (array)
    parameters for tweaking the widget
    {
        string id : id
            for database data-sources - name of a table/view column (primary-key)
            name of the column that it's values will be used as widget item keys,
        string|array text : name>description>title>text>id
            for database data-sources - name of a table/view column or columns
            the value of the column or columns will be displayed in the widget
            items. by default the first of column names ("name" or "description"
            or "title" or "text" or "id") that is found will be used for this
            purpose,
        string separator : -
            if param "text" is set to an array then the values will be displayed
            separated by this string,
        string selected : params[id]
            for database data-sources - name of a table/view column
            the selected item (atts[selected]) will be checked against values of
            this column. by default this column is the same as the id column,
        string where :
            for database data-sources - database WHERE condition,
        string|array sort :
            for database data-sources - column name or names for database ORDER BY,
        string alias : -
            when data-source is empty(has no items) this string will be shown
            instead of the widget. the empty widget will still exist but will
            be set hidden,
        array dictionary :
            {text-value: new-text-value,} before putting texts inside widget items
            if the text exists as a key in this array then the array value will be
            put inside the item,
    }
    

Returns

string
Widget HTML

datePicker

string $obj->datePicker(array atts=null, array params=null)

Render a date picker widget using jQueryUI date-picker. This widget depends on jQueryUI and will be turned into a jQueryUI date picker.
This method adds the "jquery" and ("jquery/datepicker" or "jquery/ui") keys to the factory class "js" property and ("jquery/datepicker" or "jquery/ui") to the "css" property and the JavaScript source codes for initializing the widget to the "jsx" property. The keys must be set to the appropriate library and template URLs in the applications front-end dictionary and the resources and JavaScript source codes to be loaded and executed in the page.

See also
http://artaengine.com/tutorials/browser-dictionary

Arguments

    atts=null (array)
    widget HTML attributes plus "selected" and "default" values
    {
        mixed selected :
            the widget item key or keys to be selected,
        mixed default :
            to be displayed in the widget when no option is selected
            false  display nothing
            true   add and display an item with no key and value
            string add and display an item with no key but this value
            array  (key, value) add and display an item with this key and value
        string attribute-name :
            attribute-value
            the attributes will be set to the main widget tag e.g. select or input
            when the attribute "name" is set and attribute "id" does not exists
            then "id" will be added and set to the same value as "name",
    }
    
    params=null (array)
    jQueryUI date-picker widget settings and params

Returns

string
Widget HTML

dateTime

string $obj->dateTime(array atts=null, array params=null)

Render a date-time select widget. The attributes and params can be a combination of the attributes and params of the "Widget.date()" and "Widget.time()".

Arguments

    atts=null (array)
    widget attributes
    params=null (array)
    widget params

Returns

string
Widget HTML

dropDown

string $obj->dropDown(
    array | IDbAbstract | string source,
    array atts=null,
    array params=null
)

Render a drop-down input widget. List items come from a database or an array data source.

Arguments

    source (array | IDbAbstract | string)
    data source
    IDbAbstract
        a query must have been executed with the object, the method will iterate
        over the query result to render widget items from the queried rows
    .............................................................................
    the method will create and execute a query on the database then iterates over
    the query result to render widget items from the queried rows
    [
        IDbAbstract database object to execute query with,
        string      database table or view name to be queried
    ]
    .............................................................................
    widget will be rendered from array items
    { string|int item-key : item-value, }
    .............................................................................
    widget will be rendered from array items. the item values can be an array where
    the first item is the value and the second item is an array of HTML attributes
    to be set to the HTML tag that wraps around the value 
    {
        string|number item-key :
            [
                string item-value,
                { string attribute-name : attribute-value, }
            ],
    }
    .............................................................................
    string
        'Class-name::static-property' which is set to an array
        'Class-name::static-method'   which returns an array
    
    atts=null (array)
    widget HTML attributes plus "selected" and "default" values
    {
        mixed selected :
            the widget item key or keys to be selected,
        mixed default :
            to be displayed in the widget when no option is selected
            false  display nothing
            true   add and display an item with no key and value
            string add and display an item with no key but this value
            array  (key, value) add and display an item with this key and value
        string attribute-name :
            attribute-value
            the attributes will be set to the main widget tag e.g. select or input
            when the attribute "name" is set and attribute "id" does not exists
            then "id" will be added and set to the same value as "name",
    }
    
    params=null (array)
    parameters for tweaking the widget
    {
        string id : id
            for database data-sources - name of a table/view column (primary-key)
            name of the column that it's values will be used as widget item keys,
        string|array text : name>description>title>text>id
            for database data-sources - name of a table/view column or columns
            the value of the column or columns will be displayed in the widget
            items. by default the first of column names ("name" or "description"
            or "title" or "text" or "id") that is found will be used for this
            purpose,
        string separator : -
            if param "text" is set to an array then the values will be displayed
            separated by this string,
        string selected : params[id]
            for database data-sources - name of a table/view column
            the selected item (atts[selected]) will be checked against values of
            this column. by default this column is the same as the id column,
        string where :
            for database data-sources - database WHERE condition,
        string|array sort :
            for database data-sources - column name or names for database ORDER BY,
        string alias : -
            when data-source is empty(has no items) this string will be shown
            instead of the widget. the empty widget will still exist but will
            be set hidden,
        array dictionary :
            {text-value: new-text-value,} before putting texts inside widget items
            if the text exists as a key in this array then the array value will be
            put inside the item,
    }
    

Returns

string
Widget HTML

multiCheckbox

string $obj->multiCheckbox(
    array | IDbAbstract | string source,
    array atts=null,
    array params=null
)

Render a multi-radiobox widget (only one can be selected). List items come from a database or an array data source.

Arguments

    source (array | IDbAbstract | string)
    data source
    IDbAbstract
        a query must have been executed with the object, the method will iterate
        over the query result to render widget items from the queried rows
    .............................................................................
    the method will create and execute a query on the database then iterates over
    the query result to render widget items from the queried rows
    [
        IDbAbstract database object to execute query with,
        string      database table or view name to be queried
    ]
    .............................................................................
    widget will be rendered from array items
    { string|int item-key : item-value, }
    .............................................................................
    widget will be rendered from array items. the item values can be an array where
    the first item is the value and the second item is an array of HTML attributes
    to be set to the HTML tag that wraps around the value 
    {
        string|number item-key :
            [
                string item-value,
                { string attribute-name : attribute-value, }
            ],
    }
    .............................................................................
    string
        'Class-name::static-property' which is set to an array
        'Class-name::static-method'   which returns an array
    
    atts=null (array)
    widget HTML attributes plus "selected" and "default" values
    {
        mixed selected :
            the widget item key or keys to be selected,
        mixed default :
            to be displayed in the widget when no option is selected
            false  display nothing
            true   add and display an item with no key and value
            string add and display an item with no key but this value
            array  (key, value) add and display an item with this key and value
        string attribute-name :
            attribute-value
            the attributes will be set to the main widget tag e.g. select or input
            when the attribute "name" is set and attribute "id" does not exists
            then "id" will be added and set to the same value as "name",
    }
    
    params=null (array)
    parameters for tweaking the widget
    {
        string id : id
            for database data-sources - name of a table/view column (primary-key)
            name of the column that it's values will be used as widget item keys,
        string|array text : name>description>title>text>id
            for database data-sources - name of a table/view column or columns
            the value of the column or columns will be displayed in the widget
            items. by default the first of column names ("name" or "description"
            or "title" or "text" or "id") that is found will be used for this
            purpose,
        string separator : -
            if param "text" is set to an array then the values will be displayed
            separated by this string,
        string selected : params[id]
            for database data-sources - name of a table/view column
            the selected item (atts[selected]) will be checked against values of
            this column. by default this column is the same as the id column,
        string where :
            for database data-sources - database WHERE condition,
        string|array sort :
            for database data-sources - column name or names for database ORDER BY,
        string alias : -
            when data-source is empty(has no items) this string will be shown
            instead of the widget. the empty widget will still exist but will
            be set hidden,
        array dictionary :
            {text-value: new-text-value,} before putting texts inside widget items
            if the text exists as a key in this array then the array value will be
            put inside the item,
    }
    

Returns

string
Widget HTML

multiOption

string $obj->multiOption(
    array | IDbAbstract | string source,
    array atts=null,
    array params=null
)

Render a multi-ckechbox widget (multiple items can be selected). List items come from a database or an array data source.

Arguments

    source (array | IDbAbstract | string)
    data source
    IDbAbstract
        a query must have been executed with the object, the method will iterate
        over the query result to render widget items from the queried rows
    .............................................................................
    the method will create and execute a query on the database then iterates over
    the query result to render widget items from the queried rows
    [
        IDbAbstract database object to execute query with,
        string      database table or view name to be queried
    ]
    .............................................................................
    widget will be rendered from array items
    { string|int item-key : item-value, }
    .............................................................................
    widget will be rendered from array items. the item values can be an array where
    the first item is the value and the second item is an array of HTML attributes
    to be set to the HTML tag that wraps around the value 
    {
        string|number item-key :
            [
                string item-value,
                { string attribute-name : attribute-value, }
            ],
    }
    .............................................................................
    string
        'Class-name::static-property' which is set to an array
        'Class-name::static-method'   which returns an array
    
    atts=null (array)
    widget HTML attributes plus "selected" and "default" values
    {
        mixed selected :
            the widget item key or keys to be selected,
        mixed default :
            to be displayed in the widget when no option is selected
            false  display nothing
            true   add and display an item with no key and value
            string add and display an item with no key but this value
            array  (key, value) add and display an item with this key and value
        string attribute-name :
            attribute-value
            the attributes will be set to the main widget tag e.g. select or input
            when the attribute "name" is set and attribute "id" does not exists
            then "id" will be added and set to the same value as "name",
    }
    
    params=null (array)
    parameters for tweaking the widget
    {
        string id : id
            for database data-sources - name of a table/view column (primary-key)
            name of the column that it's values will be used as widget item keys,
        string|array text : name>description>title>text>id
            for database data-sources - name of a table/view column or columns
            the value of the column or columns will be displayed in the widget
            items. by default the first of column names ("name" or "description"
            or "title" or "text" or "id") that is found will be used for this
            purpose,
        string separator : -
            if param "text" is set to an array then the values will be displayed
            separated by this string,
        string selected : params[id]
            for database data-sources - name of a table/view column
            the selected item (atts[selected]) will be checked against values of
            this column. by default this column is the same as the id column,
        string where :
            for database data-sources - database WHERE condition,
        string|array sort :
            for database data-sources - column name or names for database ORDER BY,
        string alias : -
            when data-source is empty(has no items) this string will be shown
            instead of the widget. the empty widget will still exist but will
            be set hidden,
        array dictionary :
            {text-value: new-text-value,} before putting texts inside widget items
            if the text exists as a key in this array then the array value will be
            put inside the item,
        string cell :
            the container HTML tag name e.g. 'div' or 'p'
            if set the boxes will be placed in the container otherwise there will
            be no container,
    }
    

Returns

string
Widget HTML

multiSelect

string $obj->multiSelect(
    array | IDbAbstract | string source,
    array atts=null,
    array params=null
)

Render a multi-select widget. List items come from a database or an array data source. It is optional but if the correct jQuery plugin is available the widget will use it. This method adds the "jquery" and "jquery/multiselect" keys to the factory class "js" property and "jquery/multiselect" to the "css" property and the JavaScript source codes for initializing the widget to the "jsx" property. The keys may be set to the appropriate library and template URLs in the applications front-end dictionary and the resources and JavaScript source codes to be loaded and executed in the page. The keys may be set to the Artaengine multiselect jQuery plugin (jquery.multi-select.js) or the http://odyniec.net/projects/selectlist/ plugin.

See also
http://artaengine.com/tutorials/browser-dictionary

Arguments

    source (array | IDbAbstract | string)
    data source
    IDbAbstract
        a query must have been executed with the object, the method will iterate
        over the query result to render widget items from the queried rows
    .............................................................................
    the method will create and execute a query on the database then iterates over
    the query result to render widget items from the queried rows
    [
        IDbAbstract database object to execute query with,
        string      database table or view name to be queried
    ]
    .............................................................................
    widget will be rendered from array items
    { string|int item-key : item-value, }
    .............................................................................
    widget will be rendered from array items. the item values can be an array where
    the first item is the value and the second item is an array of HTML attributes
    to be set to the HTML tag that wraps around the value 
    {
        string|number item-key :
            [
                string item-value,
                { string attribute-name : attribute-value, }
            ],
    }
    .............................................................................
    string
        'Class-name::static-property' which is set to an array
        'Class-name::static-method'   which returns an array
    
    atts=null (array)
    widget HTML attributes plus "selected" and "default" values
    {
        mixed selected :
            the widget item key or keys to be selected,
        mixed default :
            to be displayed in the widget when no option is selected
            false  display nothing
            true   add and display an item with no key and value
            string add and display an item with no key but this value
            array  (key, value) add and display an item with this key and value
        string attribute-name :
            attribute-value
            the attributes will be set to the main widget tag e.g. select or input
            when the attribute "name" is set and attribute "id" does not exists
            then "id" will be added and set to the same value as "name",
    }
    
    params=null (array)
    parameters for tweaking the widget
    {
        string id : id
            for database data-sources - name of a table/view column (primary-key)
            name of the column that it's values will be used as widget item keys,
        string|array text : name>description>title>text>id
            for database data-sources - name of a table/view column or columns
            the value of the column or columns will be displayed in the widget
            items. by default the first of column names ("name" or "description"
            or "title" or "text" or "id") that is found will be used for this
            purpose,
        string separator : -
            if param "text" is set to an array then the values will be displayed
            separated by this string,
        string selected : params[id]
            for database data-sources - name of a table/view column
            the selected item (atts[selected]) will be checked against values of
            this column. by default this column is the same as the id column,
        string where :
            for database data-sources - database WHERE condition,
        string|array sort :
            for database data-sources - column name or names for database ORDER BY,
        string alias : -
            when data-source is empty(has no items) this string will be shown
            instead of the widget. the empty widget will still exist but will
            be set hidden,
        array dictionary :
            {text-value: new-text-value,} before putting texts inside widget items
            if the text exists as a key in this array then the array value will be
            put inside the item,
    }
    

Returns

string
Widget HTML

time

string $obj->time(array atts=null, array params=null)

Render a time select widget.

Arguments

    atts=null (array)
    widget HTML attributes plus "selected" and "default" values
    {
        mixed selected :
            the widget item key or keys to be selected,
        mixed default :
            to be displayed in the widget when no option is selected
            false  display nothing
            true   add and display an item with no key and value
            string add and display an item with no key but this value
            array  (key, value) add and display an item with this key and value
        array H :
        {
            string attribute-name :
                attribute-value (attributes for the hour select box)
                the attributes will be set to the main widget tag e.g. select or
                input when the attribute "name" is set and attribute "id" does not
                exists then "id" will be added and set to the same value as "name",
        }
        array M :
        {
            string attribute-name :
                attribute-value (attributes for the minute select box)
                the attributes will be set to the main widget tag e.g. select or
                input when the attribute "name" is set and attribute "id" does not
                exists then "id" will be added and set to the same value as "name",
        }
        array S :
        {
            string attribute-name :
                attribute-value (attributes for the seconds select box)
                the attributes will be set to the main widget tag e.g. select or
                input when the attribute "name" is set and attribute "id" does not
                exists then "id" will be added and set to the same value as "name",
        }
    }
    
    params=null (array)
    has only one key name "format" that can be set to combinations of "H", "M" and "S" e.g. "HMS", which shows time parts to be displayed

Returns

string
Widget HTML