Помощь - LikeDislike

Дотация

Если вы используете в проектах LikeDislike, и вас мучает совесть - прошу

Внимание! Это первая бета версия. Исходный код можно посмотреть на github.com/artdevue/LikeDislike. Ошибки которые у вас есть, в процессе пользования Like Dislike, вы можете оставить по этому линку.

Перед установкой

Технические навыки

Хоть LikeDislike предназначен для легкой установки, но вы должны быть знакомы с следующими операциями:

Управления панелью: Уверенный пользователь администрирования панелью управления MODX Revolution.
Чанк и Снипет: Знать основы, что такое чанк и что такое снипет

Системные требования

LikeDislike требуется несколько вещей, чтобы всё работало.

Версия системы: У Вас должна быть установлена версия MODX Revolution версии не ниже 2.2.1 .
JQuery: Версия JQuery 1.4 или выше

Загрузка

Используя панель управления MODX, перейдите в Управления пакетами в строке поиска пакетов, наберите "LikeDislike", загрузите и установите пакет.

Исходный код расположен на github.com

Подключение LikeDislike к вашему сайту

В удобном месте шаблона сайта вам нужно вставить сниппет

[[likeCssjs]]

который подключит CSS и JS файлы, необходимые для работы LikeDislike.
Примечание! Если у вас на сайте не подключен JQuery, тогда в вызове нужно указать параметр &jsConnect=`true`, тогда вызов должен выглядеть следующим образом

[[likeCssjs? &jsConnect=`true`]]

Основная настройка

Перед тем как начать использовать LikeDislike, вы можете настроить его под свои приоритеты работы. Вы можете настроить работу Куки, IP и id пользователя

Основные настройки LikeDislike находяться в Настройки системы, в разделе "likedislike".

Все подсказки описаны в комментариях для каждой отдельной настройки.

Внимание! , Срок хранения куки likedislike.cookieLifetime, это образец подсчёта. Чтобы корректно сохранялось на один год куки, умножить цифры в параметре likedislike.cookieLifetime (должно получиться 31536000) и запишите одним числом

Админ панель

Выбрав в верхнем меню в разделе "Компоненты" - LikeDislike, вы попадаете в управления LikeDislike.

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

Основы

Вы можете создать пункт LikeDislike где угодно на странице. Для этого добавьте этот вызов сниппета:

[[!LikeDislike? &name=`ITEM_NAME`]]

Имя элемента (выделено жирным шрифтом) можно не указывать, если у вас на странице один вызов LikeDislike, так как по умолчанию name равно [[*pagetitle]].

Помните! , что имя элемента должно быть уникальным на одном ресурсе или исключение.
Вызов LikeDislike должен быть НЕ КЭШИРОВАННЫЙ

Хэш имени

Уникальность объекта для голосования состоит из трёх частей.

Параметры

Свойства	По умолчанию	Описание
`name`	[[*pagetitle]]	Название вашего объекта для голосования, по умолчанию равно заголовку ресурса. По названию, вы легко будете ориентироваться в модуле управления администрирования LikeDislike
`likeId`	[[*id]]	Нужно не путать с id LikeDislike. По умолчанию, это id ресурса на котором происходит вызов. Этот параметр даёт свою уникальность к примеру при использовании в коментариях
`category`	[[*class_key]]	По умолчанию это класс ресурса - modDocument. Вы можете использовать для группирования ваших объектов голосования на сайте, так же в в модуле управления администрирования LikeDislike, есть выборка по этой категории

Важно! чтобы эти три параметра ни совпадали в других ресурсах!.

Исключение: Если вы хотите показать один и тот же результат голосования в разных ресурсах или отобразить в разных шаблонах вывода результата, тогда нужно учесть, чтобы эти три параметра совподали.

Выбор шаблона

При создании объекта, шаблон используемый по умолчанию ("mini_likedislik"). Вы можете выбрать другой шаблон по умолчанию, если хотите. Просто измените параметр "likedislike.defaultTemplate" на ваш вариант в Настройки системы MODX.

Чтобы изменить шаблон для объекта, вам нужно просто указать параметр tpl в вызове сниппета, к примеру:

[[!LikeDislike? &tpl=`likedislik_up`]]

Список всех шаблонов

Название	Демонстрация	Опции
`buttons`	254 из 302 человек нравится это. А вам? код сниппета: [[!LikeDislike? &tpl=`buttons` &name=`Demo buttons`]]	`up`: текст для кнопки “up” (по умолчанию: 'Да') `down`: текст для кнопки “down” (по умолчанию: 'Нет') `question`: вопрос отображаемый до результата голосования (по умолчанию: 'А вам?')
`mini_poll`	Да 81% Нет 19% код сниппета: [[!LikeDislike? &tpl=`mini_poll` &name=`Demo mini_poll`]]	`up`: текст для кнопки “up” (по умолчанию: 'Да') `down`: текст для кнопки “down” (по умолчанию: 'Нет') `color_up`: цвет для графика с результатом “up” (по умолчанию: '#bbb') `color_down`: цвет для графика с результатом “down” (по умолчанию: '#bbb')
`mini_likedislik`	+106 код сниппета: [[!LikeDislike? &tpl=`mini_likedislik` &name=`Demo mini_likedislik`]]	`align`: 'left' или 'right' (по умолчанию: 'left')
`likedislik_up`	455 нравится голосование закрыто спасибо за ваш голос код сниппета: [[!LikeDislike? &tpl=`likedislik_up` &name=`Demo likedislik_up`]]	`align`: 'left', 'right' или 'center' (по умолчанию: 'center')
`likedislik_up_down`	+258 -130 голосование закрыто спасибо за ваш голос код сниппета: [[!LikeDislike? &tpl=`likedislik_up_down` &name=`Demo likedislik_up_down`]]	`align`: 'left', 'right' или 'center' (по умолчанию: 'center')
`up_down`	+136 код сниппета: [[!LikeDislike? &tpl=`up_down` &name=`Demo up_down`]]	`align`: 'left', 'right' или 'center' (по умолчанию: 'center')

Свои шаблоны

Важно! вы должны иметь средний уровень владения HTML и JQuery!.

Вы можете указать свой созданный шаблон ориентируясь и сохраняя логику шаблона, примеры шаблонов можете посмотреть на github.com или посмотреть у себя на сервере, в директории - путь к папке core/ components/likedislike/elements/chunks

Чанк принимает такие параметры:

Параметр	Описание
`like.id`	(numeric) id вашего объекта в БД, не путать с `&likeId`
`like.category`	(string) Категория вашего объекта для голосования, По умолчанию это класс ресурса - modDocument. Вы можете использовать для группирования ваших объектов голосования на сайте, так же в в модуле управления администрирования LikeDislike, есть выборка по этой категории.
`like.name`	(string) Название вашего объекта для голосования, по умолчанию равно заголовку ресурса. По названию, вы легко будете ориентироваться в модуле управления администрирования LikeDislike
`like.closed`	(numeric) 0 - открыто голосование, 1 - закрыто голосование
`like.date`	(strftime) Дата создания объекта голосования
`like.votes_up`	(numeric) Число голосов - Да
`like.votes_down`	(numeric) Число голосов - Нет
`like.votes_total`	(numeric) Общего количества голосов (Да + Нет)
`like.votes_balance`	(numeric) Баланс голосования (Да - Нет)
`like.votes_pct_up`	(string) Процент голосов, Да
`like.votes_pct_down`	(string) Процент голосов, Нет
`like.user_voted`	(bool) TRUE - пользователь уже голосовал, FALSE - пользователь ещё не голосовал
`like.color_up`	(string) цвет для графика с результатом “up” (по умолчанию: '#bbb')
`like.color_down`	(string) цвет для графика с результатом “down” (по умолчанию: '#bbb')
`like.tpl`	(string) Название шаблона для вашего объекта голосование
`like.up`	(string) текст для кнопки “up” (по умолчанию: 'Да')
`like.down`	(string) текст для кнопки “up” (по умолчанию: 'Да')
`like.disabled`	(string) Если голосование закрыто - тогда `disabled="disabled"`, если нет - то пусто
`like.class`	(string) Класс, который формируется из параметров `like.closedlike.user_votedlike.disabled`
`like.round`	(numeric) Количество знаков после запятой. Если вы хотите показать результат вывода с точностью до десятичных. По умолчанию - `0`
`like.question`	(string) Вопрос отображаемый до результата голосования (по умолчанию: 'А вам?')
`like.format`	(string) Формат вывода результата, по умолчагию у каждго шаблона свой резульат вывода, который можно поменять в слассе LikeDiskike, в дальнейшем я выведу в настройки.
`like.result_up`	(string) Результат голосования `up`, обработанный через формат вывода
`like.result_down`	(string) Результат голосования `down`, обработанный через формат вывода

Форматирование результатов

LikeDislike позволяет настраивать результат отображения для каждого элемента. Шаблон mini_likedislik, например, показывает баланс голосов по умолчанию. Шаблон mini_poll показан процент голосов за/против. Каждый шаблон имеет формат по умолчанию.

Вот, как настроить пользовательский формат для элемента:

[[!LikeDislike? &tpl=`likedislik_up` &format=`{+PCT_UP}%`]]

Синтаксис форматной строки

Форматирование строки это небольшой фрагмент текста с некоторыми специальным кодам в нем. Каждый код, завернутый в фигурные скобки, будет заменен с собственными значения. Вот список всех доступных кодов:

Формат	Описание
`{UP}`	Число голосов, Да
`{DOWN}`	Число голосов, Нет
`{PCT_UP}`	Процент голосов, Да
`{PCT_DOWN}`	Процент голосов, Нет
`{TOTAL}`	Общего количества голосов (Да + Нет)
`{BALANCE}`	Баланс голосования (Да - Нет)

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

Внутри фигурных скобок вы можете включить знак плюс или минус для вывода на фронте, например, {+UP} или {-DOWN}. Плюс - добавляеться к положительным значениям, минус - к отрицательным значениям. Если значения 0, тогда не будут выводиться плюс или минус.

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

Примеры

Для объекта с 10 голосов Да и 5 голосов Нет, вот то выведет при разных значениях форматирования:

&format	&round	Результат
`{UP}`		10
`{DOWN}`		5
`{+BALANCE}`		+5
`{UP} из {TOTAL} человек сказали “Да”`		10 из 15 человек сказали “Да”
`Процен голосов которые сказали “Нет”: {PCT_DOWN}%`		Процен голосов которые сказали “Нет”: 33%
`{-PCT_DOWN}`		-33%
`{-PCT_DOWN}`	1	-33,3%
`{-PCT_DOWN}`	2	-33,33%
`Счёт: {PCT_UP}/100`	1	Счёт: 66.7/100

Системное событие OnlikeDislikeSave

Важно! Системное событие OnlikeDislikeSave запустится при наличии параметра в сниппете &rating!.

Это событие запускаются во время голосования. т.е. записи Да или Нет.

Принимают следующие параметры:

Параметр	Описание
`id`	(numeric) id вашего объекта в БД, не путать с `&likeId`
`category`	(string) Категория вашего объекта для голосования, По умолчанию это класс ресурса - modDocument. Вы можете использовать для группирования ваших объектов голосования на сайте, так же в в модуле управления администрирования LikeDislike, есть выборка по этой категории.
`name`	(string) Название вашего объекта для голосования, по умолчанию равно заголовку ресурса. По названию, вы легко будете ориентироваться в модуле управления администрирования LikeDislike
`closed`	(numeric) 0 - открыто голосование, 1 - закрыто голосование
`date`	(strftime) Дата создания объекта голосования
`votes_up`	(numeric) Число голосов - Да
`votes_down`	(numeric) Число голосов - Нет
`votes_total`	(numeric) Общего количества голосов (Да + Нет)
`votes_balance`	(numeric) Баланс голосования (Да - Нет)
`votes_pct_up`	(string) Процент голосов, Да
`votes_pct_down`	(string) Процент голосов, Нет
`tvRat`	(string) название TV
`column`	(string) названия поля для записи в ресурc
`outputRat`	(string) свойства значения голоса
`typeRat`	(numeric) тип записи ('votes_up','votes_down','votes_total','votes_balance','votes_pct_up','votes_pct_down')
`resRat`	(numeric) id ресурса

Вывод результата в TV или поле ресурса

Для вывода результата голосования в TV или поле ресурса нужно использовать параметр &rating . Все свойства в параметре &rating перечисляются через запятую.