Tagl. Краткое руководство

MatrixWalks™

Version 0.95

Содержание

1. Tagl -основа Front-end публикации MatrixWalks 2

1.1 Для чего нужен Tagl 2

1.2 Технология разработки страниц на TAGL 2

1.2.1 Проектирование 2

1.2.2 Разработка шаблонов 3

1.2.3 Компиляция и отладка 3

1.2.4 Дизайн и верстка страниц 3

1.2.5 Размещение готового сайта 4

1.3 Преимущества Tagl 4

1.3.1 Компактность и простота 4

1.3.2 Структурирование и декомпозиция 4

1.3.3 Многократное использование 4

1.3.4 Расширяемость 4

1.3.5 Разделение содержания и графического оформления страниц 4

1.3.6 Компиляция 5

2. Общее описание языка 6

2.2 Тэги. 6

2.2.1 Атрибуты. 6

2.3 Поля данных. 6

2.4 Вычисляемые атрибуты 7

2.5 Комментарии 8

3. Описание Тэгов 9

3.1 Использование шаблонов и макросов 9

3.1.1 <front:use> — использование шаблона 9

3.1.2 <front:tparam> — объявление параметра используемого шаблона 9

3.1.3 <front:def> — определение простых новых тэгов 9

3.2 <front:tif>, <front:telse> — условная компиляция 10

3.3 Использование шаблонов разметки и областей 10

3.3.2 <front:area> — создание области вывода 11

3.3.3 <front:toarea> — использование области вывода 11

3.4 Задание параметров страниц 12

3.4.1 <front:pageparam> — спецификация динамических параметров страниц 12

3.5 Использование общих шаблонов 12

3.6 Тэги для работы со списками 13

3.7 Доступ к контент–базе 15

3.7.1 <front:list> — вывод списка документов 15

3.7.2 <front:sectionlist> — вывод списка рубрик 16

НЕ нашли? Не то? Что вы ищете?

3.7.3 <front:section> — вывод рубрики 16

3.7.4 <front:document> — вывод документа 17

3.7.5 <front:images> — вывод привязанных изображений 17

3.7.6 <front:links> — получение связей между документами 18

3.8 Управляющие структуры 19

3.8.1 <front:if>, <front:else> — условное включение текста 19

3.9 Использование PHP 20

3.9.1 <front:php> — вставка PHP-кода 20

3.9.2 <front:echo> — вывод значения PHP–выражения 20

3.9.3 <front:declare> — определение полей данных 20

3.9.4 <front:phpdef> — определение вычисляющего тэга 20

2. Tagl - основа Front-end публикации MatrixWalks

2.1 Для чего нужен Tagl

Одной из главных задач применения MatrixWalks является управление публикацией документов на Веб-сайтах. И если IDE MatrixWalks полностью обеспечивает рубрицирование, создание, просмотр и редактирование Документов, предназначенных для публикации (back-end системы), то необходимо и средство, обеспечивающее собственно публикацию документов в Intranet/Internet для конечного пользователя – серверные страницы, реализующие Front-end системы.

Поэтому, когда Система MatrixWalks применяется для поддержки публикации документов на страницах Intranet/Internet сайтов, в качестве средства разработки этих страниц используется Tagl –язык описания шаблонов веб-страниц и компилятор с этого языка в исполнимые скрипты на PHP. (Tagl применяется также и для служебных целей MatrixWalks но для решения аналогичных задач)

Tagl не является языком форматирования как HTML или средством стилевого оформления как CSS, а предназначен для описания информационной структуры страницы, отвечая на вопросы – какие документы или их части, в каком случае и в каких сочетаниях публикуются на данной странице. Задачи оформления остаются по-прежнему возложенными на CSS и HTML, предложения которых просто вставляются в шаблон Tagl.

На Tagl можно описывать не страницы целиком, а ее определенные области, создавая, таким образом, стандартные информационные элементы для конструирования из них целых страниц.

2.2 Технология разработки страниц на TAGL

Шаблоны Tagl можно разделить на основные и вспомогательные. Каждый основной шаблон преобразуется в процессе компиляции в отдельный скрипт PHP. Вспомогательные шаблоны выступают только как части, используемые в других шаблонах.

Преобразование шаблона на языке Tagl в страницу, которую посетитель сайта видит в окне браузера, происходит в два этапа:

1. Компиляция шаблонов в скрипты PHP. Компиляция производится по запросу разработчика на backend-сервере. В процессе компиляции Tagl–компилятор преобразует основной шаблон в скрипт PHP, используя вспомогательные шаблоны и преобразуя тэги и ссылки на поля данных в соответствующие конструкции PHP.

2. Выполнение скриптов PHP. Запрос к frontend-серверу, посылаемый браузером посетителя сайта, приводит к выполнению интерпретатором PHP соответствующего скрипта, который и формирует страницу, отображаемую браузером. Результат выполнения может зависеть от параметров запроса и от текущего состояния контент–базы.

Важно различать, какие тэги работают на этапе компиляции, а какие — на этапе выполнения. Тэги, которые на этапе выполнения (см. ???) производят вычисления или осуществляют доступ к данным, будем называть динамическими.

Примером динамического тэга может служить тэг <front:list>, выводящий список документов, так как содержимое документов берётся из контент-базы на этапе выполнения.

Напротив, тэг <front:use> динамическим не является, поскольку его действие состоит в подключении внешнего шаблона на этапе компиляции.

2.2.1 Проектирование

Аналитик с помощью Microsoft Visio или Rational Rose Web Modeler или просто на листе бумаги в произвольной форме проектирует схемы страниц сайта, указывая для каждой, как называется страница, какие области вывода(Area) включает, какие документы или их части или списки документов показываются в каждой области.

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

Области на схеме страницы оформляются как прямоугольники с названием и описанием или соответствующим графическим значком. В качестве языка диаграмм удобно использовать Rational UML Web Application Extension (www. ) в комбинации с его расширением WebML (www. ).

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

2.2.2 Разработка шаблонов

Разработчик с помощью спроектированных схем программирует на Tagl шаблоны будущих веб-страниц. На данном этапе не стоит уделять слишком много внимание особенностям форматирования и дизайна – достаточно ограничиться простым табличным разбиением страницы на области согласно схеме.

Создавать Tagl-шаблоны можно либо в окружении MatrixWalks, либо в Macromedia Dreamweaver (расширение для которого поставляется в составе пакета MatrixWalks), либо в любом текстовом редакторе. При этом, если разработка идет на удаленном сервере, то лучше всего, чтобы редактор поддерживал протокол WebDAV (DreamWeaver поддерживает), хотя подходит и FTP. Поддержка WebDAV просто необходима, если разработка страниц производится несколькими разработчиками одновременно.

Единицей компиляции является файл с шаблоном. Один файл может содержать только один шаблон. Пакеты шаблонов в одном файле не допускаются. Для удобства наборы шаблонов можно оформлять в виде структуры папок файловой системы (аналогично пакетам Java).

2.2.3 Компиляция и отладка

Особенность Tagl в том, что шаблоны на нем не исполняются, а только компилируются в полностью самостоятельные скрипты на языке PHP. На этом этапе компилятор при разборе компилируемого шаблона подключает и все вызываемые внешние шаблоны. Таким образом, большая структура последовательно вызываемых Tagl-шаблонов может быть скомпилирована всего в один PHP-скрипт.

Компилятор вызывается либо из окружения MatrixWalks, либо из Macromedia Dreamweaver. В режиме отладки для удобства разработчика лучше применять “Режим просмотра страниц”, когда Tagl-шаблон компилируется в PHP-скрипт во временный файл, затем этот скрипт немедленно исполняется и результат его исполнения также немедленно показывается пользователю. Такой режим позволяет немедленно увидеть результат работы разработчика

2.2.4 Дизайн и верстка страниц

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

Если разработка шаблонов происходит в DreamWeaver c установленным расширением MatrixWalks, то дизайнер может тут же просматривать результаты исполнения сверстанных им страниц

Процесс Программирования и Верстки итеративный – по требованию дизайнера может понадобиться перепрограммирование Tagl и наоборот. А если требуется какой-то особенный “тюнинг”, то дизайнер может вносить изменения в уже скомпилированный конечный PHP-скрипт. При этом надо помнить, что первая же компиляция полностью уничтожит такой тюнинг, поэтому применять его можно только после полного окончания программирования страницы.

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

2.2.5 Размещение готового сайта

Скомпилированные PHP-скрипты реализующие страницы Front-end сайта вполне самостоятельны и не зависят от CMS MatrixWalks. Они работают с Базой данных документов MatrixWalks напрямую. Все что им нужно – обеспечить соединение с этой Базой данных.

Поэтому на одной БД MatrixWalks легко можно поддерживать несколько совершенно разных сайтов и, в общем случае, наоборот, создать один сайт. который будет работать с различными Базами Данных MatrixWalks (хотя это достаточно сложная задача и потребует “ручной” доработки страниц).

Как IDE MatrixWalks, так и расширение для DreamWeaver поддерживают компиляцию в “тестовый” и “рабочий” вариант сайта. Закончив разработку на тестовом сайте, окончательную компиляцию можно проводить в “рабочий” сайт, который может находиться на другом удаленном сервере. Если такой возможности нет, то можно ограничиться либо режимом просмотра для отладки (если есть только “рабочий” сайт) либо переносить на рабочий сайт отлаженные страницы с “тестового” (если удаленный сервер, на котором размещен “рабочий” сайт не поддерживает WebDAV).

2.3 Преимущества Tagl

2.3.1 Компактность и простота

Конечно, Вы можете разрабатывать страницы сайта на “чистом” PHP, используя MatrixWalks DataLayer API. Однако использование Tagl намного упрощает и ускоряет разработку, поскольку он не требует знания API, а предоставляет разработчику компактный набор простых в использовании тегов, который вместе с тем достаточно мощным, чтобы описывать 99% функциональности типичных сайтов.

2.3.2 Структурирование и декомпозиция

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

2.3.3 Многократное использование

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

2.3.4 Расширяемость

Язык можно дополнять как собственными тегами, описывая их на том же Tagl. так и включением в него вызовов функций и участков PHP-кода, также оформляя их в виде тегов.

2.3.5 Разделение содержания и графического оформления страниц

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

2.3.6 Компиляция

Здесь конечно, нет преимуществ перед PHP сточки зрения быстродействия – потому что код компилируется именно в PHP. (но есть преимущества перед другими схожими с Tagl по назначению. но интерпретируемыми макроязыками).

Но компиляция позволяет сильно структурированный наборTagl-шаблонов превратить в один большой скрипт PHP, которой при исполнении кэшируется в память сервера, уменьшив таким образом количество вызовов и обращений ко внешним файлов и время на анализ скрипта. Для часто посещаемых сайтов – это может быть очень большой выигрыш в производительности.

3. Общее описание языка

Файлы, содержащие текст на языке шаблонов Tagl, мы будем называть шаблонами.

Язык содержит три типа конструкций:

· XML–тэги;

· ссылки на поля данных;

· комментарии.

3.1.1.1.1 Пример: простейший шаблон страницы

<front:pageparam name=”one” default=’World’/>

<p> Hello, %page. one% !!

3.2 Тэги.

Основной конструкцией языка шаблонов являются XML-тэги. Компилятор Tagl принимает во внимание только тэги в пространстве имён front (например, <front:section>, <front:if>). Весь остальной текст, за исключением конструкций подстановки данных, считается неструктурированным, то есть специальные символы XML в нём компилятор воспринимает как обычные. Иначе говоря, все что не является элементами Tagl, компилятор просто переносит в результирующий скрипт.

Таким образом, не нужно следить за тем, чтобы шаблон был правильно построенным XML–документом. В частности, можно использовать обычный синтаксис HTML, а не XHTML.

Однако, front–тэги должны подчиняться правилам XML. В частности, они должны быть правильно вложены друг в друга.

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

3.2.1 Атрибуты.

Атрибуты тэгов также должны быть правильными с точки зрения синтаксиса XML.

Символ двойных кавычек в значении атрибута допустимо использовать, только если значение атрибута задано в одинарных кавычках, и наоборот.

Использование специальных символов XML в значениях атрибутов недопустимо. Вместо них надо использовать соответствующие XML-сущности:

· вместо ‘>’ — > ,

· вместо ‘<’ — < ,

· вместо ‘&’ — &.

Для обозначения одинарных и двойных кавычек в атрибутах можно использовать XML–сущности ‘'’ и ‘"’.

Никакие другие XML-сущности, кроме перечисленных выше, в значениях атрибутов front-тэгов использовать нельзя (см. пример ниже).

Пример — специальные символы в атрибутах:

<front:mytag title=”Only 300 &euro;” motto=’Don't say “no”’/>

;;; Фактические значения:

;;; title: Only 300 €

;;; motto: Don’t say “no”

3.3 Поля данных.Подстановка данных

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

Подстановка полей данных в выводимый текст производится в теле тэга с помощью ссылок следующего вида:

%имя структуры. имя поля%

или просто

%имя поля%,

если имя структуры не задано.

Для задания имени структуры динамические тэги обычно имеют атрибут name.

Когда поля данных используются не для вывода, а для вычислений (например, в вычисляемых атрибутах вложенных тэгов (см. ???) или во включениях PHP-кода), употребляется ссылка со знаками ‘#’ вместо ‘%’:

#имя структуры. имя поля#

или

#имя поля#.

Пример —— поле данных в вычислении:

<front:echo>#doc. NUMBER# + 10</front:echo>

Подчеркнём ещё раз, что доступ к полям данных возможен только внутри тэга, который формирует соответствующую структуру. Исключениями являются тэги <front:pageparam> и <front:declare>, которые объявляют поля данных, доступные и вне этих тэгов.

3.4 Вычисляемые атрибуты

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

Вычисляемые атрибуты задаются следующим образом:

имя атрибута=”=выражение”

Здесь выражение - это выражение PHP, в котором, в частности, можно использовать ссылки на поля данных.

Пример — вычисляемый атрибут:

<front:list name=”doc” section=”=#page. sect#” docclass=”news”>

;;; section – вычисляемый атрибут

;;; равный значению параметра запроса sect

Один и тот же атрибут может быть как статическим, так и вычисляемым. Вот пример, в котором параметр section не является вычисляемым:

<front:list name=”doc” section=”newslist” docclass=”news”>

;;; section не является вычисляемым атрибутом

3.5 Комментарии

Комментарием считается часть строки после трёх идущих подряд символов ‘;’, включая символ новой строки в конце. Комментарии не попадают в выводимый текст.

<img src=”dot. gif” ;;; это пример комментария

alt=”test”>

;;; в выводимом тексте будет <img src=”dot. gif” alt=”test”>

4. Описание Тэгов

4.1 Использование шаблонов и макросов

Части Tagl-текста по разным соображениям бывает удобно выделять в отдельные шаблоны; например, если этот текст используется в нескольких скриптах PHP, или просто если он образует логически цельную часть, оформление которой в виде отдельного файла делает структуру шаблонов более понятной.

4.1.1 <front:use> — использование шаблона

Чтобы использовать в шаблоне текст из других шаблонов, применяется тэг <front:use>. Компилятор заменяет этот тэг на текст, порождаемый используемым шаблоном. Подчеркнём, что эта замена происходит во время компиляции, т. е. порождаемый используемым шаблоном текст не образует отдельного PHP-скрипта, а входит в текст скрипта использующего шаблона.

Используемые шаблоны могут иметь параметры. Ссылки вида %имя параметра% в тексте используемого шаблона заменяются во время компиляции на значение параметра, заданное атрибутом tmpl:имя параметра тэга <front:use>. Параметры объявляются в используемом шаблоне тэгами <front:tparam>.

Атрибуты

template — имя шаблона.

tmpl:имя параметра — значение параметра шаблона, если указанный в атрибуте template шаблон имеет параметр с таким именем.

once — если этот атрибут имеет значение true, то шаблон используется не более одного раза при компиляции одного основного шаблона, то есть только в том случае, когда он не был использован ранее с помощью другого тэга <front:use>.

4.1.2 <front:tparam> — объявление параметра используемого шаблона

Атрибуты

name — имя параметра.

default — значение параметра по умолчанию.

Если атрибут default отсутствует, и при использовании шаблона значение атрибута tmpl:имя параметра не задано, при компиляции возникает ошибка.

4.1.3 <front:def> — определение простых новых тэгов

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

С помощью тэга <front:def> можно определить свои собственные новые тэги. Вхождения нового тэга будут заменены на его определение, то есть тело тэга <front:def>; при этом тело этого вхождения будет подставлено вместо ссылки %body% в определении тэга, а значения его атрибутов будут подставлены вместо ссылок вида %имя атрибута%.

Переопределять уже существующие тэги нельзя.

4.1.3.1 Пример

Определение тэга:

<front:def name=”mydiv” params=”script”>

%body%

</div>

</front:def>

Использование тэга:

<front:mydiv script=”alert(‘Welcome!’)”>

Just click over here!

</front:mydiv>

Выводимый текст:

Just click over here!

</div>

4.1.3.2 Атрибуты

name — имя тэга

params — список атрибутов определяемого тэга, через запятую

4.2 <front:tif>, <front:telse> — условная компиляция

Эти тэги можно использовать во вспомогательных шаблонах для компиляции фрагментов текста только при выполнении указанных условий. Действие этих тэгов заключается во включении или не включении соответствующих фрагментов кода в скомпилированный PHP-скрипт. Выполнение условий проверяется во время компиляции, поэтому атрибут value почти всегда есть просто ссылка на параметр шаблона ( %имя параметра% ).

4.2.1.1 Синтаксис

<front:tif value=”%имя параметра%” условие=”эталон” >

текст, компилируемый в случае, когда условие истинно

<front:telse>

текст, компилируемый в случае, когда условие ложно

</front:else>

</front:if>

Проверка условия заключается в сравнении параметра, указанного в атрибуте value с эталоном. Имеется два условия:

· eq — проверка на равенство параметра эталону;

· neq — проверка на неравенство параметра эталону.

Вложенный тэг <front:else> не является обязательным.

4.3 Использование шаблонов разметки и областей

Во фронтэнд-библиотеке Tagl имеется возможность выводить большие фрагменты текста в указанные места используемого шаблона — области. Подстановка областей, как и подстановка параметров, происходит во время компиляции.

С помощью областей можно создавать, например, шаблоны разметки страниц: шаблон разметки содержит общее оформление (обрамление) страниц и задаёт одну или неколько областей. Шаблон, использующий данный шаблон разметки содержит соответствующий тэг front:use, в теле которого в тэгах front:toarea задано наполнение соответствующих областей.

4.3.1.1 Пример

Пример иллюстрирует использования включаемого шаблона с параметром title. Шаблон имеет две именованные области вывода — boldtext и bigtext, в которые включающий шаблон направляет некоторый текст, а также выводит значение переданного параметра.

Включаемый шаблон находится в файле: antoshka. tagl:

<front:tparam name=”title” default=”Без названия”/>

<h1>%title%</h1>

That’s how it goes!

Включающий шаблон:

<front:use template=”antoshka. tagl” tmpl:title=”Ант”>

<front:toarea name=”bigtext”>

не проходили

</front:toarea>

<front:toarea name=”boldtext”>

Это мы

</front:toarea>

</front:use>

Результат компиляции включающего шаблона:

<b>

Это мы

</b>

не проходили

</font>

That’s how it goes!

4.3.2 <front:area> — создание области вывода

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

4.3.2.1 Атрибуты

name — имя области

4.3.3 <front:toarea> — использование области вывода

Этот тэг обрамляет текст, который будет выведен в указанную область шаблона, подключаемого родительским тэгом <front:use>.

4.3.3.1 Атрибуты

name — имя области

4.4 Задание параметров страниц

Для работы с динамическими параметрами страниц (GET - или POST-переменными запроса HTTP) используется тэг <front:pageparam> и структура page.

4.4.1 <front:pageparam> — спецификация динамических параметров страниц

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

Значение параметра можно печатать с помощью ссылки вида %page. имя параметра% или использовать в вычисляемых атрибутах или PHP-коде с помощью ссылки вида #page. имя параметра#.

4.4.1.1 Атрибуты

name — имя параметра

default(php) — значение по умолчанию

4.4.1.2 Пример

<front:pageparam name=”Topic” default=”root”/>

4.5 Использование общих шаблонов

Если при компиляции основного шаблона в его каталоге или в одном из родительских каталогов находится файл с именем common. tagl, то он будет использован в начале компиляции данного основного шаблона, как если бы в его начале стоял тэг <front:use template=каталог/common. tagl/>.Поэтому общие шаблоны удобно использовать для кода, одинакового для всех файлов, находящихся в данном каталоге.

4.6 Тэги для работы со списками

Список — это упорядоченный набор структур, каждая из которых имеет одни и те же поля. Таким образом, структуры списка можно представить себе как строки таблицы с определённым набором столбцов (полей данных). В общем случае длина списка (число строк в таблице) заранее неизвестна; она определяется только во время выполнения скомпилированной страницы и может зависеть от динамических атрибутов тэга списка и от состояния контент-базы.

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

Списки формируются с помощью таких тегов как <front:list>, <front:sectionlist>, <front:links>, <front:images> и других, имеющих общий синтаксис, описанный ниже. Можно также определять собственные списковые тэги (см. описание тэга <front:phpdef>.

В теле списковых тегов обеспечивается доступ к содержимому списка. Это происходит следующим образом:

Если список непустой, и внутри него имеется вложенный тэг <front:row>, то один раз выводится текст до тэга <front:row>, затем для каждой строки списка выводится тело тэга <front:row>, затем один раз выводится текст после <front:row>. Если список непустой, и вложенного тэга <front:row> в нём нет, то для каждой строки списка выводится весь текст тела тэга списка, за исключением тэга <front:emptylist>, если он присутствует. Если же список пустой, то выводится только тело тэга <front:emptylist>, если он присутствует. Поля данных списка в целом доступны всюду в теле тэга списка. Поля структуры доступны только внутри тэга <front:row>, если он присутствует, или, в противном случае, всюду, кроме тела тэга <front:emptylist>.

4.6.1.1 Синтаксис

<front:имя тэга атрибуты>

текст до начала непустого списка

<front:row>

текст для каждой строки со %ссылками% на #поля# строки

</front:row>

текст после окончания непустого списка

<front:emptylist>

текст, выводимый когда список пуст

</front:emptylist>

</front:имя тэга>

4.6.1.2 Атрибуты

name — имя структуры для ссылки

Для листаемых списков:

startrow(php) [1] — номер первой выводимой строки, начиная с 1

rowcount(php) [0] — количество выводимых строк

4.6.1.3 Поля

length — длина списка (количество строк в нём), равна нулю для пустого списка

index — номер строки в списке

Для листаемых списков:

RecordCount — общее количество записей

cur_row — номер текущей строки в исходном списке

CurrentRow — синоним cur_row

next_row — номер первой строки на следующей странице

prev_row — номер первой строки на предыдущей странице

relativeRow — относительный номер (CurrentRow-startrow + 1)

4.7 Доступ к контент–базе

В данном разделе описаны теги, позволяющие получать из контент-базы MatrixWalks конкретные документы, рубрики, картинки и их списки, а также списки ссылок на “привязанные” документы.

4.7.1 <front:list> — вывод списка документов

Для доступа к документам, хранящимся в контент-базе MatrixWalks, используется тэг <front:list>, который формирует листаемый список (см. выше раздел «Списки»), строки которого содержат данные из полей выбранных документов.

Список формируется в соответствии с ограничениями, налагаемыми атрибутами тэга <front:list>.

4.7.1.1 Атрибуты

name [doc] — имя структуры

section(php) — рубрика, из которой выбираются документы. Eсли атрибут отсутствует или является пустой строкой, то выбираются документы из всех рубрик.

docclass(php) — код класса документов, которому должны принадлежать выбранные документы

orderby — порядок документов в списке. перечисляет поля документа с указанием направления сортировки в формате языка SQL: имя поля [ ASC|DESC]{,имя поля [ ASC|DESC]} (например, orderby=“TITLE DESC”). Можно использовать любые поля документа, кроме тех, которые физически хранятся в универсальных полях (универсальные поля имеют имена f0, f1, f2, …).

where — дополнительные фильтрующие условия в формате языка SQL для предложения WHERE (например, where=”TITLE LIKE ‘A%’”). Можно использовать поля документа с теми же оговорками, что и для атрибута orderby.

startrow(php)[1] — порядковый номер документа в списке, с которого начинается текущая страница.

rowcount(php)[0]— Количество документов на текущей странице. Если rowcount=0, все документы начиная со значения startrow выбираются для текущей страницы.

id(php) — ID документа. Если этот атрибут присутствует и не пуст, выбирается только документ с указанным ID, а атрибуты startrow и rowcount игнорируются.

template — имя шаблона, который используется вместо тела тэга. например, можно заготовить шаблон для отображения документов определённого типа, и использовать этот шаблон на разных страницах сайта. Для полей структуры списка в шаблоне можно использовать ссылки вида %.имя поля% и #.имя поля# (с пустым именем структуры).

tmpl:параметр — значение параметра шаблона, если указанный в атрибуте template шаблон имеет параметр с таким именем.

4.7.1.2 Поля

имя поля — имя поля документа, в соответствии с моделью данных класса, указанного в атрибуте docclass. Имена структур разделяются символом ‘/’.

ID — ID текущего документа

TITLE — заголовок текущего документа

NUMBER — порядковый номер текущего документа (внимание: это не то же самое, что номер документа в списке)

4.7.2 <front:sectionlist> — вывод списка рубрик

Для доступа к рубрикам, хранящимся в контент-базе MatrixWalks, используется тэг <front:sectionlist>, который формирует листаемый список (см. выше раздел «Списки»), строки которого представляют подрубрики указанной в атрибуте section рубрики. В список попадают только активные рубрики.

Для вывода нескольких уровней подрубрик следует использовать вложенные тэги <front:sectionlist>, причём у дочерних тэгов атрибут section не указывается.

4.7.2.1 Атрибуты

name — имя структуры

section(php) — код родительской рубрики. Если этот атрибут опущен, его значение берётся из объемлющего тэга <front:sectionlist> или <front:section>; если же таких объемлющих тэгов нет, выдаётся сообщеие об ошибке. Если section есть пустая строка, то в качестве родительской берётся корневая рубрика.

4.7.2.2 Поля

name — заголовок

shortname — код текущей подрубрики

numchildren — количество дочерних подрубрик текущей рубрики

level — уровень текущей рубрики в иерархии. корневая рубрика имеет уровень 0.

4.7.3 <front:section> — вывод рубрики

Для получения данных о рубрике используется тэг <front:section>.

4.7.3.1 Атрибуты

name — имя структуры

shortname(php) — код рубрики

4.7.3.2 Поля

name — заголовок рубрики

numchildren — количество дочерних подрубрик

level — уровень рубрики в иерархии. корневая (псевдо)рубрика имеет уровень 0.

4.7.4 <front:document> — вывод документа

Для получения полей документа по его ID используется тэг <front:document>.

4.7.4.1 Атрибуты

id(php) — ID документа

docclass(php) — код класса документа; наличие этого атрибута ускоряет доступ к документу

4.7.4.2 Поля

имя поля — имя поля документа, в соответствии с моделью данных класса, указанного в атрибуте docclass

ID — ID текущего документа

TITLE — заголовок текущего документа

NUMBER — порядковый номер текущего документа (внимание: это не то же самое, что номер документа в списке)

4.7.5 <front:images> — вывод привязанных изображений

Получить список изображений, привязанных к данному документу, находящихся в данной рубрике или же имеющих данный ID, можно с помощью тэга <front:images>.

Обработанные изображения хранятся в каталогах images/photo/1 (избражения исходного размера), images/photo/2 (изображения среднего размера) и images/photo/3 (изображения маленького размера). Имя файла обработанного изображения (одно и то же для трёх каталогов) находится в поле filename.

4.7.5.1 Атрибуты

document(php) — ID документа

forderid (php) — код или ID рубрики

uniqueid (php) — ID изображения

maxcount (php) — максимальное количество изображений

4.7.5.2 Поля

name — название

author — автор

source — источник

filename — имя файла обработанного изображения

origfile — имя исходного файла (в каталоге images/photo/orig)

desc — описание

4.7.6 <front:links> — получение связей между документами

Для получения списка связей между документами, а также связей между документами и внешними web-ресурсами применяется списковый тэг <front:links>.

Получить информацию о ссылках можно тремя взаимно исключающими способами:

1) по ID документа, из которого имеются ссылка (sourceid);

2) по ID документа, на который имеются ссылки (targetid);

3) по ID ссылки.

4.7.6.1 Атрибуты

sourceid(php) — ID документа, из которого имеются ссылка

targetid (php) — ID документа, на который имеются ссылки

id (php) — ID ссылки

4.7.6.2 Поля

id — ID Ссылки

name — название ссылки

url — адрес (для ссылки на внешний web-ресурс)

document — ID документа (для ссылки на документ)

4.8 Управляющие структуры

4.8.1 <front:if>, <front:else> — условное включение текста

Для организации динамического ветвления на этапе выполнения (например, для того, чтобы использовать разное оформление выводимых документов в зависимости от значений их полей), используются тэги <front:if> и <front:else>.

Если условие, указанное в атрибуте test тэга <front:if> выполняется, то будет выведен текст тела тэга <front:if> до тэга <front:if>; если же условие не выполняется, то будет выведено тело вложенного тэга <front:else>, если он присутствует.

Вложенный тэг <front:else> не является обязательным.

4.8.1.1 Синтаксис

<front:if test=”=условие”>

текст, выводимый в случае, когда условие истинно

<front:else>

текст, выводимый в случае, когда условие ложно

</front:else>

</front:if>

4.8.1.2 Атрибуты

test — условие ветвления

Обратите внимание, что хотя атрибут test динамический, ставить знак равенства перед PHP-выражением в значении этого атрибута не нужно.

4.8.1.3 Пример

<front:if test=”#pany/address#==’’”>

<i> No address was specified. </i>

<front:else>

<b> Address: </b> %pany/address%.

</front:else>

</front:if>

4.9 Использование PHP

4.9.1 <front:php> — вставка PHP-кода

Тело тэга <front:php> интерпретируется как PHP–код. В этом коде могут встречаться ссылки на любые доступные в этом месте шаблона поля вида #имя поля#,которые будут преобразованы в соответствующие PHP–выражения.

4.9.2 <front:echo> — вывод значения PHP–выражения

Этот тэг эквивалентен тексту <front:php>echo выражение</front:php>, где выражение задаётся либо как значение атрибута exp, либо как тело тэга.

4.9.2.1 Атрибуты

exp — выражение, значение которого должно быть выведено

4.9.2.2 Пример

<front:echo>#doc. NUMBER# + 10</front:echo>

4.9.3 <front:declare> — определение полей данных

Этот тэг позволяет определить собственные поля данных. Это удобно делать, когда имеется PHP-код, производящий некоторые вычисления. В этом случае результаты вычислений можно сохранить в полях данных, определяемых с помощью тэга <front:declare>; при этом поля становятся доступными с помощью ссылок на них.

4.9.3.1 Атрибуты

name — имя поля

value — начальное значение поля

type — тип поля; возможные значения: string, array, integer, boolean

Если поле имеет тип (type) array, то к элементам массива можно обращаться с помощью ссылок вида #имя поля. имя элемента# и %имя поля. имя элемента%.

4.9.4 <front:phpdef> — определение вычисляющего тэга

Этот тэг предназначен для создания собственных динамических тэгов, и таким образом для расширения набора тэгов frontend-библиотеки Tagl.

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

<front:phpdef …>

<front:attr name=”…”/> ;;; обязательный атрибут

<front:attr name=”…” default=”…”/>

;;; здесь может быть код вычисляющей функции (см. ниже)

</front:phpdef>

4.9.4.1 Тэг, вычисляющий одно значение

<front:phpdef name=”имя тэга” resultval=”имя вычисляемого поля”...>...

Вычисляющая функция должна возвратить единственное значение, которое будет доступно в теле определяемого тэга под именем, указанным в атрибуте resultval. Если тело тэга пусто, то это значение будет напечатано.

4.9.4.2 Тэг, вычисляющий структуру

<front:phpdef name=”имя тэга” resultstruct=”список полей”...>...

Вычисляющая функция должна возвратить ассоциативный массив, индексированный именами полей, указанными в атрибуте resultstruct. Эти поля будут доступны для подстановки в теле определяемого тэга.

4.9.4.3 Тэг, вычисляющий список

<front:phpdef name=”имя тэга” iterate=”yes” resultstruct=”список общих полей” resultrow=”список полей строки”...>...

Вычисляющая функция должна возвратить ассоциативный массив, индексированный именами полей, указанными в атрибуте resultstruct (эти поля будут доступны для подстановки в теле определяемого тэга). Кроме того, в элементе массива с индексом rows функция должна возвратить массив строк (ассоциативных массивов с полями, указанными в атрибуте resultrow).

4.9.4.4 Задание вычисляющей функции

Вычисляющая функция может быть задана двумя способами:

1) имя функции указывается в атрибуте function; при необходимости в атрибуте require указывается PHP-файл, содержащий определение функции. Аргументами функции будут значения атрибутов, переданные в порядке следования тэгов front:attr, плюс, возможно, атрибуты родителя (см. определение вложенных тэгов)

2) код тела функции располагается в теле тэга front:phpdef (на это указывает отсутствие атрибута function). В этом случае определение функции будет вставлено в начало скрипта страницы, содержащей определяемый тэг. Формальными аргументами функции будут значения атрибутов с именами $имя атрибута , плюс, возможно, атрибуты родителя (см. определение вложенных тэгов).

4.9.4.5 Определение вложенных тэгов

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

name — имя тэга

function — имя вызываемой функции.

iterate [no] — (yes/no) значение yes указывает на то, что тэг возвращает список

resultstruct — список имён полей возвращаемой структуры через запятую

resultval — имя единственного возвращаемого поля

resultrow — список имён полей для строк возвращаемого списка через запятую

require — имя файла. php, который необходимо подключить при выполнении страницы, содержащей определяемый тэг

parenttag — имя родительского тэга