Layout @deprecated since cv1.4.0
View @since cv1.4.0
Описание

Класс xtables\base\View обеспечивает добавление различного содержимого в шаблоны страниц для вывода их на экран.

Данный класс создает head страницы, вызывая HeadConnector, создает menu, вызывая класс Menu.

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

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

Для использование необходимо создать экземпляр класса xtables\base\View и передать в его конструктор все данные, необходимые для построения страницы из шаблона.

Для получения сгенерированной страницы нужно вызвать метод get().

Настройки

Настройка осуществляется путем передачи данных в виде ассоциативного массива в конструктор класса xtables\base\View:

  • array head - не обязательно meta теги, css и js файлы, которые необходимо подключить на конкретной странице дополнительно (базовый набор файлов определяется в шаблоне страницы); это содержимое кешируется;
  • array meta - не обязательно отдельные мета теги страницы такие, как decription, keywords, title; это не кешируется и может определяться отдельно для каждой страницы;
  • @since cv1.7.23 array js - не обязательно если необходимо переопределить значения подключаемых по умолчанию (или других) параметров js в конфигурационном файле /config/js-css-meta.php;
  • @since cv1.7.23 array css - не обязательно если необходимо переопределить значения подключаемых по умолчанию (или других) параметров css в конфигурационном файле /config/js-css-meta.php;
  • string layout_name - название шаблона;
  • array content - содержание данного массива полностью определяется в конкретном шаблоне;
    для базового шаблона, название которого соответствует контанте View::BASIC_LAYOUT, имеются следующие типы:
    View::PAGE_TITLE - название страницы в верхней части экрана;
    View::WORKFLOW - основная рабочая область.
    В ответе аякс диспетчера для загрузки данных в рабочую область и зону поиска базового шаблона можно использовать константы: View::WORKFLOW, View::WORKFLOW_SEARCH.

    Также имеется возможность устанавливать и добавлять содержимое в разных местах, используя методы данного класса setContent(), addContentTo();
  • array menus - не обязательно массив с именами меню из файла /config/Menu/menus.php, которые должны быть подключены в данном шаблоне; подключение будет происходить путем создания массива $this->head, где ключами будут названия меню; если подключение меню не нужно, то не нужно определять данный ключ массива.
  • array infoblock - не обязательно информационные иконки для добавления в инфоблок (по умолчанию в системных шаблонах вверху справа) с открывающимися меню;
    должен быть добавлен пункт меню с открывающимся меню, используя классы Bootstrap:
    
    <a href="#" class="dropdown-toggle" data-toggle="dropdown">
        <!-- some icon or other content -->
    </a>
    <ul class="dropdown-menu dropdown-menu-right" style="width: 300px; max-height: 300px; overflow-y: auto">
        <li style="width: 100%">
            <!-- dropdown item -->
        </li>
    </ul>
    

Содержимое страницы content может добавляться как через конструктор, так и с использованием следующих методов данного класса (когда добавление необходимо проводить, например, во многих местах):

setContent(string|array $name, string $content = null)

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


$view->setContent(View::WORKFLOW, 'some content');

$view->setContent([
    View::WORKFLOW => 'some content',
    View::WORKFLOW_SEARCH => 'else content'
]);

addContentTo(string $name, string $content)

Добавление содержимого в единичный блок (без удаления ранее добавленного содержимого).


$view->addContentTo(View::WORKFLOW, 'some added content');

use xtables\base\View;

$view = new View([
    'css' => [
        'bootstrap' => 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css',
        'style' => '/css/vk.style.css'
    ],
    'js' => [
        'bootstrap' => 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js'
    ],
    'meta' => [
        'title' => 'some title'
    ],
    'head' => [
        'meta' => [
            'fragment'
        ],
        'css' => [
            'date_picker'
        ],
        'js' => [
            'date_picker',
            'autocomplete'
        ]
    ],
    'layout_name' => 'xtables-basic',
    'infoblock' => [
        'some-button-content-as-shown-above'
    ],
    'menus' => [
        'some_menu_name',
        'else_menu'
    ]
]);

//$manualMenu = '';
//$view->setMenuManuallyByName('general', $manualMenu);

return $view->setContent([
    View::PAGE_TITLE => 'some page title',
    View::WORKFLOW => $mainPageData
])->get();
    

Отрисовка подключаемого файла

Данный метод имеет функции, доступные как через ссылку на объект, так и через статический прокси интерфейс:

View::renderPhp(string $filepath, array|object $data) @since cv1.4.0

Отрисовка php файла. Данные передаются через массив и доступны внутри подключаемого файла из переменной $data.
Должен быть передан абсолютный путь к имени файла.


View::renderPhp(__DIR__ . '/../views/some-file.php', [
    'one' => 'some content',
    'two' => 'else content'
]);
// $view = new View();
// $view->renderPhp(__DIR__ . '/../views/some-file.php', [
//    'one' => 'some content',
//    'two' => 'else content'
// ]);

/* in file */

/**
 * @var array $data
 */

<div><?php echo $data['one'] ?></div>
<div><?php echo $data['two'] ?></div>
    

View::renderHtml(string $filepath, array|object $data) @since cv1.4.0

Отрисовка html или другого файла. Данные передаются через массив и доступны внутри читаемого файла в виде шаблонов <!--{}-->.
Должен быть передан абсолютный путь к имени файла.


View::renderHtml(__DIR__ . '/../views/some-file.html', [
    'one' => 'some content',
    'two' => 'else content'
]);

/* in file */
<div><!--{one}--></div>
<div><!--{two}--></div>
    

View::render(string $filepath, array|object $data) @since cv1.4.0

Общий метод для подключения любого из указанных типов файлов. При обнаружении файла php он будет подключен, данные доступны в массиве в переменной $data, другие файлы - считаны, данные вставлены в шаблончики.


View::render(__DIR__ . '/../views/some-file.php', [
    'one' => 'some content',
    'two' => 'else content'
]);

View::render(__DIR__ . '/../views/some-file.html', [
    'one' => 'some content',
    'two' => 'else content'
]);
    

View::divId(string $cssId, string $cssClasses = '', string $content = '') @since cv1.4.6

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


View::divId('some-id');
$view->divId('some-id');

/* in file */
<div id="some-id"></div>

View::divId('some-id', 'some-class', 'some content');
/* in file */
<div id="some-id" class="some-class">some content</div>
    

View::ajaxLink(array $params) @since cv1.4.6

Получение ссылки для аякс запроса. Используется аякс диспетчер, обычное действие ссылки блокируется. Может быть использовано для отображения данных на той же странице в отдельных ячейках (inlets). Для формирования кнопки можно использовать классы фреймворка Bootstrap (btn btn-primary btn-block ...).

В метод должен быть передан массив с параметрами:

  • url - обязательно адрес, по которому будет сделан аякс запрос;
  • text - обязательно текст, который будет отображен в ссылке (кнопке);
  • history - если нужно сохранить состояние для аякс навигации, то нужно определить данный параметр со значением true;
  • title - всплывающий заголовок, пояснение;
  • css_classes - классы, могут использоваться, например, для формирования из ссылки кнопки и т.п.;
  • css_id - добавление идентификатора.

View::ajaxLink([
    'url' => '/some/url',
    'text' => 'some text',
    'history' => true,
    'title' => 'some title',
    'css_classes' => 'btn btn-primary btn-block',
    'css_id' => 'some-id'
]);

Inlets @since cv1.4.6

В типовых модулях xTables используется системный шаблон xtables-basic, который имеет основную рабочую область, помечаемую идентификатором #workflow.

В этой рабочей области можно создавать сетку из ячеек, используя css фреймворк Bootstrap, в которые помещать различное содержимое, в том числе с использованием ajax dispatcher.

Для создания сетки можно воспользоваться методами данного класса.

setInlets($schema = '6,6', $prefix = 'inlet')

Создание сетки по схеме. Будет создана сетка из div блоков, каждый из которых будет помечен css идентификатором inlet{num} с порядковых номером, начиная с 1 (#inlet1, #inlet2, #inlet3). Для использования другого имени, нужно передать в данный метод второй параметр с нужным названием для идентификатора. Могут быть использованы следующие варинаты схемы, соответствующие разметке css фреймворка Bootstrap:

  • '6,6,4,4,4' - будут созданы равные для всех типов экрана (кроме мобильного телефона) div блоки;
    На выходе получится разметка:
    
    <div class="col-lg-6 col-md-6 col-sm-6"></div>
    <div class="col-lg-6 col-md-6 col-sm-6"></div>
    <div class="col-lg-4 col-md-4 col-sm-4"></div>
    <div class="col-lg-4 col-md-4 col-sm-4"></div>
    <div class="col-lg-4 col-md-4 col-sm-4"></div>
        
  • '6l*8m*8s,4' - будут созданы div блоки, разные по ширине для различных экранов (кроме мобильного телефона);
    соответствуют разметке Bootstrap:
    l - col-lg-;
    m - col-md-;
    s - col-sm-.
    На выходе получится разметка:
    
    <div class="col-lg-6 col-md-8 col-sm-8"></div>
    <div class="col-lg-4 col-md-4 col-sm-4"></div>
        

addInletContent($content)

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

getInlets()

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

INLET_CARD const

Может быть использована сетка для карточки из константы View::INLET_CARD, дающая разметку '6l*8m*8s,4'.


$view = new View();
$view->setInlets('6l*8s*8s,4') // setInlets(View::INLET_CARD)
     ->addInletContent('some data')
     ->addInletContent('else data');

// ....................

$view->getInlets();
    

$view = new View();
$view->setInlets('6l*8s*8s,4') // setInlets(View::INLET_CARD)
     ->addInletContent(AjaxDispatcher::getJs('/some/url'))
     ->addInletContent('else data')
     ->getInlets();


// reply from url: /some/url
xTables::$response->json(AjaxDispatcher::getReply([
    '#inlet1' => 'some data'
]);
    
Создание шаблона

Для создания шаблона необходимо выполнить следующие действия в каталоге /config/layouts:

В файле all-layouts.json - добавить массив с параметрами, ключом которого является название создаваемого шаблона (любое обозначение латинскими буквами без пробелов);
в качестве параметров нужно передать:

  • file - название файла с шаблоном, который должен быть расположен в папке /config/layouts;
  • head - массив с тремя массивами:
    • 'meta' - мета теги, которые должны подключаться при использовании данного шаблона, кроме специфических title, description, keywords, определяемых как описано выше; всегда подключаются мета теги 'favicon', 'apple_icon';
    • 'css' - css файлы, которые должны подключаться при использовании данного шаблона; всегда подключаются необходимые для нормального функционирования xtables css файлы bootstrap и комбинированного файла стилей (стили могут редактироваться в файле /css/style.css); расположение файлов редактируется в файле /cofing/all-head.php;
    • 'js' - js файлы, которые должны подключаться при использовании данного шаблона; всегда подключаются необходимые для нормального функционирования xtables js файлы jquery, bootstrap, xtables и тег noscript; расположение файлов редактируется в файле /cofing/all-head.php.
  • menu - массив с названиями подключаемых в шаблоне меню.

Пример шаблона, составленный из системного шаблона xtables-basic:


"layout_sample": {
    "file": "layout-sample.php",
    "head": {
        "meta": [
            "fragment"
        ],
        "css": [
            "style",
            "offcanvas",
            "bootstrap"
        ],
        "js": [
            "xtables",
            "offcanvas",
            "bootstrap",
            "jquery",
            "no_script"
        ]
    },
    "menus": [
        "general"
    ]
}
    

Создать в папке /config/layouts файл с расширением php (осуществляется include файла) и названием, соответствующим указанному в массиве настроек.

Файл необходимо построить как обычную страницу html.

<!DOCTYPE html>
<html>
    <head>
        *********
        head info
        *********
    </head>
    <body>
        *********
        body info
        *********
    </body>
</html>

Для вывода содержимого в файле шаблона можно использовать функции:

  • $this->getHead() - возвращает строку с данными всех подключенныч css, js файлов и мета тегов для добавления в тег head; в head шаблона могут быть добавлены и статичные ссылки;
  • $this->getMenu($name) - возвращает меню в html тегах соответствющего имени, если подобное меню имеется;
  • $this->getContent($name) - возвращает содержимое в html тегах с именем, соответствующем используемому в конкретном шаблоне;
  • $this->getInfoBlock() - возвращает инфоблок в html тегах.

Использование модального окна шаблона xtables-basic
@since cv1.7.28

В шаблоне xtables-basic присутствует модальное окна на базе css фреймворка Bootstrap. При необходимости данные в него могут подгружаться с использованием data атрибутов кнопки вызова окна.

У данного модального окна имеются css идентификаторы, соответствующие константам:

  • View::MODAL - идентификатор самого окна;
  • View::MODAL_TITLE - заголовок окна;
  • View::MODAL_BODY - основное тело окна;
  • View::MODAL_FOOTER - нижняя часть окна.

Для использования окна нужно создать кнопку открытия модального окна. В качестве цели кнопки использовать значение константы View::MODAL.


<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#<?php echo View::MODAL ?>">
    Название кнопки
</button>

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

  • data-title - содержимое заголовка окна;
  • data-body - содержимое основного тела окна;
  • data-footer - установите значение false, чтобы скрыть нижнюю часть модального окна с кнопками;
  • data-back - название кнопки отменить (по умолчанию ОТМЕНИТЬ);
  • data-ok - название кнопки ОК (по умолчанию ОК);
  • data-block - установить со значением 1, чтобы кнопка вызова окна после нажатия на кнопку ОК самого окна (выполнения действия, окно исчезает) блокироваль;
  • data-size - размер окна lg, md, sm;
  • data-on-show - название функции, которую нужно выполнить при открытии окна (например, загрузить удаленное содержимое);
  • data-on-hide - название функции, которую нужно выполнить при закрытии окна;

<button type="button" class="btn btn-primary"
        data-title="Заголовок окна"
        data-body="Основное тело окна"
        data-back="Назад"
        data-ok="Выполнить"
        data-block="1"
        data-url="/some-url/to-do"
        data-id="12"
        data-toggle="modal" data-target="#<?php echo View::MODAL ?>">
    Название кнопки
</button>

<button type="button" class="btn btn-primary"
        data-title="Заголовок окна"
        data-body="Основное тело окна"
        data-footer="false"
        data-toggle="modal" data-target="#<?php echo View::MODAL ?>">
    Название кнопки
</button>

Ajax запрос через кнопку OK

Кнопка ОК активизирует отправку запроса через аякс диспетчер. Любые data атрибуты, кроме зарезервированных target, toggle, title, body, footer, back, ok, size, block, on-show, on-hide будут подставлены в кнопку для передачи через аякс диспетчер в качестве параметров.

При необходимости добавления html формы в основное тело окна, добавьте его через data-body, значение data-footer выставьте в false.


<button type="button" class="btn btn-primary"
        data-title="Заголовок окна"
        data-footer="false"
        data-body="&1t;form class='ajax-form' action='/some/url'>
            &1t;textarea name='some_name' rows='5' style='width: 100%'>&1t;/textarea>
            &1t;button class='btn btn-primary' type='submit' data-dismiss='modal'>OK&1t;/button>
        &1t;/form>"
        data-toggle="modal" data-target="#<?php echo View::MODAL ?>">
    Название кнопки
</button>