# =========================================================================== #
# NG CMS // Плагины // guestbook                                           #
# =========================================================================== #

Плагин позволяет организовать на сайте гостевую книгу.

При активации плагина становится доступна страница плагина: /plugin/guestbook/

Настройка плагина
=====================

[TWIG] guestbook.list.tpl
------------------------------------------------
Шаблон используется для вывода списка записей гостевой книги и формы добавления записи.

Список переменных:

  * entries - массив, содержащий записи гостевой книги:
    * id            - ID записи
    * comnum        - порядковый номер записи
    * date          - дата публикации записи (в формате, указанном в настройках плагина)
    * message       - текст записи
    * answer        - ответ администратора
    * author        - логин автора записи, либо guest (гость)
    * ip            - ip-адрес автора записи
    * edit          - ссылка на редактирование записи (для администратора)
    * del           - ссылка на удаление записи (для администратора)
    * fields        - массив с заполненными данными доп. полей записи (ключ - id поля):
      * id          - id поля
      * name        - название поля
      * value       - значение поля
    * social        - массив с данными соцсетей (ключ - название: Vkontakte, Facebook, Google, Instagram):
      * link        - ссылка на профиль пользователя
      * photo       - ссылка на аватар пользователя

  * fields  - массив всех доп. полей гостевой книги (ключ - id поля):
    * id            - id поля,
    * name          - название поля;
    * placeholder   - заполнитель поля;
    * default_value - значение поля по умолчанию;
    * required      - является ли поле обязательным;

  * total_count     - общее количество записей в гостевой книге
  * perpage         - количество записей, отображаемых на одной странице
  * errors          - сообщения об ошибках
  * success         - сообщения об успешных действиях
  * smilies         - смайлы
  * bbcodes         - BB-коды
  * ip              - ip-адрес пользователя (используется при публикации записи)
  * use_captcha     - true, если капча включена
  * use_guests      - true, если разрешено добавлять записи без входа на сайт
  * pages           - виджет постраничной навигации

[TWIG] guestbook.edit.tpl
------------------------------------------------
Шаблон используется для редактирования записи без входа в админку.
Предоставляет урезанные возможности - в частности, нельзя редактировать данные соцсетей.

Список переменных:

  * id              - ID записи
  * author          - логин автора записи, либо guest (гость)
  * message         - текст записи
  * answer          - ответ администратора
  * error           - сообщения об ошибках
  * fields  - массив всех доп. полей записи (ключ - id поля)
    * id            - id поля
    * name          - название поля
    * placeholder   - заполнитель поля
    * default_value - значение поля по умолчанию
    * required      - является ли поле обязательным
    * value         - значение, указанное автором записи

[TWIG] guestbook.block.tpl
------------------------------------------------
Шаблон используется для вывода блока последних записей в main.tpl.
Записи содержатся в переменной entries, структура подобна шаблону guestbook.list.tpl

Для вывода блока использовать конструкцию:

  {{ callPlugin('guestbook.show', {'count': '2'}) }}

где count - необходимое количество записей.

Настройки ЧПУ
---------------------

Вы можете указать собственные адреса страниц плагина. Для этого необходимо:
  1. включить ЧПУ в настройках плагина,
  2. прописать параметры URL для плагина guestbook в "Управление форматом ссылок".

Пример:

guestbook   edit    Редактирование    /guestbook/edit/{id}
guestbook           Гостевая книга    /guestbook/[{page}/][{act}]

Где:
  - {id}      для страницы редактирования: ID редактируемой записи
  - {page}    для страницы списка записей: номер страницы
  - {act}     для страницы списка записей: успешно выполнено действие (add = запись добавлена, upd = запись отредактирована, del = запись удалена)

Настройки привязки соцсетей
---------------------

1. Плагин поддерживает привязку соцсетей: Вконтакте, Facebook, Google Plus, Instagram

2. Привязка позволяет пользователю при добавлении записи нажать соответствуюшую кнопку и пройти авторизацию

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

Регистрация приложений
---------------------

Для каждой социальной сети нужно отдельно регистрировать приложение, а затем указать в настройках полученные Client ID и Client Secret

Вконтакте:

- залогиниться в свой аккаунт
- перейти по ссылке: http://vk.com/editapp?act=create
- указать название приложения (по желанию), адрес сайта, тип приложения - вебсайт
- пройти СМС-подтверждение
- получить и скопировать Client ID и Client Secret

Facebook:

- залогиниться в свой аккаунт
- перейти по ссылке: https://developers.facebook.com/apps
- нажать "Add new app" и во всплывающем окне нажать внизу Advanced setup
- указать имя (по желанию), категория - Общение
- в левом меню выбрать Settings и заполнить поле Contact Email
- оставаясь на странице Settings, нажать Add Platform, выбрать Website, указать адрес вашего сайта
- в левом меню выбрать App Details, указать User Support Email
- в левом меню выбрать Status & Review, поставить галочку "Make this app available to the general public"
- в левом меню выбрать Dashboard
- получить и скопировать Client ID и Client Secret

Google:

- залогиниться в свой аккаунт
- перейти по ссылке: https://console.developers.google.com/project
- нажать Create new project, имя указать по желанию
- дождаться сообщения об успешном создании проекта
- нажать Enable & manage API's
- нажать Google+ API, на открывшейся странице нажать Enable API
- в левом меню выбрать Credentials затем вкладку OAuth consent screen
- указать название (по желанию), сохранить изменения
- появится окно с кнопкой Create new credentials - нажать и выбрать OAuth CLient ID
- выбрать тип: Web application, название указать по желанию
- в поле Authorized redirect URIs указать: http://example.com/engine/plugins/guestbook/lib/hybridauth/?hauth.done=Google
- в следующей строке этого же поля - продублировать вышеуказанную запись с www
- получить и скопировать Client ID и Client Secret

Instagram:

- залогиниться в свой аккаунт
- перейти по ссылке: https://instagram.com/developer/clients/manage/
- нажать Register new client
- указать название и описание (по желанию), адрес сайта, Privacy policy URL, Contact Email
- в поле Valid redirect URI указать: http://example.com/engine/plugins/guestbook/lib/hybridauth/?hauth.done=Instagram
- в следующей строке этого же поля - продублировать вышеуказанную запись с www
- получить и скопировать Client ID и Client Secret
- для того, чтобы выйти из режима песочницы (Sandbox Mode) - нажать Permissions и отправить приложение на рассмотрение (Submit for review)