Class Db_ListBehavior

Db_ListBehavior class

Defined in	/phproad/modules/db/behaviors/db_listbehavior.php, lines 29-1382
Inheritance	Phpr_Extension » Phpr_ControllerBehavior » Db_ListBehavior
Author	LemonStand eCommerce Inc.

Adds record list features to back-end controllers. This class allows to extend any back-end controller with a list functionality. It allows to render configurable record lists along with processing corresponding AJAX events.

The extension can be added to a controller by listing the class name in the $implement property of the controller class:

class AbcBlog_Posts extends Backend_Controller
{
  public $implement = 'Db_ListBehavior, Db_FormBehavior';
  ...

The class works only with Db_ActiveRecord models. Model columns should be defined in the model in order to be displayed in a list.

To configure the extension, its properties should be defined in the extended controller class. Only the $list_model_class property is required. Please read the Administration Area Lists article for the usage examples and details.

Public properties

Property	Type	Description	Defined By
list_control_panel	string	specifies a partial name or a path to a partial to use as the list control panel.	Db_ListBehavior
list_custom_body_cells	string	specifies a partial name or a path to a partial to display in each list row.	Db_ListBehavior
list_custom_head_cells	string	specifies a partial name or a path to a partial to display in the list header.	Db_ListBehavior
list_default_sorting_column	string	sets the default list sorting column.	Db_ListBehavior
list_default_sorting_direction	string	sets the default list sorting direction (asc/desc) Only used if the user has not selected any custom sorting properties for the list, is only used if $list_default_sorting_column property is also set.	Db_ListBehavior
list_handle_row_click	boolean	determines whether the list should handle mouse clicks with JavaScript.	Db_ListBehavior
list_items_per_page	integer	number of records to display on a single page.	Db_ListBehavior
list_min_search_query_length	boolean	specifies a minimum search phrase length which triggers the search feature.	Db_ListBehavior
list_model_class	string	a name of the model class.	Db_ListBehavior
list_no_data_message	string	a message to display in case if there are no records to display.	Db_ListBehavior
list_no_interaction	boolean	disables all interaction features of the list - sorting, search, record links, pagination, etc.	Db_ListBehavior
list_no_pagination	boolean	disables list pagination.	Db_ListBehavior
list_no_setup_link	boolean	hides the list configuration button.	Db_ListBehavior
list_no_sorting	boolean	disables list sorting feature.	Db_ListBehavior
list_record_onclick	string	javaScript code to execute when a record is clicked.	Db_ListBehavior
list_record_url	string	an URL to redirect the browser when a list record is clicked.	Db_ListBehavior
list_render_as_tree	boolean	determines whether the list should be rendered as a tree.	Db_ListBehavior
list_render_filters	boolean	determines whether filters should be rendered by the list extension.	Db_ListBehavior
list_search_enabled	boolean	enables the list search feature.	Db_ListBehavior
list_search_fields	array	a list of the model database columns the search function should use for the data search.	Db_ListBehavior
list_search_prompt	string	specifies a prompt to display in the Search field when it has no value.	Db_ListBehavior
list_search_show_empty_query	boolean	determines whether the list records should be displayed of no search query was provided.	Db_ListBehavior
list_sorting_column	string	sets the list sorting column.	Db_ListBehavior
list_sorting_direction	string	sets the list sorting direction (asc/desc) Determines the sorting direction of the list, is only used if $list_sorting_column property is also set.	Db_ListBehavior

Public methods

Method	Description	Defined By
listBeforeRenderRecord()	executed before a list row is displayed.	Db_ListBehavior
listExtendModelObject()	allows to apply additional configuration to the list model object..	Db_ListBehavior
listGetRowClass()	returns a CSS class name for a list row.	Db_ListBehavior
listPrepareData()	prepares the list model.	Db_ListBehavior
listRender()	renders the list.	Db_ListBehavior

Events

Event	Description
core:onAfterRenderListPagination	Triggered after the Administration Area list pagination is displayed.
core:onAfterRenderListTable	Triggered after the Administration Area list table is displayed.
core:onBeforeListExport	Triggered before an Administration Area list is exported as a CSV file.
core:onBeforeListRecordDisplay	Triggered before an Administration Area list row is displayed.

Property details

¶ list_control_panel property

public string $list_control_panel;

Specifies a partial name or a path to a partial to use as the list control panel. The control panel partial should contain the toolbar element with buttons. Example of the listRender() call:

<?= $this->listRender(array('list_control_panel'=>'control_panel')) ?>

Example of the control panel partial:

<div class="toolbar">
  <?= backend_ctr_button('Return to the page list', 'go_back', url('/cms/pages')) ?>
  <div class="clear"></div>
</div>

¶ list_custom_body_cells property

public string $list_custom_body_cells;

Specifies a partial name or a path to a partial to display in each list row. The partial can contain extra list columns (TD elements).

¶ list_custom_head_cells property

public string $list_custom_head_cells;

Specifies a partial name or a path to a partial to display in the list header. The partial can contain extra list columns (TH elements).

¶ list_default_sorting_column property

public string $list_default_sorting_column;

Sets the default list sorting column. If the user has not selected any custom sorting properties for the list, then this property will be used to sort it.

¶ list_default_sorting_direction property

public string $list_default_sorting_direction;

Sets the default list sorting direction (asc/desc) Only used if the user has not selected any custom sorting properties for the list, is only used if $list_default_sorting_column property is also set.

¶ list_handle_row_click property

public boolean $list_handle_row_click;

Determines whether the list should handle mouse clicks with JavaScript. By default this feature is enabled, making entire list table cells clickable.

¶ list_items_per_page property

public integer $list_items_per_page;

Number of records to display on a single page.

¶ list_min_search_query_length property

public boolean $list_min_search_query_length;

Specifies a minimum search phrase length which triggers the search feature. This property takes effect only if $list_search_enabled property has TRUE value.

¶ list_model_class property

public string $list_model_class;

A name of the model class.

¶ list_no_data_message property

public string $list_no_data_message;

A message to display in case if there are no records to display. The default value is "There are no items in this view".

¶ list_no_interaction property

public boolean $list_no_interaction;

Disables all interaction features of the list - sorting, search, record links, pagination, etc.

¶ list_no_pagination property

public boolean $list_no_pagination;

Disables list pagination.

¶ list_no_setup_link property

public boolean $list_no_setup_link;

Hides the list configuration button. By default the list configuration button is displayed above the list on the right side of the page.

¶ list_no_sorting property

public boolean $list_no_sorting;

Disables list sorting feature. By default lists can be sorted by clicking a column title.

¶ list_record_onclick property

public string $list_record_onclick;

JavaScript code to execute when a record is clicked.

¶ list_record_url property

public string $list_record_url;

An URL to redirect the browser when a list record is clicked. Use the url() for creating back-end URLs. Example:

$this->list_record_url = url('/blog/posts/preview/');

¶ list_render_as_tree property

public boolean $list_render_as_tree;

Determines whether the list should be rendered as a tree. This feature is supported only if the model class is extended with Db_Act_As_Tree extension.

¶ list_render_filters property

public boolean $list_render_filters;

Determines whether filters should be rendered by the list extension.

¶ list_search_enabled property

public boolean $list_search_enabled;

Enables the list search feature.

¶ list_search_fields property

public array $list_search_fields;

A list of the model database columns the search function should use for the data search. This property takes effect only if $list_search_enabled property has TRUE value.

¶ list_search_prompt property

public string $list_search_prompt;

Specifies a prompt to display in the Search field when it has no value. This property takes effect only if $list_search_enabled property has TRUE value.

¶ list_search_show_empty_query property

public boolean $list_search_show_empty_query;

Determines whether the list records should be displayed of no search query was provided. This property takes effect only if $list_search_enabled property has TRUE value.

¶ list_sorting_column property

public string $list_sorting_column;

Sets the list sorting column. If this property is set, its value overrides any sorting column preferences selected by a user.

¶ list_sorting_direction property

public string $list_sorting_direction;

Sets the list sorting direction (asc/desc) Determines the sorting direction of the list, is only used if $list_sorting_column property is also set.

Method details

¶ listBeforeRenderRecord() method

public void listBeforeRenderRecord(Db_ActiveRecord $model)

$model	Db_ActiveRecord	specifies a model object to be rendered.

Executed before a list row is displayed. This method can be overridden in the controller.

¶ listExtendModelObject() method

public Db_ActiveRecord listExtendModelObject(Db_ActiveRecord $model)

$model	Db_ActiveRecord	a model object to configure.
{return}	Db_ActiveRecord	returns a configured model object.

Allows to apply additional configuration to the list model object.. This method can be overridden in the controller. Inside the method you can call the model's where() method to apply additional filters.

¶ listGetRowClass() method

public string listGetRowClass(Db_ActiveRecord $model)

$model	Db_ActiveRecord	specifies the model object being rendered in the list row.
{return}	string	returns the CSS class name.

Returns a CSS class name for a list row. This method can be overridden in the controller if list rows require additional styling. Example:

public function listGetRowClass($model)
{
  if ($model->status == -1)
    return 'error';
}

¶ listPrepareData() method

public Db_ActiveRecord listPrepareData()

{return}	Db_ActiveRecord	returns a configured model object.

Prepares the list model. This method can be overridden in the controller. By default the method creates an object of the class specified in the $list_model_class property. If you use the Filter Behavior, in this method you should call its filterApplyToModel() method. Example:

public function listPrepareData()
{
  $obj = Shop_Order::create();
  $this->filterApplyToModel($obj);

  return $obj;
}

¶ listRender() method

public void listRender(array $options=array(), string $partial=NULL)

$options	array	a associative array of options. The options allow to override list option properties defined in the controller. Note that option values specified in the method are not persistent and will not be used in the list AJAX calls (sorting, search, etc.).
$partial	string	a name of partial to use instead of the default list partial.

Renders the list. Use this method in a page view document to render the list with the parameters defined in the controller. Example:

<?= $this->listRender() ?>

LemonStand API