menu-btn

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

October CMS Documentation Docs
/

Компоненты ( 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.

<h1>{{ __SELF__.post.title }}</h1>
<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 могут использовать другие плагины.

← AJAX →