Создание полей Часть 1

##Введение.

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

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

Во всех примерах будет рассматриваться создание поля с именем simpletext_ с добавлением суффикса, соответствующего уровню установленного функционала.

Планируемые статьи:

Часть 1. Основы и базовые функции.

Основные принципы создания полей. Создание простого текстового поля с минимально необходимым функционалом (ввод, вывод, возможность полнотекстового поиска) simpletext_base.

Часть 2. Фильтрация и сортировка.

Основные принципы построения полей с возможностью фильтрации и сортировки. Создание простого текстового поля с возможностью фильтрации и сортировки simpletext_filtration.

Часть 3. Валидация.

Основные принципы построения проверки поля. Создание простого текстового поля с проверкой посредством JavaScript simpletext_validation.

Часть 4. Языковые пакеты.

Способы создания языковых пакетов. Создание языковых пакетов для русского и английского языков, поле simpletext_multilanguage.

Часть 5. Импорт и экспорт.

Поле simpletext_import.

Часть 6. Использование AJAX и MVC.

У полей Кобальт есть специальный интерфейс когда вы можете нарисовать страницу при помощи метода поля, или вызвать аякс через метод поля.

Часть 7. Установочный пакет.

Основные принципы создания установочных пакетов Joomla. Создания поля с возможностью инсталляции стандартным установщиком Joomla simpletext_installation.

##Основные принципы построения полей.

Все поля CCK Cobalt хранятся в папке components/com_cobalt/fields. Каждое поле хранится в собственной папке. Имя папки должно быть одинаковым с именем поля и состоять только из латинских букв в нижнем регистре.

Таким образом, все файлы поля simpletext_base должны находиться в папке components/com_cobalt/fields/simpletext_base.

Для обеспечения базового функционала папка components/com_cobalt/fields/simpletext_base обязательно должна содержать следующие файлы:

simpletext_base.xml - .xml файл, содержит метаданные и параметры поля.
simpletext_base.php - .php файл, содержит главный класс поля. Осуществляет обработку метаданных и параметров поля из файла .xml посредством предопределенных методов класса. Иными словами, методы класса поля обрабатывают логику работы поля и подготавливают набор необходимых переменных для работы шаблонов поля. Рекомендуется всю “логику” поля включать в методы класса поля, а HTML код поля- в файлы шаблонов.
/tmpl/input/default.php - файл шаблона по умолчанию для формы ввода.
/tmpl/output/default.php - файл шаблона по умолчанию для формы вывода в списке статей или в полном виде статьи.
simpletext_base.png - файл иконки поля размером 16x16 px. Обычно мы используем иконки из набора Fugue Icons, но Вы можете использовать любые иконки размером 16x16 px. Этот файл не является обязательным. Если его нет, по умолчанию будет показана иконка text.png.

Файл simpletext_base.xml

Содержит метаданные и параметры шаблонов поля.

Структура файла должна быть следующей.

<?xml version="1.0" encoding="utf-8"?>
<cobaltfield>
	<name>Simple Test</name>
	<group>Simple From Element</group>

	<config>
		<fields name="params">
			<fieldset name="tmpl">
				
			</fieldset>
		</fields>
	</config>
</cobaltfield>

Файл содержит 3 основных раздела, определяемых тэгами верхнего уровня: <name>, <group>, <config>.

Раздел `<name>`

Определяет имя поля. Это имя будет показываться в выпадающем списке выбора типа поля на форме создания или редактирования поля.

Раздел `<group>`

Определяет группу полей, к которой будет принадлежать поле.

Все поля объединяются в группы на основании содержания этого тэга.

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

Если необходимо создать свою группу полей, достаточно просто поместить название этой группы внутри тэга <group>...</group>. Никаких дополнительных действий не требуется, Cobalt автоматически создаст эту группу.

Предопределенные группы полей CCK Cobalt.

Имя группы	Описание
Simple Form Elements	Простые поля типа text, checkbox, radio, select и пр.
Special Form Elements	Поля для вывода данных в специальном формате типа telephone, url и пр.
Media Form Elements	Поля для работы с медиа контекстом типа gallery, image, video, audio, uploads и пр.
Commerce Form Elements	Поля для электронной коммерции, работа этих полей основана на SSI
Exclusive Form Elements	Различные эксклюзивные поля.
Relation Form Elements	Поля для создания связей между элементами контекста и отображающие списки связанных элементов.

Раздел `<config>`

Определяет параметры поля.

Структура раздела <config> должна быть следующей

<config>
	<fields name="params">
		<fieldset name="general" label="ST_LABEL1">
			<field name="param1" type="text" label="ST_PARAM1" />
		</fieldset>
		<fieldset name="playerlist" label="ST_LABEL2">
			<field name="param2" type="text" label="ST_PARAM2" />
		</fieldset>
	</fields>
</config>

Таким образом, раздел <config> состоит из наборов групп полей, ограниченных тэгами <fieldset>...</fieldset> и наборов полей внутри тэга <field>...</field> с обязательным атрибутом name="params".

Количество наборов групп полей и количество полей внутри каждой группы не ограничено. Естественно, имена групп полей и самих полей должны быть уникальными.

Существует 3 предопределенные группы полей, которые используются ядром Cobalt: tmpl, core и filter.

Группа полей `tmpl`

Добавляет обязательные настройки месторасположение шаблонов поля.

<fieldset name="tmpl">
	<field type="filelist" name="template_input" filter="php$" hide_none="1" hide_default="1" directory="/components/com_cobalt/fields/simpletext_base/tmpl/input" label="F_TMPLINPUT" default="default.php" />
	<field type="filelist" name="template_output_list" filter="php$" hide_none="1" hide_default="1" directory="/components/com_cobalt/fields/simpletext_base/tmpl/output" label="F_TMPLLIST" default="default.php" />
	<field type="filelist" name="template_output_full" filter="php$" hide_none="1" hide_default="1" directory="/components/com_cobalt/fields/simpletext_base/tmpl/output" label="F_TMPLFULL" default="default.php" />
</fieldset>

где

type="filelist" - тип параметра, в данном случае- список файлов;
name="template_input" - имя параметра;
filters="php$" - фильтр типа файла, в данном случае- только файлы с расширением .php;
hide_none="1" - прячет в списке файлов возможность не выбрать ни одного файла или выбрать пустое значение.
hide_default="1" - прячет возможность выбора значения по умолчанию. Такой параметр применим только если он наследует данные от других параметров.
directory="/components/com_cobalt/fields/simpletext_base/tmpl/input" - месторасположение файла шаблона;
label="F_TMPLINPUT" - языковая константа ярлыка параметра;
default="default.php" - имя файла шаблона по умолчанию;

Первая строка определяет местоположение шаблона формы ввода поля.

Вторая строка определяет местоположение шаблона формы вывода поля в списке статей.

Третья строка определяет местоположение шаблона формы вывода поля в полном виде статьи.

Группы полей core и filter будут рассмотрены в последующих разделах.

Остальные группы параметров можно добавлять по Вашей необходимости.

Файл simpletext_base.php

В данном файле должен находиться программный код класса поля, который (при необходимости) будет переопределять родительский класс CFormField. Родительский класс CFormField находится в файле /components/com_cobalt/library/php/fields/cobaltfield.php и содержит полный набор системных предопределенных методов, необходимых для работы поля.

Вызов системных предопределенных методов производится неявно ядром Cobalt в момент возникновения какого-либо программного события, например, ввод или вывод значения поля. В этот момент ядро Cobalt передает в предопределенный метод фактические значения параметров. В теле метода переданные параметры могут использоваться для обработки или изменения действий ядра при возникновении этого программного события. Это означает, что изменение (переопределение) предопределенных методов необходимо только если Вы хотите изменить действия ядра Cobalt при определенном событии.

Для каждого предопределенного метода зарезервированы название и синтаксис.

Программный код класса поля должен начинаться со следующего блока кода

<?php
defined('_JEXEC') or die;
require_once JPATH_ROOT.'/components/com_cobalt/library/php/fields/cobaltfield.php';
class JFormFieldCSimpletext_base extends CFormField
{
	[здесь должны располагаться методы класса поля]
}

Название класса должно быть JFormFieldCSimpletext_base, где JFormFieldC есть обязательный префикс имени класса, а Simpletext_base есть имя поля, начинающееся с большой буквы.

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

Метод	Краткое описание
onRenderList()	Выводит значение поля в списке статей.
onRenderFull()	Выводит значение поля в полном виде статьи.
getInput()	Выводит форму ввода поля.
onPrepareSave()	Сохраняет значение поля в базе данных.
onPrepareFullTextSearch()	Сохраняет значение поля для полнотекстового поиска.

Предопределенные функции родительского класса поля предназначены, в основном, для подготовки необходимых переменных для шаблонов поля. В шаблоне поля эти переменные можно получить через $this. Т.е. рекомендуется всю “логику” работы поля включать в методы класса поля, а HTML код поля- в файлы шаблонов.

метод onRenderList()

Выводит поле в списке статей через шаблон в fields/simpletext_base/tmpl/output/[filename].php. Файл шаблона выбирается в настройках поля (через параметр template_output_list).

Код метода по умолчанию:

public function onRenderList($record, $type, $section)
{
	[код пользователя]
	return $this->_display_output('list', $record, $type, $section);
} где `$record`- объект текущей записи `$type`- объект типа контента статьи `$section`- объект текущей секции

метод onRenderFull()

Выводит поле в полном виде статьи через шаблон в fields/simpletext_base/tmpl/output/[filename].php. Файл шаблона выбирается в настройках поля (через параметр template_output_full).

Код метода по умолчанию:

public function onRenderFull($record, $type, $section)
{
	[код пользователя]
	return $this->_display_output('full', $record, $type, $section);
}

Метод, аналогичный методу onRenderList.

метод getInput()

Выводит форму ввода поля через шаблон в fields/simpletext_base/tmpl/input/[filename].php. Файл шаблона выбирается в настройках поля (через параметр template_input).

Код метода по умолчанию:

public function getInput()
{
	[код пользователя]
	return $this->_display_input();
}

Перед return $this->_display_input(); можно поставить свой фрагмент кода и установить необходимые переменные в $this. Потом к этим переменным можно будет иметь доступ в файле шаблона.

метод onPrepareSave()

Сохраняет значение поля в базе данных.

Код метода по умолчанию:

public function onPrepareSave($value, $record, $type, $section)
{
	[код пользователя]
	return $value;
}

Переменная $value может быть строкой или массивом данных. Вы можете вернуть или строку или массив данных. Нет необходимости его сериализовать. Это будет сделано автоматически. Вернете массив то и получите массив. Вернете строку то и получите строку в $this->value.

В дальнейшем значение поля можно получить в любом другом методе, например onRenderList или onRenderFull, в переменной $this->value.

метод onPrepareFullTextSearch()

Сохраняет значение поля для полнотекстового поиска.

Код метода по умолчанию:

public function onPrepareFullTextSearch($value, $record, $type, $section)
{
	[код пользователя]	
	return $value;
}

Должен возвращать всегда только строку или одноуровневый массив, в котором каждое значение массива является строкой.

Файл шаблона вывода поля (output)

Предназначен для вывода поля на форме и, как указывалось выше, находится в папке fields/simpletext_base/tmpl/output/[filename].php.

По умолчанию для вывода поля в списке статей и в полном виде статьи используется одинаковый шаблон.

Код шаблона по умолчанию

<?php defined('_JEXEC') or die(); ?>
[код пользователя]
<?php echo $this->value;?>

Т.е. по умолчанию шаблон вывода просто выводит переменную $this->value;. Это конечно сработает если значение строковое.

Необходимо помнить, что в некоторых типах полей переменная $this->value может быть массивом (если Вы используете массив для ввода значений этого поля).

Параметры поля в файлах шаблонов доступны через

$this->params->get('params.parameter_name', 'default_value');

где

parameter_name - имя параметра
default_value - значение параметра по умолчанию

Например, в шаблон формы вывода поля по умолчанию в полном виде статьи tmpl/output/default.php можно добавить следующий фрагмент кода

<span><?php echo $this->values ?></span>

Файл шаблона ввода поля (input)

Предназначен для ввода поля на форме и, как указывалось выше, находится в папке fields/simpletext_base/tmpl/input/[filename].php.

Код шаблона по умолчанию

<?php defined('_JEXEC') or die(); ?>
[код пользователя]
<input type="text" placeholder="" name="jform[fields][<?php echo $this->id;?>]" id="field_<?php echo $this->id;?>" value="<?php echo htmlspecialchars($this->value, ENT_COMPAT, 'UTF-8');?>">

Обратите внимание на параметр name. Он обязательно должен начинаться с jform[fields][<?php echo $this->id;?>].

Если в поле необходимо иметь несколько элементов input, можно создать массив jform[fields][<?php echo $this->id;?>][] или массив с ключом jform[fields][<?php echo $this->id;?>][name] (для информации, ключи хранятся в столбце index таблицы js_res_record_values базы данных). Как это можно использовать для фильтрации, будет объяснено позже.

На примере функции вывода значения поля в списке статей можно кратко описать взаимосвязь всех вышеописанных элементов следующим образом:

Ядро Cobalt вызывает метод onRenderList() класса поля.
Метод onRenderList():
- получает необходимые параметры из simpletext_base.xml через $this->params->get()
- обрабатывает полученные параметры и формирует необходимые переменные для шаблона вывода
- сохраняет эти переменные в $this
- вызывает шаблон поля, который определен в параметре template_output_list файла simpletext_base.xml.
Шаблон поля:
- получает необходимые параметры из simpletext_base.xml через $this->params->get()
- получает необходимые переменные через $this
- на основании полученных параметров и переменных строит шаблон поля с помощью HTML кода
- выводит значение поля на форме.

Установочный пакет поля Simple Text Base находится в прикрепленном файле по ссылке.

Search Documentation

Создание полей Часть 1 - Основа

Файл simpletext_base.xml

Раздел `<name>`

Раздел `<group>`

Раздел `<config>`

Группа полей `tmpl`

Файл simpletext_base.php

метод onRenderList()

метод onRenderFull()

метод getInput()

метод onPrepareSave()

метод onPrepareFullTextSearch()

Файл шаблона вывода поля (output)

Файл шаблона ввода поля (input)

Разное

Поля

Шаблоны

Файл simpletext_base.xml

Раздел <name>

Раздел <group>

Раздел <config>

Группа полей tmpl

Файл simpletext_base.php

метод onRenderList()

метод onRenderFull()

метод getInput()

метод onPrepareSave()

метод onPrepareFullTextSearch()

Файл шаблона вывода поля (output)

Файл шаблона ввода поля (input)

Разное

Поля

Шаблоны

Раздел `<name>`

Раздел `<group>`

Раздел `<config>`

Группа полей `tmpl`