Описание функций - Модуль Простой адаптивный форум (обсуждения)

Описания полей

Разделы форумов: "\Grain\Forum\SectionTable"

Форумы: "\Grain\Forum\ForumTable"

Темы: "\Grain\Forum\TopicTable"

Сообщения: "\Grain\Forum\MessageTable"

Файлы: "\Grain\Forum\FileTable"

Подписки: "\Grain\Forum\SubscriptionTable"

Примечание: Единовременно для одной подписки должно быть заполнено только одно из трех полей: "ALL", "FORUM_ID" или "TOPIC_ID".

События

События ORM

Для выполнения каких-либо дополнительных действий или изменения данных при добавлении, изменении удалении объектов модуля, вы можете использовать 9 стандартных событий технологии ORM (onBeforeAdd, onAdd, onAfterAdd, onBeforeUpdate, onUpdate, onAfterUpdate, onBeforeDelete, onDelete, onAfterDelete) для следующих объектов модуля:

• "\Grain\Forum\Section": Разделы форумов"
• "\Grain\Forum\Forum": Форумы
• "\Grain\Forum\Topic": Темы
• "\Grain\Forum\Message": Сообщения
• "\Grain\Forum\Subscription": Подписки (общая, на форум, на тему)

Пример:

use Bitrix\Main\Entity;

 

$eventManager = \Bitrix\Main\EventManager::getInstance();

$eventManager->addEventHandler('grain.forum', '\Grain\Forum\Message::onBeforeUpdate', 'BeforeMessageUpdateHandler');

 

function BeforeMessageUpdateHandler(Entity\Event $event)

{

    $arErrors = array();

    

    $primary = $event->getParameter("id");

    

    // запрещаем менять сообщение с идентификатором 1234

    if($primary["ID"] == 1234)

    {

        $arErrors[] = new Entity\EntityError("Изменение данного сообщения запрещено администратором");

    }

    

    $fields = $event->getParameter("fields");



    // запрещаем менять текст сообщения на слишком короткий

    if(array_key_exists('MESSAGE',$fields) && strlen($fields["MESSAGE"])<=5)

    {

        $entity = $event->getEntity();

        $arErrors[] = new Entity\FieldError($entity->getField("MESSAGE"), "Слишком короткое сообщение");

    }

    

    $changedFields = array();

    

    // добавляем к сообщению дату изменения

    if(array_key_exists('MESSAGE',$fields)) 

    {

        $date = new \Bitrix\Main\Type\DateTime();

        $changedFields["MESSAGE"] = $fields["MESSAGE"]." (изменено ".$date->toString().")";

    }

    

    // запрещаем изменять активность сообщений

    $unsetFields = array("ACTIVE");        

        

    $result = new Entity\EventResult();

    if(!empty($arErrors))

    {

        $result->setErrors($arErrors);

    }

    else

    {

        $result->modifyFields($changedFields);

        $result->unsetFields($unsetFields);

    }

    

    return $result;

}

При использовании данного кода, результат попытки изменения текста сообщения с идентификатором 1234 на "5" из публичной части, будет выглядеть так:

OnGetSubscribers - событие при получении списка подписчиков

Событие возникает при получении списка подписчиков на тему. Позволяет модифицировать список идентификаторов пользователей для отправки уведомлений.

Пример:

namespace Grain\ForumNotifications;



\Bitrix\Main\EventManager::getInstance()->addEventHandler( 

    'grain.forum', 

    'OnGetSubscribers', 

    '\Grain\ForumNotifications\OnGetSubscribers'

); 



function OnGetSubscribers(\Bitrix\Main\Event $event) 

{

    $topicId = $event->getParameter(0);

    $forumId = $event->getParameter(1);

    $arUserId = $event->getParameter(2);

    

    … // добавляем или удаляем ID пользователей из массива

    

    $result = new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::SUCCESS, $arUserId);

    return $result;

}

События при создании фильтров в публичной части

События OnGlobalsGetSectionFilter, OnGlobalsGetSectionFields, OnGlobalsGetForumFilter, OnGlobalsGetForumFields, OnGlobalsGetSearchParams возникают при получении базовых фильтров для выборки разделов, форумов и результатов поиска в публичной части соответственно. По умолчанию, во всех случаях, фильтр представляет собой следующий массив:

Array

(

    "SITE_ID" => {значение константы SITE_ID или GRAIN_FORUM_SITE_ID, если она установлена}

)

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

Пример работы с событиями при создании фильтров

Классы и функции

Выборка, добавление, изменение и удаление объектов (ORM)

Добавление, изменение и удаление объектов (или сущностей, т.е. разделов, форумов, тем, сообщений, подписок) производится при помощи технологии ORM. При этом используются следующие названия классов:

• "\Grain\Forum\SectionTable": Разделы форумов"
• "\Grain\Forum\ForumTable": Форумы
• "\Grain\Forum\TopicTable": Темы
• "\Grain\Forum\MessageTable": Сообщения
• "\Grain\Forum\SubscriptionTable": Подписки (общая, на форум, на тему)

Пример 1, выборка последних сообщений форума:

use Grain\Forum\MessageTable;

use Grain\Forum\Tools;

$arFilter = Array( // фильтр

    "ACTIVE"=>"Y", // выбираем только публичные сообщения, если не указывать данный ключ фильтра, будут выбраны также скрытые

    "TOPIC.FORUM_ID"=>32, // из форума с ID = 32

);

$arSelect = array( // поля для выборки

    '*', // все поля сообщения

    'TOPIC_NAME'=>'TOPIC.NAME', // название темы

    'TOPIC_CODE'=>'TOPIC.CODE', // код темы 

    'FORUM_CODE'=>'TOPIC.FORUM.CODE', // код форума 

    'TOPIC_URL_TEMPLATE'=>'TOPIC.FORUM.TOPIC_URL_TEMPLATE', // шаблон пути к теме 

);

$arOrder = array(

    'ADDED' => 'DESC', // сортировка по дате добавления обратным порядком

);

$limit = 10; // ограничиваем выборку 10 записями

$result = MessageTable::getList(array(

    'filter' => $arFilter,

    'select' => $arSelect,

    'order' => $arOrder,

    'limit' => $limit,

));

while($arMessage = $result->fetch()) {

    $arMessage["TOPIC_URL"] = str_replace(Array("#FORUM#","#TOPIC#"),Array($arMessage["FORUM_CODE"],$arMessage["TOPIC_CODE"]),$arMessage["TOPIC_URL_TEMPLATE"]); // создаем ссылку на тему

    $arMessage["USER"] = Tools::getUserInfo($arMessage["USER_ID"],50,"Неизвестный (не Эрнст)","/user/#id#/"); // получаем информацию о пользователе

    echo "<pre>\$arMessage = "; print_r($arMessage); echo "<pre>";

}

Пример 2, добавление сообщения:

use Grain\Forum\MessageTable;

use Bitrix\Main\Type\DateTime;

$arFields = Array(

    "ACTIVE"=>"Y",

    "USER_ID"=>$USER->GetID(),

    "TOPIC_ID"=>32,

    "MODIFIED"=>new DateTime,

    "MESSAGE"=>"Текст сообщения",

);

$result = MessageTable::add($arFields);

if ($result->isSuccess()) 

{

    $id = $result->getId();

    echo "Сообщение добавлено, ID = ".$id;

} 

else 

{

    $errors = $result->getErrors();    

    foreach ($errors as $error) {

        echo "Ошибка добавления сообщения: ".$error->getMessage()."<br />";

    }

}

Пример 3, изменение темы:

use Grain\Forum\TopicTable;

use Bitrix\Main\Type\DateTime;

$arFields = Array(

    "NAME"=>"Новое название темы",

    "MODIFIED"=>new DateTime,

);

$result = TopicTable::update(321,$arFields); // обновляем тему с ID = 321

if ($result->isSuccess()) 

{

    echo "Тема успешно изменена";

} 

else 

{

    $errors = $result->getErrors();    

    foreach ($errors as $error) {

        echo "Ошибка изменения темы: ".$error->getMessage()."<br />";

    }

}

Пример 4, удаление форума:

use Grain\Forum\ForumTable;

$result = ForumTable::delete(3); // удаляем форум с ID = 3 (все темы и сообщения этого форума будут удалены автоматически)

if ($result->isSuccess()) 

{

    echo "Форум успешно удален";

} 

else 

{

    $errors = $result->getErrors();    

    foreach ($errors as $error) {

        echo "Ошибка удаления форума: ".$error->getMessage()."<br />";

    }

}

\Grain\Forum\Tools::getMessageUrl - получение адреса сообщения

Возвращает ссылку на сообщение с учетом постраничной навигации.

\Grain\Forum\Tools::getUserInfo - получение информации о пользователе

Возвращает массив с информацией о пользователе.

Пример:

use \Grain\Forum\Tools;

print_r(Tools::getUserInfo(2,50,false,"/user/#ID#/"));

Результат:

Array

(

    [ID] => 3

    [LOGIN] => mylogin

    [NAME] => Иван

    [LAST_NAME] => Петров

    [SECOND_NAME] => 

    [PERSONAL_PHOTO] => Array

        (

            [ID] => 37

            [TIMESTAMP_X] => 26.10.2016 15:13:54

            [MODULE_ID] => main

            [HEIGHT] => 100

            [WIDTH] => 100

            [FILE_SIZE] => 4744

            [CONTENT_TYPE] => image/jpeg

            [SUBDIR] => main/b3b

            [FILE_NAME] => dragon_avatar.jpg

            [ORIGINAL_NAME] => dragon_avatar.jpg

            [DESCRIPTION] => 

            [HANDLER_ID] => 

            [EXTERNAL_ID] => 952273053b10c89c4d67e1c795f59b17

            [~src] => 

            [SRC] => /upload/main/b3b/dragon_avatar.jpg

        )



    [PERSONAL_GENDER] => 

    [DISPLAY_NAME] => Иван Петров

    [URL] => /user/3/

    [AVATAR] => Array

        (

            [src] => /upload/resize_cache/main/b3b/50_50_275511db9cefbc414a902a46f1b8fae16/dragon_avatar.jpg

            [width] => 50

            [height] => 50

            [size] => 3408

        )



)

\Grain\Forum\Tools::addEntityNames - добавление стандартных названий сущностей к $arParams

Добавляет к массиву (например, к $arParams в компоненте или шаблоне) стандартные названия сущностей (таких, например, как "Форум", "Тема", "Темы") при их отсутствии в определенных ключах.

Пример выполнения на пустом массиве:

use \Grain\Forum\Tools;

$ar = array();

Tools::addEntityNames($ar);

print_r($ar);

Результат выполнения:

Array

(

    [SECTION_NAME] => Раздел

    [SECTION_NAME_M] => Разделы

    [FORUM_NAME] => Форум

    [FORUM_NAME_M] => Форумы

    [TOPIC_NAME] => Тема

    [TOPIC_NAME_M] => Темы

    [MESSAGE_NAME] => Сообщение

    [MESSAGE_NAME_M] => Сообщения

    [TOPIC_ADD_NAME] => Создать тему

    [MESSAGE_ADD_NAME] => Оставить сообщение...

    [AUTH_NAME] => Чтобы оставить сообщение, необходимо <a href="#URL#">авторизоваться</a>.

    [UNKNOWN_USER_NAME] => Пользователь #ID#

)

\Grain\Forum\Tools::incViews - инкремент счетчика просмотров

Увеличивает на 1 счетчик количества просмотров объекта (раздела, форума, темы).

Пример:

use \Grain\Forum\Tools;

Tools::incViews("forum",3); // Увеличиваем на 1 количество просмотров форума с ID = 3

\Grain\Forum\Tools::normalizeHtml - очистка html кода от запрещенных тегов

Очищает html-код от запрещенных тегов. Возвращает очищенный html-код.

\Grain\Forum\Tools::htmlToText - преобразование html-кода в текст

Преобразует html-код в простой текст (например, для отправки почтой без использования html). Возвращает простой текст.

\Grain\Forum\Tools::getFileMeta - получение метаиформации файлов

Возвращает метаиформацию файлов из сообщения в html-виде (теги meta, link) и добавляет ссылки itemref к изображениям.

\Grain\Forum\Cache::registerTag - регистрация тега для тегированного кеша

Помечает кеш при выборке определенным тегом (например, кеш компонента)

Пример:

use Grain\Forum\ForumTable;

use Grain\Forum\Cache;



if($this->StartResultCache(false))

{

    $arResult["FORUM"] = Array();

    if($arParams["FORUM"]) 

    {

        $arFilter = Array('=CODE'=>$arParams["FORUM"],'SITE_ID'=>GRAIN_FORUM_SITE_ID);

        $result = ForumTable::getList(array(

            'filter'  => $arFilter,

        ));

        

        if($arResult["FORUM"] = $result->fetch()) {

            Cache::registerTag("forum",$arResult["FORUM"]["ID"]);

            ...

        }

    }

}

\Grain\Forum\Cache::clearByTag - очистка кеша для объекта

Очищает кеш, помеченный тегом определенного объекта

Пример:

use \Grain\Forum\Cache;

Cache::clearByTag("forum",3); // очищаем кеш форума с ID = 3

\Grain\Forum\FileTable::getEntityFiles - получение списка файлов сущности

Возвращает массив со списком файлов сущности. Ключами в данном массиве будут являються идентификаторы файлов форума.

\Grain\Forum\FileTable::applyEntityFiles - применение списка файлов к сущности

Применяет список файлов к сущности.

\Grain\Forum\FileTable::deleteEntityFiles - удаление всех файлов сущности

Удаляет все файлы сущности, в т.ч. из файловой системы битрикс и непосредственно с сервера.

Многосайтовость

При стандартных настройках модуля, при наличии нескольких сайтов на одном экземпляре Битрикс, форумы будут независимыми друг от друга, т.е. на каждом сайте будут отдельные форумы. Однако, если такая логика не подходит для вашего проекта, ее легко изменить. Для этого достаточно установить константу GRAIN_FORUM_SITE_ID в /bitrix/php_interface/init.php или в /local/php_interface/init.php (если папка /local/ присутствует у вас на сайте).

Например, если вы хотите, чтобы форумы, созданные на сайте с идентификатором "s1" отображались на всех сайтах, установите значение константы в "s1":

define("GRAIN_FORUM_SITE_ID","s1");

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

define("GRAIN_FORUM_SITE_ID","my_unique_id");

Таким образом, вы можете легко организовать собственную логику привязки форумов к разделам, поддоменам и пр. Например, следующий код позволяет организовать привязку форумов к поддоменам, даже если с точки зрения Битрикс у вас на всех поддоменах работает сайт с одним и тем же идентификатором:

if($_SERVER["HTTP_HOST"]=="subdomain1.domain.com")

    define("GRAIN_FORUM_SITE_ID","subdomain1");

elseif($_SERVER["HTTP_HOST"]=="subdomain2.domain.com")

    define("GRAIN_FORUM_SITE_ID","subdomain2");

Добавление собственных полей к объектам (сущностям) модуля

Способ 1 - изменение полей ORM

Технология ORM позволяет в удобной форме описывать поля сущностей (в нашем случае сущности ORM - это разделы, форумы, темы, сообщения). Один из способов кастомизации модуля состоит в копировании папки модуля (/bitrix/modules/grain.forum) в папку /local/modules. При этом вы можете изменить поля любой сущности, в т.ч. добавить новые, при условии переустановки модуля с удалением таблиц (если он был установлен).

После копирования папки модуля в папку /local/modules файлы описания сущностей ORM будут находится по следующим путям:

• /local/modules/grain.forum/lib/section.php - описание сущности "Раздел форума"
• /local/modules/grain.forum/lib/forum.php - описание сущности "Форум"
• /local/modules/grain.forum/lib/topic.php - описание сущности "Тема"
• /local/modules/grain.forum/lib/message.php - описание сущности "Сообщение"

Пример описания поля "Сообщение" в сущности "Тема":

new Entity\TextField('MESSAGE', array(

    'required' => true, // обязательное

)),

При установке модуля, описанные таким образом поля будут созданы в базе данных автоматически.

После создания или изменения самих полей, необходимо будет реализовать их поддержку в компонентах модуля.

Плюсы метода:

• При копировании модуля на другие проекты, отсутствие необходимости создания каких-либо полей вручную

Минусы метода:

• Необходимость пересоздавать таблицы БД (или добавлять изменять поля вручную для форумов, где уже существуют реальные данные)
• Модуль в папке /local/modules не будет обновляться через систему обновлений

Способ 2 - использование "пользовательских полей"

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

Таким образом, если вам необходимо добавить свое поле, например, к теме сообщения, то для начала, необходимо создать его через административную часть. Для этого, перейдем в раздел "Настройки > Настройки продукта > Пользовательские поля" и нажмем кнопку "Добавить". В поле объект, укажем, например, "GRAIN_FORUM_TOPIC":

После создания поля, необходимо внедрить его поддержку в компоненты модуля. Для этого вы можете скопировать нужные компоненты из папки "/bitrix/components/grain" в папку "/local/components/grain". Вместо пространства имен "grain" при копировании компонентов вы можете использовать собственное пространство имен по своему усмотрению.

Пример кода для сохранения значения пользовательского поля для объекта "GRAIN_FORUM_TOPIC":

$GLOBALS["USER_FIELD_MANAGER"]->Update(

    "GRAIN_FORUM_TOPIC", // название объекта

    789, // идентификатор темы 

    6, // значение поля (например, идентификатор группы пользователей для типа поля "Универсальная привязка")

);

Пример кода для выборки значений всех пользовательских полей объекта "GRAIN_FORUM_TOPIC":

$arTopicUserFields = array();

$rsUserFields = $GLOBALS["USER_FIELD_MANAGER"]->GetUserFields(

    "GRAIN_FORUM_TOPIC", // название объекта

    789 // идентификатор темы

); 

foreach ($rsUserFields as $FIELD_NAME => $arUserField) 

    $arTopicUserFields[$FIELD_NAME] = $arUserField;

Плюсы метода:

• Отсутствие необходимости копирования папки модуля, и, соответственно, возможность установки обновлений
• Возможность использования любых типов свойств (полей), например, "Таблица" или "Универсальная привязка" при наличии соответствующих модулей

Минусы метода:

• Необходимость создавать поля заново при переносе изменений на другой проект
• Более сложная реализация в компонентах