Поиск сообщества

В приложении MVC модель отвечает за взаимодействие с данными и передачу их контроллеру. То же самое и в Invision Community. Вообще говоря, экземпляр модели относится к предмету. Например, если бы у вас были форумы и темы, Форум был бы модель, как и Тема. Модель для каждого из них предоставляет методы, позволяющие взаимодействовать с ними. При разработке моделей для вашего приложения перечислите, с чем работает ваше приложение, - это, скорее всего, и будут ваши модели. Название и местоположение Название модели всегда должно быть существительным в единственном числе; то есть модель всегда относится к одной вещи. Названия моделей так же должны быть в формате PascalCase. Модели расположены в директории /sources вашего приложения. Как обсуждалось в документе Автозагрузка классов, в этой директории должны быть подпапку с таким же названием, как и ваша модель, а сама модель должна находится в данной поддиректории (вместе с любыми поддерживающими модулями). /sources/topic/topic.php - некорректно: директория/модель в нижнем регистре. /sources/Topics/Topics.php - некорректно: множественное имя модели /sources/Topic/Topic.php - Корректно Еще раз обращаясь к руководству по автозагрузке, имя класса в файле PHP должно иметь префикс с подчеркиванием. Например, если ваш файл был назван Topic.php, класс модели, который он содержит, должен называться _Topic. Базовые модели Существует несколько базовых моделей, которые часто будут расширять ваши модели. Каждый из них будет рассмотрен более подробно - включая полный обзор методов, которые они предоставляют - в соответствующих разделах в этой документации. Базовыми являются: \IPS\Node\Model - Методы для работы с нодами, древовидная структура, применимая для категорий (и многое другое). \IPS\Content\Item - Методы для работы с элементами контента, например, темы, изображения галереи. \IPS\Content\Comment - Методы для работы с комментариями (включая сообщения форумов). \IPS\Content\Review - Методы для работы с отзывами. Эти четыре базовые модели реализуют паттерн Active Record в Invision Community. Пример: /exampleApp/sources/Counter/Counter.php Очень простая автономная модель, которая предоставляет метод для хранения и увеличения числа. <?php namespace IPS\exampleApp; class _Counter { protected $counter = 0; public function incrementCounter () { $this->counter++; } } /exampleApp/modules/front/example/index.php Контроллер, который создает экземпляр вышеуказанной модели, затем вызывает метод incrementCounter, который он предоставляет. namespace IPS\exampleApp\modules\front\example; class _index extends \IPS\Dispatcher\Controller { public function manage() { $myCounter = new \IPS\exampleApp\Counter(); $myCounter->incrementCounter(); } }

Цепочка наследования Ваша модель комментариев расширяет несколько классов. А именно: \IPS\Content\Comment - Предоставляет возможности комментариев. Рассмотрим эти функции в данном разделе. \IPS\Content - Предоставляет небольшое количество функций, которые являются общими для моделей контента и моделей комментариев, таких как получение автора и работа с $databaseColumnMap. \IPS\Patterns\ActiveRecord - Обеспечивает функциональность загрузки элементов из базы данных, работы с их свойствами, сохранения и удаления. Дополнительную информацию об этом класс смотрите в документе Active Records. Основной скелет namespace IPS\yourApp; class _Comment extends \IPS\Content\Comment { /** * @brief [ActiveRecord] Multiton Store */ protected static $multitons; /** * @brief Default Values */ protected static $defaultValues = NULL; /** * @brief [Content\Comment] Item Class */ public static $itemClass = 'IPS\yourApp\YourClass'; /** * @brief [ActiveRecord] Database Table */ public static $databaseTable = 'yourapp_comments'; /** * @brief [ActiveRecord] Database Prefix */ public static $databasePrefix = 'comment_'; /** * @brief Title */ public static $title = ‘thing_comments’; /** * @brief Database Column Map */ public static $databaseColumnMap = array( 'item' => 'fid', 'author' => 'mid', 'author_name' => 'author', 'content' => 'text', 'date' => 'date', 'ip_address' => 'ip_address' ); } Указание свойств вашего класса Модели комментариев требуют нескольких статических свойств для настройки их поведения, большинство из которых идентичны модели элемента контента. Многие из них относятся к классу Active Records. public static $application = 'string'; Обязательное. Ключ приложения, к которому принадлежит комментарий. public static $module = 'string'; Обязательное. Ключ модуля, к которому принадлежит комментарий. public static $multitons = array(); public static $defaultValues = NULL; Обязательное. Унаследовано от \IPS\Patterns\ActiveRecord. Эти два свойтсва требуемы классом \IPS\Patterns\ActiveRecord. Они не нуждаются в переопределени; они просто должны быть определены. public static $databaseTable = 'string'; Обязательное. Унаследовано от \IPS\Patterns\ActiveRecord. Имя таблицы базы данных, в которой хранятся эти комментарии. public static $databasePrefix = 'string'; Необязательное. Унаследовано от \IPS\Patterns\ActiveRecord. Указывает префикс поля, используемый этой таблицей. public static $databaseColumnMap = array(); Обязательное. Возможности, предоставляемые расширяемыми классами вашей модели, будут проверять этот массив, чтобы узнать, какие столбцы какую информацию хранят в вашей базе данных. Требуются следующие элементы: item Обязательный. Должен содержать название столбца, который хранит ID элемента контента, к которому принадлежит этот комментарий. author Обязательный. Должен содержать название столбца, который хранит номер ID пользователя, опубликовавшего контент. content Обязательный. Должен содержать название столбца, который хранит фактический текст комментария. date Обязательный. Должен содержать название столбца, который хранит unix-время даты публикации комментария. ip_address Обязательный. Должен содержать название столбца, который хранит IP-адрес автора комментария. author_name Необязательный. Может содержать название столбца, который хранит имя пользователя, опубликовавшего комментарий. first Необязательный. Может содержать название столбца, который хранит логическое значение, указывающее, является ли этот комментарий первым у элемента. public static $commentTemplate = 'string'; Необязательный. Задает шаблон, который будет использоваться для отображения комментария (смотрите метод html() ниже). Например: array( array( 'global', 'core', 'front' ), 'commentContainer' ); public static $formTemplate = 'string'; Необязательный. Задает шаблон, который будет использоваться для отображения формы комментария. Например: array( array( 'forms', 'core', 'front' ), 'commentTemplate' ); public static $formLangPrefix = 'string'; Необязательный. Указывает префикс для добавления к языковым строкам, используемым моделью, что позволяет создавать собственные языковые строки для вашей цели. Доступные методы в модели комментариев В дополнение к тем, которые предоставляются классом \IPS\Patterns\ActiveRecord (которые работают точно так же, как и для моделей элементов контента), доступно несколько дополнительных методов. \IPS\Http\Url url( string $action ) Возвращает URL-адрес комментария, автоматически вычисляет правильный номер страницы, в том числе и якорь в нужном месте страницы. Этот метод уже определен для вас. $action (string, необязательный) если параметр будет передан, добавится параметр 'do=value' в URL-адрес. \IPS\Content\Item item() Возвращает элемент контента, которому принадлежит этот комментарий. IPS\Member author() Возвращает объект \IPS\Member для пользователя, разместившего элемент контента. Например: $comment = YourClass::load( 1 ); $user = $comment->author(); echo $comment->name; string truncated( [ boolean $oneLine ] ) Возвращает содержимое в формате, подходящем для использования с виджетом data-ipsTruncate. $oneLine (boolean, необязательный, по умолчанию FALSE) - По умолчанию абзацы превращаются в разрыв строки. Если этот параметр имеет значение TRUE, параграфы заменяются пробелами вместо разрывов строк, что делает усеченный контент подходящим для однострочного отображения. boolean canEdit( [ \IPS\Member $member ] ) Возвращает логическое значение, указывающее, может ли передаваемый пользователь редактировать элемент контента. $member (\IPS\Member, необязательный) - Если предоставлено, при выполнении проверки используются разрешения пользователя. По умолчанию используется текущий авторизованный пользователь. boolean canDelete( [ \IPS\Member $member ] ) Возвращает логическое значение, указывающее, может ли передаваемый пользователь удалить элемент контента. $member (\IPS\Member, необязательный) - Если предоставлено, при выполнении проверки используются разрешения пользователя. По умолчанию используется текущий авторизованный пользователь. boolean static modPermission( string $type [, \IPS\Member $member [, \IPS\Node\Model $container ] ] ) Возвращает логическое значение, указывающее, имеет ли передаваемый пользователь разрешение на выполнение действия, указанного в параметре $type в указанном контейнере $container (если указан). $type (string, обязательный) - Тип проверяемого разрешения. Допустимые значения: edit. delete. move. hide (если включено скрытие/одобрение). unhide (если включено скрытие/одобрение). view_hidden (если включено скрытие/одобрение) $member (\IPS\Member, необязательный) - Если предоставлено, использует разрешения этого пользователя при выполнении проверки. По умолчанию используется текущий авторизованный пользователь. $container (\IPS\Node\Model, необязательный) - Если предоставлено, проверяет разрешение именно в этом контейнере. void modAction( string $type [, \IPS\Member $member [, string $reason ] ] ) Выполняет указанное действие модерации. Выбрасывает исключение OutOfRangeException, если пользователь не имеет разрешения на выполнение этого действия. $type (строка, обязательный) - Тип выполняемого действия модерации. Обратитесь к списку в предыдущем методе для допустимых значений. $member (\IPS\Member, необязательный) - Если предоставлено, использует разрешения этого пользователя при выполнении проверки. По умолчанию используется текущий авторизованный пользователь. $reason (строка, необязательный) - Используется только для действий скрыть/показать; определяет причину, по которой предпринимается действие. boolean isFirst() Возвращает true или false, что указывает, является ли это первым комментарием элемента контента. boolean isIgnored( [ \IPS\Member $member ] ) Указывает, игнорирует ли пользователь автора комментария. $member (\IPS\Member, optional) - если указано, используются предпочтения данного пользователя при проверки на статус игнорирования. По умолчанию используется текущий авторизованный пользователь. string dateLine() Возвращает строку, которая может использоваться в шаблонах, чтобы показывать, когда был добавлен комментарий, например. "Добавлено 2 часа назад". string html() Возвращает HTML-код для отображения комментария, обёрнутый в шаблон комментария.

Наследственная цепочка Ваша модель контента расширяет несколько классов. В свою очередь, это: \IPS\Content\Item - Предоставляет возможности Элементов Контента. Данный класс содержит весь код для различных дополнительных функций элементов контента, которые вы активируете, добавив свойства и интерфейсы в вашу модель. \IPS\Content - Предоставляет небольшое количество функций, которые являются общими для моделей Элемента Контента и моделей Комментария Контента (проясним позже) таких, как получение автора и работа с $databaseColumnMap. \IPS\Patterns\ActiveRecord - Обеспечивает функциональность загрузки элементов из базы данных, работы с их свойствами, сохранения и удаления. Дополнительную информацию об этом классе см. в документе Active Records. Основной скелет <?php namespace IPS\yourapp; class _YourClass extends \IPS\Content\Item { /** * @brief Multiton Store */ protected static $multitons; /** * @brief Default Values */ protected static $defaultValues = NULL; /** * @brief Application */ public static $application = 'yourapp'; /** * @brief Module */ public static $module = 'yourmodule'; /** * @brief Database Table */ public static $databaseTable = 'table'; /** * @brief Database Prefix */ public static $databasePrefix = 'prefix_'; /** * @brief Database Column Map */ public static $databaseColumnMap = array( 'author' => 'author' ); /** * @brief Title */ public static $title = ‘thing’; /** * Get URL * * @param string|NULL * @return \IPS\Http\Url */ public function url( $action=NULL ) { $url = \IPS\Http\Url::internal( ... ); if ( $action ) { $url = $url->setQueryString( 'do', $action ); } return $url; } } Указание свойств класса Модели Элемента Контента требуют указания нескольких статических свойств для настройки их поведения. Многие из них относятся к классу Active Records. public static $application = 'string'; Обязательное. Ключ приложения, к которому принадлежит элемент контента. public static $module = 'string'; Обязательное. Ключ модуля, к которому принадлежит элемент контента. public static $multitons = array(); public static $defaultValues = NULL; Обязательное. Наследуется от \IPS\Patterns\ActiveRecord. Эти два свойства обязательны по требованию \IPS\Patterns\ActiveRecord. Их нет необходимости переназначать; они просто должны быть определены. public static $databaseTable = 'string'; Обязательное. Наследуется от \IPS\Patterns\ActiveRecord. Имя таблицы базы данных, в которой хранятся эти элементы контента. public static $databasePrefix = 'string'; Необязательное. Наследуется от \IPS\Patterns\ActiveRecord. Указывает префикс поля, используемый этой таблицей. public static $databaseColumnMap = array(); Обязательное. Возможности, предоставленные классами выше, которые расширяет ваша модель, будут проверять этот массив, чтобы узнать, какие столбцы хранятся в вашей базе данных. Требуются следующие элементы, и во всех случаях значение с $databasePrefix опущено: author - Должно содержать имя столбца, содержащего ID пользователя, разместившего контент. title - Должно содержать имя столбца, содержащего заголовок контента. date - Должно содержать имя столбца, который содержит UNIX-время, когда был создан элемент контента. ip_address - Должно содержать имя столбца (без $databasePrefix), который содержит IP-адрес пользователя, разместившего контент. public string $title = 'string'; Ключ для языковой строки, описывающий то, чем является ваш элемент контента (Например, 'Тема', 'Файла', 'Изображение', и т.д.) Доступные методы моделей Элементов Контента В дополнение к тем методам, которые предоставляются \IPS\Patterns\ActiveRecord (которые работают точно так же, как и для нод), доступен ряд дополнительных методов. \IPS\Patterns\ActiveRecordIterator static getItemsWithPermission( ... ) Получает элементы контента, к которым у текущего пользователя есть доступ. Смотрите phpDoc в файле /system/Content/Item.php для просмотра всех поддерживаемых аргументов. \IPS\Member author() Возвращает объект \IPS\Member пользователя, разместившего элемент контента. Например: $item = YourClass::load( 1 ); $user = $item->author(); echo $user->name; boolean canView( [ \IPS\Member $member=NULL ] ) Возвращает логическое значение, указывающее, может ли предоставленный пользователь просматривать элемент контента. По умолчанию всегда будет возвращать значение TRUE, но зависит от включены ли разрешения и если включено Hiding. $member (\IPS\Member, optional) - Если предоставлено, используются разрешения текущего пользователя при выполнении проверки. По умолчанию будет использоваться текущий пользователь. boolean canEdit( [ \IPS\Member $member=NULL ] ) Возвращает логическое значение, указывающее, может ли предоставленный пользователь редактировать элемент контента. $member (\IPS\Member, optional) - Если предоставлено, используются разрешения текущего пользователя при выполнении проверки. По умолчанию будет использоваться текущий пользователь. boolean canDelete( [ \IPS\Member $member=NULL ] ) Возвращает логическое значение, указывающее, может ли предоставленный пользователь удалить элемент контента. $member (\IPS\Member, optional) - Если предоставлено, используются разрешения текущего пользователя при выполнении проверки. По умолчанию будет использоваться текущий пользователь. boolean static modPermission( string $type [, \IPS\Member $member=NULL [, \IPS\Node\Model $container=NULL ] ] ) Возвращает логическое значение, указывающее, имеет ли предоставленный пользователь разрешение выполнить действие, указанное параметром $type в указанном контейнере $container (если предоставлен). $type (string, required) Тип проверяемого разрешения. Допустимые значения: edit delete move feature (если включена такая возможность) unfeature (если включена такая возможность) pin (если включена такая возможность) unpin (если включена такая возможность) lock (если включена такая возможность) unlock (если включена такая возможность) hide (если включена такая возможность) unhide (если включена такая возможность) view_hidden (если включена такая возможность) $member (\IPS\Member, optional) Если предоставлено, используются разрешения текущего пользователя при выполнении проверки. По умолчанию будет использоваться текущий пользователь. $container (\IPS\Node\Model, optional) Если предоставлено, проверяет разрешение именно в этом контейнере ноды. void modAction( string $type [, \IPS\Member $member=NULL [, string $reason=NULL ] ] ) Выполняет указанное действие модерации. Выбрасывает исключение OutOfRangeException, если пользователь не имеет разрешения на выполнение этого действия. $type (строка, обязательно) - Тип выполняемого действия модерации. Допустимые значения можете найти в списке предыдущего метода. $member (\IPS\Member, необязательно) - Если предоставлено, используются разрешения текущего пользователя при выполнении проверки. По умолчанию будет использоваться текущий пользователь. $reason (строка, необязательно) - Используется только для действий скрыть/показать; определяет причину, по которой предпринимается действие.

Базовый класс, который будут расширять классы вашей ноды, это \IPS\Node\Model. Этот класс предоставляет широкий набор специальных методов для работы с данными вашей ноды. \IPS\Node\Model в свою очередь расширяет \IPS\Patterns\ActiveRecord, предоставляя стандартные способы выборки и взаимодействия с основными данными в вашей базе данных. <?php namespace IPS\yourApp; class _ExampleModel extends \IPS\Node\Model { //... } Затем ваша модель может быть загружена в ваши контроллеры, например так: $item = \IPS\yourApp\exampleModel::load( 1 ); Указание свойств класса Классы нод требуют несколько статических свойств для настройки своего поведения. Многое наследуется от \IPS\Patterns\ActiveRecord. protected static $multitons = array(); Обязательное свойство. Унаследовано от \IPS\Patterns\ActiveRecord. Просто должно быть определено подклассами \IPS\Patterns\ActiveRecord. public static $nodeTitle = 'string'; Обязательное. Ключ языковой строки во множественном числе, определяющий сущность вашей ноды, например "Форумы" или "Категории". public static $databaseTable = 'string'; Обязательное. Унаследовано от \IPS\Patterns\ActiveRecord. Задаёт таблицу базы данных, к которой относится паттерн ActiveRecord. public static $databaseColumnOrder = 'string'; Обязательное. Должен быть столбец в вашей таблице базы данных (без префикса), который содержит номер позиции, в порядке которой будут выстроены ноды (центральный код будет обрабатывать настройку и использовать значение, но вам нужно создать для этого поле - столбец INT). public static $databasePrefix = 'string'; Необязательное. Унаследовано от \IPS\Patterns\ActiveRecord. Указывает префикс поля, используемого этой таблицей. public static $databaseColumnId = 'string'; Необязательное (по умолчанию: 'id'). Унаследовано от \IPS\Patterns\ActiveRecord. Задает поле первичного ключа для этой таблицы базы данных. public static $nodeSortable = boolean; Необязательное (по умолчанию: true) Определяет, будут ли ноды сортироваться администраторами в админцентре. public static $modalForms = boolean; Необязательное (по умолчанию: false) Определяет, будут ли формы редактирования/добавления нод в админцентре отображаться во всплывающем модельном окне. Определение методов вашего класса В дополнение к методам, унаследованным от \IPS\Patterns\ActiveRecord, класс \IPS\Node\Model также предоставляет дополнительные методы (некоторые из которых обязательны в вашем собственном классе). public void url() Обязательный. Должен вернуть объект \IPS\Http\Url, указывающий на местоположение во фронт-енде, где пользователи могут просматривать элементы контента в вашей ноде. public void form( \IPS\Helpers\Form $form ) Обязательный. Должен определять элементы формы в объекте $form, которые будут использованы для оображения формы для редактирования/добавления нод в админцентре. public static array roots() Возвращает массив нод. Если вы реализуете отношение с родитель-потомок, метод возвращает только те, у которых нет родителя. public static array search( string $column, string $query, string $order=NULL, mixed $where=array() ) Возвращает массив нод, соответствующих поиску. public array getButtons( string $url [, boolean $subnode=FALSE] ) Должен вернуть массив кнопок для отображения в дереве нод для нод в админцентре. Базовый класс определяет следующие кнопки автоматически (на основе конфигурации модели ноды): add edit permissions copy empty delete Вы можете определить дополнительные кнопки. Обязательно вызовите parent::getButtons( $url ) в вашем классе для установки стандартных кнопок. Геттеры и сеттеры Поскольку \IPS\Node\Model расширяет \IPS\Patterns\ActiveRecord, могут быть определены геттеры и сеттеры для обработки определённых свойств нод. \IPS\Node\Model определил большинство из них, поэтому вам нужно только определить свои собственные, если хотите обрабатывать поля по-разному. Например, вы всегда определяете метод get__title(), но вам практически никогда не понадобится вручную определять метод get__id(). Свойство Описание Get Set Стандартное значение $_id Возвращает ID номер вашей ноды. Значение столбца "id" в базе данных. $_title Возвращает заголовок вашей ноды. Пустая строка $_description Возвращает описание ноды, или NULL если не применимо. NULL $_badge Может использоваться для возврата бэйджа, отображаемого при просмотре нод в админцентре. Смотрите phpDocs. NULL $_icon Может использоваться для возврата иконки в строке, отображаемой при просмотре нод в админцентре. Возвращает CSS класс для иконки. NULL $_enabled Если реализовано, добавит бэйдж "Включено" / "Отключено", на который можно кликнуть, чтобы переключить статус. Вы должны реализовать это, если у ваших нод есть концепция включения/отключения. NULL $_locked Если вы используете $_enabled, это можно использовать для указания того, что отдельная нода не может быть включена/отключена и заблокирована в текущем состоянии. NULL $_position Возвращает позицию ноды. Значение столбца в базе данных, представленное $databaseColumnOrder $_items Количество элементов контента в ноде NULL $_comments Количество комментариев к элементам контента в ноде NULL $_reviews Количество отзывов к элементам контента в ноде NULL Формы модели При просмотре нод в админцентре Invision Community автоматически строит формы для их добавления/изменения. Поэтому вы должны определить метод формы в вашей модели, которые должны строить элементы форм для отображения. Например: 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 ) ); } Этот код создаёт форму с двумя элементами - Переводимое поле, позволяющее администратору установить локализованное название вашей ноды, и поле ДаНет для другого (не существующего, в данном случае) свойства. При сохранении формы, любые поля, соответствующие столбцам в таблице базы данных, будут установлены автоматически. Однако вам может потребоваться дополнительная работа. В этом примере, поскольку заголовок является переводимым, его нельзя хранить в определенном столбце базы данных, поэтому нам нужно сохранить его в языковой системе. Это можно сделать, переопределив метод saveForm(). Например так: public function saveForm( $values ) { // Need to do this as if we’re creating a new node, we // won’t have an ID yet and the language system will need one to // store the title. if ( !$this->id ) { $this->save(); } \IPS\Lang::saveCustom( 'yourApp', "yourApp_category_{$this->id}", $values['category_title'] ); parent::saveForm( $values ); }