FFCMS Wiki

Официальная документация разработчика и администратора

Инструменты пользователя

Инструменты сайта


helper:html:listing

HTML помощник: Списки (listing)

Помощник списки(listing) предназначен для быстрой генерации html-кода для различных структурированных данных. При помощи списков можно генерировать html-структуры вида ul>li{*n} и ol>li{*n}. Кроме того, результаты генерации могут быть обрамлены стилями, в результате чего при помощи листингов можно строить элементы меню.

Класс Listing содержит один статический метод - display(array) который в качестве аргумента принимает массив с параметрами листинга.

Введение в использование

Рассмотрим простейший пример использования листинга:

use Ffcms\Core\Helper\HTML\Listing;
 
echo Listing::display([
    'type' => 'ul',
    'property' => ['class' => 'myFirstListing'],
    'items' => [
        ['type' => 'text', 'text' => 'Hello, world', 'property' => ['id' => 'mySelectorId']],
        ['type' => 'link', 'link' => ['content/read', 'hello-world'], 'text' => 'Hello world page', 'linkProperty' => ['class' => 'btn btn-info']]
    ]
]);

Данный вызов листинга сгенерирует следующий html:

<ul class="myFirstListing">
    <li id="mySelectorId">Hello, world</li>
    <li><a href="{$site_url}/content/read/hello-world" class="btn btn-info">Hello world page</a></li>
</ul>

и будет выглядеть следующим образом: listing example

Как вы уже поняли, при передаче аргумента в метод display в виде массива, его ключами вы определяете:

  • type: тип отображаемой конструкции (ul/ol)
  • property: глобальные атрибуты корневой конструкции (к примеру, class, id или другие)
  • items: массив элементов списка, которые будут отображены
  • activeOrder: уровень калькуляции «активности» элемента в случае использования списка ссылок. Допустимые значения: controller, action, id.

С типом и атрибутами конструкции все достаточно ясно, однако более подробно стоит остановиться на элементах списка.

Элементы списка

Элементы списка items представляются в виде массива и являются основным содержимым списка. Каждый элемент описывается свойствами в виде массива key→value. Основные свойства каждого элемента перечислены ниже:

  1. type: обязательное свойство. Указывает на тип отображаемого элемента. Допустимы значения: text, link.
  2. text: обязательное свойство. Значение (текст) текущего элемента для отображения.
  3. link: обязательное при type = 'link'. Указатель ссылки в формате ffcms (см. Url::link()). Используется для генерации html-кода ссылки на какую-либо страницу.
  4. property: необязательное свойство. Возможность указать атрибуты текущему элементу списка в виде массива.
  5. propertyLink: необязательное свойство. В случае использования элемента type = 'link' предоставляет возможность задать атрибуты для ссылки.
  6. html: необязательное свойство. Позволяет использовать безопасный html-синтаксис в свойстве text в случае, если значение установлено в true.
  7. !secure: необязательное свойство. Позволяет использовать любой html-синтаксис в свойстве text в случае, если значение установлено в true.
  8. activeClass: название css-класса для активного элемента (если не определен используется .active).

Область применения

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

Допустим, вашей задачей является отображение списка пользователей сайта из базы данных в каком-либо виджете или приложении. Используя active record вы можете получить список пользователей сайта из базы в виде объекта, а при помощи помощника списков вы можете сгенерировать html-представление:

use Apps\ActiveRecord\User;
use Ffcms\Core\Helper\HTML\Listing;
 
$items = [];
foreach (User::get() as $user) {
    $item[] = [
        'type' => 'link',
        'link' => ['profile/show', $user->getID()],
        'text' => $user->getProfile()->getNickname()
    ];
}
 
echo Listing::display([
    'type' => 'ul',
    'items' => $items
]);

Ту же самую реализацию вы могли бы проделать и с классическим HTML:

// ... skipped use look at previous example
echo '<ul>';
    foreach (User::get() as $user) {
        echo '<li><a href="' . \App::$Alias->baseUrl . '/profile/show' . $user->id . '">' . $user->getProfile()->getNickname() . '</a></li>';
    }
echo '</ul>';

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

Вы можете сказать, что 2ой пример с классическим html-кодом куда более прост, чем первый, однако это лишь на первый взгляд так. Во первых, по мере усложнения конструкции, в том числе: по мере добавления классов, id, якорей «активности» текущего элемента и т.д. конструкция из классического кода может достичь монструозного размера и уровня сложности (и вложенности), а на ряду с этим, архитектура элемента в Listing::display() будет достаточно проста и структурирована в не зависимости от сложности и размера архитектурной реализации.

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

echo Listing::display([
    'type' => 'ul',
    'property' => ['class' => 'nav nav-menu'],
    'activeOrder' => 'id',
    'items' => [
        ['type' => 'link', 'link' => ['content/read', 'my-content'], 'text' => 'My content', property => ['class' => 'content-backgrounded', 'style' => 'color: #FFFFFF']],
        ['type' => 'link', 'link' => ['profile/show', \App::$User->identity()->getID()], 'My profile', property => ['id' => \App::$User->identity()->getID()]]
        ['type' => 'link', 'link' => ['user/logout'], '<i class="fa fa-sign-out"></i> Logout', 'html' => true]
    ]
])

При условии, что пользователь находится на странице /content/read/my-content данный листинг сгенерирует следующий html-код:

<ul class="nav nav-menu">
    <li class="active content-backgrounded" style="color: #FFFFFF"><a href="{$baseUrl}/content/read/my-content">My content</a></li>
    <li id="{$userId}"><a href="{$baseUrl}/profile/show/{$userId}">My profile</a></li>
    <li><a href="{$baseUrl}/user/logout"><i class="fa fa-sign-out"></i> Logout</a></li>
</ul>

Обратите внимание, первый элемент списка <li> получил дополнительный класс .active, т.к. пользователь находится в данный момент на этой странице.

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

Лучшие концепции

При использовании помощника списки следует помнить:

  • списки должны использоваться только в представлениях и НЕ должны использоваться в моделях или контроллерах
  • списки желательно использовать с динамическими данными или сложными статическими структурами
  • следует осторожно использовать атрибут !secure - в случае его включения ваше приложение может быть подвержено XSS-атаке
helper/html/listing.txt · Последние изменения: 2017/09/01 12:58 (внешнее изменение)