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

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

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

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

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

 

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

    News


    Назначение

    Вывод записей из справочника в заданном дизайне.

    Ключи

    source Строка, источник данных. Могут быть следующие варианты:
    • Имя таблицы со справочником (файла в папке Data). Расширение обычно указывать не нужно. Возможно указывать несколько таблиц через запятую, тогда результирующая выборка будет содержать все записи из них.
    • URL веб-сервиса, который выдает данные в формате .dat файлов (требуется установленная библиотека LWP). Несколько URL через запятую задать нельзя.
    • Начиная с версии 4.36 допустимо указывать псевдоним папки в библиотеке файлов: files://folder_alias, folder_alias2,...., folder_aliasN. В результате элементами справочника станут файлы, которые находятся в папке с псевдонимом (задается в админзоне - правым щелчком мыши по папке). Начиная с 4.43 наряду с псевдонимами папок допустимо использовать id папок, которые можно посмотреть в files.xml. Этот способ подходит для небольших сайтов, где папка создается разработчиком и не планируется её удалять и создавать заново. Нужно понимать, что в таком случае id папки изменится и все ссылки на этот id придется искать и корректировать разработчику вручную. Вложенные папки при этом не учитываются. Атрибутами справочника становятся атрибуты тэгов file в файле files.xml, то есть filename, filesize, filetype, id, title и т.д. плюс могут добавляться доп. свойства (см. "Библиотеку разработчика"). Порядок вывода записей будет соответствовать порядку следования файлов в библиотеке файлов, то есть ключ sort действовать не будет. Чтобы поменять порядок файлов используется мышь с удержанием Ctrl.
    design Строка, идентификатор (атрибут id) секции newsdesign в файле news_design.xml. Определяет какой дизайн используется для отрисовки справочника.
    filter Составной фильтр для выбора только определенных записей из таблицы.
    count

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

    Если значение положительное, например 5, то в выборке остается 5 "верхних" записей. Если значение отрицательное, например -3, то в выборке будут удалены 3 "верхние" записи.

    sort Параметр сортировки.
    condition Составное условие.
    items_per_page Число, ограничивает количество записей при постраничном выводе. Если ключ не задан, режим постраничного разбиения не используется.
    distinct Имя поля уникализации.
    designfile Строка, указывает xml файл в папке Templates где будет произведен поиск шаблона с идентификатором, определенным в ключе design. Данная опция присутствует в системе начиная с версии 4.38. Если не задан - по умолчанию используется стандартный файл news_design.xml. Расширение ".xml" в ключе можно не указывать.
    extrafield Perl выражение, результат вычисления которого помещается в специальное поле текущей записи с именем extrafield, которое может быть выведено на страницу или быть использовано как параметр для сортировки выборки. Например, если задать ключу extrafield значение sqrt(%fieldname%)+5, то в поле $Attribute:extrafield$ будут помещены квадратные корни от значений в поле fieldname той же записи плюс 5. Если при вычислении данного выражения произойдет ошибка, то в поле попадет само выражение, поэтому разработчик должен быть внимателен.

    Также, в ключе можно задать макрос, который будет обсчитываться для каждой записи в выборке, результат выполнения которого будет размещен в поле extrafield. Макрос должен быть записан так, чтобы все символы $, [, ], ; и : были предварены обратными слэшами. Например, для подключения из таблицы aaa поля title из записи с id равным значению поля parentid текущей записи, макрос должен быть записан как \$DataField\[source\: aaa\; filter\: id=%parentid%\; field\: title]\$. Это позволит передать макрос внутрь ключа и посчитать его уже при обработке записей, подставляя на каждом шагу обработки в макрос свое значение поля parentid. Если не квотировать слэшами макрос, макропроцессор сначала выполнит его и результат вставит в ключ, что даст неверный результат. Такой прием позволяет, например, выполнить сортировку записей по значению, которое находится в другой таблице, а также для других задач.

    Комментарии

    Общие сведения

    Справочник, это набор записей одинаковой структуры. Ближайшим аналогом данного понятия в теории баз данных является "таблица".

    Выборка - это набор записей, которые прошли фильтрацию, заданную в filter и отсечены ключом count.

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

    Все шаблоны оформления для любых справочников ("дизайны") хранятся в файле Templates/news_design.xml.

    Принцип работы макроса

    Принцип вывода данных с помощью данной макроподстановки на страницах сайта таков: в каждом дизайне определяются секции header, footer, item, delimiter, empty. При выводе записей из справочника из этих секций в цикле набирается конструкция:

    header
    item
    delimiter
    item
    delimiter
    ...
    item
    footer

    При отсутствии записей в выборке будет отрисована только секция empty.

    Таким образом, секция item отрисовывается в цикле при прохождении всех записей в выборке по очереди. Выборка - это набор записей, которые удовлетворили ключу filter макроса $News[]$. Чтобы вывести значение какого-либо поля для текущей записи в секции item необходимо использовать локальную подстановку $Attribute:fieldname$, где fieldname - имя нужного поля. То есть, подстановка $Attribute:id$, использованная в секции item, выведет значение поля id для каждой записи в выборке.

    Типовое применение шаблонов

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

    • На первой странице сайта выводятся несколько анонсов последних новостей с датами и ссылками «подробнее»;
    • На странице просмотра конкретной новости (/news/?nid=идентификатор_новости) выводится полное содержание со ссылкой на архив новостей;
    • На странице «архив новостей» (/news_archive) выводятся анонсы всех новостей со ссылками «подробнее».

    Постраничный вывод

    Постраничный вывод организуется автоматически при задании ключа items_per_page. При этом для вывода постраничного навигатора необходимо в дизайне вставить локальную макроподстановку {$}PageNavigator$. В HTML, который генерируется системой, можно увидеть, что постраничный навигатор использует CSS класс pages (и другие подклассы) при отрисовке. Разработчик может прописать эти классы в CSS чтобы менять внешний вид постраничного навигатора произвольным образом.

    Системные атрибуты

    Внутри дизайна вывода макроса $News[]$ возможно использование нескольких системных атрибутов, которые автоматически прописываются системой "на лету" (в таблицах на диске их нет). Используются они точно так же, через {$}Attribute:имяатрибута$.

    • drillnumber, сквозной номер от 1 до N. Присваивается только выводимым на странице записям (прошедшим фильтр и постраничную разбивку). Атрибут может быть использован только в секции item дизайна;
    • totalcount, число новостей в выборке. Постраничная разбивка не учитывается. Атрибут может быть использован в любой секции дизайна;
    • isFirst - индикатор первой записи в выборке. Возвращает 1 если запись первая или пустую строку, если это не так;
    • isLast - индикатор последней записи в выборке. Возвращает 1 если запись последняя или пустую строку, если это не так.

    Примечание: макросы в секции delimiter не отрабатываются, это статический блок для HTML кода.

    Модификаторы Prev и Next

    Иногда при просмотре элемента справочника (например, новости или картинки в галерее) требуется перейти к следующему или предыдущему элементу без возврата к общему списку. Для этого в дизайне можно воспользоваться модификаторами Prev и Next, позволяющими в момент обработки записи N получать все свойства соседних записей с номерами N-1 и N+1.

    Простой пример, который будучи использованным в news_design.xml даст полное понимание как это работает:

    <P>PREV <A HREF="/news/?nid=$Prev:Attribute:id$">$Prev:Attribute:caption$</A>
    <P>CURR <A HREF="/news/?nid=$Attribute:id$">$Attribute:caption$</A>
    <P>NEXT <A HREF="/news/?nid=$Next:Attribute:id$">$Next:Attribute:caption$</A>

    Нужно помнить, что у первой записи в выборке нет предыдущей, а у последней - нет следующей. Соответственно, обращение к их атрибутам будет возвращать пустоту. Проверить есть элемент или нет можно проверив атрибут Id, если он пустой - записи нет.

    Если в выборке после сортировки, выделения уникальных записей, ограничения количества и фильтрации останется несколько записей, то модификаторы Prev и Next будут возвращать правильные соседние записи. В особом случае, когда разработчик указывает в filter конструкцию id=..., которая должна вернуть только одну запись, система сама пристыкует к ней соседей по выборке, которая образовалась бы если бы фильтр по id не был указан.

    Внимание: модификаторы Prev/Next могут располагаться только в секции item дизайна, если их поставить в footer, header или delimiter, то они будут выведены как обычные строки.

    Примеры

    Пример №1
    $News[source: news; design: news_firstpage; count: 3]$ - ключ count указывает количество выводимых новостей. Если он опущен – выводятся все записи.

    Пример №2
    $News[source: news; design: news_details; filter: id=]$ - страница с конкретной новостью. Для вывода одной нужной новости задается ключ filter, значение которого определяется выражением поле=значение_поля. Вместо подстановки будет вставлено значение параметра nid переданного в ссылке.

    Пример №3
    $News[source: news; design: news_archive]$ - страница с архивом новостей.

    Пример №4
    $News[source: news; design: news_archive; condition: $Empty[]$]$
    $News[source: news; design: news_details; filter: id=; condition: $NotEmpty[]$]$ - cложное использование. Может применяться, например, когда вы организуете сложное меню с подсветкой, которая будет активирована на одном и том же пункте как при просмотре новости, так и при просмотре архива. В таком случае на странице необходимо использовать сразу две подстановки, идущие друг за другом, одна из которых будет отработана.

    Пример №5
    $News[source: jobs; design: jobs_firstpage; count: 3; sort: money, desc, auto]$ - в данном случае, используется еще один ключ, sort. Он позволяет задать имя поля, по которому произвести сортировку данных перед выводом, порядок сортировки и тип поля по которому производится сортировка.

    Пример №6
    $News[source: banners; design: banner_place; filter: state=on; count: 1; sort: random; nocache: on]$ - будет выведен один баннер (count: 1) из числа опубликованных (точнее с полем state в котором должно быть значение on), случайным образом взятый из выборки (sort: random), каждый раз при загрузке страницы баннер будет браться новый (nocache: on приводит к некэшированию макроса).

    Пример №7
    $News[source: files://folder_alias_1,folder_id_2; design: photogallery; count: 50; sort: reverse]$ - файлы из библиотеки файлов из папок с alias=folder_alias_1 и id=folder_id_2 будут выведены в дизайне photogallery (где можно выводить уменьшенные картинки и навигацию), вывод будет в обратном порядке (файлы добавляются в конец папок в админке, а выводить их обычно удобно по дате добавления в обратном порядке).

    « к списку макроподстановок

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

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

    Реклама: