Работа с шаблонами

Поле

Для подключения полей необходимо подключить файл с шаблонами полей

1
#include <fields>// подключаем файл fields.tpl все поля ввода в системе

Виды полей

Простое поле

1
[[field | type: input | name: name | object: data | inputsize: sLarge | size: span3]]

image013


Большое поле (textarea)

1
[[field | type: textarea | object: data | name: comment]]

image015

Поле даты

1
[[field | type: date | object: data | name: date | format: date | tags: disabled]]

image016

Поле даты и времени

1
[[field | type: datetime | object: data | name: date | format: date | tags: disabled]]

image018

Выпадающий список

1
[[field | type: select | object: data | name: contract | field: number]]

image021

Поле выбора

1
[[field | type: formSelect | object: data | name: owner | field: name | form: /companies/select/]]

Поля выбора представляют собой поле, которое можно заполнить, выбрав что-то, воспользовавшись поиском в специальном «Модальном окне».
image022

По щелчку на лупе открывается следующее окно:

image024

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

Иногда бывает необходимость подгрузить какие-либо поля при выборе позиции в поле выбора. Чтобы не писать дополнительный код, используется встроенный механизм.
В примере выше было необходимо выбрать контрагента, но теперь нам необходимо «подгрузить» еще и «Юридические лица» этого «Контрагента» в выпадающий список. Для этого используется следующая конструкция.

Поле списка, зависящее от поля выбора

1
[[field | type: subSelect | master: owner | object: data | name: company_details | field: name]]

В поле master указываем поле выбора.

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

1
[[field | type: input | object: data | name: phone | accept: : company_details.phone]]

и в поле «Телефое» автоматически «подгрузится» информация о телефоне выбранного «Юридического лица».

Свойства полей

  • type – тип поля (input, select, date и т. д.)
  • object – служебное поле
  • name – имя свойства сущности которое отображается в данном поле
  • types – можно добавить классы CSS к полю
  • params – атрибуты к полю(disabled или другие)
  • size – классы bootstrap отвечающие за размер поля
  • prefix – префикс имени поля, обычно используется в фильтрах поиска
  • format — date или datetime у даты
  • field – у полей с типом select – поле кторое показывается в select
  • master – поле, откуда подгружается select
  • form – у поля «выбора» – ссылка на форму выбора

Табличные части

1
[[dTable | name: products | id: prodTable | key: num]]

В name пишется имя табличной части по которому можно будет обратится из php скрипта.
ID может понадобиться для динамического(JS) изменения таблицы, в key указывается поле, которое будет использоваться, как ключ для полей для использования при динамическом изменении.

Затем указываются столбцы:

1
[[column | table: products | name: product | width: 50% | header: $data.products.product.name]]

в table указывается имя таблицы к которой принадлежит столбец
В header указывается наименование шапки столбца

1
[[column | table: products | name: edit | type: edit | path: /companies/$company/commercial/$commercial/products]]

Столбец ссылки на форму редактирования позиции. в path необходимо указать корректную форму

1
[[column | table: products | name: delete | type: delete]]

Столбец для удаления строки

Ниже пример «Табличной части» из программы для вывода позиций товаров «Коммерческого предложения» на форму:

1
2
3
4
5
6
7
8
9
10
11
<div class="tableContainer">
              [[dTable | name: products | id: prodTable | key: num]]
              [[column | table: products | name: num | width: 1% | header: № | type: num | align: center]]
              [[column | table: products | name: product | width: 50% | header: $data.products.product.name]]
              [[column | table: products | name: number | width: 10% | header: $data.products.number.name | align: right]]
              [[column | table: products | name: reserve | width: 10% | header: $data.products.reserve.name | align: right]]
              [[column | table: products | name: price_nds | width: 20% | header: $data.products.price_nds.name | align: right | tags:  nowrap]]
              [[column | table: products | name: total | width: 20% | header: $data.products.total.name | align: right | tags:  nowrap]]
              [[column | table: products | name: edit | type: edit | path: /companies/$company/commercial/$commercial/products]]
	  [[column | table: products | name: delete | type: delete]]
</div>

Вот так выглядит данный шаблон в программе:
image026

Кнопки

Шаблонов кнопок не так много в системе, как полей. Однако вы можете использовать следующие шаблоны

[[save]] – создает кнопку «Сохранить»

image028

Закладки

Вкладки представляют собой следующие элементы формы:
image030

По сути — это простые ссылки на формы списков или редактирования «Объектов»

Для того чтобы объявить в шаблоне закладки необходимо сделать следующее:

1) Подключить в «Шаблоне» шаблон «Закладок»

1
2
3
4
5
#include <tabs>
</re>
2) В PHP-скрипте написать конструкцию вида:
<pre lang="LANGUAGE" line="1">  
$this->printTabs("Контрагенты",["/details/","Юридические лица"]);

То есть Вы передаете аргументы функции, если вкладка сейчас «Активна», то она идет без ссылки. Если же это не активная «Вкладка», то передаете массив, в котором первым аргументом указывается «ссылка», а вторым — «Название вкладки».

Модальные формы

Модальная форма является отдельным типом «Формы». Для того чтобы сделать какую либо форму модальной необходимо унаследовать ее класс в PHP коде, от класса «ModalForm».

1
class Edit extends \Kernel\Actions\Forms\ModalEdit

Чтобы вызвать такую форму использую функцию «showFormModal». Данная функция находится в пакете «js» «interface/modal_form». Также для работы «Модальных форм» требуется подключение модуля lib/bootstrap-modal.

Пример вызова функции:

1
showFormModal('/payment_orders/add/',{'order': '1'})

Вызов данной функции выведет окно создания новой оплаты для объекта «Счет» с «id»=1.

  • Первый параметр — адрес «формы»
  • Второй параметр — post переменные (массив)

При вызове «Модальной формы» не обязательно передать переменные, можно просто вызвать ее, не указывая второй параметр.

1
showFormModal('/payment_orders/add/')

Чтобы закрыть модальную форму, необходимо выполнить команду hideModal() из того окна в котором форма была создана, т.е. например вызвать parent.hideModal() из самой «Модальной формы».

Работа с блоками

Хранение шаблонов

Директория для хранения шаблонов на сервере: /{PROJECT}/templates/.
Шаблоны хранятся в файлах с расширением «.tpl».
Шаблоны могут иметь иерархические названия, например companies/orders/edit.

При определении пути шаблона применяются следующие правила:

  • В пути к шаблонам с иерархическими названиями каждый шаг иерархии, кроме последнего, соответствует названию папки. Последний — названию файла. Пример: companies/orders/edit загружается из /{PROJECT}/templates/companies/orders/edit.tpl. При создании шаблонов из «Конфигуратора» пути формируются автоматически.
  • <Базовые шаблоны, не подчиненные иерархии, хранятся в директории: /{PROJECT}/templates/base/. Например, изменив их можно поменять форму отображения «поля», «таблицы», «кнопок» и т. д. Доступ к этим шаблонам из «Конфигуратора» программы отсутствует.

Вызов шаблонов

Шаблоны отправляются на «парсинг» методом display($template) класса Kernel\Http\Page (экземпляр которого хранится в $this->page).

Вызвать шаблон /{PROJECT}/templates/companies/list.tpl

1
$this->page->display("companies/list");

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

Описание шаблонов

Шаблоны представляют с собой HTML-разметку совмещенную с понятным для парсера шаблонным синтаксисом. Описанию этого синтаксиса посвящен данный раздел.

Блоки

Система блоков — основа шаблонизации. Блоком называется некоторая совокупность последовательного HTML-кода. Блоки могут быть вложенными (содержать другие блоки).

Система блоков выполняет следующие задачи:

  • Сокрытие и отображение определенных частей шаблона (определенных блоков). Все блоки по умолчанию скрыты (за исключением отмеченных специальными флагами, см. ниже). Другими словами, блоки вносят в шаблон древовидную иерархию.
  • Повторное отображение частей шаблона с иными параметрами и значениями. К примеру, при отображение списка на представление элемента может отводиться только один блок.
  • Изменение содержимого одних частей шаблона (точнее, его вывода) из других. То есть, поддержка нелинейности построения документа.
  • Структуризация шаблона (или набора шаблонов)
Базовый синтаксис

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

1
2
3
4
5
6
<div>Text 1</div>
{BLOCK} ##начало блока
<div>Text 2</div>
<p>Text 3</p>
{/BLOCK} ##конец блока
<div>Text 4</div>

По умолчанию блоки скрыты. Другими словами, отображение шаблона выше выведет:


Text 1
Text 4

Чтобы сделать блок видимым, необходимо вызвать метод:

1
$this->page->block($blockName, $params = [])

$blockName — название блока
$params — переменные (см. ниже)

Например:

1
$this->page->block("BLOCK"); //Значение второго параметра см. ниже

Результат:


Text 1
Text 2
Text 3
Text 4

Повторный вызов выведет блок несколько раз подряд. (1, 2, 3, 2, 3, 2, 3 …, 4).

Блочные переменные

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

1
2
3
4
5
6
7
<div>Отправленные приветствия:</div>
{GREATING}
<div>
  <strong>$date</strong>: Здравствуйте, $name$.
</div>
{/GREATING}
<a href="#">Вернуться назад</a>

Для передачи значения в блок используется второй аргумент метода block($blockName, $params = []) — ассоциативный массив, в котором ключ — название переменной, а значение — соответственно, значение.

1
$this->page->block("GREATING", ["date" => "18:20", "name" => "Августина Арчибальдовна"]);

Это выведет:

Отправленные приветствия:
18:20: Здравствуйте, Августина Арчибальдовна.

Разумеется, что можно вызвать метод несколько раз подряд. Это приведет к последовательному выводу блоков с разными параметрами.

1
2
3
4
5
6
7
8
$this->page->block("GREATING", ["date" => date("H:i:s"),
                                "name" => "Августина Арчибальдовна"]);
 
$this->page->block("GREATING", ["date" => date("H:i:s", time() + 3600),
                                "name" => "Константин Игоревич"]);
 
$this->page->block("GREATING", ["date" => date("H:i:s", time() + 7200),
                                "name" => "Матильда Карловна"]);

Результат:

Отправленные приветствия:

17:25:15: Здравствуйте, Августина Арчибальдовна.
18:25:15: Здравствуйте, Константин Игоревич.
19:25:15: Здравствуйте, Матильда Карловна.

Вложенные блоки

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

Например, «Список сотрудников»:

1
2
3
4
5
6
7
8
9
{DEPARTMENT}
<div>
  <strong>$name</strong>:
  {EMPLOYEE}
  <div>$name</div>
  {/EMPLOYEE}
  ===
</div>
{/DEPARTMENT}

У каждого блока свои пространства имен.

При вызове блока-наследника, он помещается в родительский блок, вызванный последним. Обратите внимание на адрес вложенных блоков:

1
2
3
4
5
$this->page->block("DEPARTMENT", ["name" => "Отдел продаж"]);
$this->page->block("DEPARTMENT.EMPLOYEE", ["name" => "Виктория"]);
$this->page->block("DEPARTMENT.EMPLOYEE", ["name" => "Оксана"]);
$this->page->block("DEPARTMENT", ["name" => "IT отдел"]);
$this->page->block("DEPARTMENT.EMPLOYEE", ["name" => "Василий"]);

Вывод:

Список сотрудников:
Отдел продаж:
Виктория
Оксана
IT отдел:
Василий

Флаги

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

Флаги «show» и «invert»
Эти флаги модифицируют отображение блока.
Блок, отмеченный флагом show, отображается всегда.

Такие блоки используются исключительно для внутренней структуризации документа.

1
2
3
4
<div>Text 1</div>
{BLOCK show}
<div>Text 2: $variable</div>
{/BLOCK}

Обе строки будут выведены, однако переменная будет иметь название BLOCK.variable и задаваться через set-синтаксис (см. ниже).
Флаг invert работает по тому же принципе, однако вызов метода block для него скроет блок (другими словами, вызовет обратное относительно обычного блока, поведение.

Флаги «prepend» и «append»
Блоки с такими флагами не являются полноценными блоками. Они могут задаваться только после одноименного блока без флага и просто добавляют к нему HTML-код: в начало (prepend) или в конец (append).

Добавленный код считается полноценной частью исходного блока.

1
2
3
4
5
6
7
8
9
10
11
Текст письма:
<br>
{LETTER}
Поздравляем, вы допущены до участия в нашем проекте.
{/LETTER}
{LETTER prepend}
Многоуважаемый $name!<br>
{/LETTER}
{LETTER append}
<br>Желаем удачи!
{/LETTER}$this->page->block("LETTER", ["name" => "Сергей"]);


Текст письма:

Многоуважаемый Сергей!
Поздравляем, вы допущены до участия в нашем проекте.
Желаем удачи!

Флаг «reorderable»

По умолчанию, порядок отображения различных блоков определяется их следованием в тексте.

Пример шаблона:

1
2
3
4
5
6
{HEADS}
<div>Орел!</div>
{/HEADS}
{TAILS}
<div>Решка!</div>
{/TAILS}

Пример PHP-сценария:

1
2
3
4
$this->page->block("HEADS");
$this->page->block("TAILS");
$this->page->block("TAILS");
$this->page->block("HEADS");

Выведет (вне зависимости от порядка обращений к методу block):


Орел!
Орел!
Решка!
Решка!

Это не всегда удобно (например, при отображение активных и неактивных пунктов меню).
Чтобы изменить это поведение, необходимо поместить блоки в родительский блок с флагом reorderable.

Блоки, вложенные в reorderable, отображаются в порядке вызова.

1
2
3
4
5
6
7
8
{FLIPS reorderable}
{HEADS}
<div>Орел!</div>
{/HEADS}
{TAILS}
<div>Решка!</div>
{/TAILS}
{/FLIPS}

Обратите внимание, название теперь отражает иерархию:

1
2
3
4
$this->page->block("FLIPS.HEADS");
$this->page->block("FLIPS.TAILS");
$this->page->block("FLIPS.TAILS");
$this->page->block("FLIPS.HEADS");

Выведет:


Орел!
Решка!
Решка!
Орел!

Флаг «static»

Статический блок — это шаблон внутри шаблона. Он недоступен для метода block, однако может быть вызван из любого места шаблона с использованием особого синтаксиса: названия блока, заключенного в двойные квадратные скобки. Например, [[SEPARATOR]].

1
2
3
{SEPARATOR static}
===<br>
{/SEPARATOR}

Пример:

1
2
3
4
Позиция 1<br>
Позиция 2<br>
[[SEPARATOR]]
Позиция 3

Выведет:

Позиция 1
Позиция 2
===
Позиция 3

В статический блок можно передавать параметры. Параметры отделяются символом «|» и вводятся в порядке {КЛЮЧ}:{ЗНАЧЕНИЕ}. Внутри статического блока параметры обозначаются символом «#» со следующим за ним названием параметра. Названия параметров могут содержать только буквы.

1
2
3
4
5
6
{ITEM static}
Название: #name<br>
Цена: #price руб.<br><br>
{/ITEM}
[[ITEM | name: Пылесос Koshiba | price: 10 000]]
[[ITEM | name: Видеокамера Hamsung | price: 55 700]]

Выведет:


Название: Пылесос Koshiba
Цена: 10 000 руб.

Название: Видеокамера Hamsung
Цена: 55 700 руб.

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

Переменные

Из «PHP-сценария» можно передать переменные в «Шаблон». Переменные обозначаются при помощи символа $ (для переменных препарсинга внутри статического блока — #).

Присваивание переменных внутри блока происходит через синтаксис метода block. Этот метод, однако, не может быть применен к переменным вне каких-либо блоков, а также к переменным внутри блока с флагом show. Для таких случаев используется метод setобъекта $this->page внутри сценария.
Синтаксис параметра метода set полностью соответствует синтаксису второго параметра метода block (учтите иерархичность названия для переменных внутри блоков).

1
2
3
4
5
6
7
8
9
$var1<br>
{BLOCK}
$var2<br>
{/BLOCK}
{OTHER_BLOCK show}
$var3<br>
{/OTHER_BLOCK}$this->page->block("BLOCK", ["var2" => 2]);
$this->page->set(["var1" => 1,
                  "OTHER_BLOCK.var3" => 3]);
Значение по умолчанию

Можно задавать переменным значение по-умолчанию. Для обычных переменных оно заключается в символы «~» сразу после название переменной. Для переменной препарсинга — в символы «*».

Пример шаблона:

1
2
3
4
5
6
7
8
{BLOCK}
Значение — $value~не определено~.<br>
{/BLOCK}
{STATIC_BLOCK static}
Название: #name*неизвестно*.<br>
{/STATIC_BLOCK}
[[STATIC_BLOCK | name: <strong>Песня про зайцев</strong>]]
[[STATIC_BLOCK]]$this->page->block("BLOCK");

Пример скрипта:

1
$this->page->block("BLOCK", ["value" => "42"]);

Вывод:


Значение — не определено.
Значение — 42.
Название: Песня про зайцев.
Название: неизвестно.

Шаблон отображения значения

Для переменных можно также указывать шаблон, в который подставляется значение переменной, в случае, если оно задано (не пусто) и является или может быть преобразовано к истине. Шаблон указывается сразу после названия переменной, заключается в символы «^^». Место в шаблоне, куда необходимо подставить переменную, обозначается символом «%».

Пример шаблона:

1
2
3
4
5
6
{ITEM}
Название: $name<br>
$frequency^Частота: %GHz<br>^
$size^Размер: %Gb<br>^
===<br>
{/ITEM}

Пример скрипта:

1
2
3
4
$this->page->block("ITEM", ["name" => "Intel Core i7",
                            "freq" => "3.40"]);
$this->page->block("ITEM", ["name" => "Seagate ST500",
                            "size" => "500"]);

Вывод:

Название: Intel Core i7
Частота: 3.40GHz
===
Название: Seagate ST500
Размер: 500Gb
===

Подключение вложенных шаблонов

Шаблоны можно вкладывать друг в друга средствами синтаксиса #include <{ИМЯ}>. Вложение равноценную повторному вызову display с точки зрения присваивания переменных и вывода блоков, однако имеет ряд преимуществ, таких как возможность вкладывать шаблоны внутрь блоков, порождая новые витки иерархии.

Примеры:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
//файл "template1.tpl" 
Содержимое подключенного файла
 
 
 
//файл @template2.tpl"
{BLOCK}
Содержимое подключенного блока<br>
{/BLOCK}
 
 
//файл template.tpl
 
<pre lang="LANGUAGE" line="1"> 
#include <template1>
{PARENT show}
Содержимое основного файла
#include <template2>
{/PARENT}

Сценарий PHP:

1
2
$this->page->display("template");
$this->page->block("PARENT.BLOCK"); //Важно! Вложенные подключенные блоки

Вывод:

Содержимое подключенного файла
Содержимое основного файла
Содержимое подключенного блока

Языковые константы

Языковые параметры подставляются на этапе препарсинга и вводятся при помощи конструкции #L:{ИМЯ}. По-умолчанию, для шаблона выбирается языковой файл, путь которого совпадает с путем до шаблона (но, разумеется, в иерархии иного типа). Если файл отсутствует, берется следующий в списке и так далее.

Языковые переменные находятся вне иерархий блоков.

Пример использования:

1
2
3
4
#L:PageTitle
{BLOCK}
#L:SomeWord
{/BLOCK}
Комментарии

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

Пример формы:

1
2
3
4
#include <template> ##Подключаем шаблон
{MAIN} ##Основной блок
... ##Просто текст
{/MAIN}
Стили (CSS)

В системе используются стандартные шаблоны оформления CSS на основе Bootstrap.

Подробнее: http://twitter.github.com/bootstrap/

Последние правки: 15.06.2017 12:58:43