Система управления контентом CAIRO

Формат файла импорта

Виктор Грищенко


Содержание

1. Структура файла
2. Файл entities.xml
3. Файл links.xml
4. Файл dictionaries.xml
5. Файл users.xml
6. Файл controls.xml

Список иллюстраций

1. Структура архива файла импорта

Список примеров

1. Структура файла entities.xml
2. Импорт изображения
3. Структура файла links.xml
4. Структура файла dictionaries.xml
5. Структура файла users.xml
6. Структура файла controls.xml

Аннотация

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

1. Структура файла

Импортируемый файл представляет собой ZIP-архив, который содержит XML-файлы, описывающие параметры объектов, связи между ними, справочники и каталог с внешними файлами. Структура архива приведена на рисунке 1.

Рисунок 1. Структура архива файла импорта

Структура архива файла импорта

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

В файле links.xml содержатся ссылки, которые указывают связи сущностей, перечисленных в entities.xml.

Справочники перечислены в файле dictionaries.xml.

В каталоге MEDIA находятся все внешние файлы, на которые ссылаются сущности в файле entities.xml.

Все XML-файлы должны быть представлены в кодировке UTF-8 и соответствовать установленному формату. Отступы и выравнивания в XML-файлах не обязательны. Рассмотрим подробнее формат каждого из этих файлов.

2. Файл entities.xml

В файле entities.xml перечислены параметры сущностей, импортируемых в систему. Формат файла приведен в примере 1. Описания всех сущностей содержатся внутри глобального тега <entities>. Каждая сущность описывается тегом <entity>.

Пример 1. Структура файла entities.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
Этот файл содержит информацию о параметрах сущностей.
-->

<!--Основной контейнер-->
<entities>

    <!--
    Описание сущности

    id      - идентификатор сущности в документе;
    updated - дата/время последнего обновления;
              дата задается  в формате YYYYMMDDHHmmSS;
    type    - тип импортируемой сущности.
    -->

    <entity id="1" updated="20050111114028" type="class_entity">
        <!--
        Внутренний идентификатор.
        Поле идентификатора используется для
        связи сущностей в документе и сущностей в базе данных.
        -->

        <param>
            <!--Псевдоним параметра-->
            <name>inner_id</name>
            <!--Значение параметра-->
            <value>1234</value>
        </param>
        <!--
        Далее идет перечень параметров сущности
        -->

        <param>
            <!--Псевдоним параметра-->
            <name>my_string</name>
            <!--Значение параметра-->
            <value>Foo</value>
        </param>
        <!--
        Аналогичным образом описываются все остальные параметры
        сущности
        -->

    </entity>
    <!--
    Удаляемая сущность.
    Признаком удаления сущности является атрибут delete="true".
    Для удаляемой сущности не обязательно показывать все параметры. Достаточно
    указать только внутренний идентификатор.
    -->

    <entity id="2" updated="20050111114028" delete="true" type="class_entity">
        <param>
            <!--Псевдоним параметра-->
            <name>inner_id</name>
            <!--Значение параметра-->
            <value>5678</value>
        </param>
</entities>

Тег <entity> имеет три обязательных атрибута: (id, updated и type) и один необязательный - delete. Атрибут id содержит идентификатор сущности внутри документа. Это означает, что внутри одного документа не может быть двух тегов <entity> с одинаковыми значениями атрибута id, но в разных документах теги с одинаковыми id могут описывать разные сущности. Эти же идентификаторы используются и в файле links.xml для определения связей сущностей.

Атрибут updated содержит дату последнего обновления импортируемой сущности. Дата должна быть представлена в формате YYYYMMDDHHmmSS. Этот атрибут используется для исключения возможности замены старым импортом новых данных. То есть, если дата последнего обновления сущности в БД будет новее значения updated в файле, то сущность обновлена не будет.

Последний обязательный атрибут type определяет тип импортируемой сущности. Тип сущности задается именем его основной таблицы. Этот параметр можно найти в Интерфейсе администратора в разделе "Управление структурой данных".

Необязательный атрибут delete используется только для удаления сущности. Если он присутствует, то сущность будет полностью удалена из системы вместе со всеми ссылками. При этом атрибут updated игнорируется.

Кроме атрибутов тег <entity> содержит также описания параметров сущности. При организации импорта необходимо определить поле, по которому будут связываться сущность в БД и данные во внутренней системе предприятия. Чаще всего для этого в типе сущности описывается дополнительное поле, которое содержит идентификатор сущности во внутренней системе предприятия. Этот идентификатор может быть как числовым, так и строковым.

При добавлении сущности набор параметров должен содержать, как минимум, все обязательные поля плюс поле-идентификатор. Обязательные поля определены в структуре сущностей. Доступ к настройкам полей можно получить в универсальном интерфейсе администратора в разделе "Управление структурой данных". Для обновления достаточно указать идентификатор и значения обновившихся полей. При удалении же сущности достаточно ее идентифицировать с помощью внутреннего идентификатора. Каждый параметр описывается конструкцией следующего вида:

<param>
    <name><!-- Имя параметра --></name>
    <value><!--Значение параметра--></value>
</param>

Имя параметра соответствует имени поля, которое описывает его в Cairo. Имя поля можно узнать в Интерфейсе администратора в разделе "Управление структурой данных". Значение параметра не может содержать спецсимволы XML. Все они должны заменяться на их представление с амперсандом (например, двойная кавычка заменяется на литерал "&quot;", а знак меньше - на "&lt;").

Существуют определенные особенности передачи некоторых типов данных. Например, дата должна передаваться только в формате YYYYMMDD, дата-время - YYYYMMDDHHmmSS, а время соответственно HHmmSS. Кроме того, следует обратить внимание на импорт изображений и файлов (обозначим их медиа-данными). При импорте медиа-данных все файлы должны быть помещены в подкаталог MEDIA, а в соответствующих параметрах тега <value> записывается их имя. Формат импорта остальных типов полей соответствует формату их ввода в форме.

Пример 2. Импорт изображения

<?xml version="1.0" encoding="UTF-8"?>
<entities>
    ...
    <entity id="125" updated="20050111114028" type="class_image">
        <param>
            <!--Псевдоним параметра-->
            <name>inner_id</name>
            <!--Значение параметра-->
            <value>6234</value>
        </param>
        ...
        <param>
            <!--Импортируем изображение-->
            <name>my_image</name>
            <!--
            Значение параметра
            Файл image-001.jpg должен находиться
            в подкаталоге MEDIA
            -->

            <value>image-001.jpg</value>
        </param>
        <!--
        Аналогичным образом описываются все остальные параметры
        сущности
        -->

    </entity>
    ...
</entities>

3. Файл links.xml

В файле links.xml описывается структура импортируемых сущностей. Чаще всего импорт происходит в один узел дерева сущностей, поэтому основным механизмом является импорт в родителя по умолчанию. Однако, допускается и импорт в сущность, отличную от родителя по умолчанию. Для этого следует явно указать ее идентификатор в структуре данных Cairo. Подробнее этот вариант импорта будет рассмотрен ниже.

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

Сущности могут связываться друг с другом двумя типами связей: жесткой и символической. Каждая сущность может иметь более одного родителя, и когда удаляется последняя жесткая ссылка на нее удаляются и все оставшиеся символические. Тип ссылки указывается в атрибуте type тега <link>.

Пример 3. Структура файла links.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
В этом файле на каждую сущность в entities.xml
есть описание связи.

Для обновляемых сущностей запись
в этом файле необязательна
-->

<!--Глобальный контейнер-->
<links>
    <!--
    Начало описания связи

    Идентификатор не должен повторятся внутри файла.
    Жесткая ссылка (type="hard")
    -->

    <link id="1" type="hard">
        <!--Параметр pos указывает порядок сущности в списке-->
        <pos>1</pos>
        <!--
        Указываем идентификатор сущности в БД ресурса.
        Он имеет атрибут type="global"
        -->

        <parentid type="global">185</parentid>
        <!--Параметр childid соответствует идентификатору id в файле entities.xml-->
        <childid>10</childid>
    </link>

    <!--Помещаем символическую ссылку на сущность
    (type="symbolic") в другого родителя-->

    <link id="2" type="symbolic">
        <pos>1</pos>
        <parentid type="global">187</parentid>
        <childid>10</childid>
    </link>

    <!--Помещаем данные в родителя по умолчанию-->
    <link id="3" type="hard">
        <pos>1</pos>
        <parentid>0</parentid>
        <childid>2</childid>
    </link>

    <!--Прикрепляем сущность к другой, импортируемой в этом же файле.-->
    <link id="4" type="hard">
        <pos>1</pos>
        <!--Идентификатор родительской сущности из импортируемого файла-->
        <parentid>21</parentid>
        <!--Идентификатор дочерней сущности из импортируемого файла-->
        <childid>22</childid>
    </link>

    <!--Явно указываем точку вложения-->
    <link id="5" type="hard">
        <pos>1</pos>
        <!--Идентификатор точки вложения-->
        <enclusure>163</enclusure>
        <parentid>0</parentid>
        <childid>23</childid>
    </link>

    <!--Удаляем ссылку на сущность.-->
    <link id="6" delete="true">
        <pos>1</pos>
        <!--Идентификатор родительской сущности из импортируемого файла-->
        <parentid>21</parentid>
        <!--Идентификатор дочерней сущности из импортируемого файла-->
        <childid>23</childid>
    </link>

</links>

Связь устанавливается между двумя сущностями. Одна из них является родительской, другая – дочерней. Идентификатор родительской сущности описан в теге <parentid>, идентификатор дочерней - <childid>.

Сущности могут вкладываться в родительскую в определенном порядке, тогда этот порядок указан в теге <pos>. Если порядок не важен, то в тег записывается значение 1. При вставке в упорядоченный список сущность сдвигает все, которые лежат ниже ее.

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

Сущности могут вкладываться одна в другую более чем один раз. Например, в каталог объявление может быть вложено просто как дочернее, так и как избранное объявление с соответствующим способом вывода. В этом случае в ссылке приводится тег <enclosure>, который содержит идентификатор связи. Идентификатор связи можно узнать в разделе "Управление структурой данных" в интерфейсе администратора. В случае, если тег <enclosure> не приведен, то он будет вычислен автоматически, но это может привести к конфликтной ситуации, когда сущность добавится к родителю в ошибочную связь.

В качестве идентификаторов сущностей в связи могут использоваться внутрисистемные идентификаторы. Для этого при определении тега родителя или ребенка используется в связи используется атрибут type="global" и указывается идентификатор в структуре данных Cairo. Этот механизм, фактически реализует импорт в родителя, отличного от родителя по умолчанию.

Если необходимо удалить связь, то в теге <link> добавляется атрибут delete="true", аналогично тому, как это делается при удалении сущности.

4. Файл dictionaries.xml

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

Общий вид файла справочников приведен в примере 4. Файл состоит из раздела common, который содержит параметры справочников и их элементы. Справочник описывается идентификатором (уникальным среди справочников), заголовком и комментарием. Элементы справочника имеют идентификатор, уникальный среди всех элементов справочников, псевдоним (alias), значение (value) и комментарий (comment). Комментарий может быть пустым.

Пример 4. Структура файла dictionaries.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!--
Файл описывает справочники и их элементы.
-->

<dictionaries>
    <common>

        <dictionary id="1">
            <title>Город</title>
            <comment>Справочник городов</comment>
            <items>
                <item>
                    <alias>Донецк</alias>
                    <value>1</value>
                    <comment></comment>
                </item>
                <item>
                    <alias>Киев</alias>
                    <value>2</value>
                    <comment></comment>
                </item>
                <item>
                    <alias>Луганск</alias>
                    <value>3</value>
                    <comment></comment>
                </item>
            </items>
        </dictionary>

        <dictionary id="2">
            <title>Реки</title>
            <comment>Справочник рек</comment>
            <items>
                <item>
                    <alias>Днепр</alias>
                    <value>1</value>
                    <comment></comment>
                </item>
                <item>
                    <alias>Дунай</alias>
                    <value>2</value>
                    <comment></comment>
                </item>
            </items>
        </dictionary>

    </common>
</dictionaries>

Справочники связываются по названию (содержимое тега title). При этом, если в системе уже существует справочник с таким же названием, как у импортируемого, то все его элементы удаляются и на их место записываются данные из файла импорта.

5. Файл users.xml

Достаточно редко возникает необходимость импортировать информацию о пользователях. Для этих целей используется файл users.xml. Файл позволяет добавлять, обновлять, удалять учетные записи пользователей пользователе, а также изменять принадлежность пользователя группам.

Учетная запись пользователя имеет набор обязательных параметров, кроме того, для каждого ресурса можно определить дополнительный набор параметров. Поэтому формат файла users.xml может расширяться дополнительным набором параметров. Общий вид файла приведен в примере 5.

Пример 5. Структура файла users.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
В этом файле описываются учетные записи,
импортируемые на сайт.
-->


<users>
    <!--
    Описываем учетную запись пользователя
    -->

    <user>
        <!--
        Идентификатор пользователя
        -->

        <uid>175</uid>

        <!--
        Группы, к которым принадлежит пользователь.
        Они могут не описываться. Если же они описаны, то
        после обновления пользователь будет входить только
        в группы, описанные здесь.

        Информация о группах импортируется в файле groups.xml
        -->

        <groups>
            <!--
            Идентификаторы групп
            -->

            <gid>3</gid>
            <gid>7</gid>
            <gid>17</gid>
        </groups>

        <!--
        Обязательные параметры учетной записи
        Формат описания параметров учетной записи аналогичен
        описанию параметров сущности в файле entities.xml
        -->

        <!--
        Псевдоним пользователя.
        -->

        <param>
            <name>nick</name>
            <value>boris123</value>
        </param>
        <!--
        Пароль пользователя

        Пароль должен передаваться в виде MD5-хэша
        -->

        <param>
            <name>passw</name>
            <value>5f4dcc3b5aa765d61d8327deb882cf99</value>
        </param>

        <!--
        Адрес электронной почты
        -->

        <param>
            <name>email</name>
            <value>boris123@example.com</value>
        </param>

        <!--
        Фамилия
        -->

        <param>
            <name>lastname</name>
            <value>Иванов</value>
        </param>

        <!--
        Имя
        -->

        <param>
            <name>firstname</name>
            <value>Петр</value>
        </param>

        <!--
        Отчество
        -->

        <param>
            <name>surname</name>
            <value>Васильевич</value>
        </param>

        <!--
        Пол
        - 1 - Мужской
        - 2 - Женский
        Параметр не обязателен
        -->

        <param>
            <name>sex</name>
            <value>1</value>
        </param>

        <!--
        Дата рождения

        Дата задается в формате YYYYMMDD
        Параметр не обязателен
        -->

        <param>
            <name>birthday</name>
            <value>19670101</value>
        </param>

        <!--
        Дополнительная информация
        -->

        <param>
            <name>about</name>
            <value></value>
        </param>

        <!--
        Далее следуют параметры специфические для ресурса,
        если они определены
        -->


    </user>

    <!--
    Удаляем пользователя
    -->

    <user delete="true">
        <uid>176</uid>
    </user>

</users>

Для обновления пользователя достаточно указать его идентификатор и обновившиеся параметры. Все остальные параметры затронуты не будут.

6. Файл controls.xml

В настоящий момент единственная функциональность, которая заложена в файл controls.ini - полная очистка сущностей. Эту возможность можно использовать в отладочных целях и крайне не рекомендуется применять в рабочих проектах.

Формат файла представлен в примере 6. Внутри тегов clear содержатся идентификаторы удаляемых сущностей. Один тег может содержать только один идентификатор. После импорта архива с таким файлом все потомки указанных сущностей будут удалены.

Пример 6. Структура файла controls.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
Файл описывает очищаемые сущности
-->

<controls>

    <clear>
        <!--Идентификатор очищаемой сущности (берется из БД)-->
        <entid>2577</entid>
    </clear>

    <clear>
        <entid>2578</entid>
    </clear>

</controls>