Пишем первый аддон для XenForo. MVC, шаблоны, стили, настройки, навигация — используем все

Кир разместил на форуме учебный аддон, на котором можно продемострировать, как нужно писать аддоны для XenForo. Этим мы сейчас и займемся. Этот учебный аддон содержит парочку ошибок, возможно, для того, чтобы мы себя проявили, обнаружив и исправих их. Мы создадим такой же аддон с самого начала и позволим себе немного улучшить / исправить то, что получилось у Кира.



Задача такова. Надо написать аддон, который на отдельной странице будет выводить список самых понравившихся пользователям сообщений на форуме (т.е. сообщений, которые больше всего «лайкнули» пользователи). Администратор должен иметь возможность настроить максимальное количество выводимых на странице сообщений в панели управления, а также выбирать в стиле форума цвет обводки аватаров. Аддон должен быть полностью фразируемым и встраиваться в главное меню форума в отдельную вкладку.

В первую очередь надо перевести форум в режим отладки. Это можно сделать добавив в файл /library/config.php строчку

$config['debug'] = true;

Войдите в панель управления администратора и перейдите на появившуюся закладку Разработка. Выберите там «Создать дополнение». В качестве ID нам надо указать любую уникальную строку. Пусть это будет «LikeReviewRus» (без кавычек, конечно). В поле заголовка введите любой поясняющий текст. Он ни на что не влияет, просто будет отображаться в панели управления. Сохраните. У нас получилось пустое дополнение.

Теперь давайте создадим опцию для лимита количества сообщений на страницу. Перейдите на вкладку Главная и зайдите в Настройки. Добавьте группу настроек. ID группы пусть будет LikeReviewRusSettingsGroup. Заголовок можете указать произвольный. Этот текст вы увидите в числе других групп настроек. Не делайте его слишком длинным. Имейте ввиду, что это текст для отображения на «Master language»-языке форума. Фактически, таким языком является английский и наш аддон в идеале должнен бы быть изначально тоже на английском. Затем мы могли бы его перевести и распространять русскую локализацию вместе с файлом аддона. Но для простоты давайте пока все строки указывать на родном языке. В качестве дополнения выберите наш аддон и сохраните.

После сохранения вы окажетесь в этой группе настроек. Изначально она пустая и нам нужно создать здесь настройку. Нажмите «добавить опцию». В качестве имени опции введите LikeReviewRusMaxToDisplay. Выберите дополнение, придумайте заголовок и поясняющий текст. Нам нужно вводить только целые числа, поэтому в качестве формата надо выбрать «Поле ввода числа со стрелками». В параметрах формата можно указать

min=1
step=5
max=100

Это означает, что минимальное значение настройки — 1, при каждом нажатии на стрелку будет прибавляться / отниматься 5, а максимальное число, которое можно туда ввести — 100. Тип данных пусть будет «Беззнаковое целое». Значение по умолчанию — 30. Остальные настройки пока оставим как есть. Сохраните. Вы сразу же сможете проверить, что у вас получилось.

Теперь давайте создадим настройку стиля. Перейдите на вкладку Внещний вид и щелкните по Настройкам стиля. Создайте там новую группу. Пусть ее ID будет LikeReviewRusStyle. Все остальные параметры, включая пункт Дополнение, вы можете выбрать самостоятельно. Сохраните, а затем зайдите в эту группу. Вы сразу попадете в диалог создания нового свойства стиля. Имя свойства — LikeReviewRusAvatarBorder. Укажите Дополнение, заголовок и описание. В качестве типа свойства укажите Скаляр и выберите цвет. Возможно, вам также придется снова вручную выбрать группу. Это баг и его исправят. Сохраните и посмотрите, что у вас получилось. Класс, правда? :)

Теперь нам нужно создать немного фраз, чтобы аддон можно было переводить на другие языки. Щелкните по ссылке Фразы на странице Внешний вид. Создайте фразы с заголовками LikeReviewRus_Header (для отображения в самом верху страницы) и LikeReviewRus_Description для отображения ниже в качестве описания. В качестве текста для этой последней фразы введите «Это {numPosts} больше всего понравившихся пользователям постов». Ниже вы увидите, как в шаблоне вместо {numPosts} будет вставлено количество.

Теперь нам нужно создать шаблон для страницы, которую мы будем показывать. Щелкните по разделу Шаблоны на вкладке Внешний вид. Теперь создайте новый шаблон. В качестве имени шаблона укажите likereviewrus.css и вставьте следующее содержимое.

.mostLikedPosts
{
}

	.mostLikedPosts .avatar
	{
		float: left;
		margin-right: 10px;
	}
	
		.mostLikedPosts .avatar img
		{
			width: 64px;
			height: 64px;
			border: 3px solid {xen:property LikeReviewRusAvatarBorder};
		}

	.mostLikedPosts .likedPost
	{
		position: relative;
	}
	
	.mostLikedPosts .primaryContent
	{
		padding: 0;
		padding-top: 10px;
	}
	
	.mostLikedPosts h3
	{
		font-size: 12pt;
		margin-bottom: 5px;
	}
	
	.mostLikedPosts .likes
	{
		display: block;
		position: absolute;
		right: 0px;
		top: 10px;
		width: 24px;
		height: 24px;
		line-height: 24px;
		text-align: center;
		border-radius: 13px;
		font-weight: bold;
		background: {xen:property primaryLighterStill};
		border: 1px solid {xen:property primaryLighter};
	}
	
		.mostLikedPosts .likes:hover
		{
			background-color: {xen:property secondaryLightest};
			border-color: {xen:property secondaryLighter};
			color: {xen:property secondaryDark};
			text-decoration: none;
			box-shadow: 0 0 10px {xen:property secondaryMedium};
		}
	
	.mostLikedPosts .meta
	{
		font-size: 11px;
		padding-top: 5px;
		padding-bottom: 5px;
		margin-left: 80px;
		margin-bottom: -1px;
		margin-top: 10px;
		border: 1px solid {xen:property primaryLighterStill};
		border-right: none;
		border-top-left-radius: 10px;
	}
	
		.mostLikedPosts .meta dd
		{
			margin-right: 10px;
		}
		
			.mostLikedPosts .meta dd strong
			{
				font-weight: bold;
			}

Выберите дополнение, сохраните и выйдите. Мы просто набили список CSS стилей, которыми просто будем пользоваться в шаблоне. Тегами {xen:property} обозначены места, в которые будут вставлены данные из основных настроек стиля (найдите их, кстати). Обратите внимание, что мы вставили туда и настройку стиля, которую создали сами, исправляя ошибку автора (хоть слегка и безвкусно).

Теперь создайте еще один шаблон и назовите его likereviewrus_index. Вставьте в него следующее содержимое:

<xen:title>{xen:phrase LikeReviewRus_Header}</xen:title>

<xen:navigation>
	<xen:breadcrumb href="{xen:link likes-review}">{xen:phrase LikeReviewRus_Header}</xen:breadcrumb>
</xen:navigation>

<xen:require css="likereviewrus.css" />

<div class="sectionMain mostLikedPosts">
	<h2 class="subHeading">{xen:phrase LikeReviewRus_Description, 'numPosts={xen:count $likedPosts}'}</h2>
	
	<ol>
		<xen:foreach loop="$likedPosts" value="$post">
		
			<li class="likedPost">
				<div class="primaryContent">
					<xen:avatar user="$post" size="m" img="true" />
					<h3><a href="{xen:link posts, $post}">{$post.title}</a></h3>
					<div class="muted">{xen:helper wordTrim, $post.message, 140}</div>
					<a href="{xen:link posts/likes, $post}" class="likes OverlayTrigger"><strong>{xen:number $post.likes}</strong></a>
					
					<dl class="secondaryContent pairsInline meta">
						<dt>{xen:phrase posted_by}</dt> <dd><a href="{xen:link members, $post}" class="username">{$post.username}</a></dd>
						<dt>{xen:phrase date}</dt> <dd><xen:datetime time="$post.post_date" /></dd>
						<dt>{xen:phrase likes}</dt> <dd><a href="{xen:link posts/likes, $post}" class="OverlayTrigger">{xen:number $post.likes}</a></dd>
					</dl>
				</div>
			</li>
		
		</xen:foreach>
	</ol>
	
	<div class="sectionFooter">{xen:phrase showing_x_posts, 'numPosts={xen:count $likedPosts}'}</div>
</div>

Теперь давайте разберем все теги, которые нам тут встретились.

• <xen:title> — тег указывает заголовок страницы.
• <xen:require> — подключает указанный CSS файл
• <xen:navigation> и <xen:breadcrumb> — определяют, что будет показано в виде цепочки навигации. В данном случае это просто одна ссылка. Более сложные варианты мы здесь пока рассматривать не будем
• {xen:link} — строит URL с использованием параметров (likes-review) согласно правилам роутинга форума. О роутинге немного позже.
• {xen:phrase} просто вставляет значение фразы на языке, который пользователь указал в свох настройках. Если перевода для фразы на этот язык нет, будет показан оригинальный вариант на основном языке. В одинарных кавычках может следовать список параметров для фразы. Параметры внутри фразы определяются, как вы уже заметили, фигурными скобками.
• {xen:count} — возвращает количество записей, полученных в результате запроса к базе данных. Сам запрос мы определим позже.
• <xen:foreach> — определяет foreach цикл, как и в PHP
• <xen:avatar> — вставляет аватар пользователя, определяя его по данным, указанном в параметре user.
• {xen:helper} — просто стандартная функция внутри шаблона для обрезания длинного текста. Такие функции можно определять и самому.
• {xen:number} и <xen:datetime>- форматируют переданные данные, согласно настройкам, заданным в текущем языке (на котором пользователь видит страницу)
• Конструкции вроде {$post.username} — просто вставка значения с ключом username из массива в переменной шаблона $post. Как передавать переменные в шаблон я покажу чуть позже.

Вот и все. Обратите внимание, что шаблон указывается неполностью (без , и так далее). То есть это просто внутренняя часть страницы, снаружи которой будут стандартные элементы XenForo.

Теперь немного о том, как XenForo обрабатывает запросы. Если вы знакомы с MVC моделью, скорее всего, вы хорошо это представляете. Если нет, вкратце это выглядит примерно так. XenForo разбирает пришедший ему HTTP запрос и по правилам роутинга определяет, какому контроллеру передать управление для его обработки. Контроллер принимает запрос, создает модель данных (которая, например, просто читает данные из БД запросом), затем строит вид (фактически, превращает щаблоны в HTML код) и передает модель с данными ему. Получившееся мессиво отправляется в браузер пользователя.

Для того, чтобы XenForo понял, на какой запрос нужно показывать нашу страницу со списком самых классных на форуме сообщений, нам нужно перво-наперво создать правило роутинга. Перейдите на вкладку Разработка и щелкните по ссылке Префиксы роутинга. Создайте новый публичный префикс. В качестве строки префикса укажите likes-review. В настройке использования класса для генерации ссылки выберите Никогда, в качестве имени класса укажите LikeReviewRus_Route_Prefix_LikesReview. Не забудьте верно выбрать дополнение.

Настройка в панели управления закончена. Теперь мы приступаем к кодингу. В первую очередь накодим наш класс для обработки префикса роутинга. Перейдите в папку Library и создайте там подкаталог LikeReviewRus, в ней папку Route, внутри Prefix. Вот уж воистину смерть кащеева у нас получилась. Теперь создавайте файл LikesReview.php Его содержимое:

<?php

class LikeReviewRus_Route_Prefix_LikesReview implements XenForo_Route_Interface
{
	/**
	 * Match a specific route for an already matched prefix.
	 *
	 * @see XenForo_Route_Interface::match()
	 */
	public function match($routePath, Zend_Controller_Request_Http $request, XenForo_Router $router)
	{
		return $router->getRouteMatch('LikeReviewRus_ControllerPublic_Index', 'index', 'likes-review');
	}
}

В данном случае мы говорим, что при обнаружении префикса likes-review (мы его в админке настроили), нужно передавать управление контроллеру LikeReview_ControllerPublic_Index, передать ему в качестве действия «index», а в качестве majorsection — likes-review. Вторая ошибка Кира :)

Теперь создайте путь \library\LikeReviewRus\ControllerPublic, зайдите туда и создайте там файл Index.php. Его содержимое:

<?php

class LikeReviewRus_ControllerPublic_Index extends XenForo_ControllerPublic_Abstract
{
	public function actionIndex()
	{
		$maxResults = XenForo_Application::get('options')->LikeReviewRusMaxToDisplay;

		$likedPosts = $this->_getLikeReviewModel()->getMostLikedPosts($maxResults);

		$viewParams = array(
			'likedPosts' => $likedPosts
		);

		return $this->responseView('LikeReviewRus_ViewPublic_Index', 'likereviewrus_index', $viewParams);
	}

	/**
	 * @return LikeReview_Model_LikeReview
	 */
	protected function _getLikeReviewModel()
	{
		return $this->getModelFromCache('LikeReviewRus_Model_LikeReview');
	}
}

Что тут происходит? У данного контроллера определено только одно действие (index, в названии метода использован camelCase). В этом действии извлекается содержимое настройки максимального количества результатов (помните, мы ее создавали). Затем создается модель данных для списка самых крутых постов, затем создаются параметры для передачи в вид (просто параметры для шаблона, $viewParams) и после этого строится вид (рендерится шаблон likereview_index, responseView) и ему передаются параметры. Вспомогательный метод _getLikeReviewModel просто достает модель из общего кеша, если она была закеширована.

Теперь переходим к нашей модели данных. Создайте путь library\LikeReviewRus\Model и войдите туда. Создайте файл LikeReview. Его содержимое:

<?php

class LikeReviewRus_Model_LikeReview extends XenForo_Model
{
	/**
	 * Gets the most liked posts in descending order
	 *
	 * @param integer Maximum posts to fetch
	 *
	 * @return array
	 */
	public function getMostLikedPosts($limit)
	{
	    //Сначала выбираем данные о супер-постах напрямую из таблицы xf_liked_content, 
		//ограничивая количество переданным параметром
		$limitedSql = $this->limitQueryResults("
			SELECT content_id, COUNT(*) AS likes
			FROM xf_liked_content
			WHERE content_type = 'post'
			GROUP BY content_id
			ORDER BY likes DESC
		", $limit);
		
		//Получаем в массив содержимое первой колонки датасета (fetchCol) с ID номерами нужных нам постов
		$postIds = $this->_getDb()->fetchCol($limitedSql);

		//Используем модель данных постов на форуме для получения списка постов по их ID номерам
		//Указываем, что нам надо соединить посты с соответствующими им темами и пользователями
		$postResults = $this->_getPostModel()->getPostsByIds($postIds, array
		(
			'join' => XenForo_Model_Post::FETCH_THREAD | XenForo_Model_Post::FETCH_USER
		));

		//Строим массив с результатом, где в качестве индекса использовано количество "лайков" поста.
		$posts = array();
		foreach ($postResults AS $post)
		{
			$posts["$post[likes].$post[post_date]"] = $post;
		}
		
		//Сортируем
		krsort($posts);

		//Возвращаем
		return $posts;
	}

	/**
	 * @return XenForo_Model_Post
	 */
	protected function _getPostModel()
	{
		//Возвращаем модель данных о постах из кеша
		return $this->getModelFromCache('XenForo_Model_Post');
	}
}

Теперь попробуйте перейти на страницу www.xenforo.local/likes-review. Вы должны увидеть список постов с благодарностями. Обратите внимание на толстую уродливую рамку аватаров :)

Теперь попробуем добавить закладку на эту страницу в основную навигацию. Перейдите в админку на вкладку Разработка и создайте новый обработчик события. Обрабатывать будем событие navigation_tabs. Имя класса обработчика LikeReviewRus_Tabs_MainTab, имя метода addTab.

Еще создайте шаблон likesreviewrus_links со следующим содержимым:

<ul class="secondaryContent blockLinksList">
	<li><a href="{xen:link likes-review}">{xen:phrase LikeReviewRus_Header}</a></li>
</ul>

Это шаблон для создания под-ссылок для основного раздела. Пока там у нас только одна основная ссылка будет.

Создайте путь library\LikeReviewRus\Tabs, перейдите туда и создайте там файл MainTab.php. Его содержимое:

<?php
class LikeReviewRus_Tabs_MainTab
{
    public static function addTab(array &$extraTabs, $selected)
    {
        $extraTabs['likes-review'] =array(
            'title' =>  new XenForo_Phrase('LikeReviewRus_Header'), //Название основной вкладки
            'href'   =>  XenForo_Link::buildPublicLink('likes-review'), //Строим ее ссылку
			'selected' => ($selected == 'likes-review'), //Определяем, на ней ли мы сейчас
			'linksTemplate' => 'likesreviewrus_links', //определяем шаблон для рендеринга под-ссылок
        );
    }
}

Навигация готова. Для того, чтобы она красиво отображалась, вам стоит включить ЧПУ-ссылки в настройках SEO форума. Для того, чтобы посмотреть, какие запросы использует страница, откройте ее, добавив в конец /_debug=1. В частности, вы увидите, что вызов new XenForo_Phrase генерирует отдельный запрос, что не есть хорошо. Для того, чтобы этого избежать, откройте фразу LikeReviewRus_Header и поставьте галочку, чтобы она добавлялась в глобальный кеш.

Вот и все. Надеюсь, вам понравилось :) Если какие опечатки — сообщайте. Впрочем, думаю, после всего описанного вам не составит труда их исправить самостоятельно, если они есть.

P.S. Кстати, российское сообщество XenForo начало разработку своих аддонов. В частности, совсем недавно на нашем форуме появился аналог аддона VBulletin для склеивания подряд отправленных пользователем постов, написанный Pepelac.