The AMI_ModListView class

AMI_View
   |
   --AMI_ModPlaceholderView
      |
      --AMI_ModListView

• Introduction

Module list component view abstraction.

• Class synopsis

AMI_ModListView extends AMI_ModPlaceholderView {

/* Properties */

// Column rules object

protected array $aColumnFormatters = array();

// Column layouts

protected array $aColumnLayouts = array();

// Columns array

protected array $aColumns = array();

// Columns types

protected array $aColumnTypes = array();

// List default elements template (placeholders)

protected array $aPlaceholders = array( '#list_header', '#flags', 'position', 'public', 'flags', '#common', 'date_created', 'cat_header', 'common', '#columns', 'columns', '#actions', 'front_view', 'edit', 'actions', 'list_header' );

// Sort columns list

protected array $aSortColumns = array();

// Body column set name

protected string $bodyItemSet = 'body_item';

// Body row set name

protected string $bodyRowSet = 'body_row';

// Body set name

protected string $bodySet = 'body';

// Footer set name

protected string $footerSet = 'footer';

// Header column set name

protected string $headerItemSet = 'header_item';

// Header row set name

protected string $headerRowSet = 'header_row';

// Header set name

protected string $headerSet = 'header';

// List set name

protected string $listSet = 'list';

// Model typification

protected AMI_ModTable $oModel;

// Order column

protected string $orderColumn = 'id';

// Order column direction

protected string $orderDirection = 'asc';

/* Inherited Properties */

// Locale

protected AMI_View::$aLocale = array();

// Scope

protected AMI_View::$aScope = array();

// Locale file name

protected AMI_View::$localeFileName = '';

// Template block name

protected AMI_View::$tplBlockName = '';

// Template file name

protected AMI_View::$tplFileName = '';

/* Methods */

// Add column into array.

public addColumn ( string $column, [ string $placeholderPos = '' ] ) returns AMI_ModListView;

// Adds column (if not added yet) and its type for corresponding column.

public addColumnType ( string $column, string $type ) returns AMI_ModListView_JSON;

// Adding order.

public addOrder ( string $column, [ bool $direction = true ] ) returns AMI_ModListView;

// Adds column formatter.

public formatColumn ( string $column, callback $callback, [ $aArgs = array() ] ) returns AMI_ModListView;

// Allows modify the value of a cell in the list.

public get ( ) returns void;

// Return columns for list model.

public getColumns ( ) returns array;

// Getting sorting order.

public getOrder ( ) returns string;

// Getting sorting direction.

public getOrderDirection ( ) returns string;

// Returns sortable columns.

public getSortColumns ( ) returns array;

// Remove column.

public removeColumn ( string $column ) returns AMI_ModListView;

// Sets fixed column alignment.

public setColumnAlign ( string $column, string $align ) returns AMI_ModListView;

// Sets fixed column class name.

public setColumnClass ( string $column, string $class ) returns AMI_ModListView;

// Sets fixed column layout.

public setColumnLayout ( string $column, $aLayout ) returns AMI_ModListView;

// Sets fixed column width.

public setColumnWidth ( string $column, string $width ) returns AMI_ModListView;

// Adds sort columns.

protected addSortColumns ( $aColumns ) returns AMI_ModListView;

// Displays image in separate column if (bool)value is TRUE.

protected fmtColIcon ( mixed $value, $aArgs ) returns string;

// Date/time formatter.

protected fmtDateTime ( string $value, $aArgs ) returns mixed;

// Encodes column value.

protected fmtHTMLEncode ( mixed $value, $aArgs ) returns mixed;

// Extended Date/time formatter. For FMT_DATEs Replaces yesterday date by localized word "yesterday" (today, tommorow).

protected fmtHumanDateTime ( string $value, $aArgs ) returns mixed;

// Replaces column value by its localized caption.

protected fmtLocaleCaption ( mixed $value, [ $aArgs = array() ] ) returns mixed;

// Strips tags from column value.

protected fmtStripTags ( mixed $value, $aArgs ) returns mixed;

// Truncates column value.

protected fmtTruncate ( mixed $value, $aArgs ) returns mixed;

// Model typification.

protected _setModel ( object $oModel ) returns AMI_ModListView;

/* Inherited Methods */

// Constructor.

public AMI_ModPlaceholderView::__construct ( ) returns AMI_ModPlaceholderView;

// Add new field placeholders into placeholder list using AMI_ModPlaceholderView::putPlaceholder() without sections.

public AMI_ModPlaceholderView::addPlaceholders ( $aPlaceholders ) returns AMI_ModPlaceholderView;

// Puts placeholder into required position.

public AMI_ModPlaceholderView::putPlaceholder ( string $name, [ string $positions = '' ], [ bool $isSection = false ] ) returns bool|int;

// Constructor.

public AMI_View::__construct ( ) returns AMI_View;

// Adds locale.

public AMI_View::addLocale ( $aLocale, [ bool $doOverwrite = true ] ) returns AMI_View;

// Adds script code.

public AMI_View::addScriptCode ( string $code ) returns AMI_View;

// Adds script file.

public AMI_View::addScriptFile ( string $file ) returns AMI_View;

// Returns view data.

public AMI_View::get ( ) returns mixed;

// Returns prepared view scope.

public AMI_View::getScope ( string $type, [ $aScope = array() ] ) returns array;

// Initialize, processing after setting model.

public AMI_View::init ( ) returns AMI_View;

// Adds locale from resource.

public AMI_View::setModel ( mixed $oModel, [ $aLocale = array() ], string $path ) returns AMI_View;

// Set module id.

public AMI_View::setModId ( string $modId ) returns void;

// Sets view scope.

public AMI_View::setScope ( $aScope ) returns AMI_View;

protected AMI_View::addOpenGraphTags ( $header, $description, [ $image = '' ] ) returns void;

// Returns module id.

protected AMI_View::getModId ( ) returns string;

// Returns module specific locale path.

protected AMI_View::getModLocalePath ( ) returns string;

// Returns template object.

protected AMI_View::getTemplate ( ) returns AMI_iTemplate;

// Parses block template and returns the result as a string.

protected AMI_View::parse ( string $setName, [ $aScope = array() ] ) returns string;

// Sets up model object.

protected AMI_View::_setModel ( mixed $oModel ) returns AMI_View;

}

Tags:

abstract
since	5.10.0

• Class Properies

protected array $aColumnFormatters: Column rules object

protected array $aColumnLayouts: Column layouts

protected array $aColumns: Columns array

protected array $aColumnTypes: Columns types

protected array $aPlaceholders: List default elements template (placeholders)

protected array $aSortColumns: Sort columns list

protected string $bodyItemSet

Body column set name

List set name

protected string $bodyRowSet

Body row set name

List set name

protected string $bodySet

Body set name

List set name

protected string $footerSet

Footer set name

List set name

protected string $headerItemSet

Header column set name

List set name

protected string $headerRowSet

Header row set name

List set name

protected string $headerSet

Header set name

List set name

protected string $listSet

List set name

protected AMI_ModTable $oModel: Model typification

protected string $orderColumn: Order column

protected string $orderDirection: Order column direction

• Class Methods

// Add column into array.

public addColumn ( string $column, [ string $placeholderPos = '' ] ) returns AMI_ModListView;

string $column
Column name
string $placeholderPos
Placeholder position (since 5.12.4)

Example:

// AmiSample_ListViewAdm::__construct()
$this
->addColumn('id')
->addColumn('nickname')
->addColumn('birth', 'nickname.before');

// Adds column (if not added yet) and its type for corresponding column.

public addColumnType ( string $column, string $type ) returns AMI_ModListView_JSON;

string $column
Column name
string $type
Column type, none|hidden|int|float|text|date|datetime
- none - no column data will be passed to client (since 5.14.0);
- hidden - hidden column;
- int|float - column containing number;
- text - column containing text;
- mediumtext - wide column containing text;
- longtext - column containing long text data
- date|datetime - column containing date/time.

List loads column types from fields added by AMI_ModFormView::addField().
Other fields has 'text' type by default, call this method to change default 'text' type.
Also virtual fields should be added calling this method to be visible in the list.
See AmiSample_ListViewAdm for usage example.

Example:

// AmiSample_ListViewAdm
public function __construct(){
parent::__construct();
// Init columns
$this
->addColumn('id')
->addColumn('nickname')
->addColumn('birth')
->addColumnType('age', 'int')
->setColumnTensility('nickname');
// ...
}

// Adding order.

public addOrder ( string $column, [ bool $direction = true ] ) returns AMI_ModListView;

string $column
Column name
bool $direction
Direction: true - asc, false - desc

// Adds column formatter.

public formatColumn ( string $column, callback $callback, [ $aArgs = array() ] ) returns AMI_ModListView;

string $column
Column name
callback $callback
Callback
array $aArgs
Formatter arguments

Passed $aArgs always contain 'aScope' (array, list view scope) and oItem (AMI_ModTableItem, current list item model).

Example:

class MyModule_ListViewAdm extends AMI_ModListView{
// ...
public function __construct(){
$this->formatColumn(
'announce',
array($this, 'fmtTruncate'),
array(
'doSaveWords' => false,
'length' => 200
)
);
$this->formatColumn(
'announce',
array($this, 'fmtMyAnnounce'),
array(
'key1' => 'value1'
)
);
}
protected function fmtMyAnnounce($value, array $aArgs){
// $aArgs contains third AMI_ModListView::formatColumn() argument
// ...
return $value;
}
// ...
}

Tags:

see	AMI_ModListView::fmtTruncate()
todo	Decide about public method access (i.e. to call from extensions).
since	5.12.0

// Allows modify the value of a cell in the list.

public get ( ) returns void;

Overrides: AMI_View::get().

Overridden in child classes as: AMI_ModListView_JSON::get(), AMI_ModCatsView::get(), Hyper_AmiMultifeeds_CatsViewFrn::get(), Hyper_AmiMultifeeds_StickyCatsViewFrn::get(), AMI_ModItemsView::get(), Hyper_AmiClean_ItemsViewFrn::get(), Hyper_AmiMultifeeds_ItemsViewFrn::get(), Hyper_AmiMultifeeds_StickyItemsViewFrn::get(), Hyper_AmiMultifeeds_SpecblockViewFrn::get(), Hyper_AmiMultifeeds_BrowseItemsViewFrn::get().

// Return columns for list model.

public getColumns ( ) returns array;

Return columns added by AMI_ModListView::addColumn().
Can be overridden in child classes to cancel previously added columns.

Example:

protected function getColumns(){
return array('id', 'name');
}

Tags:

since

5.14.0

// Getting sorting order.

public getOrder ( ) returns string;

// Getting sorting direction.

public getOrderDirection ( ) returns string;

// Returns sortable columns.

public getSortColumns ( ) returns array;

Tags:

amidev

// Remove column.

public removeColumn ( string $column ) returns AMI_ModListView;

string $column
Column name

Tags:

since

5.12.8

// Sets fixed column alignment.

public setColumnAlign ( string $column, string $align ) returns AMI_ModListView;

string $column
Column name
string $align
Column alignment (allowed values: 'left', 'center', 'right', 'justify')

Tags:

since

5.14.4

// Sets fixed column class name.

public setColumnClass ( string $column, string $class ) returns AMI_ModListView;

string $column
Column name
string $class
Column class name (null or empty string to reset)

Tags:

since

5.14.4

// Sets fixed column layout.

public setColumnLayout ( string $column, $aLayout ) returns AMI_ModListView;

string $column
Column name
array $aLayout
Column layout as array(width => width, align: align, classname: classname)

Tags:

since

5.14.4

// Sets fixed column width.

public setColumnWidth ( string $column, string $width ) returns AMI_ModListView;

string $column
Column name
string $width
Column width (allowed values: 'extra-narrow', 'narrow', 'normal', 'wide', 'extra-wide')

Tags:

since

5.14.4

// Adds sort columns.

protected addSortColumns ( $aColumns ) returns AMI_ModListView;

array $aColumns
Columns list

Example:

// AmiSample_ListViewAdm
public function __construct(){
// ...
// Init columns
$this
// ...
->addSortColumns(
array(
'public',
'nickname',
'birth'
)
);
// ...
}

Tags:

since

5.12.4

// Displays image in separate column if (bool)value is TRUE.

protected fmtColIcon ( mixed $value, $aArgs ) returns string;

mixed $value
Not false to display icon
array $aArgs
Arguments:
- name - image class name part ("col-icon-{$name}");
- caption - forced icon caption,
- has_inactive - flag specifying to display inactive icon,
- caption_inactive - forced inactive icon caption.

Common column formatter.

Example:

class MyModule_ListViewAdm extends AMI_ModListViewAdm{
// ...
public function init(){
// ...
// Following code will output flag columns containing green checkbox icon
foreach(array('flag1', 'flag2', ...) as $column){
$this->setColumnLayout($column, array('align' => 'center'));
$this->formatColumn($column, array($this, 'fmtColIcon'), array('class' => 'checked'));
}
// ...
}
}

Tags:

see	AMI_ModListView::handleFormatCell()
see	AMI_ModListView::formatColumn()
since	5.14.4

// Date/time formatter.

protected fmtDateTime ( string $value, $aArgs ) returns mixed;

string $value
Value to format
array $aArgs
Arguments:
- format AMI_Lib_Date::FMT_DATE, AMI_Lib_Date::FMT_TIME or AMI_Lib_Date::FMT_DATETIME;

Common column formatter.

Tags:

see	AMI_ModListView::handleFormatCell()
see	AMI_ModListView::formatColumn()
since	5.12.4

// Encodes column value.

protected fmtHTMLEncode ( mixed $value, $aArgs ) returns mixed;

mixed $value
Value to format
array $aArgs
Arguments

Common column formatter.

Tags:

see	AMI_ModListView::handleFormatCell()
see	AMI_ModListView::formatColumn()
since	5.12.0

// Extended Date/time formatter. For FMT_DATEs Replaces yesterday date by localized word "yesterday" (today, tommorow).

protected fmtHumanDateTime ( string $value, $aArgs ) returns mixed;

string $value
Value to format
array $aArgs
Arguments:
- format AMI_Lib_Date::FMT_DATE, AMI_Lib_Date::FMT_TIME or AMI_Lib_Date::FMT_DATETIME;

Common column formatter.

Tags:

see	AMI_ModListView::handleFormatCell()
see	AMI_ModListView::formatColumn()
since	5.14.4

// Replaces column value by its localized caption.

protected fmtLocaleCaption ( mixed $value, [ $aArgs = array() ] ) returns mixed;

mixed $value
Value to format
array $aArgs
Arguments

Common column formatter.

Tags:

see	AMI_ModListView::handleFormatCell()
see	AMI_ModListView::formatColumn()
since	5.12.4

// Strips tags from column value.

protected fmtStripTags ( mixed $value, $aArgs ) returns mixed;

mixed $value
Value to format
array $aArgs
Arguments

Common column formatter.

Tags:

see	AMI_ModListView::handleFormatCell()
see	AMI_ModListView::formatColumn()
since	5.12.0

// Truncates column value.

protected fmtTruncate ( mixed $value, $aArgs ) returns mixed;

mixed $value
Value to format
array $aArgs
Arguments:
- length - maximum string length (int, 50 by default);
- doSaveWords - save whole words (bool, true by default);
- doStripTags - strip tags before truncation (bool, false by default);
- doHTMLEncode - HTML encode after truncation (bool, true by default);
- tail - tail after truncation (string, '...' by default).

Common column formatter.

Tags:

see	AMI_ModListView::handleFormatCell()
see	AMI_ModListView::formatColumn()
since	5.12.0

// Model typification.

protected _setModel ( object $oModel ) returns AMI_ModListView;

object $oModel
Model

Overrides: AMI_View::_setModel().

Overridden in child classes as: AMI_ModSubitemsView::_setModel().