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

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

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

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

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

 

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

    Общие принципы работы с макросами


    Назначение

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

    В справочнике по макросам (http://www.twl.ru/tsdn/macroses) вы найдете конкретные примеры использования и подробное описание алгоритма работы и ключей каждого макроса. В данной статье перечисляются общие для всей системы макросов свойства.

    Ключи

    нет

    Комментарии

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

    Макросы могут быть отключены в определенных блоках принудительно с помощью локальных макрозамен $NOMACRO_START$ и $NOMACRO_FINISH$. Это применяется обычно для документирования и иных схожих целей.

    Общий вид записи любого макроса

    $MacrosName[key1: value1; key2: value2; ...; filter: fieldname=fieldvalue; condition: boolean; nocache: boolean]$

    key1..keyN - это ключи, value1..valueN - значения ключей. Ключи задают определенные параметры выполнения макроса, его входные данные, такие как порядок сортировки полей, имена таблиц с данными и тому подобное. Значения ключей могут (если не указано обратное) заключаться в кавычки, которые будут игнорированы при выполнении макроса. Важно понимать:
     - кавычки обязательно должны присутствовать, если значение ключа в момент выполнения макроса может располагаться на нескольких строках.
     - один ключ от другого отделяется с помощью "точки с запятой", но помимо этого рекомендуется ставить пробел после точки с запятой, чтобы макропроцессор
     - если внутри значения ключа могут быть символы "двоеточие", или "точка с запятой", во избежании ложной обработки таких последовательностей макропроцессором рекомендуется квотировать данные символы, то есть предварять их символом "обратный слэш" ("\"). Если квотирование может быть также неверно интерпретировано, например, при выводе блоков javascript, используйте макросы QuoteText и Replace.

    Общие для многих макросов ключи

    filter

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

    Слева в условии (значение А) должно быть имя поля, значение которого будет использоваться при сравнении, а справа (значение В) может быть как макросом, так и жестко прописанной константой.

    Возможные условия:

    • A>B ("больше")
    • A!>B, A<=B ("не больше", синоним "меньше либо равно")
    • A<B ("меньше")
    • A!<B, A>=B ("не меньше", синоним "больше либо равно")
    • A=B ("равно")
    • A!=B ("не равно")
    • A in B (строка A входит в строку B)
    • A !in B (строка A не входит в строку B)
    • A rin B, A contains B (reverse in, строка B входит в строку A, или, что то же самое, A содержит B)
    • A !rin B, A !contains B (not reverse in, строка B не входит в строку A, или, что то же самое, A не содержит B)

    Если A и B являются положительными или отрицательными числами, или нулями, то сравнение значений будет вестись как числовых (кроме условий in и rin). Десятичным разделителем для заданных значений и для значений из базы могут быть как точки, так и запятые.

    Если A и B удовлетворяют маске DD.MM.YYYY или hh:mm:ss DD.MM.YYYY, сравнение идет в формате "дата-время" (кроме условий in и rin).

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

    Значение B не должно быть обрамлено кавычками, т.к. кавычки будут считаться за обычный символ.

    Значение B не может содержать запятых. Поэтому, если они возможны в результате выполнения макроса или в константе, то их необходимо заменять на "\," (без кавычек) с помощью макроса Replace.

    Значение B может содержать несколько вариантов, которые расцениваются как "логическое ИЛИ", разделенные "||", то есть A = B||B1||B2. Данная возможность употребляется редко, т.к. почти полная её эмуляция достигается конструкцией вида A in "B.B1.B2", где точки нужны только как разделители разных значений, и вместо них может быть что угодно другое (пробел, тире и так далее) в зависимости от логики проекта.

    Пример

    В справочнике есть поле color, которое может принимать значения blue, red, green. Для чтого, чтобы вывести записи со значениями green и blue в одной выборке нужно написать ключ filter так:

    filter: color in blue.green (вместо точки можно использовать любой символ кроме запятой, даже пробел).

    Если мы хотим проверить одновременно несколько условий, пишем их через запятую:

    filter: color in blue.green, weight >= 20, weight <=100, brand != Prada

    sort

    Режим сортировки записей. Через запятую перечисляются три параметра:

    • имя поля по которому сортируют или несколько имен полей через / в порядке использования при сортировке;
    • asc или desc (восходящая/нисходящая) сортировка, если полей несколько - несколько asc или desc через / соответственно заданным в первом параметре полям;
    • режим сравнения значений: literal (строковые), numeric (числовые), date(дд.мм.гггг), datetime (чч:мм:сс дд.мм.гггг), auto (автоматическое определение типа по первой записи в справочнике), если полей несколько - перечисляется несколько режимов через / для каждого из них.

    Если ключ не задан, его значение по умолчанию будет равно "date, desc, auto".

    Также, данный ключ может иметь особые, "не тройные" значения:

    • random, записи в выборке будут перемешаны случайным образом (после фильтрации);
    • reverse, записи будут выведены в обратном порядке.
    • extrafield, записи сортируются по создаваемому на лету, вычислимому полю (только в макросе News).

    Пример

    sort: date, desc, auto
    sort: state/created, desc/asc, literal/auto
    sort: random
    sort: reverse

    distinct

    Содержит имя поля, по содержимому которого будут удалены все дубликаты в выборке. Если в выборке есть записи, которые дублируют друг друга полностью или частично, то используя этот ключ можно задать имя поля, значение которого не должно повторяться. К примеру, если в записи 1 есть имя (поле firstname) Алексей и в записи 2 есть такое же имя в том же поле, то задав ключ как distinct: firstname в выборке появится только запись 1, а вторая будет проигнорирована.

    condition

    Составное условие выполнения макроса. Специальный ключ, который обычно реализуется у любого макроса (но может отсутствовать если в нем нет смысла или если макрос написан сторонним разработчиком). В качестве значения в него передается строка из boolean переменных через запятую. Под boolean строкой понимается любое из значений on/1/true/yes, которые будут заставлять макрос выполняться, или значений "пустая строка"/0/false/no, которые приведут к тому, что макрос не будет выполняться и вместо макроса будет выведена пустая строка. В то же время, если ключ condition вообще не задан, макрос будет выполнен безусловно.

    Пример

    condition: 986F8D3F0489456781060C37BECD297B=125, !=, $Attribute:id$="123456"

    "Логическое И" в условиях выполнения макросов

    В condition можно передавать комбинацию условий, разделяемых запятыми (и пробелами после запятых, которые будут игнорироваться). Все условия будут объединены операцией "логическое И", то есть общее условие будет истинно, если будут истинны все его составляющие. Например, запись "condition: 1, 0, 1, 1" будет эквивалентна "condition: 0", а "condition: on, yes, 1, true" будет эквивалентна "condition: 1".

    Таким образом, condition позволяет просто реализовывать ситуацию, когда макрос выполняется только если все условия истинны.

    "Логическое ИЛИ" в условиях выполнения макросов и более сложные комбинации условий

    Ситуация, когда макрос должен быть выполнен если выполнено любое из перечисленных условий, непосредственно в ключе condition не реализуется, но её можно решить следующими способами:
     - Посредством записи нескольких одинаковых макросов друг за другом, каждый из которых будет выполнен только при выполнении какого-то из условий. Обычно это достаточно удобно с точки зрения чтения кода, но если истинны будут одновременно несколько условий, макросы сработают больше раз чем нужно. Поэтому этот способ годится не всегда, хотя для подавляющего большинства ситуаций этого достаточно.
     - Можно сначала вычислить условия с помощью других макросов, а затем результат подать в ключ condition.

    Например, у нас есть два атрибута $Attribute:a$ и $Attribute:b$, привязанные к полям типа checkbox, и следовательно принимающие значения on или "пустая строка". Нам нужно выполнить макрос News только один раз при условии ИЛИ (истинно любое условие или оба сразу). Запишем атрибуты подряд: $Attribute:a$$Attribute:b$, получив в результате строку onon. Затем можно подать данную строку внутрь макроса $NotEmpty[]$, который на выходе даст "истина" в случае любой непустой строки, а в случае если оба атрибута будут пустыми - значение "ложь". В итоге искомый результат мы получим при такой записи:

    $News[table: ...; design: ...; condition: $NotEmpty[$Attribute:a$$Attribute:b$]$]$

     - Можно использовать специальные возможности макроса Math, который позволяет вычислять логические выражения в нотации языка Perl, например, вполне легально можно вычислить выражение вида (1 || 1) && 0. Единственно, все параметры подобного выражение, конечно, должны будут быть строками, с которыми можно проводить логические операции, в данном случае строками "1" или "0".

    Обработка макросов

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

    Написание собственных макросов

    Разработчик знакомый с языком Perl может реализовывать любые свои функциональности создавая свои собственные макросы. Как это сделать подробно описано в соответствующих статьях раздела "Книга рецептов" (http://www.twl.ru/tsdn/cookbook). Самый простой путь - взять небольшой макрос типа Empty или Or, посмотреть в код (папка /cgi-bin/Macro), выбросить ненужное, написать своё, переименовав макрос и единственную в нем процедуру так, как нужно разработчику.

    Примеры

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

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

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

    Реклама: