Узлы (nodes) создаются администратором. Хотя в Invision Community 4 узлы используются для различных целей, в этом документе рассматривается их использование в качестве контейнеров для элементов содержимого.
В приложении IP.Board, forum является узлом - форумы содержат темы, которые являются элементами содержимого. В приложении IP.Downloads, category - это узел; категории содержат файлы, которые являются элементами содержимого.
Примечание: Узлы могут иметь под-узлы отличного от себя класса. Поскольку это сложно и обычно не нужно для элементов содержимого, касающиеся этого методы и свойства были опущены в данной документации.
Требования
Модель
Скелетон
namespace IPS\yourApp;
class _YourClass extends \IPS\Node\Model
{
/**
* @brief [ActiveRecord] Multiton Store
*/
protected static $multitons;
/**
* @brief [ActiveRecord] Default Values
*/
protected static $defaultValues = NULL;
/**
* @brief [ActiveRecord] Database Table
*/
public static $databaseTable = 'table';
/**
* @brief [ActiveRecord] Database Prefix
*/
public static $databasePrefix = 'prefix_';
/**
* @brief [Node] Node Title
*/
public static $nodeTitle = 'categories';
/**
* Get URL
*
* @return \IPS\Http\Url
*/
public function url()
{
return \IPS\Http\Url::internal( ... );
}
/**
* [Node] Add/Edit Form
*
* @param \IPS\Helpers\Form $form The form
* @return void
*/
public function form( $form )
{
$form->add( ... );
}
}
Наследование
Ваша модель расширяет количество классов. В свою очередь, они: -
\IPS\Node\Model
Обеспечивает функцию узлов. Он содержит весь код для различных дополнительных функций элементов содержимого, которые вы сможете активировать, добавив свойства и интерфейсы к своей модели.
\IPS\Patterns\ActiveRecord
Обеспечивает функции для загрузки элементов из базы данных, работы с их свойствами, их сохранения и удаления.
Необходимые методы и свойства
array static $multitons array static $defaultValues;
Простые требования \IPS\Patterns\ActiveRecord - вам не нужно ничего делать помимо их определения.
string static $databaseTable
Имя таблицы базы данных, в которой хранятся ваши Узлы (вам необходимо ее создать).
string static $databasePrefix
Если все колонки в таблице вашей базы данных начинаются с одного и того же префикса, можно указать это здесь, и тогда вам не нужно указывать его каждый раз, когда вы просматриваете значение столбца. Важно, чтобы в таблице вашей базы данных была колонка {$databasePrefix}id, содержащая числовое значение первичного ключа.
string static $nodeTitle
Должен быть языковой ключ, содержащий слово, которое объясняет чем являются ваши узлы (например, "форумы" или "категории»).
string static $databaseColumnOrder
Должна быть колонка (без префикса) в вашей базе данных, которая содержит номер позиции, из которой будут по порядку вызываться узлы (центральный код будет обрабатывать установку и использование значения, но вам нужно создать для этого поле - оно должно быть INT колонкой).
url()
Должно возвращать объект \IPS\Http\Url, указывающий местоположение в клиентской части, где пользователи могут просматривать элементы содержимого в вашем узле.
form( \IPS\Helpers\Form $form )
См. раздел по формам ниже.
Дополнительные методы
bool static $nodeSortable
Если вы установите значение FALSE (по умолчанию - TRUE), администраторы не смогут изменить порядок следования узлов.
bool static $modalForms
Если задано значение TRUE (по умолчанию - FALSE), формы добавить/редактировать будут открываться в режимных окнах.
Доступные методы
В дополнение к предоставляемым \IPS\Patterns\ActiveRecord, есть еще ряд дополнительных методов:
static roots()
Возвращает массив узлов. Если вы используете взаимосвязь родитель / дочерний элемент, он вернет только те, которые не имею родителя.
static search( string $column, string $query, string $order=NULL, array $where )
Возвращает массив узлов, соответствующих критерию поиска.
getButtons( \IPS\Http\Url $url )
Возвращает массив кнопок для отображения в узле дерева.
Методы set и get
Как уже говорилось во введении, класс \IPS\Patterns\ActiveRecord позволяет вам использовать методы для создания get и set. Некоторые специальные свойства будут применены к методам get и set ключевыми методами, поэтому Вам нужно создать методы для их обработки. В большинстве случаев вам не нужно реализовывать этот метод, так как существующего в \IPS\Node\Mode уже достаточно - создавайте метод только в том случае, если этого не достаточно (например, вы будете всегда хотеть создать метод get title(), но почти никогда - метод get id()).
Свойство | Описание | Get/Set | \IPS\Node\Model возвращает значения по-умолчанию, если вы не создали метод |
$_id | Должен вернуть ID вашего узла. | Get only | Значение колонки "id" в базе данных. |
$_title | Возвращает название вашего узла. | Метод get и поиск | пустая строка |
$_description | Должен выдавать только описание узла, либо NULL, если не применимо. | Get only | NULL |
Свойство | Описание | Get/Set | \IPS\Node\Model возвращает значения по-умолчанию, если вы не создали метод |
$_badge | Можно использовать для возврата значка для отображения при просмотре узлов в панели управления администратора. См. phpDocs. | Get only | NULL |
$_icon | Может быть использована для отображения иконки в ряду при просмотре узлой в панели управления администратора. Возвращает имя класса CSS иконки. | Get only | NULL |
$_enabled | Если будет реализована, добавит значок "Enabled"/"Disabled", который будет переключать статус при нажатии. Вы должны реализовать это, если у ваших узлов есть концепция включения/выключения. | Get и Set | NULL |
$_locked | Если вы используете $_enabled, это можно использовать для указания того, что у определенного узла нельзя переключить статус включен/выключен и его текущий статус заблокирован. | Get only | NULL |
$_position | Возвращает позицию узла. | Get only | Значение в столбце в базе данных, представленное $databaseColumnOrder |
$_items | Количество элементов содержимого в узле (см. главу 2). | Get and Set | NULL |
$_comments | Число комментариев к элементу содержимого в узле (см. главу 3). | Get and Set | NULL |
$_reviews | Количество обзоров к элементу содержимого в узле (см. главу 3). | Get and Set | NULL |
В качестве примера как это может работать: названия узлов почти всегда хранятся в виде языковой строки в базе данных, таким образом, большинство узлов имеют метод, который выглядит так:
protected function get title() {
return \IPS\Member::loggedIn()->language()-
>get(“yourApp_category_{$this->id}”);
}
Обратите внимание, что “_title” иногда отправляется к методу search (см. Доступные Методы ниже). Поэтому вам может потребоваться перезаписать этот метод, чтобы получить узлы, которые соответствуют искомому заголовку. В качестве короткого пути, если вы используете языковые строки для заголовков по примеру, описанному выше, вы можете просто добавить статичное свойство $titleSearchPrefix к вашей модели с префиксом.
public static $titleSearchPrefix = 'yourApp_category_';
Формы
При просмотре ваших узлов в Панели Администратора, форма добавить/изменить будет доступна автоматически. Вам необходимо определить метод form( \IPS\Helpers\Form $form ) для определения какие элементы формы будут показаны. Например:
/**
* [Node] Add/Edit Form
*
* @param \IPS\Helpers\Form $form The form
* @return void
*/
public function form( \IPS\Helpers\Form $form )
{
$form->add( new \IPS\Helpers\Form
\Translatable( 'category_title', NULL, TRUE, array( 'app' => 'yourApp', 'key' => ( $this->id ? "yourApp_category_{$this->id}" : NULL ) ) ) );
$form->add( new \IPS\Helpers\Form
\YesNo( 'category_example', $this->example ) );
}
Это позволит создать форму с 2мя элементами - Переносным полем, позволяющим администратору устанавливать заголовок, и полем Yes/No для другого свойства.
Когда форма будет сохранена, любые поля, соответствующие столбцам в таблице базы данных, будут установлены автоматически. Тем не менее, вам, возможно, потребуется проделать дополнительную работу - в данном примере, из-за того, что заголовок переносимый, его нельзя хранить в определенной колонке базы данных - поэтому мы должны хранить его в языковой системе. Это может быть сделано путем переопределение метода saveForm( array $values ). Например:
/**
* [Node] Save Add/Edit Form
*
* @param array $values Values from the form
* @return void
*/
public function saveForm( $values )
{
// Нужно сделать это, если мы создаем новый узел, у нас пока не будет ID и языковой системе он потребуется для хранения заголовка.
if ( !$this->id )
{
$this->save();
}
\IPS\Lang::saveCustom( 'yourApp', "yourApp_category_{$this->id}", $values['category_title'] );
parent::saveForm( $values );
}
Контроллер
Скелетон
namespace IPS\yourApp\modules\admin\yourModule; class _yourController extends \IPS\Node\Controller
{
/**
* Node Class
*/
protected $nodeClass = 'IPS\yourApp\YourClass';
}
Введение
Контроллер, только за счет определения, будет создавать страницу, где администраторы могут просматривать и управлять узлами. Если вы добавляете дополнительные функции к своему Элементу Содержимого, контроллер будет выполнять больше действий.
Взаимосвязь "родитель-дочерний элемент"
Введение
Узлы могут быть дочерними элементами других узлов, что почти всегда верно для узлов, содержащих элементы содержимого (например, форум может быть подфорумом другого подфорума); укажите колонку в таблице базы данных (без префикса), в которой содержится ID номер родителя.
Другие требования
Нет
Что меняется после внедрения
Контроллер автоматически обрабатывает отображение взаимосвязь родитель / дочерний элемент и позволяет перетаскивать узлы один в другой.
Дополнительные методы, доступные после внедрения
static roots()
Возвращает массив узлов, у которых нет родителя.
parent()
Возвращает непосредственного родителя.
parents()
Возвращает Splstack всех родительских узлов (непосредственный родительский узел, затем родительский узел этого узла, итд.)
hasChildren()
Возвращает логическое значение, указывающее имеет ли узел дочерние элементы.
childrenCount()
Возвращает число дочерних элементов.
children()
Возвращает массив дочерних узлов.
Как применить
Добавьте статичное свойство к своей модели, $databaseColumnParent, содержащее название колонки базы данных (без префикса), в которой содержится ID родительского узла.
Если ваше приложение изначально было разработано для предыдущей версии Invision Community и использует значение отличное от 0 для указания узла, не имеющего родителя, добавьте дополнительное статичное свойство, $databaseColumParentRootValue, указав каким должно быть это значение.
Ограничения панели управления администратора (ACP)
Введение
Ограничения Панели Администратора позволяют администраторам ограничивать права доступа других администраторов к панели управления.
Другие требования
Нет
Что меняется после внедрения
Контроллер автоматически проверяет ограничения панели управления администратора и отказывает в доступе к запрещенным областям.
Дополнительные методы, доступные после внедрения
static restrictionCheck( string $key ) static canAddRoot()
canAdd() canEdit() canCopy()
canManagePermissions() canDelete()
Все методы возвращают логическое значение, указывающее может ли вошедший пользователь выполнить действие.
Как применить
Во-первых, создайте необходимые ограничения панели администратора в центре разработчика для своего приложения.
Затем добавьте статичные свойства к своей модели, $restrictions, содержащие массив из трех элементов:
- app должен содержать ключ приложения, содержащий ограничения
- module должен содержать ключ модуля, содержащий ограничения
- Третье свойство зависит от того насколько конкретные ограничения вам нужны - см. ниже.
Есть 3 пути реализации:
- Если вы хотите вручную указать права на выполнение каких действий следует проверять, добавьте третий элемент - map - который должен быть ассоциативным массивом. Ключи должны быть: add, edit, permissions (нужно только если ваш узел поддерживает права доступа) и delete. Значения должны быть ключами ограничения для проверки этих действий.
- Если вы хотите использовать эти ключи с префиксом (например, ваши ключи ограничения "foo_add”, “foo_edit”, итп.), добавьте третий элемент под названием prefix с указанием префикса (в этом примере, “foo_”.
- Если вы хотите использовать только одно ограничение для всех прав доступа, добавьте третий элемент под названием
- all со значением, которое является ключом ограничения.
Права пользователей
Введение
Разрешения позволяют администраторам контролировать, какие группы пользователей могут выполнять какие-либо действия (такие как просмотр элементов содержимого, создание новых элементов содержимого, добавление комментариев к элементам содержимого, итп.) в каждом узле.
Другие требования
Нет
Что меняется после внедрения
Методы hasChildren(), childrenCount()и children()будут возвращать только дочерние узлы, которые в данный момент пользователь может просматривать. Все методы используют два параметра для управления этим поведением:
children( string $permissionCheck=‘view', \IPS\Member $member = NULL )
$permissionCheck контролирует какие права проверяются. $member контролирует для какого пользователя следует осуществлять проверку (если NULL, то используется вошедший в данный момент пользователь).
loadAndCheckPerms(…)теперь будет выдавать ошибку OutOfRange, если загружается узел, для просмотра которого у вошедшего пользователя нет прав.
Дополнительные методы, доступные после внедрения
static canOnAny( string $permission, \IPS\Member $member = NULL )
Возвращает логическое значение, указывающее есть ли у $member (вошедший в данный момент пользователь если NULL) права на выполнение действия $permission на узле any. Это можно использовать, например, для определения нужно ли отображать кнопку "Создать новый элемент содержимого".
can( string $permission, \IPS\Member $member = NULL )
Ведет себя так же как и canOnAny(), но является объект-методом, для проверки прав на определенном узле.
permissions()
Возвращает массив с рядом узла из таблицы базы данных core_permission_index, в которой содержится информация о правах определенных групп.
Как применить
Во-первых, нужно чтобы Ваша модель использовала интерфейс \IPS\Node\Permissions.
Затем добавьте три новых свойства для модели:
$permApp
Ключ приложения, к которому принадлежит ваш класс.
$permType
Уникальный ключ, представляющий ваш класс в таблице core_permissions_index (например, “forums” или “categories”).
$permissionMap
Вы можете использовать до 7 разных прав доступа - это свойство должно быть массивом данных с ключами, которые вы хотите использовать (которые используются при вызове методов, такие как can()) к колонкам, которые будут использоваться для хранения этих прав доступа в таблице core_permisisons_index. Каждое значение должно быть либо строкой "view" (что обязательно) или числом от 2 до 7.
Например:
public static $permissionMap = array( 'view' => 'view', 'read' => 2, 'add' => 3, 'download' => 4, 'reply' => 5, 'review' => 6 );
В этом примере доступные ключи доступа: “view”, “read”, “add”, “download”, “reply” и “review”. “view” (может просматривать узел), “read” (модет видеть содержимое элементов в узле) и“add” (может создавать новые элементы содержимого) всегда обязательны. “reply” является обязательным, если к элементам содержимого можно оставлять комментарии. “review” является обязательным, если к вашим элементам содержимого можно оставлять обзоры.
В панели управления администратора матрица прав будет показывать права доступа в том порядке, в кором вы их определили. Столбцы в матрице будут искать языковую строку с ключом "perm__{$key}" - таким образом, в этом примере, нужно будет создать новую языковую строку с ключом "perm__download" ("perm__view", "perm__read", и т.д. уже определены).
