Содержимое разделов CRM системы описывается в файлах structure.xml. Они находятся в папках config/sections/<Код раздела>. Здесь рассмотрены API этих файлов.
Структура файла
<MENU_TAB>
<TAB
(section_type="common" table="Таблица раздела") | section_type="special"
caption="Название раздела">
Описание раздела
</TAB>
</MENU_TAB>
Все описания помещаются в тег TAB. Тег содержит следующие атрибуты.
- section_type. Определяет тип раздела. Может принимать следующие значения.
common
— стандартный раздел.special
— нестандартный раздел, в этом случае все теги кроме SOURCE игнорируются.
- caption. Название раздела для отображения.
- table. Основная таблица раздела, из которой будут браться данные для отображения.
Описание раздела
section_type=“common”
<GRID
[name="Код таблицы"]
[lines_count="Количество строк в таблице"]
[display_search="no"]
[hide_buttons="yes|no"]
[disable_dblclick="no"]
[ondblclick=""]
[is_editable="yes"]
[is_have_pages="no"]
[js_source_file="Файл со скриптом Javascript."
[js_function="Функция-обработчик инициализации таблицы."]
[after_grid_modify="Функция-обработчик события после изменения записи."]
[after_delete_record="Функция-обработчик события после удаления записи."]
[js_path="full"]]
[php_source_file="файл со скриптом PHP."
[php_on_prepare="Функция-обработчик события перед рисованием таблицы на сервере."]]
[php_replace_script="PHP скрипт для переопределения прорисовки таблицы."
php_replace_function="Функция для прорисовки таблицы."]
[sort_column="Порядковый номер колонки для сортировки."]
[sort_direction="asc|desc"]>
<COLUMNS>
{Описание колонки}
</COLUMNS>
<FILTERS [overall="Условие, которое применяется всегда. В версии 4.0.08+."]>
{Описание фильтра}
</FILTERS>
</GRID>
<GRID_WND
Атрибуты, аналогичные атрибутам GRID плюс следующие атрибуты:
caption="Заголовок окна"
width="Ширина окна"
height="Высота окна">
<COLUMNS>
{Описание колонки}
</COLUMNS>
</GRID_WND>
<EDITCARD
[name="Код карточки"]
caption="Заголовок карточки"
width="Ширина карточки"
height="Высота карточки"
layout="Расположение элементов"
[draw_extra_button="yes"]
[show_card_top_panel="yes|no"]
[show_card_details="yes|no"]
[js_source_file="Файл со скриптом Javascript."
[js_function="Функция-обработчик инициализации карточки."]
[on_after_save="Функция-обработчик события после изменения записи."]
[js_path="full"]]
[php_source_file="файл со скриптом PHP."
[php_on_prepare="Функция-обработчик события перед рисованием карточки на сервере."]
[php_on_before_post="Функция-обработчик события перед сохранением карточки на сервере."]
[php_on_after_post="Функция-обработчик события после сохранения карточки на сервере."]]
[parent_card_source="grid"
parent_card_name="Код раздела с описанием карточки."]>
[<TABS>
<TAB
caption="Название закладки"
rows="Количество строк на закладке"/>
</TABS>]
<ELEMENTS>
{Описание поля}
</ELEMENTS>
</EDITCARD>
<DETAILS [hide_access_detail="yes|no"]>
{Описание вкладки}
</DETAILS>
Тег GRID используется только в случае, если TAB.section_type = common
. Тег GRID содержит следующие атрибуты.
- lines_count. Количество строк в таблице.
- display_search =
yes|no
. Отображать ли строку поиска в таблице. - hide_buttons =
yes|no
. Скрыть ли кнопки Добавить, Изменить, Удалить. Также определяет, доступно ли открытие карточки при двойном щелчке на строке таблицы. - disable_dblclick =
yes|no
. Отключает стандартный обработчик на двойной щелчок по строке таблицы записей. Атрибут присутствует в системе начиная с версии 3.4.05. - ondblclick =
{обработчик javascript}
. Переопределяет стандартный javascript обработчик на двойной щелчок по строке таблицы записей. Атрибут присутствует в системе начиная с версии 3.4.11. - is_editable =
yes|no
. Редактируемая таблица или нет. - is_have_pages =
yes|no
. Постраничное отображение записей или нет. Если нет, то в таблице будут отображаться сразу все записи. - js_source_file. Название файла со скриптом Javascript, содержащего клиентскую логику. В версии 4+ по умолчанию используется config/sections/<Код раздела>/<Код таблицы>.js.
- js_function. Название обработчика в Javascript файле, который вызывается сразу после прорисовки таблицы. В версии 4+ по умолчанию используется метод onOpen().
- after_grid_modify. Javascript обработчик события после изменения записи. В версии 4+ по умолчанию используется метод onAfterFieldSave().
- after_delete_record. Javascript обработчик события после удаления записи. В версии 4+ по умолчанию используется метод onAfterDelete().
- js_path. Способ задания пути к файлу Javascript.
- php_sourcefile. Название файла со скриптом PHP, содержащий серверную логику. В версии 4+ по умолчанию используется config/sections/<Код раздела>/<Код скрипта>.php. <Код скрипта> - аналогично коду карточки, но вместо префиксов
c
иdc
используются префиксыs
иds_
соответственно. - php_on_prepare. Функция, которая будет вызвана перед созданием таблицы записей на сервере. Функция предназначена для динамического изменения параметров таблицы записей source_type, source_name, detail_name и т.д. В версии 4+ по умолчанию используется метод onPrepareGrid().
- php_replace_script. Переопределение функции прорисовки таблицы на пользовательскую. В версии 4+ по умолчанию используется файл аналогично php_source_file.
- php_replace_function. Имя функции, которая будет вызвана для рисования таблицы. Данная функция должна возвращать строку в формате HTML. После прорисовки могут быть вызваны обработчики из js_function. В версии 4+ по умолчанию используется метод onReplaceGrid().
В теге GRID_WND описывается окно для выбора значений в lookup полях, которые ссылаются на данный раздел. Тег GRID_WND содержит следующие атрибуты.
- lines_count. Количество строк в таблице.
- caption. Заголовок окна.
- width. Ширина окна.
- height. Высота окна.
В теге EDITCARD описывается карточка раздела. Тег EDITCARD содержит следующие атрибуты.
- caption. Заголовок окна карточки.
- name. Код карточки, уникальный в рамках конфигурации.
- width. Ширина окна карточки.
- height. Высота окна карточки.
- layout. Параметры расположения элементов на карточке. Набор чисел, разделенных запятыми. Каждое число показывает, сколько элементов отображать в строке карточки. Порядок числа — это номер строки на карточке. Поля будут располагаться на карточке в порядке следования их тегов FIELD.
Примеры:
- layout=
“1, 1, 1”
— три строки, по одному полю в каждой. - layout=
“1, 2”
— 2 строки. В первой будет размещено одно поле, во второй — два.
- layout=
- draw_extra_button =
yes|no
. Отображать ли кнопку Сохранить и добавить. - show_card_top_panel =
yes|no
. Атрибут определяет, показывать ли верхнюю панель для карточки. Если не указан, то значение по умолчанию определяется параметрами стиля. - show_card_details =
yes|no
. Если карточка открыта не из раздела и значение атрибута равноno
, то панель с вкладками у карточки будет свернута. Если атрибут не определен, то значение по умолчанию определяется параметрами стиля. - js_source_file. Название файла со скриптом Javascript, содержащего клиентскую логику. В версии 4+ по умолчанию используется config/sections/<Код раздела>/<Код карточки>.js.
- js_function. Название обработчика в Javascript файле, который вызывается сразу после прорисовки карточки. В версии 4+ по умолчанию используется метод onOpen().
- on_after_save. Javascript обработчик события после изменения записи. В версии 4+ по умолчанию используется метод onAfterSave().
- js_path. Способ задания пути к файлу Javascript.
- php_sourcefile. Название файла со скриптом PHP, содержащий серверную логику. В версии 4+ по умолчанию используется config/sections/<Код раздела>/<Код скрипта>.php. <Код скрипта> - аналогично коду карточки, но вместо префиксов
c
иdc
используются префиксыs
иds_
соответственно. - php_on_prepare. PHP обработчик события перед рисованием карточки на сервере. Может возвращать массив FieldValues - в этом случае эти значения будут установлены на карточке при ее открытии на клиенте. Также, функция может вернуть массив параметров, указывающий какую карточку нужно открыть вместо этой (это может быть использовано, например, для отображения различных карточек для каждого типа заказа). Формат:
Project_onPrepare($params)
, гдеparams
- ассоциативный массив, содержащий параметры, с которыми вызвана карточка: раздел, вкладка, id записи, параметры карточки и т.д. В версии 4+ по умолчанию используется метод onPrepare(). - php_on_before_post. PHP обработчик события перед сохранением карточки на сервере. Если функция вернет массив вида
array(\‘Error\’ => \’[сообщение об ошибке]\‘)
, то запись сохранена не будет, а на клиенте будет показано соответствующее сообщение об ошибке. Обработчик может быть использован для проверки введенных данных на сервере. Формат:Contact_BeforePost($p_table, $p_id, $OldData, $NewData)
. В версии 4+ по умолчанию используется метод onBeforePost(). В версии 4+ событие вызывается не только при создании/изменении, но и перед удалением записи. Если перед удалением обработчик возвращает false, то удаление отменяется. - php_on_after_post. PHP обработчик события после сохранения карточки на сервере. Функция может вернуть ошибку - массив вида
array(\‘Error\’ => \’[сообщение об ошибке]\‘)
или сообщение - массив видаarray(\‘Message\’ => \’[обычное сообщение]\‘)
. Если вернулась ошибка, то она отобразится на клиенте и карточка закрыта не будет. Если вернулось сообщение, то карточка будет закрыта, а сообщение будет показано пользователю. Если функция ничего не вернула, то сохранение произойдет в обычном режиме и никаких собщений показано не будет. Формат:Project_AfterPost($p_table, $p_id, $p_oldvalues, $p_newvalues)
. В версии 4+ по умолчанию используется метод onAfterPost(). В версии 4+ событие вызывается не только после создания/изменения, но и после удаления записи. - parent_card_source. Способ определения внешней карточки.
grid
— карточка определена в другом разделе. В этом случае описание ELEMENTS должно быть вынесено во внешний файл.
- parent_card_name. Название (код) раздела, в котором содержится описание карточки.
section_type=“special”
<SOURCE js_source_file=”Имя файла Javasctipt” js_function=”Название функции Javascript”/>
Тег SOURCE используется только в случае, если TAB.section_type = special
. Тег содержит следующие атрибуты.
- js_source_file. Название файла со скриптом Javascript, содержащего клиентскую логику.
- js_function. Название функции в Javascript файле, которая вызывается при открытии раздела.
Описание колонки
<ITEM
caption=”Заголовок колонки”
width=”Ширина колонки”
(
(db_field=”Имя колонки”
row_type=“common” |
(row_type=“domain”
row_type_domain_name=”Название домена”) |
(row_type=“fk_column”
row_type_parent_table=”Таблица“
row_type_parent_display_column=”Отображаемая колонка”))
|
(row_type=“fk_column_extended”
[row_type_joins=”join для подключения дополнительной таблицы с указанием алиаса”]
row_type_display_column_with_alias=”Отображаемая колонка или значение“
[column_alias=”Алиас для именования колонки”])
)
[row_datatype=“string|date|datetime|int|decimal”]
[row_type_alias=”Алиас колонки”]
[display_format=“none|ongrid|hidden”]
[disable_sort=“yes|no”]
[column_caption=”Служебное название колонки”]
[total=“count|sum|avg - Операция для вычисления итога”] />
Тег COLUMNS.ITEM содержит следующие атрибуты.
- db_field. Имя колонки в базе данных.
- caption. Заголовок для отображения названия колонки в таблице.
- width. Ширина колонки. Можно задавать как в процентах, так и пикселях.
- row_type =
common|domain|fk_column|fk_column_extended
. Тип колонки. - row_type_parent_table. Название таблицы, на которую ссылается колонка.
- row_type_parent_display_column. Колонка для отображения.
- row_type_domain_name. Название (код) домена, где хранятся значения для отображения.
- row_type_joins.
join
для подключения дополнительной таблицы с указанием алиаса. - row_type_display_column_with_alias. Отображаемая колонка или значение. При выводе колонки желательно пользоваться алиасом, определенными в row_type_joins.
- row_datatype. Тип колонки, это поле используется для более правильной сортировки. По умолчанию —
common
. - row_type_alias. Алиас колонки. Используется для удобного обращения к колонкам при описании фильтров в теге FILTERS.
- display_format =
none|ongrid|hidden
. Отображать или нет колонку.ongrid
— отображать колонку и в таблице, и в опциях поиска.hidden
— колонка присутствует и в таблице, и в опциях поиска, но в таблице не отображается. В таблице колонка пристутсвует в виде атрибута тега TR.none
— не отображать колонку в таблице, но отображать в опциях поиска.
- disable_sort. Позволяет отключить сортировку по данной колонке. Значение по умолчанию
no
. Если указаноyes
, то по колонке нельзя будет включить сортировку. Это требуется, например, в тех случаях, когда значение колонки вычисляется в Javascript. Атрибут присутствует в системе начиная с версии 3.0.07. - column_caption. Служебное название колонки, которое будет задавать имя атрибута для поля, у которого display_format=hidden. Если данный атрибут не задавать, то название поля будет формироваться в старом стиле — автоматически. Атрибут присутствует в системе начиная с версии 3.2.03.
- total. Функция для вычисления итога. Атрибут присутствует в системе начиная с версии 4.0.05.
Описание фильтра
<ITEM
caption=”Заголовок фильтра”
(where_clause=”Условие фильтра (SQL)“
[default_selected=“yes|no”]
[sort_column=“1”]
[sort_direction=“desc”]
[hard_where=“Условие для принудительной фильтрации. Версии до 4.0.08.”]) |
([auto_table=”Название таблицы в БД”]
[auto_filter_column=”Название колонки в БД”]
[auto_display_column=”Название колонки в БД”]
[auto_sort_column=”Название колонки в БД”]
[auto_where_clause=”Условие фильтра (SQL)”])
[auto_value_selected=”Значение, которое будет выбрано при открытии раздела”]
[values_where_clause=”Условие фильтрации значений для автофильтра (SQL)”])
[item_style=”Стиль фильтра (CSS). До версии 4.0.16.”]
[class=”Класс CSS. Версия 4.0.16+”]
[title=”Всплывающая подсказка. Версия 4.0.16+”]
[field=”Код поля в карточке. Версия 4.0.15+“
[default=”SQL запрос для заполнения значения по умолчанию. Версия 4.0.15+”]] />
Если теги ITEM вложенные, то фильтры рисуются древовидными. Тег FILTERS.ITEM содержит следующие атрибуты.
- caption. Заголовок для отображения названия фильтра.
- where_clause. SQL условие фильтра, можно использовать алиасы колонок, которые определяются в теге COLUMNS. Если условие задано пустой строкой, то фильтр не может быть активен, такие фильтры можно использовать как называния групп фильтров. Фильтр с условием
1=1
выбирает все записи. Также доступны следующие стандартные функции._iris_user_id[]
— ID текущего пользователя._iris_current_date[]
— текущая дата.
- default_selected. Выбран ли фильтр по умолчанию при открытии раздела.
- sort_column. При выборе фильтра будет выполнятся сортировка таблицы по этой колонке.
- sort_direction. Направление сортировки при выборе фильтра.
- auto_table. Имя таблицы для выбора значений фильтра. С версии 4.0.07 доступны функции автозамены.
- auto_filter_column. Поле таблицы, которое будет подставляться в условие автофильтра. С версии 4.0.07 доступны функции автозамены.
- auto_display_column. Поле таблицы, которое будет выводиться в качетстве caption для автофильтра. С версии 4.0.07 доступны функции автозамены.
- auto_sort_column. Поле таблицы, по которой будет проводится сортировка значений автофильтра.
- auto_where_clause. Условие фильтрации. Условие используется, если из таблицы автофильтра выбирать только определенные значения. Данное условие должно сожержать строку #VALUE#, в которую будет вставлено значение auto_filter_column. Пример:
auto_where_clause=“AT.Code=\‘#VALUE#\‘”
. - auto_value_selected. Указывается значение #VALUE#, которое будет выбрано при открытии раздела для автофильтра. Необязательный параметр.
- values_where_clause. Условие фильтрации значений для автофильтра. Необязательный параметр. Атрибут присутствует в системе начиная с версии 3.4.09. С версии 4.0.07 доступны функции автозамены.
- item_style. CSS стиль оформления фильтра. Устарел. Вместо этого атрибута рекомендуется использовать атрибут class.
- class. CSS класс оформления фильтра. Для версии 4.0.16+.
- field. Код поля в карточке, которое должно быть отображено на месте фильтра. Используется, например, для фильтрации по указанной дате. Значение поля будет передано в #VALUE# в условие filter_where. Для версии 4.0.15+.
- default. Значение поля field по умолчанию. Определяется SQL запросом. Доступны функции макроподстановки. Для версии 4.0.15+.
Описание поля
<FIELD
(
elem_type=“spacer” |
(elem_type=“splitter” caption=”Заголовок поля” [small=“no”]) |
(elem_type=“button”
caption=”Текст на кнопке”
(method=”Название метода-обработчика” |
onclick=”Обработчик. Вместо onclick желательно использовать method.”)
[code=”Идентификатор кнопки. В карточке к нему будет добавлен префикс ‘_’”]
[align=“left|middle|right - выравнивание кнопки, по умолчанию - left”]
[width=”Ширина - по умолчанию 100%”]) |
(elem_type=“detail”
code=”Код вкладки (вкладка должна быть описана в DETAIL)“
[height=”Высота”]) |
(elem_type=“matrix”
code=”Код вкладки (вкладка должна быть описана в DETAIL)”) |
(
(elem_type=“email|url|password”
datatype=“string”
row_type=“common”) |
(elem_type=“phone”
datatype=“string”
[row_type=“common”]
[db_field_addl=“Поле для добавочного номера”
[mandatory_addl=“yes|no”]]) |
(elem_type=“textarea”
datatype=“string”
row_type=“common”
[textarea_rows=”Количество строк в многострочном поле”]
[is_rich_control=“yes”
[toolbar_type=“Mini”]]) |
(elem_type=“text”
((datatype=“string|int|decimal” row_type=“common”) |
(datatype=“date|datetime” row_type=“date”) |
(datatype=“file” row_type=“file”))) |
(elem_type=“lookup”
datatype=“id”
row_type=“fk_column”
row_type_parent_source_type=“grid|dict”
row_type_parent_source_name=”Код источника данных (таблица или справочник)“
row_type_parent_display_column=”Колонка для отображения“
filter_where=”условие фильтрации”) |
(elem_type=“select”
(row_type=“fk_column”
datatype=“id”
(row_type_parent_table=”Название таблицы“
row_type_parent_display_column=”Колонка для отображения”
[order_by=”Название поля для сортировки”]
[db_field_ext=”Дополнительные поля”]) |
row_type_sql=”Условие для выбора значений в выпадающий список.”) |
(row_type=“domain”
datatype=“string|int|decimal|date|datetime|id”
row_type_domain_name=”Код домена”)) |
(elem_type=“checkbox”
row_type=“domain”
row_type_domain_name=“Название домена”
row_type_checked_index=“Целое число, порядок значения в xml-описании домена, соответствующее отмеченному чекбоксу”
datatype=“int|string”) |
(elem_type=“radiobutton”
row_type=“domain”
row_type_domain_name=“Название домена”
datatype=“int|string”)
caption=”Заголовок поля“
db_field=”Название поля в БД“
[mandatory=“yes|no”]
[title=“Всплывающая подсказка при наведении мыши на название поля”]
)
)
/>
Тег EDITCARD.FIELD содержит следующие атрибуты.
- caption. Заголовок поля, отображается на карточке.
- db_field. Название поля в БД.
- elem_type. Тип графического элемента. Атрибут может принимать следующие значения.
text
— текстовое поле.textarea
— многострочное текстовое поле.select
— выпадающий список.lookup
— поле-справочник.email
— текстовое поле с пиктограммой email.url
— текстовое поле с пиктограммой url.button
— кнопка, доступна в версии 4.0.10+.detail
— таблица вкладки, доступно в версии 4.0.10+.matrix
— карточки вкладки, доступно в версии 4.0.10+.splitter
— разделитель с заголовком.spacer
— пустой элемент.
- datatype. Тип данных, используется для оформления и обработки значения элемента. Атрибут может принимать следующие значения.
string
— строка.int
— целое число.decimal
— дробное число.date
— дата.datetime
— дата и время.id
— ссылка на другое поле (справочник).file
— поле для прикрепления файла. Смотрите также пример.
- row_type. Тип данных, используется для определения способа определения элемента. Атрибут может принимать следующие значения.
common
— обыкновенное поле (строка, число).date
— дата и дата-время.fk_column
— ссылка на другое поле (справочник).domain
— домен.file
— поле для прикрепления файла. Смотрите также пример.
- row_type_domain_name. Код домена. Домены определяются в файле config/dictionary/domains.xml.
- row_type_parent_source_type. Способ описания источника данных.
grid
— таблица.dict
— справочник.
- row_type_parent_source_name. Название источника данных.
- Если row_type_parent_source_type=
grid
, то код раздела. - Если row_type_parent_source_type=
dict
, то код справочника.
- Если row_type_parent_source_type=
- row_type_parent_table. Название таблицы, на которую ссылается поле.
- row_type_parent_display_column. Поле для отображения.
- filter_where. Условие фильтрации для отображаемых записей. Начиная с версии 3.6.01 при указании условия можно использовать строку :record_id
- order_by. Название поля, по которому необходимо сортировать значения в выпадающем списке. Можно указывать несколько полей через запятую, в этом случае сортировка будет выполняться последовательно по указанным полям. Обычно используется совместно с атрибутом db_field_ext.
- db_field_ext. Дополнительные поля, которые нужно поместить в выпадающий список в качестве атрибутов, записываются через запятую. Применяется, в частности, для связки двух полей-справочников друг с другом. Например, в карточке заказа стадии заказа связаны с типом заказа.
Пример:db_field_ext=“code, description”
— это значит, что в выпадающий список будут помещены поля id, db_field, code, description. Поля, указанные в db_field_ext будут выведены как дополнительные атрибуты в теге OPTION выпадающего списка. Поле db_field_ext удобно использовать, когда необходимо вывести дополнительную информацию, фильровать значения выпадающих списков по коду и т.д. - row_type_sql. Данный атрибут задает произвольный SQL запрос для выпадающего списка. В запросе необходимо указать первым в списке поле ID, чтобы поля с внешними ключами могли сохраняться нормально. Атрибут полезно использовать, если, например, значения нужно отображать с учетом прав доступа по записям.
Пример:row_type_sql=“select T0.id, T0.email, T1.r, T1.is_primary from iris_emailaccount T0 left join iris_emailaccount_defaultaccess T1 on (T0.id = T1.emailaccountid and t1.contactid=_iris_user_id[]) where T1.r=\‘1\‘”
При указании условия можно использовать строку :record_id - textarea_rows. Количество строк в многострочном поле.
- is_rich_control =
yes
|no
. Отображать многострочное поле как текстовый редактор с расширенными возможностями форматирования. - mandatory =
yes
|no
. Обязательно ли заполнение поля.
Описание вкладки
<DETAIL
caption=”Заголовок вкладки“
[showoncard=“yes|no”]
[showinsection=“yes|no”]
name=”Код вкладки”
detail_fk_column=”Колонка-связка с родительской таблицей”
detail_bound_clause=”Условие связки вкладки с родительской записью“ |
detail_table=”Таблица вкладки“>
<GRID Стандартные атрибуты GRID >
<COLUMNS>
{Описание колонки}
</COLUMNS>
</GRID>
<EDITCARD Стандартные атрибуты EDITCARD >
[<TABS>
{Описание закладки}
</TABS>]
<ELEMENTS>
{Описание поля}
</ELEMENTS>
</EDITCARD>
</DETAIL>
Тег DETAIL содержит следующие атрибуты.
- caption. Заголовок вкладки.
- showoncard. Показывать ли вкладку на панели вкладок карточки.
- showinsection. Показывать ли вкладку в разделе (используется в стилях, в которых вкладки показываются в разделах).
- name. Код вкладки, уникальный в рамках конфигурации.
- detail_fk_column. Колонка, которая ссылается на ID родительской таблицы.
- detail_bound_clause. SQL условие связки родительской записи и записей вкладки (вместо detail_fk_column, когда этого определения не хватает).
- external. Описание вкладки содержится вовне данного файла или нет. Если
yes
, то описание GRID и EDITCARD должно быть вынесено во внешний файл. - detail_file. Файл, содержащий описание вкладки (обычно в каталоге config/common/Sections/<Код раздела>).
- detail_table. Таблица, содержащая данные вкладки.