Amiro.CMS API Reference
Amiro.Ru / Manual
Loading search...

The AMI_ModTable class

• Introduction

Module table model.

• Class synopsis

AMI_ModTable implements AMI_iModTable {
/* Properties */
// Flag specifying extensions are initialized already
protected static array $extInitialized = array();
// Attributes
protected array $aAttributes = array();
// Database table name, must be declared in child classes
protected string $tableName = '';
/* Methods */
// Constructor.
public __construct ( [ $aAttributes = array() ] ) returns AMI_ModTable;
// Destructor.
public __destruct ( ) returns void;
// Returns item model object and add new data without saving.
public add ( [ $aData = array() ] ) returns AMI_ModTableItem;
// Adds validators array for fields.
public addValidators ( $aValidators ) returns AMI_ModTable;
// Drops attribute.
public dropAttr ( string $name ) returns AMI_ModTable;
// Exludes fields not from available list.
public filterFields ( $aFields ) returns array;
// Returns item model object and load data for key field param.
public find ( int $id, [ $aFields = array('*') ] ) returns AMI_ModTableItem;
// Returns item model object and load data for non-primary key field.
public findByFields ( $aSearchCondition, [ $aFields = array('*') ] ) returns AMI_ModTableItem;
// Returns attribute.
public getAttr ( string $name, [ mixed $defaultValue = null ] ) returns mixed;
// Returns array of available fields.
public getAvailableFields ( [ bool $bAppendEventFields = true ] ) returns array;
// Returns dependence resource name.
public getDependenceResId ( string $alias ) returns string|null;
// Returns real field name by its alias.
public getFieldName ( string $alias, [ string $prefix = '' ] ) returns string;
// Called when receive array of validators, allow add own validators.
public getItem ( [ mixed $type = '' ] ) returns void;
// Returns list model object.
public getList ( [ string $type = '' ] ) returns AMI_ModTableList;
// Returns next primary key field value.
public getNextPKValue ( ) returns int|null;
// Event, called for add columns to the query result, a compound derived from the dependent model.
public getQueryBase ( [ mixed $type = '' ], [ mixed $bJoinDependentTables = true ] ) returns void;
// Returns database table name.
public getTableName ( ) returns string;
// Checks if model has a field.
public hasField ( string $name, [ bool $bAppendEventFields = false ] ) returns bool;
// Returns TRUE if attribute is present.
public issetAttr ( string $name ) returns bool;
// Activate or deactivate dependence for the next query.
public setActiveDependence ( string $alias, [ bool $isActive = true ] ) returns mixed;
// Sets attribute.
public setAttr ( string $name, mixed $value ) returns AMI_ModTable;
// Sets table dependences (from other table models for JOIN SQL part).
public setDependence ( string $modId, string $alias, string $condition, [ string $joinType = 'INNER JOIN' ] ) returns void;
// Deinitialize extensions.
protected cleanupExtensions ( ) returns void;
// Returns module id.
protected getModId ( ) returns string;
// Sets passed attributes.
protected initAttributes ( $aAttributes ) returns void;
// Initialize extensions for model.
protected initExtensions ( ) returns void;
// Set pair tableName => moduleId to registry variable tableBlockNames. Used for cache expiring.
protected storeTableBlockName ( ) returns void;
}

• Class Details

Module table models have high abstraction level, modules ids are obtained from resource ids or class names by default.

Since 6.0.2 you can pass following attributes to model constructor:
  • extModeOnConstruct:
  • - 'common' - initialize extensions using current module option),
  • - 'none' (by default),
  • - 'all' - initialize all supported extensions;
  • extModeOnDestruct:
  • - 'none' - do not cleanup extension handlers (by default);
  • - 'cleanup' - cleanup all extension handlers.
  • doRemapListItems (since 6.0.4):
  • - FALSE (by default) - fast items loading, no fields remapping, no using fields callbacks
  • - TRUE - load fields with remapping and using fields callbacks

• Class Properies

protected static array $extInitialized

Flag specifying extensions are initialized already

protected array $aAttributes

Attributes

protected string $tableName

Database table name, must be declared in child classes

• Class Methods

// Constructor.
public __construct ( [ $aAttributes = array() ] ) returns AMI_ModTable;
  • array $aAttributes
    Attributes of table model (since 6.0.2)
// Destructor.
public __destruct ( ) returns void;
Tags:
see self::cleanupExtensions()
since 6.0.2
// Returns item model object and add new data without saving.
public add ( [ $aData = array() ] ) returns AMI_ModTableItem;
  • array $aData
    Array with item data to be stored
// Adds validators array for fields.
public addValidators ( $aValidators ) returns AMI_ModTable;
  • array $aValidators
    Array of validators in format 'aField' => array('validator1', 'validator2', ...)
Model automatically validates fields in terms of database fields description for following types:
'int', 'float', 'double',
'char', 'varchar',
'tinytext', 'text', 'mediumtext',
'tinyblob', 'blob', 'mediumblob',
'datetime', 'date', 'time'.

There are predifined system validators, other validators are custom and can be descibe by developers:
  • 'required' means that field must be declared in model;
  • 'filled' means that field must be declared in model and not equal to the empty string.
Example:
  •  class DemoModule_Table extends AMI_ModTable{
  •  }
  •  
  •  class DemoModule_TableItem extends AMI_ModTableItem{
  •      public function __construct(AMI_ModTable $oTableDB_Query $oQuery null){
  •          parent::__construct($oTable$oQuery);
  •          $this->oTable->addValidators(
  •              array(
  •                  'header' => array('filled''virtual_field_presence'),
  •                  'body'   => array('required')
  •              )
  •          );
  •          // Custom validator handler
  •          AMI_Event::addHandler('on_save_validate_{virtual_field_presence}'array($this'validateVirtualFieldPresence')$this->getModId());
  •      }
  •  
  •      // $aEvent is array containing following data:
  •      // - 'field' - field name,
  •      // - 'value' - field value,
  •      // - 'oItem' - AMI_ModTableItem object
  •      // - 'oTable' - AMI_ModTable object
  •      // - 'oTableItemModifier' - AMI_ModTableItemModifier object
  •      // );
  •      public function validateVirtualFieldPresence($namearray $aEvent$handlerModId$srcModId){
  •          if(!isset($aEvent['oItem']->virtual_field)){
  •              $aEvent['message''Missing `virtual_field` when `header` field is present';
  •          }
  •          return $aEvent;
  •      }
  •  }
  •  
  •  $modId 'demo_module';
  •      array(
  •          $modId '/table/model'      => 'DemoModule_Table',
  •          $modId '/table/model/item' => 'DemoModule_TableItem'
  •      )
  •  );
  •  
  •  $oItem AMI::getResourceModel($modId '/table')->$oTable->getItem();
  •  try{
  •      $oItem->save();
  •      $oResponse->write('Item is saved successfully');
  •      $oResponse->write('Item is not saved, validation failed');
  •      d::vd($e->getData());
  •  }
// Drops attribute.
public dropAttr ( string $name ) returns AMI_ModTable;
  • string $name
    Attribute name
Tags:
since 6.0.2
// Exludes fields not from available list.
public filterFields ( $aFields ) returns array;
  • array $aFields
    Fields
// Returns item model object and load data for key field param.
public find ( int $id, [ $aFields = array('*') ] ) returns AMI_ModTableItem;
  • int $id
    Primary key value
  • array $aFields
    Fiedls to load (since 5.12.8)

Implementation of: AMI_iModTable::find().

Tags:
see AMI_ModTableItem::addFields() for $aFields parameter explanation
// Returns item model object and load data for non-primary key field.
public findByFields ( $aSearchCondition, [ $aFields = array('*') ] ) returns AMI_ModTableItem;
  • array $aSearchCondition
    Filter array key => value
  • array $aFields
    Fiedls to load (since 5.12.8)

Implementation of: AMI_iModTable::findByFields().

// Returns attribute.
public getAttr ( string $name, [ mixed $defaultValue = null ] ) returns mixed;
  • string $name
    Attribute name
  • mixed $defaultValue
    Default value to return
Tags:
since 6.0.2
// Returns array of available fields.
public getAvailableFields ( [ bool $bAppendEventFields = true ] ) returns array;
  • bool $bAppendEventFields
    Fire 'on_get_available_fields' event to append extension fields

Implementation of: AMI_iModTable::getAvailableFields().

Overridden in child classes as: AmiUsers_Users_Table::getAvailableFields().

Dependend model fields returns model alias as index and array of its fields as value.

  Example:

will contain:
 array(
     0 => 'announce',
     1 => 'body',
     ....
     'cat' => array(
          0 => 'id',
          1 => 'header',
          ...
     )
Common possible fields description:
  • id - item identifier (int),
  • public - flag specifying front-side item displaying (0/1),
  • header - item header (string),
  • announce - short item description (string),
  • body - full item description (string),
  • lang - item locale (string, 2-3 chars),
  • date_created - item creation date,
  • date_modified - item modification date,
  • sublink - part of front-side item link (string),
  • id_page - front-side page id, used for multipage modules (int),
  • id_owner - owner user id (int),
  • position - item position, used in lists when ordering by position (int),
  • details_noindex - forbid page indexing for search engines (0/1),
  • hide_in_list - do not display item in lists on front-side (0/1),
  • sticky - flag specifying if item is sticky for lists on front-side (0/1),
  • date_sticky_till - date when sticky flag will be reset (string, datetime),
  • html_title - HTML meta title (string),
  • html_keywords - Comma separated HTML meta keywords (string),
  • html_description - HTML meta description (string),
  • html_is_kw_manual - are HTML meta fields filled manually(0/1), since 5.12.8,
Common Images extension fields description (will be able if Images extension is turned on for module):
  • ext_img - item image (string),
  • ext_img_small - item small image (string),
  • ext_img_popup - item popup image (string).
To override options for image autogeneration system functionality,
you can specify following Images extension options in fast environment context.
These options can be changed from module options interface at "Extension Images" section.

Usage example:
  •  $modId 'news';
  •  // Images that can be resize automatically
  •  AMI::setOption($modId'generate_pictures'array('picture''popup_picture''small_picture'));
  •  // Default preference image
  •  AMI::setOption($modId'prior_source_picture''popup_picture');
  •  // Resized image maximum width
  •  AMI::setOption($modId'picture_maxwidth'300);
  •  // Resized image maximum height
  •  AMI::setOption($modId'picture_maxheight'300);
  •  // Small image maximum width
  •  AMI::setOption($modId'small_picture_maxwidth'80);
  •  // Small image maximum height
  •  AMI::setOption($modId'small_picture_maxheight'80);
  •  // Popup image maximum width
  •  AMI::setOption($modId'popup_picture_maxwidth'800);
  •  //  Popup image maximum height
  •  AMI::setOption($modId'popup_picture_maxheight'600);
  •  // Enlarge image from original if required
  •  AMI::setOption($modId'generate_bigger_image'true);

Common Ratings extension fields description:
  • ext_rate_opt - item rating options,
  • ext_rate_count - item votes count,
  • ext_rate_rate - item rating.
Common Tags extension fields description:
  • ext_tags - tags identifiers (comma-separated integers),
Common Discussion extension fields description:
  • ext_dsc_disable - disable item discussion possibility
Attention! Following fields can be available in case of Categories extension activity.
Common Categories extension fields description (array key will be category model alias, cat as usual).
  • id - item category identifier (int),
  • header - item category header (string),
  • sublink - part of front-side item category link (string).
Tags:
todo Move extension fields description to appropriate classes
todo Reset $this->aHTMLFields for cms_pages, it has these fields
// Returns dependence resource name.
public getDependenceResId ( string $alias ) returns string|null;
  • string $alias
    Required alias of a dependence
// Returns real field name by its alias.
public getFieldName ( string $alias, [ string $prefix = '' ] ) returns string;
  • string $alias
    Alias
  • string $prefix
    Prefix
See PlgAJAXResp::__construct() for usage example.
Tags:
deprecated After db field names standardization this method will became useless.
// Called when receive array of validators, allow add own validators.
public getItem ( [ mixed $type = '' ] ) returns void;

Implementation of: AMI_iModTable::getItem().

// Returns list model object.
public getList ( [ string $type = '' ] ) returns AMI_ModTableList;
  • string $type
    Postfix for 'on_query_add_joined_columns' event

Implementation of: AMI_iModTable::getList().

// Returns next primary key field value.
public getNextPKValue ( ) returns int|null;
Tags:
since 5.14.0
// Event, called for add columns to the query result, a compound derived from the dependent model.
public getQueryBase ( [ mixed $type = '' ], [ mixed $bJoinDependentTables = true ] ) returns void;
// Returns database table name.
public getTableName ( ) returns string;
// Checks if model has a field.
public hasField ( string $name, [ bool $bAppendEventFields = false ] ) returns bool;
  • string $name
    Field name in table
  • bool $bAppendEventFields
    Fire 'on_get_available_fields' event to append extension fields

Implementation of: AMI_iModTable::hasField().

See PlgAJAXResp::initModel() for usage example.
Tags:
todo Reset $this->aHTMLFields for cms_pages, it has these fields.
// Returns TRUE if attribute is present.
public issetAttr ( string $name ) returns bool;
  • string $name
    Attribute name
Tags:
since 6.0.2
// Activate or deactivate dependence for the next query.
public setActiveDependence ( string $alias, [ bool $isActive = true ] ) returns mixed;
  • string $alias
    Table model alias (see setDependence)
  • bool $isActive
    Is dependant mode active
// Sets attribute.
public setAttr ( string $name, mixed $value ) returns AMI_ModTable;
  • string $name
    Attribute name
  • mixed $value
    Attribute value
Tags:
since 6.0.2
// Sets table dependences (from other table models for JOIN SQL part).
public setDependence ( string $modId, string $alias, string $condition, [ string $joinType = 'INNER JOIN' ] ) returns void;
  • string $modId
    Module id
  • string $alias
    Joined table alias
  • string $condition
    Join condition (ON)
  • string $joinType
    Type of join, INNER JOIN by default
Since 5.12.8 this method scope is changed from protected to public.

Example:
  •  class Articles_Table extends AMI_ModTable{
  •      protected $tableName 'cms_articles';
  •  
  •      public function __construct(array $aAttributes array()){
  •          $this->setDependence('articles_cat''cat''cat.id=i.id_cat');
  •  ...
// Deinitialize extensions.
protected cleanupExtensions ( ) returns void;
Tags:
since 6.0.2
// Returns module id.
protected getModId ( ) returns string;
// Sets passed attributes.
protected initAttributes ( $aAttributes ) returns void;
  • array $aAttributes
    Attributes
Tags:
since 6.0.2
// Initialize extensions for model.
protected initExtensions ( ) returns void;
Tags:
since 6.0.2
// Set pair tableName => moduleId to registry variable tableBlockNames. Used for cache expiring.
protected storeTableBlockName ( ) returns void;