Table

Table builder. To renders highly customizable and flexible sortable HTML tables from model data. With the methods of this class you can create either a table of model data rows or a data sheet style table to display information about one row. After querying data from an "IModel" instance you can pass it to a table renderer the renderer will fetch/iterate data row(s).
The overall concept is to query data using an "IModel" instance then passing the instance and the data columns (and optional settings) to a "Table" object. You can provide a list of the "IModel" instance properties and methods as the table columns, the renderer will iterate on the "IModel" and display the data from this list. The renderer will try to get their labels from a method called "labels()" on the "IModel" instance or the data properties destination, if non supplied then the property/method name itself will be used.
To fully understand how this class works it is recommended to see the examples.
Source
Table.php
Depends on
IModel , Paging , Utils , Render

Constants

CHECKBOX = 'checkbox'

Action type - when defining row actions, if action type is set to this then a checkbox will be put in place for each row.

COLUMN = 0

i18n data style - (used only for "renderView()") show by column, show like other data.

GROUP_IN_ROW = 1

Group row style - put a separated column for each col and show data under them.

GROUP_LIST = 0

Group row style - show group data in one big column as colVal1, colVal2.

GROUP_METHOD = 2

Group row style - put the return value of a model's method.

LOCALE = 1

i18n data style - (used only for "renderView()") show by locale, separate i18n data and show under locales.

RADIO = 'radio'

Action type - when defining row actions, if action type is set to this then a radio option will be put in place for each row.

Properties

hasRows

$obj->hasRows

Will be set to true if data was not empty. This is useful when you want to an alternative message instead of an empty table.

Methods

__construct

Table $obj = new Table(IModel model=null, [string] | array cols=null)

Construct the object, you can also set the "IModel" instance and the data property names (table columns) to be displayed in the table. The "IModel" instance and the properties can be set using the "set()" method.

Arguments

    model=null (IModel)
    IModel instance to render it's queried data
    cols=null ([string] | array)
    The IModel instance property names or method names which provide values for the table columns. If no column is passed then all model data properties will be displayed

Returns

void

actions

Table $obj->actions(array actions=null)

Set row actions. Actions are optional extra columns added to a row, Note that this configs can be passed to the renderer methods directly instead of using this method. e.g: update | delete | link | radio | check.

Arguments

    actions=null (array)
    Action definition
    {
        array optional-action-key-name : {
            string html-attribute-name :
                value - "Model::key-property-name" and "Model::property-name"
                string instances will be replaced by their real values,
            const  type     : null
                "null"=button or anchor or "Table::CHECKBOX" or "Table::RADIO",
            string text     :
                contents/text to show inside the action tag,
            string show     :
                model method-name which returns true or false - if this config
                is provided then for each row this method will be called by
                the renderer and the action will only be added to the row if
                the return value is true,
            bool   checked  :
                if action is checkbox or radio then true=set the box
                to checked,
            bool   selected :
                alias for "checked",
            array replace   :
                a list of property names to be available to be replaced in
                attribute values. the attribute values may contain
                "Model::key-property-name" and "Model::property-name" strings.
                If you want to replace any property other than model's key
                property you must specify it here. This improves performance,
        }
        array optional-actions-group-key : {
            string select :
                it is possible to have one col for an action and have a
                different type of action(selective) for each row - a list of
                available actions must be defined (as below) and a selector
                (a model method) which selects an action for each row. set
                the model's method-name which returns one of the group
                action-key from the below actions to this key - the renderer
                will call this method for each row and use the returned string
                as the key to select one of the actions defined as below,
            array optional-action-key-name : {
                string html-attribute-name :
                    value - "Model::key-property-name" and
                    "Model::property-name" string instances will be replaced
                    by their real values,
                const  type     : null
                    ("null" = button) or anchor or "Table::CHECKBOX" or
                    "Table::RADIO",
                string text     :
                    contents/text to show inside the action tag,
                string show     :
                    model method-name which returns true or false -
                    if this config is provided then for each row this method
                    will be called by the renderer and the action will only
                    be added to the row if the return value is true,
                bool   checked  :
                    if action is checkbox or radio then true=set the box
                    to checked,
                bool   selected :
                    alias for "checked",
                array replace   :
                    a list of property names to be available to be replaced
                    in attribute values. the attribute values may contain
                    "Model::key-property-name" and "Model::property-name"
                    strings - if you want to replace any property other than
                    model's key property you must specify it here. this is to
                    improve performance,
            }
        }
    }
    

Returns

Table
For method chaining

attributes

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

Set attributes to be applied to the table HTML tags to customize the table. Note that this configs can be passed to the renderer methods directly instead of using this method.

Arguments

    atts=null (array)
    To address elements and set their attributes
    {
        array table : {
            string attribute-name : value,
        }
        array div : {
            string attribute-name : value,
        }
        array th : {
            array model-property(method)-name : {
                string      attribute-name : value,
                string|bool sort           :
                    to define sort handlers for cols
                    "jsFunction(this, Table::COL)"
                    "true"
                    "Arta.listSort(this, Table::COL)",
            }
        }
        array tr : {
            string attribute-name : value,
        }
        array label : {
            string attribute-name : value,
        }
        array model-property(method)-name : {
            string attribute-name : value,
        }
        array # : {
            string attribute-name : value,
        }
    }
    

Returns

Table
For method chaining

group

Table $obj->group([string] | array cols)

To group a table by one or some columns. When the columns (which are defined as the group) of a row have the same values as the previous row then they will be displayed empty.

Arguments

    cols ([string] | array)
    A subset of the "IModel" instance property and method list which are given to the renderer

Returns

Table
For method chaining

groupStyle

Table $obj->groupStyle(const style=Table::GROUP_LIST, string method=null)

To set the style of group header row. As the recurring data will be left empty the first data that will be displayed may be formatted using this method.

Arguments

    style=Table::GROUP_LIST (const)
    or "Table::GROUP_LIST" or "Table::GROUP_IN_ROW" or "Table::GROUP_METHOD"
    method=null (string)
    When "Table::GROUP_METHOD", then this method of the "IModel" instance will decide and return what to be shown in the group header row

Returns

Table
For method chaining

params

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

Set render parameters. Note that this configs can be passed to the renderer methods directly instead of using this method.

Arguments

    params=null (array)
    Params definition
    {
        bool   stripe     : true
            true=add an "odd" or "even" value to the rows class attribute,
        string no_result  :
            if model query was empty return this text instead of
            rendered table,
        string tag_action : div
            not available for "renderTable()" - each action will be inside
            this tag,
        string ag_actions : span
            not available for "renderTable()" - action container will be
            inside this tag,
        string tag_data   : span
            not available for "renderTable()" - tag around data,
        const  i18n       : Table::LOCALE
            not available for "renderTable()" i18n data show style one of
            "Table::LOCALE" or "Table::COLUMN",
        bool   empty      : false
            not available for "renderTable()"
            true=do show all columns data
            false=do not show column if data is null,
    }
    

Returns

Table
For method chaining

renderDiv

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

To iterate over data of the set queried "IModel" instance, rendering the data in a table made of div rows and each row data are rendered in a table/tr/td.

Arguments

    actions=null (array)
    Alternative to using "actions()"
    {
        array optional-action-key-name : {
            string html-attribute-name :
                value - "Model::key-property-name" and "Model::property-name"
                string instances will be replaced by their real values,
            const  type     : null
                "null"=button or anchor or "Table::CHECKBOX" or "Table::RADIO",
            string text     :
                contents/text to show inside the action tag,
            string show     :
                model method-name which returns true or false - if this config
                is provided then for each row this method will be called by
                the renderer and the action will only be added to the row if
                the return value is true,
            bool   checked  :
                if action is checkbox or radio then true=set the box
                to checked,
            bool   selected :
                alias for "checked",
            array replace   :
                a list of property names to be available to be replaced in
                attribute values. the attribute values may contain
                "Model::key-property-name" and "Model::property-name" strings.
                If you want to replace any property other than model's key
                property you must specify it here. This improves performance,
        }
        array optional-actions-group-key : {
            string select :
                it is possible to have one col for an action and have a
                different type of action(selective) for each row - a list of
                available actions must be defined (as below) and a selector
                (a model method) which selects an action for each row. set
                the model's method-name which returns one of the group
                action-key from the below actions to this key - the renderer
                will call this method for each row and use the returned string
                as the key to select one of the actions defined as below,
            array optional-action-key-name : {
                string html-attribute-name :
                    value - "Model::key-property-name" and
                    "Model::property-name" string instances will be replaced
                    by their real values,
                const  type     : null
                    ("null" = button) or anchor or "Table::CHECKBOX" or
                    "Table::RADIO",
                string text     :
                    contents/text to show inside the action tag,
                string show     :
                    model method-name which returns true or false -
                    if this config is provided then for each row this method
                    will be called by the renderer and the action will only
                    be added to the row if the return value is true,
                bool   checked  :
                    if action is checkbox or radio then true=set the box
                    to checked,
                bool   selected :
                    alias for "checked",
                array replace   :
                    a list of property names to be available to be replaced
                    in attribute values. the attribute values may contain
                    "Model::key-property-name" and "Model::property-name"
                    strings - if you want to replace any property other than
                    model's key property you must specify it here. this is to
                    improve performance,
            }
        }
    }
    
    atts=null (array)
    Alternative to using "attributes()"
    {
        array table : {
            string attribute-name : value,
        }
        array div : {
            string attribute-name : value,
        }
        array th : {
            array model-property(method)-name : {
                string      attribute-name : value,
                string|bool sort           :
                    to define sort handlers for cols
                    "jsFunction(this, Table::COL)"
                    "true"
                    "Arta.listSort(this, Table::COL)",
            }
        }
        array tr : {
            string attribute-name : value,
        }
        array label : {
            string attribute-name : value,
        }
        array model-property(method)-name : {
            string attribute-name : value,
        }
        array # : {
            string attribute-name : value,
        }
    }
    
    params=null (array)
    Alternative to using "params()"
    {
        bool   stripe     : true
            true=add an "odd" or "even" value to the rows class attribute,
        string no_result  :
            if model query was empty return this text instead of
            rendered table,
        string tag_action : div
            not available for "renderTable()" - each action will be inside
            this tag,
        string ag_actions : span
            not available for "renderTable()" - action container will be
            inside this tag,
        string tag_data   : span
            not available for "renderTable()" - tag around data,
        const  i18n       : Table::LOCALE
            not available for "renderTable()" i18n data show style one of
            "Table::LOCALE" or "Table::COLUMN",
        bool   empty      : false
            not available for "renderTable()"
            true=do show all columns data
            false=do not show column if data is null,
    }
    

Returns

string
HTML

renderTable

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

To iterate over data of the set queried "IModel" instance, rendering the data in a table made of table/tr/td elements.

Arguments

    actions=null (array)
    Alternative to using "actions()"
    {
        array optional-action-key-name : {
            string html-attribute-name :
                value - "Model::key-property-name" and "Model::property-name"
                string instances will be replaced by their real values,
            const  type     : null
                "null"=button or anchor or "Table::CHECKBOX" or "Table::RADIO",
            string text     :
                contents/text to show inside the action tag,
            string show     :
                model method-name which returns true or false - if this config
                is provided then for each row this method will be called by
                the renderer and the action will only be added to the row if
                the return value is true,
            bool   checked  :
                if action is checkbox or radio then true=set the box
                to checked,
            bool   selected :
                alias for "checked",
            array replace   :
                a list of property names to be available to be replaced in
                attribute values. the attribute values may contain
                "Model::key-property-name" and "Model::property-name" strings.
                If you want to replace any property other than model's key
                property you must specify it here. This improves performance,
        }
        array optional-actions-group-key : {
            string select :
                it is possible to have one col for an action and have a
                different type of action(selective) for each row - a list of
                available actions must be defined (as below) and a selector
                (a model method) which selects an action for each row. set
                the model's method-name which returns one of the group
                action-key from the below actions to this key - the renderer
                will call this method for each row and use the returned string
                as the key to select one of the actions defined as below,
            array optional-action-key-name : {
                string html-attribute-name :
                    value - "Model::key-property-name" and
                    "Model::property-name" string instances will be replaced
                    by their real values,
                const  type     : null
                    ("null" = button) or anchor or "Table::CHECKBOX" or
                    "Table::RADIO",
                string text     :
                    contents/text to show inside the action tag,
                string show     :
                    model method-name which returns true or false -
                    if this config is provided then for each row this method
                    will be called by the renderer and the action will only
                    be added to the row if the return value is true,
                bool   checked  :
                    if action is checkbox or radio then true=set the box
                    to checked,
                bool   selected :
                    alias for "checked",
                array replace   :
                    a list of property names to be available to be replaced
                    in attribute values. the attribute values may contain
                    "Model::key-property-name" and "Model::property-name"
                    strings - if you want to replace any property other than
                    model's key property you must specify it here. this is to
                    improve performance,
            }
        }
    }
    
    atts=null (array)
    Alternative to using "attributes()"
    {
        array table : {
            string attribute-name : value,
        }
        array div : {
            string attribute-name : value,
        }
        array th : {
            array model-property(method)-name : {
                string      attribute-name : value,
                string|bool sort           :
                    to define sort handlers for cols
                    "jsFunction(this, Table::COL)"
                    "true"
                    "Arta.listSort(this, Table::COL)",
            }
        }
        array tr : {
            string attribute-name : value,
        }
        array label : {
            string attribute-name : value,
        }
        array model-property(method)-name : {
            string attribute-name : value,
        }
        array # : {
            string attribute-name : value,
        }
    }
    
    params=null (array)
    Alternative to using "params()"
    {
        bool   stripe     : true
            true=add an "odd" or "even" value to the rows class attribute,
        string no_result  :
            if model query was empty return this text instead of
            rendered table,
        string tag_action : div
            not available for "renderTable()" - each action will be inside
            this tag,
        string ag_actions : span
            not available for "renderTable()" - action container will be
            inside this tag,
        string tag_data   : span
            not available for "renderTable()" - tag around data,
        const  i18n       : Table::LOCALE
            not available for "renderTable()" i18n data show style one of
            "Table::LOCALE" or "Table::COLUMN",
        bool   empty      : false
            not available for "renderTable()"
            true=do show all columns data
            false=do not show column if data is null,
    }
    

Returns

string
HTML

renderView

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

To only show the data of the current row of the queried "IModel" instance. This can be useful when creating a data sheet view of a row.

Arguments

    atts=null (array)
    Alternative to using "attributes()"
    {
        array table : {
            string attribute-name : value,
        }
        array div : {
            string attribute-name : value,
        }
        array th : {
            array model-property(method)-name : {
                string      attribute-name : value,
                string|bool sort           :
                    to define sort handlers for cols
                    "jsFunction(this, Table::COL)"
                    "true"
                    "Arta.listSort(this, Table::COL)",
            }
        }
        array tr : {
            string attribute-name : value,
        }
        array label : {
            string attribute-name : value,
        }
        array model-property(method)-name : {
            string attribute-name : value,
        }
        array # : {
            string attribute-name : value,
        }
    }
    
    params=null (array)
    Alternative to using "params()"
    {
        bool   stripe     : true
            true=add an "odd" or "even" value to the rows class attribute,
        string no_result  :
            if model query was empty return this text instead of
            rendered table,
        string tag_action : div
            not available for "renderTable()" - each action will be inside
            this tag,
        string ag_actions : span
            not available for "renderTable()" - action container will be
            inside this tag,
        string tag_data   : span
            not available for "renderTable()" - tag around data,
        const  i18n       : Table::LOCALE
            not available for "renderTable()" i18n data show style one of
            "Table::LOCALE" or "Table::COLUMN",
        bool   empty      : false
            not available for "renderTable()"
            true=do show all columns data
            false=do not show column if data is null,
    }
    

Returns

string
HTML

set

Table $obj->set(IModel model=null, [string] | array cols=null)

Set the "IModel" instance and the data property names (table columns) to be displayed in the table. The "IModel" instance and the properties can be set using the "set()" method.

Arguments

    model=null (IModel)
    IModel instance to render it's queried data
    cols=null ([string] | array)
    The IModel instance property names or method names which provide values for the table columns. If no column is passed then all model data properties will be displayed

Returns

Table
For method chaining

style

void $obj->style(string method)

Styling means giving different HTML class attribute to each table row. This can be done by defining a method in your model which checks things and returns a string value which would be the class attribute value for the row being iterated. While iterating on the "IModel" instance, the renderer will call the method and set the returned value in the row's "tr" element "class".

Arguments

    method (string)
    The "IModel" method name which returns a string to be set to the row's class attribute * @return Table For method chaining

Returns

void

Example

$table = new Table();
$table->render();