Модели (Model)

    7.1 Модель данных (Table)

Модель предоставляет разработчику интерфейс для доступа к данным. При этом, модель данных не хранит непосредственно данные, этим занимается модель элемента. Но модель данных умеет этими данными управлять. Например, выдавать данные в некотором внешнем формате, а сохранять в удобном внутреннем формате.

Модель данных выполняет следующие роли:

1. Создает модель списка
2. Создает модель элемента
3. Управляет зависимостью моделей (добавление, активация / деактивация)
4. Возвращает информацию о модели (столбцы таблицы базы данных, атрибуты файлов и т.п.)

Следует обратить внимание, что ресурсы моделей списка и элемента можно получить непосредственно из хранилища ресурсов, но верным является получение данных моделей через модель данных.

Пример получения модели данных для модуля новостей:

$oNewsTableModel = AMI::getResourceModel('news/table');

 Результат: экземпляр объекта News_Table

     7.2 Модель списка (TableList)

Модель списка отвечает за получение списка элементов и предоставляет средства для его обхода.

Модель списка не хранит данные, этим занимается модель элемента.

Модель списка выполняет следующие роли:

1. Наложение фильтров на данные
2. Наложение лимитов на количество возвращаемых данных
3. Указание данных, которые необходимо получить

Модель списка используется для загрузки данных списка, который будет передан для отрисовки сущности отображения. Проще всего модель списка понимать, как итератор по данным, возвращающий модели элементов, хранящих данные, или выборку нескольких записей одной таблицы из базы данных.

Пример получения модели списка для модуля новостей:

$oNewsModelList = AMI::getResourceModel('news/table')->getList();

Результат: экземпляр объекта News_TableList

      7.3 Модель элемента (TableItem)

Модель элемента отвечает за хранение данных.

Модель списка выполняет следующие роли:

1. Загрузку данных в класс из хранилища
2. Сохранение данных из класса в хранилище
3. Удаление одного элемента из хранилища
4. Получение свойств(а) загруженного элемента
5. Установка свойств(а) загруженному элемента
6. Установка списка свойств, для которых будет запоминаться исходное состояние и получение изменившихся свойств

Проще всего модель элемента понимать, как одну запись одной таблицы в базе данных.

Пример получения модели элемента для модуля новостей:

$oNewsModelItem = AMI::getResourceModel('news/table')->getItem();

Результат: экземпляр объекта News_TableItem.

Пример задания неквотируемого значения поля:


class AmiSample_TableItemModifier extends AMI_ModTableItemModifier{
    // Добавляем неквотируемое поле `ts`
    public function getDefaultsOnSave($onCreate){
        $aDefaults = parent::getDefaultsOnSave($onCreate);
        $aDefaults['append']['ts'] = DB_Query::getSnippet('%s')->plain('NOW()');
        $aDefaults['overwrite']['ts'] = DB_Query::getSnippet('%s')->plain('NOW()');
        return $aDefaults;
    }
    // ...
}

// ....

$oTableItem = AMI::getResourceModel('ami_sample/table')->getItem();
// Устанавливаем значение
$oTableItem->ts = DB_Query::getSnippet('DATE_ADD(NOW(), INTERVAL 5 day');

       7.4 Зависимость (соединение) моделей (JOIN)

Зависимость моделей — это возможность получения данных из другой модели, связанной с текущей по какому-либо правилу.

Зависимость бывает активной и неактивной. Активная зависимость указывает на то, что при получении списка элементов (одного элемента), необходимо произвести соединение моделей, и вернуть результаты, содержащие данные главной и зависимой моделей. Неактивная зависимость указывает на то, что существует потенциальная возможность соединения моделей. Все зависимости не активны по умолчанию, их необходимо активизировать явным образом.

Проще всего активную зависимость моделей понимать, как соединение двух таблиц в базе данных, а неактивную, как возможность такого соединения.

Пример добавления зависимости моделей (статей и категорий статей) метод setDependence()

class Articles_Table extends AMI_ModTable{
    public function __construct(){
        $this->setDependence('articles_cat', 'cat', 'cat.id=i.id_cat');
...
    }
...
}

Пример активации зависимости моделей статей и категорий статей (только после данной конструкции, будет происходить соединение таблиц) метод setActiveDependence

AMI::getResourceModel('articles/table')->setActiveDependence('cat');

       7.5 Вычисляемые и виртуальные поля

Вычисляемые поля – это механизм преобразования данных из внутреннего формата хранения во внешний формат. Типовой пример вычисляемого поля – «дата создания», которая хранится в БД в mysql формате даты, но выдается моделью наружу в формате, соответствующем текущей локализации.

Виртуальные поля – это поля, которые физически не существуют в БД, как отдельное поле, но возвращаются моделью. Пример виртуального поля – поле «возраст», которое вычисляется «на лету» в зависимости от даты рождения, и которое не нужно сохранять в БД.

Виртуальные поля являются частным видом вычисляемых полей, поэтому далее будет идти речь только о вычисляемых полях.

Для того чтобы обозначить поле, как вычисляемое, в конструкторе модели элемента необходимо вызвать метод setFieldCallback. Пример:

	$this->setFieldCallback('birth', array($this, 'fcbDate'));

Первый параметр – название свойства модели, второй – callback, они начинаются с префикса fcb. Пример использования из документации:

	 // AmiSample_TableItem::__construct()


	$this->setFieldCallback('birth', array($this, 'fcbDate'));

Существует возможность добавления собственных callback-функций. Пример добавления и прототип для собственных callback-функций приведен в описании метода setFieldCallback. Рекомендуется для собственных callback-функций использовать префикс fcb.

       7.6 Валидаторы

Валидатор – это метод проверки корректности данных при сохранении модели элемента. Если хотя бы один из валидаторов данных модели возвращает ошибку, модель элемента не может быть сохранена, в этом случае генерируется исключение (exception) AMI_ModTableItemException

Добавление валидаторов осуществляется посредством вызова метода addValidators. Пример:

         $this->oTable->addValidators(
             array(
                 'header' => array('filled', 'virtual_field_presence'),
                 'body'   => array('required')
             )
         );

Существуют системные валидаторы:

Поля всех групп, кроме обязательных полей, проверяются на значения и длину, соответствующие аналогичным полям в БД mysql.

Валидатор 'required' отличается от 'filled' тем, что 'required' требует наличие поля, а 'filled' требует не только наличие, но и неравенство значения поля пустой строке.

Существует возможность создание собственных валидаторов. Для добавления собственного валидатора, для определенности назовем валидатор virtual_field_presence', необходимо:

1. Добавить созданный валидатор обычным способом посредством вызова addValidators
2. Зарегистрировать обработчик события 'on_save_validate_{virtual_field_presence}'
3. Имплементировать код обработчика события

class DemoModule_TableItem extends AMI_ModTableItem{
     public function __construct(AMI_ModTable $oTable, DB_Query $oQuery = null){
         parent::__construct($oTable, $oQuery);

         // Добавляем валидатор
         $this->oTable->addValidators(
             array(
                 'header' => array('virtual_field_presence'),
             )
         );

         // Обработчик события
         AMI_Event::addHandler('on_save_validate_{virtual_field_presence}', array($this, 'validateVirtualFieldPresence'), $this->getModId());
     }

     public function validateVirtualFieldPresence($name, array $aEvent, $handlerModId, $srcModId){
         // Код валидатора
         return $aEvent;
     }
}

Параметры события $aEvent:

Для того чтобы указать, что валидация не пройдена, необходимо задать непустое значение $aEvent['error_message'].

Валидаторы рекомендуется добавлять в конструкторе модели элемента, т.е. только тогда, когда они действительно могут использоваться.