Вход для клиентов и партнеров
в начало сайта
Партнерская программаОнлайн демоСкачатьКарта сайта
 

Регламент
Документация
Часто задаваемые вопросы (FAQ)
Решения типовых вопросов
Форум поддержки
Библиотека разработчика

Посмотрите демо-ролики и убедитесь в том, что "Twilight CMS" очень удобна в управлении, понятна и проста.

Бесплатно скачайте "Twilight.Basic", установите на своем компьютере и изучите систему более детально.

Если вам нужно установить "Twilight CMS" на существующий сайт или разработать новый - обращайтесь в отдел интеграции.

 

Ваше имя
Ваш Email
Вопрос
Twilight.basic
  • Узнайте больше
  • Сравните версии
  • Twilight.selection
  • Узнайте больше
  • Сравните версии
  • Twilight.evolution
  • Узнайте больше
  • Сравните версии
  •  
    Главная // Библиотека разработчика // Справочники // Форматы служебных файлов //

    entities.xml


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

    Определение сущности в файле enitities.xml

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

    <entities>
        <entity id="camera" name="Фотоаппарат" assign="catalog">
            <field id="title" type="locked" name="Модель"/>
            <field id="date" type="date" name="Дата выпуска"/>
            <field id="manufacturer" type="string" name="Производитель"/>
            <field id="picture" type="image" name="Изображение"/>
            <field id="price" type="money" name="Цена"/>
            <field id="brief" type="text" name="Краткое описание"/>
            <field id="detail" type="linkedhtml" name="Детальное описание"/>
        </entity>
        <entity id="camera_container" name="Фотоаппараты">
            <field id="id" type="string" name="Идентификатор" locked="yes"/>
            <field id="title" type="string" name="Название" locked="yes"/>
            <field id="commentary" type="string" name="Описание категории товаров"/>
        </entity>
        <entity id="film" name="Фотопленка" admin-template=”photofilm”>
            <field id="title" type="string" name="Производитель"/>
            <field id="title" type="money" name="Цена"/>
            <field id="lumen" type="text" name="Светочувствительность"/>
            <field id="cadr" type="text" name="Количество кадров"/>
        </entity>
    </entities>

    Тэг <entity> - это дескриптор («описатель») сущности. Он должен иметь уникальный идентификатор (атрибут id), по которому в дальнейшем можно на него ссылаться и название (атрибут name), которое выводится в админзоне в заголовках редакторов.

    Если указан атрибут assign со значением assign ="catalog", то данная сущность будет выводиться редактору сайта в числе возможных для присвоения новой создаваемой категории товаров в каталоге. Если в рамках entities.xml данный параметр отсутствует, то редактору сайта будут выведены все доступные Системе сущности.

    Для того, чтобы задать набор свойств для катагории, необходимо создать новую сущность с id, содержащим после символа "_" (подчеркивание) служебное слово container. Например, для описания категории содержащей сущности id="camera", необходимо создать сущность с id="camera_container".

    Необязательный атрибут тэга entity admin-template ="photofilm" позволяет разработчику при необходимости конструировать формы с жестко заданным расположением полей на экране. Если его не задавать, то поля будут выведены в порядке появления в тексте XML файла, что экономит время разработчику в простых случаях. Более подробное описание работы со своими шаблонами для редактора сущности будет приведено ниже.

    Тэг <field id="title" type="string" name="Производитель"/> описывает поле сущности, с идентификатором title (должен быть уникален в пределах сущности), типом поля string, подписанное в редакторах админзоны как «Производитель».

    Предопределенные типы для полей сущности

    Типы, которые обозначены для каждого из полей через атрибут type на самом деле обозначают не стандартное понятие «тип данных» (данные не имеют никаких особенных типов, это обычные строки), а используемый для редактирования данного свойства элемент редактора (формы).

    • checkbox: Редактор типа «включено-выключено», при состоянии «checked» в поле прописывается значение «on» (без кавычек).
    • cnid: Поле выбора идентификатора папки каталога.
    • date: Редактор даты в формате дд.мм.гггг со всплывающим календарем.
    • email: Поле типа string с иконкой, при нажатии на которую появляется возможность выбрать шаблон письма из числа имеющихся в email_notifications.dat и послать письмо на адрес введенный в поле.
    • folderalias: Поле выбора псевдонима (alias) папки в библиотеке файлов.
    • html: Мини-редактор HTML «встроенный» в форму ("inline").
    • image: Редактор ссылки на картинку из библиотеки файлов (URL файла).
    • image_preview: То же, что и image, только под полем ввода пути к картинке сразу показывается уменьшенное изображение (только для версий 4.38+). 
    • linkedhtml: Полная версия редактора HTML, хранится в отдельном хранилище, что ускоряет работу и по другим причинам. Редактор открывается в том же фрейме где и редактор сущности полностью его заменяя, поскольку он занимает много места и по-другому работать с ним будет неудобно.
    • money: Редактор денежного типа, пока идентичен типу string.
    • locked: Поле, которое будет нельзя редактировать.
    • parent: Поле будет отображать значение, из другого справочника. Запись из которого будет найдена по id, который должен либо находиться в поле parentid текущей записи, либо в поле с именем, которое лежит в атрибуте linkid описания сущности.
    • radio: Поле типа «группа radiobutton». Для использования этого типа тэг field обязан содержать ряд дополнительных атрибутов
      • table – хранилище, в котором находится перечень вариантов для выбора;
      • radiotitle – имя столбца в хранилище, в котором находится подпись к каждому варианту выбора;
      • radiovalue – имя столбца в хранилище, в котором находится значение, которое будет использовано для поля типа Radio в случае выбора соответствующего варианта;

    Пример тэга type="radio" «в сборе»:

    <field id="state" type="radio" table="statuses" radiotitle="statusname" radiovalue="statusid" name="Ахауля"/>

    Пример файла statuses.dat:

    statusid::0::statusname::не опубликован
    statusid::1::statusname::опубликован
    • sampletext: блок текста аналогичный обычному text, но с возможностью помимо ввода значения в поле вручную выбрать одно из наиболее часто встречающихся в базе в этом поле значений. Удобно, если нужно часто вводить похожую информацию, например темы платежных поручений.
    • select: Поле типа «select» (выпадающий список с возможностью выбора одного из вариантов). Для использования этого типа тэг field обязан содержать ряд дополнительных атрибутов (аналогично типу radio):
      • table – хранилище, в котором находится перечень вариантов для выбора;
      • optiontitle – имя столбца в хранилище, в котором находится подпись к каждому варианту выбора. Начиная с версии 5.21 можно задавать несколько имен полей через пробел;
      • optionvalue – имя столбца в хранилище, в котором находится значение, которое будет использовано для поля типа Radio в случае выбора соответствующего варианта;
      • noemptyoption - если ключ установлен в yes/on/true/1, то в выпадающем списке не будет возможности "ничего не выбрать", то есть поле в базе после сохранения записи через админзону никогда не будет пустым.
      • params – HTML параметры, дополнительно вставляемые в тэг select. В том числе, можно использовать параметр multiple, который позволит выбирать несколько значений, которые в таблицах базы данных будут храниться в одном поле, разделенные символом с кодом 0.

    Пример тэга «в сборе»:

    <field id="state" type="select" table="statuses" optiontitle="statusname" optionvalue="statusid" name=" Ляляпта " params=” onClick=alert(‘click!’)”/>

    Пример файла statuses.dat можно взять из предыдущего примера для типа radio.

    • string: Строка.
    • text: Блок текста.
    • url: Ссылка на файл из библиотеки файлов.

    Внимание: все имена типов чувствительны к регистру.

    Определение параметров сортировки столбцов в админзоне

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

    Ключ может принимать следующие значения:

    • literal - сортировка строковых значений, по умолчанию;
    • numeric - сортировка числовых значений;
    • datetime[mask] - сортировка поля, где значения представлены как дата-время. Учитывая, что форматы даты-времени могут быть самыми разными, вместо mask нужно задать комбинацию из MM (месяц, 2 знака), DD (день, 2 знака), YYYY (год, 4 знака), YY (год, 2 знака), hh (часы, 2 знака), mm (минуты, 2 знака), ss (секунды, 2 знака). Таким образом, если вы хотите, чтобы корректно отсортировался столбец, содержащий значения вида "15.02.2008 15:45" нужно задать маску "DD.MM.YYYY hh:mm", а чтобы распознавалась дата в формате "2007/02/28" - "YYYY/MM/DD".

    Пример: <field id="date" type="date" sortas="datetime[DD.MM.YYYY]" name="Дата"/>

    Определение своего типа данных в редакторе сущности

    Разработчик может добавить новый элемент формы для редактирования своих типов данных или модифицировать существующие. Редактор для каждого из используемых в сущности типов должен находится в папке Templates, имя файла редактора формируется как field_[type].html.

    Поле, которое создает разработчик, будет отправлено в базу после нажатия пользователем "сохранить" только в случае если в нем будет присутствовать элемент html формы, например поля input, textarea, select, checkbox и т.п. Имя поля (атрибут name) в таком редакторе прописывается как $name$, текущее значение поля (value) как $value$. Необходимо вызывать javascript процедуру SomethingChanged() при любом изменении в элементе формы для активизации кнопки «сохранить» в редакторе. Проще всего повесить обработчики на события onchange, onkeypress и т.п. любым способом. Для примера можно взять любое, уже определенное в Системе, поле, файлы системных полей лежат в /Admin/Templates.

    Но строго говоря специализированное поле не обязательно должно сохраняться в базу. Иногда нужно специальным образом отобразить уже имеющиеся данные в админзоне, без необходимости сохранения. Иногда нужно отобразить вообще внешние данные, и их сохранять самостоятельно своими скриптами через внешнее API или веб-сервисы. Естественно, разработчик может в шаблоне своего поля создать необходимые скрипты, использовать Flash и библиотеку JQuery (в админзоне по умолчанию она уже подключена, вручную подгружать её не требуется).

    Система позволяет разработчику определить в шаблоне поля две процедуры, которые будут вызваны сразу после загрузки редактора (PreProcessor_N) и непосредственно перед сохранением данных (PostProcessor_N). Это позволит инициализировать значение поля своими процедурами. Например, получив данные через ajax или преобразовав значение из базы в что-то своё. А затем, когда данные будут готовы к сохранению преобразовать их обратно или отправить куда-то еще через ajax.

    function PreProcessor_$field_id$(){
    }

    function PostProcessor_$field_id$(){
    }

    В данном случае необходимо просто скопировать приведенный скелет процедур без изменений и заполнить процедуры своими скриптами. Макрозамена $field_id$ является порядковым номером поля на форме, который присваивается Системой. Разработчик может использовать данную замену в своих целях наравне с $name$ и $value$ в рамках шаблона своего поля, например, заполнить им атрибут id у html элементов формы или создавать сложные ключи.

    В рамках шаблона своего поля допустимо использовать любые макросы системы ($News[]$, $DateField[]$ и т.п.). При этом нужно помнить, что значение, которое будет подставлено вместо $value$ (то, что хранится в базе) обработано не будет, и, соответственно, если внутри поля будет введен макрос - он будет отображен "как есть", а не выполнен. В целях безопасности в системе запрещено интерпретировать значения полей из базы данных, за исключением макрозамен типа $RealmURL$, $ServerPath$ и т.п.

    Название поля в entities.xml и имя файла шаблона поля должны быть в одинаковом регистре, расширение html обязательно должно быть в нижнем регистре.

    Определение своего шаблона расположения полей в редакторе сущности

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

    Поля из дескриптора сущности перебираются по очереди, для них в шаблоне ищутся макроподстановки, которые указывают куда выводить элементы формы и подписи. Использовать можно следующие локальные макроподстановки (нигде более они не работают):

    • Если для текущего поля из дескриптора в шаблоне найдена подстановка $FieldLabel[fieldid]$, то в этом месте будет выведено название (атрибут name тэга field с id =”fieldid”). Также для текущего поля будет автоматически обработан макрос $FieldControl[fieldid]$, который выводит элемент формы для редактирования согласно указанному в дескрипторе типу;
    • Если $FieldLabel[]$ для текущего поля из дескриптора в шаблоне нет, то будет поиск макроса вида $Field[fieldname]$, вместо которого будет выведено название и элемент формы (на одной строке, без переноса).

    Готовый к употреблению шаблон должен находиться в папке Admin/Templates. Если шаблон сущности в дескрипторе объявлен, но на диске не существует, то Система выдаст сообщение об ошибке.

    Иногда в процессе эксплуатации сайта появляется необходимость добавить одно-два поля к сущности. Для того, чтобы не переделывать HTML шаблон редактора сущности в Системе достаточно добавить это поле в дескриптор сущности в файле entities.xml. Все поля, которые не прописаны в шаблоне, но есть в entities.xml, будут автоматически дописаны к шаблону в конце.

    noemptyoption
    « к списку

    версия для печати

     
    © 2003-19 Страта Технологии (создание сайтов, разработка cms), Twilight CMS in english.
    Наш адрес: Москва, пр. Маршала Жукова д.51
    Тел.: (495) 222-6436, E-mail: , карта сайта, условия использования информации о CMS
    Звоните через Skype:  

    Реклама: