Skip to content

use.block

Jump to bottom
do- edited this page Aug 5, 2019 · 15 revisions

ВНИМАНИЕ: в новых разработках рекомендуется использовать show_block.

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

 use.block ('auth_toolbar') // верхняя панель
 use.block ('menu')         // боковое меню
 use.block ($_REQUEST.type) // то, что, собственно, хотел увидеть пользователь, открывая данный URL

Table of Contents

Что такое "блоки"

Блоки — это программные единицы приложений на базе elu.js, каждая из которых имеет:

  • символическое имя (формат: как идентификатор C, пакетов/пространств имён нет);
  • определённое место на экране;
  • источник данных, которые там отображаются;
  • набор действий, связанных именно с этими данными.
Например, если на экране требуется отобразить верхнюю панель с логотипом, часами, ФИО текущего пользователя и кнопкой "Выход" — её можно реализовать в виде блока 'auth_toolbar': поскольку кнопка "Выход" связана с тем же объектом данных ($_USER), что и плашка с ФИО.

А вот панель поиска/фильтрации над таблицей сотрудников отдельным блоком делать нельзя: ведь её поля ввода управляют содержимым тела таблицы, а не самой панели.

Как устроен блок

С точки зрения клиентского программного кода, каждый блок — это ровно три одноимённых файла, расположенных каждый в своей директории. Два из них являются модулями requirejs, а третий — шаблоном HTML5.

Модуль данных: app/js/data/{name}.js

Это requirejs-модуль, определяющий источник данных для блока.

В течение своей загрузки он определяет обработчики действий (см. $_DO), а в результате выдаёт функцию, которая:

  • формирует объект данных (обычно вызовом query, но возможно, с использованием локально хранимой информации)
  • передаёт его функции, полученной в качестве единственного параметра.
Типовой data-модуль выглядит так: 
 define ([], function () {

  ///  ... здесь определяются компоненты $_DO ... ///

  return function (done) {

   query (      // будет запущен AJAX-запрос 
    {},         // с параметрами type и id из текущего $_REQUEST
    {},         // без дополнительных параметров,
    done        // а для полученного объекта data будет вызвана done (data)
   )

  }
       
 });

Первые два параметра query могут быть и непусты. Например, если параметр type в AJAX-запросе отличен от $_REQUEST.type ('users' вместо 'user'): 

  return function (done) {
   query ({type: "users"}, {}, done)
  }

или, скажем, передаются дополнительные параметры поиска: 

  return function (done) {
   query ({}, {query: values ($(#queryForm))}, done)
  }

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

Рассмотрим пример упрощённой схемы single sign on: если по ходу загрузки главного модуля выясняется, что $_USER не определён, то на сервер отправляется запрос ?type=sessions&action=create, в ответ на который должен прийти объект данных с карточкой текущего пользователя: 

 return function (done) {    
  if ($_USER) return done ()                
   query ({type: 'sessions', action: 'create'}, {}, function (data) {
    if (!data || !data.user) redirect ('/')
    setup_user (data.user)
    done ()
   })               
 }

Впрочем, не исключён и вырожденный случай, когда модуль для первичного отображения не требует никаких данных с сервера: тогда всё, что нужно -- вызвать done напрямую: 

  return function (done) { done () }

В elu.js есть вспомогательная API-функция, реализация которой как раз сводится к вызову первого аргумента без параметров: она называется fire. Так что исходный текст data-модуля простейшего блока, никак не обращающегося к серверу, сводится к одной строке: 

 define ([], function () {return fire});

Шаблон: app/html/{name}.html

В этом файле находится HTML-код, который требуется отобразить в соответствующей области экрана, обогатив данными, полученными data-модулем.

Формат: стандартный HTML5 без каких-либо синтаксических расширений. Все преобразования (сокрытие, тиражирование фрагментов и т. п.) должны осуществляться во view-модуле, в основном функцией fill.

Модуль отображения: app/js/view/{name}.js

Этот requirejs-модуль экспортирует функцию, которая:

  • принимает на вход 2 параметра:
    • объект данных, полученный data-модулем;
    • HTML-шаблон в виде jQuery-объекта;
  • заполняет шаблон данными;
  • выводит полученный результат в свою область;
  • (обычно) определяет функцию $_F5 для обновления этой области актуальными данными без перезагрузки страницы и даже блока в целом;
  • назначает для элементов области (и, возможно, остального экрана) обработчики js-событий:
    • те из них, что требуют запросов к серверу, должны быть ранее определены в data-модуле как компоненты $_DO.
Clone this wiki locally