API XML-описаний разделов

Содержимое разделов 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 
  [lines_count="Количество строк в таблице"]
  [display_search="no"]
  [hide_buttons="yes|no"]
  [is_editable="yes"]
  [is_have_pages="no"]
  [js_source_file="Файл со скриптом Javascript" 
    [js_function="Функция-обработчик инициализации таблицы"]
    [after_grid_modify="Функция-обработчик события после изменения записи"]
    [after_delete_record="Функция-обработчик события после удаления записи"] 
    [js_path="full"]]
  [php_replace_script="PHP скрипт для переопределения прорисовки таблицы."
    php_replace_function="Функция для прорисовки таблицы."]>
  <COLUMNS>
    {Описание колонки}
  </COLUMNS>
  <FILTERS>
    {Описание фильтра}
  </FILTERS>
</GRID> 

<GRID_WND
  lines_count="Количество строк в таблице"
  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"]]
  [parent_card_source="grid"
    parent_card_name="Код раздела с описанием карточки"]>
  <ELEMENTS>
    {Описание поля}
  </ELEMENTS>
</EDITCARD> 

<DETAILS>
  {Описание вкладки}
</DETAILS> 

Тег GRID используется только в случае, если TAB.section_type = common. Тег GRID содержит следующие атрибуты.

• lines_count. Количество строк в таблице.
• display_search = yes|no. Отображать ли строку поиска в таблице.
• hide_buttons = yes|no. Скрыть ли кнопки Добавить, Изменить, Удалить. Также определяет, доступно ли открытие карточки при двойном щелчке на строке таблицы.
• is_editable = yes|no. Редактируемая таблица или нет.
• is_have_pages = yes|no. Постраничное отображение записей или нет. Если нет, то в таблице будут отображаться сразу все записи.
• js_source_file. Название файла со скриптом Javascript, содержащего клиентскую логику.
• js_function. Название функции в Javascript файле, которая вызывается сразу после прорисовки таблицы.
• after_grid_modify. Javascript обработчик события после изменения записи.
• after_delete_record. Javascript обработчик события после удаления записи.
• js_path. Способ задания пути к файлу Javascript.
• php_replace_script. Переопределение функции прорисовки таблицы на пользовательскую.
• php_replace_function. Имя функции, которая будет вызвана для рисования таблицы. Данная функция должна возвращать строку в формате HTML. После прорисовки могут быть вызваны обработчики из js_function.

В теге 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 строки. В первой будет размещено одно поле, во второй — два.
• draw_extra_button = yes|no. Отображать ли кнопку Сохранить и добавить.
• show_card_top_panel = yes|no. Атрибут определяет, показывать ли верхнюю панель для карточки. Если не указан, то значение по умолчанию определяется параметрами стиля.
• show_card_details = yes|no. Если карточка открыта не из раздела и значение атрибута равно no, то панель с вкладками у карточки будет свернута. Если атрибут не определен, то значение по умолчанию определяется параметрами стиля.
• js_source_file. Название файла со скриптом Javascript, содержащего клиентскую логику.
• js_function. Название функции в Javascript файле, которая вызывается сразу после прорисовки карточки.
• on_after_save. Javascript обработчик события после изменения записи.
• js_path. Способ задания пути к файлу Javascript.
• 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 
  db_field="Имя колонки" 
  caption="Заголовок колонки" 
  width="Ширина колонки" 
  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="Отображаемая колонка или значение")
  [row_datatype="date|int|decimal"]
  [row_type_alias="Алиас колонки"] 
  [display_format="none|ongrid|hidden"] 
  [disable_sort="yes|no"] />

Тег 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 — колонка присутствует и в таблице, и в опциях поиска, но в таблице не отображается.
  • none — не отображать колонку в таблице, но отображать в опциях поиска.
• disable_sort. Позволяет отключить сортировку по данной колонке. Значение по умолчанию no. Если указано yes, то по колонке нельзя будет включить сортировку. Это требуется, например, в тех случаях, когда значение колонки вычисляется в Javascript. Атрибут присутствует в системе начиная с версии 3.0.07.

Описание фильтра

<ITEM 
  caption="Заголовок фильтра" 
  where_clause="Условие фильтра (SQL)"
  [item_style="Стиль фильтра (CSS)"] 
  [default_selected="yes|no"]
  [sort_column="1"]
  [sort_direction="desc"] />

Если теги ITEM вложенные, то фильтры рисуются древовидными. Тег FILTERS.ITEM содержит следующие атрибуты.

• caption. Заголовок для отображения названия фильтра.
• where_clause. SQL условие фильтра, можно использовать алиасы колонок, которые определяются в теге COLUMNS. Если условие задано пустой строкой, то фильтр не может быть активен, такие фильтры можно использовать как называния групп фильтров. Фильтр с условием 1=1 выбирает все записи. Также доступны следующие стандартные функции.
  • _iris_user_id[] — ID текущего пользователя.
  • _iris_current_date[] — текущая дата.
• item_style. CSS стиль оформления фильтра.
• default_selected. Выбран ли фильтр по умолчанию при открытии раздела.
• sort_column. При выборе фильтра будет выполнятся сортировка таблицы по этой колонке.
• sort_direction. Направление сортировки при выборе фильтра.

Описание поля

<FIELD
  (
    elem_type="spacer" | 
    (elem_type="splitter" caption="Заголовок поля) |
    (
      (elem_type="email|url" 
        datatype="string" 
        row_type="common") | 
      (elem_type="textarea" 
        datatype="string" 
        row_type="common"
        [textarea_rows="Количество строк в многострочном поле"]
        [is_rich_control="yes"]) | 
      (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="Колонка для отображения" ) | 
      (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="Код домена"))
      caption="Заголовок поля"
      db_field="Название поля в БД"
      [mandatory="yes|no"]
    )
  )
/>

Тег EDITCARD.FIELD содержит следующие атрибуты.

• caption. Заголовок поля, отображается на карточке.
• db_field. Название поля в БД.
• elem_type. Тип графического элемента. Атрибут может принимать следующие значения.
  • text — текстовое поле.
  • textarea — многострочное текстовое поле.
  • select — выпадающий список.
  • lookup — поле-справочник.
  • email — текстовое поле с пиктограммой email.
  • url — текстовое поле с пиктограммой url.
  • 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_table. Название таблицы, на которую ссылается поле.
• row_type_parent_display_column. Поле для отображения.
• 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'"
• textarea_rows. Количество строк в многострочном поле.
• is_rich_control = yes|no. Отображать многострочное поле как текстовый редактор с расширенными возможностями форматирования.
• mandatory = yes|no. Обязательно ли заполнение поля.

Описание вкладки

<DETAIL
  caption="Заголовок вкладки" 
  name="Код вкладки" 
  detail_fk_column="Колонка-связка с родительской таблицей" 
  [detail_bound_clause="Условие связки вкладки с родительской записью"]
  (external="yes" 
  detail_file="Файл с описанием вкладки") |
  detail_table="Таблица вкладки">

<GRID Стандартные атрибуты GRID >
  <COLUMNS>
    {Описание колонки}
  </COLUMNS>
</GRID>

<EDITCARD Стандартные атрибуты EDITCARD >
  <ELEMENTS>
    {Описание поля}
  </ELEMENTS>
</EDITCARD>

</DETAIL>

Тег DETAIL содержит следующие атрибуты.

• caption. Заголовок вкладки.
• name. Код вкладки, уникальный в рамках конфигурации.
• detail_fk_column. Колонка, которая ссылается на ID родительской таблицы.
• detail_bound_clause. SQL условие связки родительской записи и записей вкладки (вместо detail_fk_column, когда этого определения не хватает).
• external. Описание вкладки содержится вовне данного файла или нет. Если yes, то описание GRID и EDITCARD должно быть вынесено во внешний файл.
• detail_file. Файл, содержащий описание вкладки (обычно в каталоге config/common/Sections/<Код раздела>).
• detail_table. Таблица, содержащая данные вкладки.