API виджетов

Код виджета

Для инициализации любого виджета Cackle вам необходимо разместить javascript код в месте, где вы хотели бы использовать виджет.

<div id="mc-container"></div>
<script type="text/javascript">
  cackle_widget = window.cackle_widget || [];
  cackle_widget.push({widget: 'Comment', id: 1});
  (function() {
    var mc = document.createElement('script');
    mc.type = 'text/javascript';
    mc.async = true;
    mc.src = ('https:' == document.location.protocol ? 'https' : 'http') + '://cackle.me/widget.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(mc, s.nextSibling);
  })();
</script>

Инициализация

Любой виджет Cackle определяется javascript объектом в массиве глобальной переменной cackle_widget. Например виджет комментариев с id = 1:

cackle_widget = window.cackle_widget || [];    //Инициализация глобальной переменной cackle_widget
cackle_widget.push({widget: 'Comment', id: 1});  //Добавление в cackle_widget виджета комментариев

Можно добавить сразу несколько виджетов на страницу.
Например два виджета комментариев, виджет последних комментариев, счетчик и виджет опроса

(второй виджет комментариев будет размещен в элементе с id="comment"):

cackle_widget = window.cackle_widget || [];
cackle_widget.push({widget: 'Comment', id: 1});
cackle_widget.push({widget: 'Comment', id: 1, container: 'comment'});
cackle_widget.push({widget: 'CommentRecent', id: 1});
cackle_widget.push({widget: 'CommentCount', id: 1});
cackle_widget.push({widget: 'Poll', id: 5});

Настройка виджетов

Для изменения стандартного поведения виджетов, необходимо добавить или поменять параметры настройки. Это можно сделать добавив или изменив свойства и методы javascript объекта виджета, например:

cackle_widget.push({widget: 'Comment', id: 1, someParams: 'someValue'});

Для изменения доступны следующие параметры:

Параметр	Тип	Значение по умолчанию	Комментарий
widget	Строка	Login Comment CommentRecent CommentCount CommentAdmin Review ReviewRating ReviewAdmin Chat ChatAdmin Poll	Определяет текущий виджет Login - виджет логина Comment - виджет комментариев CommentRecent - виджет последних комментариев CommentCount - виджет количества комментариев CommentAdmin - виджет модерации комментариев Review - виджет отзывов ReviewRating - виджет рейтинга товаров (для главной страницы) ReviewAdmin - виджет модерации отзывов Chat - онлайн консультант ChatAdmin - приложение оператора онлайн консультанта Poll - виджет опросов
id	Число		Идентификатор текущего виджета
container	Строка		Для всех виджетов контейнер по умолчанию разный: Login: mc-login Comment: mc-container CommentRecent: mc-last CommentCount: нет Review: mc-review ReviewRecent: mc-review-recent Chat: нет ChatAdmin: mc-chat-admin Poll: mc-poll Меняя контейнер вы делаете возможным использование нескольких виджетов на одной странице в разных местах.
countContainer	Строка		Идентификатор HTML элемента (id) в который будет помещен текущее количество комментариев или отзывов. В основном используется для Tab-ов переключения между комментариями, отзывами. Пример: `<span id="count"></span>` ... countContainer: 'count'
channel	Строка	Текущий адрес страницы	Любой идентификатор, к которому будут привязаны комментарии (отзывы) на данной странице. По умолчанию это текущий адрес страницы без домена. Например для `http://site.ru/post/test?a=123&c=zzz`, channel равен `/post/test?a=123&c=zzz`.
chanParam	String		Название параметра из адреса веб-страницы к значению которого будут привязаны комментарии или отзывы. Например, если указать `chanParam: 'product_id'`, то комментарии на `http://site.ru/test?product_id=123` и `http://site.ru/test?utm_source=google&product_id=123` будут одинаковые.
chanWithoutParams	Boolean	false	Если true, то в channel удаляются все параметры. Например для `http://site.ru/post/test?a=123&c=zzz`, channel будет равен `/post/test`.
url	Строка	Текущий адрес страницы	Изменяет текущий адрес страницы. Например виджет инициализируется на странице `http://site.ru/post/test?a=123&c=zzz`, если добавить `url: 'http://mirror.ru/something'`, то ссылки на комментарии будут `http://mirror.ru/something#cc-12345`
ratingOff	Boolean	false	Скрывает форму голосования (звездочки) и микроразметку рейтинга в виджете комментариев
schemaOff	Boolean	false	Отключает микроразметку schema.org (Product, AggregateRating, Rating) в виджете отзывов
product	Объект		Добавляет описание товара в виджет отзывов согласно микроразметке http://schema.org/Product. Используя данный параметр, отзывы индексируются в Google вместе с выводом рейтинга в виде звезд в результатах поиска. Например: product: {brand: 'Apple', name: 'iPhone 6 Plus 128Gb', photo: 'http://site.ru/iphone.png', price: 65000, priceCurrency: 'RUB'}
lang	Строка	en	Язык виджета. Доступны: ru - Русский uk - Украинский be - Белорусский kk - Казахский en - Английский es - Испанский de - Немецкий lv - Латвийский lt - Литовский el - Греческий fr - Французский ro - Румынский hy - Армянский ka - Грузинский it - Итальянский bg - Болгарский hi - Хинди id - Индонезийский pt - Португальский
msg	Объект		Для использования своих надписей в виджете комментариев, отзывов.
providers	Строка	googleplus;twitter; vkontakte;odnoklassniki;mymailru; yandex;tumblr;live;linkedin; stackoverflow;dropbox; soundcloud;foursquare;yammer; 500px;flickr;google;yahoo; myopenid;livejournal; wordpress;verisign;cackle; anonym;other;	Порядок следования социальных иконок авторизации. Например можно ограничится всего двумя: `providers: 'vkontakte;odnoklassniki;other;'` Иконка 'other' служит для отсечения остальных иконок и вызова главного окна авторизация.
theme	Строка	black	Тема виджета: 'black' - для сайтов с темным фоном.
stream	Boolean	false	Превращает виджет комментариев в непрерывный чат, в этом режиме пользователи видят новые сообщения мгновенно, без уведомлений.
ssoAuth	Строка		MD5 данные пользователя для входа через механизм Единой авторизации (Single sign-on).
ssoProvider	Объект		Добавляет свою иконку Единой авторизации (Single sign-on).
ssoPrimary	Boolean	false	Единая авторизации (Single sign-on) является основной, при этом из всех других авторизации (социальная, анонимная) будут произведен выход.
authPopup	Функция		Переопределяет окно авторизации виджета. Подробнее смотрите Переопределение окна авторизации.
sort	Строка	desc	Сортировка комментариев в виджете: 'asc' (от ранних к новым), 'desc' (от новых к ранним).
size	Число	10	Число комментариев / отзывов на странице, максимум 100.
replies	Число	5	Число ответов (комментариев) к отзывам на странице, максимум 100.
level	Число	4	Уровень вложенность комментариев, 1 - отменяет древовидный вид.
badge	Строка	Админ	Подпись комментария от модератора.
badgeHide	Boolean	false	Скрыть бейдж модератора.
shareSocial	Массив	['vkontakte', 'odnoklassniki', 'mymailru', 'twitter', 'googleplus']	Социальные сети в которые можно расшарить комментарий.
timeFormat	Строка		Форма времени, например: 'yyyy-MM-dd hh:mm:ss'.
textHigh	Число		Максимальная высота комментария (0 - не использовать).
agreement	Ссылка		Ссылка на соглашение о комментировании (выводится в виде checkbox со ссылкой).
guestFirst	Boolean		Вкладка Анонимная авторизация будет первая в окне входа.
guestHideEmail	Boolean		Скрыть Email при анонимной авторизации.
callback.create	Массив функций		Событие при появлении нового комментария, отзыва. callback.create удобно применять при треке комментариев через Google Analytics или сохранении комментария в стороннею базу.
callback.edit	Массив функций		Событие при редактировании комментария
callback.status	Массив функций		Событие при модерации комментария, отзыва
callback.vote	Массив функций		Событие при голосовании за комментарий, отзыв
callback.submit	Массив функций		Событие отправки комментария, отзыва (только в браузере автора комментария)
callback.reply	Массив функций		Событие добавления комментария к отзыву (только в браузере автора комментария)
callback.ready	Массив функций		Окончание загрузки виджета
callback.loggedin	Массив функций		Успешный вход пользователя
callback.logout	Массив функций		Выход пользователя
callback.subscribe	Массив функций		Пользователь подписался на комментарии
callback.unsubscribe	Массив функций		Пользователь отписался

Пример настройки

Данный пример служит наглядной демонстрацией использования параметров виджета комментариев с id 1.

<div id="comments"></div>
<script type="text/javascript">
cackle_widget = window.cackle_widget || [];

cackle_widget.push({
  widget: 'Comment',
  id: 1,
  container: 'comments',
  countContainer: '#commentsCount',
  channel: '123555',
  chanWithoutParams: true,
  url: 'http://ajax.me/somepath#somepage',
  lang: 'ru',
  providers: 'stackoverflow;twitter;vkontakte;odnoklassniki;linkedin;yammer;',
  theme: 'black',

  ssoAuth: '4t34c4y78n3t54y42874nyt847yct874ynt74y84t05= 34tg34g345g3542452g45 1444634545634',
  ssoProvider: {
    name: 'Sign-in by ajax.me',
    url: 'http://ajax.me/sign',
    logo: 'http://ajax.me/logo.png',
    width: 30,
    height: 30
  },

  sort: 'asc',
  timeFormat: 'MM-yy hh:mm:ss',

  callback: {
    create: [function(comment) { console.log(comment); }],
    edit: [function(comment) { console.log(comment); }],
    status: [function(comment) { console.log(comment); }],
    vote: [function(comment) { console.log(comment); }],
    submit: [function(comment) { console.log(comment); }],
    ready: [function(comment) { console.log(comment); }]
  }
});

(function() {
  var mc = document.createElement('script');
  mc.type = 'text/javascript';
  mc.async = true;
  mc.src = ('https:' == document.location.protocol ? 'https' : 'http') + '://cackle.me/widget.js';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(mc, s.nextSibling);
})();
</script>

Свои надписи в виджете (комментариев, отзывов)

С помощью параметра msg можно использовать свой текст в виджете комментариев или отзывов. Для это в коде инициализации виджета добавьте параметр msg в следующем формате (например для виджета Комментариев):

cackle_widget.push({
  widget: 'Comment',
  id: 1,
  msg: {
    placeholder: 'Ваш вопрос?',
    submit: 'Спросить',
    sort: 'Порядок'
  }
});

Название ключей текста (placeholder, submit, sort, и т.д.) можно посмотреть в JavaScript файле локализации виджета по адресу: http://cackle.me/widget/js/lang/<widget_name>[_<lang>].js.
Например для Русского языка:

Виджет комментариев: http://cackle.me/widget/js/lang/comment_ru.js
Виджет отзывов: http://cackle.me/widget/js/lang/review_ru.js

Использование Cackle на AJAX сайтах

Любой виджет вы всегда можете инициализировать динамически с помощью метода Cackle.bootstrap

<html>
<head>

<script type="text/javascript">
var cackle_ajax_init = function() {
  cackle_widget = [];
  cackle_widget.push({widget: 'Comment', id: 1, url: 'http://example.com/#somepage'});
  Cackle.bootstrap(true);
};
</script>

</head>
<body>

<button onclick="cackle_ajax_init()">Reload Cackle</button>

<div id="mc-container"></div>
<script type="text/javascript">
cackle_widget = window.cackle_widget || [];
(function() {
  var mc = document.createElement('script');
  mc.type = 'text/javascript';
  mc.async = true;
  mc.src = ('https:' == document.location.protocol ? 'https' : 'http') + '://cackle.me/widget.js';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(mc, s.nextSibling);
})();
</script>

</body>
</html>

Переопределение окна авторизации

Для переопределения окна авторизации необходимо добавить в объект виджета параметр authPopup, значение которого функция, где происходит логика переопределенной авторизации. Функция принимает на вход параметр: сallback.

Параметр callback - функция, которую необходимо вызывать после AJAX авторизации (без обновления страницы) с передачей SSO токена в качестве единственного аргумента.

В независимости от того, обновляете вы страницу или нет (AJAX), после авторизации будет автоматически вызвано предшествующее событие юзера (публикация комментария, голосование, оценка и т.д.) если оно было.

Примеры использования:

<script type="text/javascript">
cackle_widget = cackle_widget || [];
cackle_widget.push({
  widget: 'Comment',
  id: 1,
  authPopup: function(callback) {
    // 1) Пример ajax авторизации через виджет Cackle Login
    Cackle.Login.main({
      host: 'http://localhost:8080',
      id: 1,
      container: 'cackle-login',
      data: {
        providers: 'google;vkontakte;twitter',
        callback: function() {
          callback();
        }
      }
    });

    // 2) Пример ajax единой авторизации (SSO), например через выдуманный плагин ajaxLogin
    $('#ajax-login').ajaxLogin({
      success: function(ssoAuth) {
        // Авторизация прошла успешно, ssoAuth это SSO токен сформированный на сервере
        callback(ssoAuth);
      }
    });
  }
});
</script>

// 3) Пример авторизации с обновлением страницы
<script type="text/javascript">
cackle_widget = cackle_widget || [];
cackle_widget.push({
  widget: 'Comment',
  id: 1,
  authPopup: function(callback) {
    // Редирект на страницу авторизации сайта
    window.location.href = "http://site.com/login";
  }
});
// Далее идет процесс авторизации на сервере
// Возвращение обратно к форме виджета ложится на плечи разработчика
// После успешной авторизации предшествующее событие (если оно было) вызывается автоматически
</script>