Компоненты ( Components )

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

Эта статья описывает основы работы с компонентами и не объясняет, как использовать их с AJAX. Эта тема описана в AJAX.

Примечание: Использование компонентов внутри фрагментов ограничивает их функционал (см. динамические фрагменты).

Введение

Если Вы используете административный интерфейс, то можете добавлять компоненты на страницы или шаблоны, кликнув по нему в панели Компоненты. Если же Вы используете текстовый редактор, то должны указать его название в Разделе Конфигурации. Пример добавления компонента To-do на страницу:

title = "Components demonstration"
url = "/components"

[demoTodo]
maxItems = 20
==
...

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

При добавлении компонента на страницу он автоматически создает переменную с таким же именем:

{% component 'demoTodo' %}

Примечание: Если два компонента с одинаковым именем добавлены на страницу и в шаблон, то первый из них перекроет свойства второго.

Псевдонимы

Если два плагина создают компоненты с одинаковыми именами, то Вы можете добавить их на страницу или шаблон, указав полный путь. Пример:

[October\Demo\Components\Todo demoTodoAlias]
maxItems = 20

Первый параметр в секции - имя класса, второй - псевдоним, который используется в коде как ссылка на компонент. Пример:

{% component 'demoTodoAlias' %}

Также псевдонимы позволяют определить несколько компонентов одного и того же класса на одной странице, указав сначала название компонента, после (через пробел) псевдоним. Пример:

[demoTodo todoA]
maxItems = 10
[demoTodo todoB]
maxItems = 20

Использование внешних значений

По умолчанию свойства компонентов инициализируются в Разделе Настроек, где определен сам компонент:

[demoTodo]
maxItems = 20
==
...

Однако, вы можете инициализировать свойства при помощи внешних значений - URL параметров или параметров фрагментов (для компонентов, определенных во фрагментах). Используйте {{ paramName }} для значений, которые должы быть получены из переменных фрагмента:

[demoTodo]
maxItems = {{ maxItems }}
==
...

Предполагается, что в предыдущем примере компонент demoTodo находится во фрагменте и указана переменная maxItems:

{% partial 'my-todo-partial' maxItems='10' %}

Используйте {{ :paramName }}, чтобы получить значение из URL. Например:

[demoTodo]
maxItems = {{ :maxItems }}
==
...

Страница, на которой находится компонент, должна иметь соответствующий адрес:

url = "/todo/:maxItems"

В административной части сайта Вы можете использовать Инспектора для привязки внешних значений к компоненту. Не используйте скобки {{ }}! Каждое свойство имеет иконку справа, при нажатии на которую, открывается поле для ввода значения, куда можно добавить название параметра paramName или :paramName.

Передача переменных в компонент

Components can be designed to use variables at the time they are rendered, similar to Partial variables, they can be specified after the component name in the {% component %} tag. The specified variables will explicitly override the value of the component properties, including external property values.

In this example, the maxItems property of the component will be set to 7 at the time the component is rendered:

{% component 'demoTodoAlias' maxItems='7' %}

Примечание: Not all components support passing variables when rendering.

Настройка шаблона по умолчанию

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

Перемещение разметки во фрагмент

Каждый компонент может иметь фрагмент default.htm, содержимое которого, замещает тег {% component %}. Пример:

url = "blog/post"

[blogPost]
==
{% component "blogPost" %}

Вы можете скопировать весь код из components/blogpost/default.htm и вставить его прямо в страницу или фрагмент, например, с названием blog-post.htm.

{{ __SELF__.post.title }}

<p>{{ __SELF__.post.description }}</p>

Внутри кода Вы можете найти переменную __SELF__, которая указывает на объект компонента. Она должна быть заменена на псевдоним (в нашем примере - это blogPost):

<h1>{{ blogPost.post.title }}</h1>
<p>{{ blogPost.post.description }}</p>

Теперь вы можете добавить фрагмент в страницу или шаблон:

{% partial 'blog-post.htm' %}

Переопределение фрагментов компонента

Все фргаменты компонента могут быть переопределены, используя фрагменты темы. Если компонент называется channel и использует фрагмент title.htm:

url = "mypage"

[channel]
==
{% component "channel" %}

Вы можете переопределить его, путем создания файла /themes/НАЗВАНИЕТЕМЫ/partials/ПСЕВДОНИМ/title.htm.

"View Bag"

В Октябре существует специальный компонент, который называется viewBag и который может использоваться на любой странице и любом шаблоне. В нем Вы можете заранее определить нужные вам переменные, после чего использовать их в коде. Например, указать активный пункт меню:

title = "About"
url = "/about.html"
layout = "default"

[viewBag]
activeMenu = "about"
==

<p>Page content...</p>

Получить его можно следующим образом::

description = "Default layout"
==
[...]

<!-- Main navigation -->
<ul>
    <li class="{{ viewBag.activeMenu == 'about' ? 'active' }}">About</li>
    [...]
</ul>

Примечание: viewBag скрыт в административной части сайта и может редактироваться только через текстовый редактор.

Примечание: viewBag могут использовать другие плагины.