Ассистент¶

Модуль ELiS Assistent создает виртуального помощника в виде блока, с которым пользователь может общаться и просить выполнить определенные задачи.

Блок с помощником может размещаться в любой части сайта стандартными средствами Drupal (admin/structure/block).

Сам модуль ELiS Assistent имеет только лишь базовый функционал, фактически навыки (skills) с определенными полезными действиями (actions) надо разрабатывать самостоятельно в виде отдельных модулей.

Некоторые модули ELiS, такие как ELiS H5P и ELiSsearch реализуют навыки для виртуального помощника.

Установка¶

Установите модуль ассистента (# dnf install drupal7-elis-mod-assistent) и включите модуль ELiS Assistent.

В настройках модуля admin/config/content/elis_assistant задайте имя помощника, приветствие (может содержать HTML-код), цвет фона и текста блока с ассистентом и несколько эмоциональных изображений, желательного одного размера.

Вам понадобится минимум одно собственное изображение ассистента (default image), которое будут видеть пользователи по умолчанию.

В настройках прав модуля ELiS Assistent в admin/people/permissions добавьте право нужным ролям на использование ассистента.

В настройках блоков в admin/structure/block найдите блок ELiS Assistent и разместите его в нужной части сайта.

Эмоции¶

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

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

Навыки¶

У помощника есть навыки, которые должны наследоваться от класса ElisAssistantSkill (sites/all/modules/elis_assistant/class/ElisAssistantSkill.class.php).

Сам навык имеет только имя, фразу активации и несколько действий (массив actions).

Реальную работу обеспечивают именно действия из ElisAssistanSkill->actions.

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

Пример кода:

class MYMODULEAssistantSkill extends ElisAssistantSkill {

  public function __construct() {
    $this->id = get_class($this);
    $this->activationPhrases = array('MYMODULE фраза 1','MYMODULE фраза 2');
    $this->actions = array();

    $action = new MYMODULEAssistantSkillAction(); // действие, которое тоже реалзует ваш модуль, см. ниже
    $this->actions[] = $action;
  }

  public isCanUse($account) {
    return TRUE;
  }

}

У навыка есть метод isCanUse($account), который по умолчанию возвращает для всех TRUE. Переопределите его, если хотите, чтобы навык могли использовать только некоторые пользователи.

Действия¶

Действия навыка должны наследоваться от класса ElisAssistantSkillAction (sites/all/modules/elis_assistant/class/ElisAssistantSkillAction.class.php).

У действий, как и у навыка, есть фразы активации.

Когда пользователь пишет какое-либо сообщение, сравниваются его слова со всеми фразами активации и если есть попадание, то возможные действия в виде заглавий (title) попадают в автодополнение.

Если пользователь выберет из автодополнение действие и оно является кликабельным, вызовется callback действия (ElisAssistantSkillAction::callback), который должен указывать на какой-то статический метод класса.

Если пользователь не выберет автодополнение, а просто отправит помощнику текстовое сообщение, помощник проверит с какими фразами активации есть попадания сообщения пользователя, выберит действие с наибольшим числом попаданий согласно весовому коэффициенту действия (ElisAssistantSkillAction::weight, больше - выше вероятность срабатывания) и вызовет ElisAssistantSkillAction::callback.

class MYMODULEAssistantSkillAction extends ElisAssistantSkillAction {

  public $id = 'MYMODULE_action1';
  public $title = 'Мое действие 1';
  public $activationPhrases = array('активируйся по попаданию в эту фразу','или по попаданию во вторую фразу');
  public $callback = 'MYMODULEAssistantSkillAction::callback_my_action'; // этот статический метод будет вызван при выполнении действия
  public $isClickable = true;

  public static function isCanUse($account) {
    return ($account->uid > 0) ? TRUE  : FALSE;
  }

  public static function callback_my_action() {
    $msg = new ElisAssistantMsg();
    $msg->html = '<div>Hello worlds</div>';
    return $msg;
  }

}

У действия есть метод isCanUse($account), который по умолчанию возвращает для всех TRUE. Переопределите его, если хотите, чтобы навык могли использовать только некоторые пользователи.

Выполнение действий¶

Обработчик действий ElisAssistantSkillAction::callback должен совершить какую-то полезную работу и в качестве ответа вернуть экземпляр класса ElisAssistantMsg (sites/all/modules/elis_assistant/class/ElisAssistantMsg.class.php).

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

Чтобы получить текстовое сообщение пользователя, инициировавшего действие, вам нужно его получить из параметра $_REQUEST[‘text’] и как-то обработать.

Обработав действие и возвращая ответ в виде сообщения ElisAssistantMsg, вам надо пользователю передать какую-то информацию.

Сообщение пользователю¶

Отправка сообщения пользователю осуществляется созданием и заполнением экземпляра ElisAssistantMsg (sites/all/modules/elis_assistant/class/ElisAssistantMsg.class.php).

Ответ пользователя может быть текстовым, тогда вы заполняете ElisAssistantMsg->text.

Если вам надо отправить ответ в виде HTML-кода, заполните ElisAssistantMsg->html. При этом имейте в виду, что в такой HTML нельзя размещать JavaScript.

Если дополнительно к HTML надо выполнить JavaScript, то заполните ElisAssistantMsg->script. При этом скрипт будет выполнен после отображения ElisAssistantMsg->html.

Добавление навыка¶

Чтобы ваш модуль добавил навык в список доступных, модуль должен реализовать хук hook_elis_assistant.

Пример:

function MYMODULE_elis_assistant($module=array()) {
  $skill = new MYMODULEAssistantSkill(); // здесь должен быть ваш класс, наследующий ElisSearchAssistantSkill
  $module['skills'][] = $skill;
  return $module;
}

Стилизация внешнего вида помощника¶

В sites/all/modules/elis_assistant/css/ElisAssistant.css определены стили.

Вы можете переопределить эти стили стандартными средствами Drupal, например создав блок с HTML-кодом и выведя его там же, где и помощник.

Некоторые настройки внешнего вида доступны также в настройках модуля admin/config/content/elis_assistant

Примеры¶

Посмотрите примеры в sites/all/modules/elis_h5p/elis_h5p.assistant.inc и sites/all/modules/elis_search/elissearch.assistant.inc.

Обратите внимание, если помощник на сообщение пользователя не найдет навык по фразам активации, то он выполнит навык и действие по умолчанию (у которых задан флаг isDefault), таким навыком и действием является полнотекстовый поиск. Вам не стоит создавать другие навыки по умолчанию.