Файл шаблона (*.tmpl)

Файл шаблона (*.tmpl) является основным файлом описания рендеринга и содержит три вида секций описывающие опции, данные и сам шаблон. Для удобства разработки проще создавать шаблон либо используя плагин SublimeFCFPlugin, VSCodeFCFFramework либо команду:

$ fcfmngr create template-file [TEMPLATE_NAME] [SUPER_NAME]

Где:

TEMPLATE_NAME - Имя нового шаблона

SUPER_TEMPLATE - Путь к базовому шаблону. Необязательный параметр

Перед подробным рассмотрением структуры шаблона приведем его пример:

//~OPTIONS { // Basic inheritance template // Default: undefined // extends:"", // Automatic template update mode when the argument changes. // Acceptable values: // true|"all" - The update is performed on any change // "external" - The update is performed only if the external template was the initiator of the change. // false - The template is not being updated // The option can be overridden by the fcfAutoUpdate template argument. // Default: false autoUpdate: false, // If true, the rendering is performed on the client side. // Acceptable values: // true|"all" - Rendering is done on the client, when done on the browser side // "update" - The first render is done on the server side and the update is on the client side // "update_np" - The first render is done on the server side and the update is on the client side. // Parameters of the programmable type are not recalculated. // false - Rendering is always done on the server side // This parameter can be overridden by the fcfClientRendering template argument, but only if the option is true. // Default: false clientRendering: false, // Additional JS & CSS files to connect (JS files are also connected on the server side) // Default: [] include: [], // Plug-in additional JS & CSS files on the client side // Default: [] clientInclude: [], // [Начиная с версии 1.1.43] DOM elements merge flag. // If true, then existing items are not replaced when updated, but updated. // Default: false merge: false, // If the parameter is false, the template is not wrapped in a container, // a wrapper is not created for it, and its arguments are not available on the client. // Default: true wrapper: true, // The template is displayed when the template is locked or false, // then the lock is performed only by the transparent container. // If the option is true, then @controls:lock is used. // The option can be overridden by the fcfLockTemplate template argument. // Default: true lockTemplate: true } //~ARGUMENTS { } //~TEMPLATE <h1>Hello wonderful world!</h1>

Как упоминалось ранее, шаблон имеет три секции. Каждая секция начинается с символов //~. Соответственно имеем секции OPTIONS, ARGUMENTS и TEMPLATE. Только секция TEMPLATE является обязательной, остальные секции могут быть не объявлены.

Секция OPTIONS

Секция OPTIONS содержит в себе объект с описанием опций шаблона которые не меняются и описывают его основные программные характеристики.

Значения опций шаблона на клиенте доступны через метод fcf.NClient.Wrapper.getOptions(). Описание основных опций шаблона приведено ниже.

Опция extends Содержит в себе путь к базовому шаблону, от которого наследуется текущий. При наследовании шаблона происходит перегрузка значений OPTIONS и ARGUMENTS, а содержимое шаблона и подшаблонов подменяется наследником. Опция autoUpdate Режим автообновления шаблона при изменении его аргументов. Может принимать одно из нескольких значений:
  • true|"all" - Обновление шаблона выполняется при любом изменении аргумента шаблона вызовом метода Wrapper.setArg()
  • "external" - Обновление шаблона выполняется при изменении аргумента шаблона инициатором которого является внешний код и изменение выполняется не из вложенного шаблона. Данный режим используется при построении внутренней логики визуализации шаблона.
  • false - Обновление шаблона не выполняется при изменении аргументов

Параметр можно переопределить с помощью аргумента шаблона fcfAutoUpdate.

Параметр можно переопределить с помощью аргумента шаблона fcfAutoUpdate.

Значение по умолчанию: false

Опция clientRendering

Разрешение рендеринга на клиенте. Перечень допустимых значений:

  • true|"all" - Рендеринг и обновление вызываемое на стороне браузера выполняется на стороне браузера.
  • "update" - Первый рендеринг выполняется на стороне сервера, а обновление происходит на стороне браузера.
  • "update_np" - Первый рендеринг выполняется на стороне сервера, а обновление происходит на стороне браузера. При обновлении программные аргументы не пересчитываются.
  • false - Рендеринг Выполняется только на стороне сервера

Параметр можно переопределить с помощью аргумента шаблона fcfClientRendering.

Значение по умолчанию: false

Опция include Массив подключаемых JS и CSS файлы. JS файлы подключаются так же на стороне сервера. Опция clientInclude Массив подключаемых JS и CSS файлов, только на стороне браузера. Опция merge [С версии 1.1.43] Флаг слияния DOM дерева при обновлении шаблона. Если true, то существующие элементы при обновлении не заменяются, а обновляются.

Значение по умолчанию: false

Опция wrapper [С версии 1.1.36] Флаг создания враппера для шаблона. Если параметр равен false, шаблон не упаковывается в контейнер, для него не создается оболочка, а его аргументы недоступны на клиенте.

Значение по умолчанию: true

Опция lockTemplate Шаблон отображаемый, при блокировки методом Wrapper.lock() или false, тогда блокировка выполняется только прозрачным контейнером. Если опция не указана или равна true, используется шаблон @controls:lock. Параметр можно переопределить с помощью аргумента шаблона fcfLockTemplate.

Значение по умолчанию: true

Секция ARGUMENTS

Секция ARGUMENTS хранит в себе объект с аргументами шаблона. Аргументы могут быть представлены просто значением или результатом одной из функций fcf.argVal(), fcf.argUrl(), fcf.argRef(), fcf.argRecordRef(), fcf.argProg(). Аргументы представленные в виде значения не проходят ни какой обработки и поставляются в шаблон в том виде как представлены, над остальными типами аргументов проходит предварительная сборка и токенизация. Более подробно о специализированных аргументах советуем прочитать на соответствующих страницах документации, на которые ссылаются вышеприведенные функции.

Все аргументы шаблона доступны в теле шаблона через переменную args.

Пример:

//~ARGUMENTS { title: "first page", description: fcf.argProg(), } //~TEMPLATE <h2>@{{args.title}}@</h2> @{{args.description}}@ Системные аргументы

Помимо аргументов определенных пользователем, имеются системные аргументы, имя которых начинается с префикса fcf. Ниже представлено их описание и назначение:

  • string fcfId - идентификатора шаблона
  • string fcfClass - CSS классы добавляемые в заголовок шаблона
  • string fcfClassInner - CSS классы добавляемые в заголовок шаблона. Данный аргумент должен использоваться только внутри объявления шаблона и не перегружаться внешним рендером
  • string fcfStyle - CSS стили добавляемые в заголовок шаблона
  • string fcfStyleInner - CSS стили добавляемые в заголовок шаблона. Данный аргумент должен использоваться только внутри объявления шаблона и не перегружаться внешним рендером
  • bool|string fcfAutoUpdate - перегружает значение опции шаблона autoUpdate
  • bool|string fcfClientRendering - перегружает значение опции шаблона clientRendering
  • false|undefined|string fcfLockTemplate - перегружает значение опции шаблона lockTemplate
  • string fcfEvent[EVENT_NAME] - переменные обработки события DOM элемента действий шаблона. Имя переменной начинается с префикса fcfEvent, после следует имя события с заглавной буквы. Значение представляет из себя строку с Javascript кодом, в котором доступны следующие переменные:

    • Event event - Объект события
    • fcf.NClient.Wrapper wrapper - Объект враппера шаблона
    • fcf.NClient.Wrapper parent - Враппер родителя шаблона

    Пример:

    //~ARGUMENTS { fcfEventClick: "wrapper.onClick()", }

При использовании токенизации аргументов в токенизаторе доступны следующие предопределенные переменные

  • object args - объект аргументов шаблона
  • object decor - объект содержащий классы оформления. В качестве ключа выступает кодовое имя группы классов, а в качестве значения строка содержащая CSS классы оформления. Формируется темами оформления. Пока функционал тем не реализован в полной мере.
  • fcf.RouteInfo route - объект с информацией о маршруте

Пример:

//~ARGUMENTS { val1: "12345", val2: fcf.argVal("@{{args.val1}}@6789"), } //~TEMPLATE @{{args.val2}}@

Результат:

123456789 Секция TEMPLATE

В секции шаблона записываются правила формирования HTML.

Секция шаблона имеет три управляющие конструкции: конструкция %{{ }}% кода, конструкция вывода @{{ }}@ и конструкция перевода !{{ }}!

Конструкция кода %{{ }}% Данный блок содержит управляющий код Javascript. При использовании блоков if, while, for и других внутри которых применяется разрыв конструкции %{{ }}%, должны использоваться скобки { } Конструкция перевода !{{ }}! Выводит текст в шаблон с применением перевода на язык пользователя.

Пример

!{{Hello world}}! Конструкция вывода @{{ }}@ Данный блок выполняет вывод данных в тело шаблона.

Пример

%{{ let array = ["first", "second", "third"]; for(let i = 0; i < array.length; ++i) { }}% <p>@{{array[i]}}@</p> %{{ } }}%

Результат

<p>first</p> <p>second</p> <p>third</p>

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

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

  • object args - объект аргументов шаблона
  • object decor - объект содержащий классы оформления. В качестве ключа выступает кодовое имя группы классов, а в качестве значения строка содержащая CSS классы оформления. Формируется темами оформления. Пока функционал тем не реализован в полной мере.
  • fcf.RouteInfo route - объект с информацией о маршруте
  • fcf.NRender.NDetails.TemplateRender render - Внутренний объект рендера шаблона.
Объявление событий в шаблоне

Помимо штатного метода объявления обработчиков событий DOM элемента, разработчик может объявлять события через атрибуты fcfEvent[EVENT_NAME]. В отличии от штатных событий в коде обработчика события доступны дополнительные переменные:

  • Event event - Объект события
  • fcf.NClient.Wrapper wrapper - Объект враппера шаблона
  • fcf.NClient.Wrapper parent - Враппер родителя шаблона

Пример:

//~TEMPLATE <a fcfEventClick="wrapper.onClick(event)">Link</a> Подшаблоны

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

Для рендеринга подшаблона используется путь, который имеет формат: [MAIN_TEMPLATE_PATH]+[SUBTEMPLATE_NAME]

Где:

MAIN_TEMPLATE_PATH - путь к основному шаблону

SUBTEMPLATE_NAME - Имя подшаблона

Если рендеринг выполняется внутри основного шаблона то полный путь может быть не указан: +[SUBTEMPLATE_NAME]

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

//~TEMPLATE <h1>Example of the simple list</h1> %{{ let list = [ {name: "first", value: "value 1"}, {name: "second", value: "value 2"}, {name: "third", value: "value 3"}, ]; list.forEach((a_item)=>{ }}% @{{ render.template("+item", {value: a_item}) }}@ %{{ }); }}% //~TEMPLATE item <div> <b>@{{args.value.name}}@</b> - @{{args.value.value}}@ </div>

Результат:

<h1>Example of the simple list</h1> <div> <b>first</b> - value 1 </div> <div> <b>second</b> - value 2 </div> <div> <b>third</b> - value 3 </div>

Как видно из примера рендеринг дочернего шаблона выполняется через путь "+item":

render.template("+item", {value: a_item})