Файл и класс поля

Поле формы в InstantCMS это класс, унаследованный от системного класса cmsFormField, который находится по пути /system/core/formfield.php. Поля могут, как подключаться в админке, например в типах контента, так и инициализироваться в вашем PHP коде.

Размещение

Файл класса поля размещается в системной папке fields /system/fields/{название поля}.php

Пример: /system/fields/myfield.php

Название класса поля

В файле должен быть определен класс поля название которого должно быть сформировано по принципу: field{Name}, где {Name} - название поля. Название поля совпадает с названием файла, таким образом, учитывая пример выше, класс должен называться fieldMyfield.

Название поля (файла) может состоять из нескольких слов, разделенных знаком подчеркивания (_). В этом случае название метода формируется по принципу: field{ManyWordsName}. Каждая заглавная буква в {ManyWordsName} соответствует знаку подчеркивания в названии поля.

Класс должен наследоваться от системного класса cmsFormField

Пример

<?php
 
class fieldMyfield extends cmsFormField {
 
}

Свойства класса

Название	Описание
`$name`	Имя поля в форме. Определяется автоматически при инициализации объекта поля.
`$title`	Название поля. Используется при создании поля в админке.
`$is_public`	Флаг, указывающий, что поле может быть использовано для создания в полях типов контента, конструкторе форм и т.п. Может принимать true или false, по умолчанию true.
`$is_virtual`	Флаг, указывающий, что при создании данного поля в админке (в типах контента например) движок не будет создавать соответствующее поле в таблице базы данных. Это полезно, если ваше поле не предполагает хранить данные, а предназначено выводить некие данные в зависимости от контекста использования. Может принимать true или false, по умолчанию false.
`$sql`	Последняя часть строки SQL запроса для создания поля в базе данных. Например, поле создаётся командой ALTER TABLE `cms_widgets_pages` ADD `groups` TEXT NULL DEFAULT NULL , тогда эта переменная должна содержать `TEXT NULL DEFAULT NULL`. Это свойство необходимо только в том случае, если поле доступно для создания в типах контента, т.е. предыдущее свойство `$is_public` установлено в true.
`$cache_sql`	Последняя часть строки SQL запроса для создания поля в базе данных, в котором будет храниться кэшированное значение. Например, у нас есть поле в CMS - «Местоположение». В базу данных записываются числовые значения города, страны, региона. По этим числовым значениям быстро и удобно работает поиск данных. Но когда нам нужно вывести, например в списке записей, названия «Страна - регион - город», нужно будет для каждой записи списка сделать дополнительно три запроса SQL, что скажется на производительности не лучшим образом. Поэтому, для таких случаев создаются поля кэширования (денормализация), в которые и пишутся уже текстовые значения. Данное свойство используется совместно с включенным свойством`$is_denormalization`, см. ниже.
`$is_denormalization`	Флаг, указывающий, что нам нужна денормализация данных, полученных из поля формы. По умолчанию false.
`$allow_index`	Флаг, указывающий, что при создании поля в базе данных (например, при добавлении поля в типах контента) необходимо также добавить SQL индекс к этому полю. Если в вашем поле индекс необходим, а также тип поля не `TEXT` то свойство должно быть установлено в true (это значение по умолчанию). Важно! Если индекс не нужен, то установите значение этого свойства в false.
`$var_type`	Устанавливается тип получаемой переменной из поля. Переменная, полученная с этого поля будет принудительно приведена к указанному типу. Возможные значения: boolean, integer, double, string, array, object, resource. Если данное свойство не задано, то тип входящих данных определяется из значения по умолчанию, заданного для поля при его инициализации. Крайне рекомендуем задать это свойство, с типа входных данных начинается безопасность.
`$filter_type`	Свойство определяется, если ваше поле должно быть доступно в фильтре записей типа контента на сайте. Установите свойство в true, если ваше поле может быть в фильтре. Также вы можете уточнить тип фильтрации: int, str или date. В этом случае в простых фильтрах в админке поле также будет присутствовать. Свойство не влияет на валидацию данных и приведение к типу.
`$filter_hint`	Краткое описания поля фильтрации для простых фильтров в админке (фильтр записей типов контента или фильтр пользователей в админке). Используется, если предыдущее свойство `$filter_type` задано в int, str или date.
`$field_id`	ID поля, если запись о нём есть в таблице. Свойство актуально для полей, создающихся в админке, например в типах контента, в профилях или в группах (сообществах).

Языковые константы

Языковые константы определяются в файле /system/languages/{ВАШ_ЯЗЫК}/language.php и имеют вид LANG_PARSER_{FIELD}_{NAME}. Или должен быть создан языковой файл для Вашего поля по пути /system/languages/field_{название_поля}.php.

Методы и их назначение

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

Название	Параметры	Описание
`getInput`	`$value` (значение поля)	Возвращает HTML код поля для формы. Шаблон поля должен быть расположен по пути `/templates/{название_шаблона}/assets/fields/{fieldname}.tpl.php`, где {fieldname} - название поля без нижних подчеркиваний. Если вам нужно изменить поведение этого метода, переопределите его в своем класса поля.
`getFilterInput`	`$value` (значение поля)	Возвращает HTML код поля для панели поиска. Вызывает метод `getInput`, предварительно убирая флаг «это обязательное поле для заполнения». Если в вашем поле планируется иная логика поля в фильтре, переопределите этот метод, иначе определять в своём классе поля этот метод не нужно.
`parse`	`$value` (значение поля)	Возвращает отформатированное значение поля для показа в записи (HTML код или любую другую строку). Внимание! Этот метод должен быть определён в вашем классе, если поле должно выводить значение в записи.
`parseTeaser`	`$value` (значение поля)	Возвращает отформатированное значение поля для показа в списке записей (HTML код или любую другую строку). По умолчанию метод передаёт управление в метод `parse`. Переопределите, если вам нужна другая логика и вывод поля в списке.
`afterParse`	`mixed $value, array $item` (Значение уже отформатированного поля, массив полей записи, с уже обработанными данными)	Выполняет некие действия после отработки метода parse для всех полей одной записи.
`getStringValue`	`$value` (значение поля)	Если значение вашего поля предполагает тип, отличный типа «string» или же значение поля формируется как некий HTML код, то этот метод должен вернуть как минимум строковое представление значения. По умолчанию метод передаёт управление в метод `parse`. Метод используется при автоматическом формировании SEO параметров по шаблонам: slug (URL страницы), title, keywords, description.
`store`	`mixed $value , boolean $is_submitted [, mixed $old_value ]`	Метод, который подготавливает входную переменную из поля для записи в базу данных. В нём вы можете выполнять все необходимые действия с данными, полученными из поля формы. Возвращать метод должен переменную типа string или array, при этом, если возвращается массив, то при добавлении в базу движок автоматически преобразует его в YAML строку. По умолчанию метод возвращает переменную `$value` без изменений.
`storeFilter`	`mixed $value`	Подготавливает входную переменную из поля формы фильтра.
`afterStore`	`array $item , object $model , string $action`	Метод вызывается после сохранения записей типов контента, профилей и групп. В метод передаются: полный массив записи, объект модели контроллера контекста работы и действие - add или edit.
`storeCachedValue`	`$value` (значение поля)	Метод, аналогичный предыдущему, но должен вернуть строку, которая будет использоваться для денормализации значения. Переопределяться должен только в том случае, если для поля свойство `$is_denormalization` установлено в true. Например, в поле «Местоположение» в базу данных записывается id страны (региона, города) и само название страны (региона, города).
`delete`	`$value` (значение поля)	Метод, который вызывается при удалении записи в типах контента. `$value` - это текущее значение данного поля. В методе должны выполняться некие действия по удалению неких данных поля, кроме очистки самого значения в базе данных. Например, в поле «Изображения» этот метод удаляет файлы изображений.
`applyFilter`	`$model` (Объект модели из контекста вызова), `$value` (Значение поля)	Метод, который вызывается при применении фильтра списка записей, например, при работе фильтра списка записей типов контента, списка пользователей, групп. В метод первым параметром передаётся объект модели `$model` текущего контекста работы. Например, при применении фильтра записей типов контента `$model` - это объект модели контроллера content. Вторым параметром передаётся значение для этого поля, пришедшее из формы фильтра. В методе вы должны реализовать нужную фильтрацию для этого поля, пользуясь объектом модели и значением из формы. Вернуть метод должен объект модели `$model`.
`getRules`	–	Метод возвращает массив правил валидации для поля. Если ваше поле предполагает какие-либо однозначные правила валидации (например в значении поля могут быть только числа), то переопределите этот метод. В этом случае вы должны дополнить свойство $rules объекта класса своими правилами и вернуть массив. Например: public function getRules() { $this->rules[] = array('number'); return $this->rules; }
`hookAfterAdd`	`string $content_table_name , array $field , object $model`	Метод вызывается после создания поля в админке, например в типах контента, профилях или группах. В метод передаются соответственно: название таблицы, для которой поле создаётся, массив данных поля и объект модели контроллера контекста работы.
`hookAfterUpdate`	`string $content_table_name , array $field , array $field_old , object $model`	Метод вызывается после редактирования поля в админке, например в типах контента, профилях или группах. В метод передаются соответственно: название таблицы, для которой поле создаётся, новый массив данных поля, старый (до редактирования) массив данных поля и объект модели контроллера контекста работы.
`hookAfterRemove`	`string $content_table_name , array $field , object $model`	Метод вызывается после удаления поля в админке, например в типах контента, профилях или группах. В метод передаются соответственно: название таблицы, для которой поле было создано, массив данных поля и объект модели контроллера контекста работы.

Вернуться к оглавлению работы с формами