SalesPlatform Vtiger CRM Developers Руководство Создание нового модуля

Материал из SalesPlatform Wiki
Перейти к: навигация, поиск

Главная страница руководства


Модуль является функциональной единицей Vtiger CRM. Каждый модуль, следуя паттерну Model-View-Controller (MVC), состоит из Моделей, Контроллеров, Представлений и связанных с ними ресурсов, которые необходимы для управления данными и пользовательского интерфейса. Модули бывают двух типов: Модуль-сущность (Entity Module) и Модуль-расширение (Extension Module). В данной статье речь пойдет о создании Модуля-сущности.

Vt important.png Важно
Перед тем, как создавать новый Модуль, выполните действия из статьи «Окружение разработчика».

Содержание

Модуль “MyModule

Модуль будет состоять из двух блоков:

  1. Общая информация
  2. Описание
Состав полей блока “Общая информация”
Название поля Тип поля
Название* Текстовое поле
Заказ* Поле-ссылка на карточку Заказа
Статус* Выпадающий список. Значения: Активно, Неактивно
Дата Дата
Ответственный* Ответственный


Состав полей блока “Описание”
Название поля Тип поля
Описание Текстовая область


Поля отмеченные звездочкой (*) для обязательного заполнения.
Связанные списки

Для начала в корне системы создайте файл для размещения кода модуля <filename>.php. В нем подключите модули Module.php и Package.php.

 <?php
 include_once('vtlib/Vtiger/Module.php'); 
 require_once('vtlib/Vtiger/Package.php');

В файле Module.php описан класс Vtiger_Module, который предлагает API для работы с модулями Vtiger CRM, таких как initWebservice, getInstance, setRelatedList и другие.
Включить протоколирование.

 $Vtiger_Utils_Log = true;

Сохранение имени модуля в переменной MODULENAME.

 $MODULENAME = 'MyModule';

Создание нового модуля.

 $moduleInstance = new Vtiger_Module();

В поле name задать имя модуля.

 $moduleInstance->name = $MODULENAME;

В поле parent задать глобальный раздел, к которому принадлежит модуль.

 $moduleInstance->parent = 'Tools';

Сохранение изменений.

 $moduleInstance->save();

Для Модуля инициализировать (создать) 2 таблицы.

 $moduleInstance->initTables();
Перечень созданных таблиц
Таблица Имя таблицы в БД Описание
Базовая таблица vtiger_<modulename> Содержит поля нового модуля
Настраиваемая таблица vtiger_<modulename>cf Содержит настраиваемые (пользовательские) поля


Класс Vtiger_Block предлагает API для работы с блоком Модуля, содержащий контейнер, в котором помещаются все поля.
Создание нового блока.

 $info_block = new Vtiger_Block();

Отображение названия блока для пользователя.

 $info_block->label ='LBL_'. strtoupper($moduleInstance->name) . '_INFORMATION';

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

 $moduleInstance->addBlock($info_block);

Второй блок “Описание” создается аналогичным способом.
Класс Vtiger_Field предлагает API для работы с полями Модуля, которые являются основными элементами, которые хранят и отображают данные записи модуля.

Создание полей для Модуля "MyModule"

Создание текстового поля

Пример текстового поля (см. рис.1).

Рис. 1: Текстовое поле


Создание нового поля.

 $name_filed = new Vtiger_Field();

Присвоение имени полю.

 $name_filed->name = 'name';

Отображение названия поля для пользователя.

 $name_filed->label = 'Name';

Каждое поле в Модуле содержит информацию, которая может быть представлена в разных видах: текстовое поле, выпадающий список, текстовая область, дата и время и др.
Тип поля задается свойством uitype. Список некоторых из них можно посмотреть по ссылке: https://wiki.vtiger.com/index.php/UI_Types .

Список наиболее из распространенных полей представлен ниже
UI type Описание
1 Текстовое поле
4 Автоинкрементное поле (номер идентификатор сущности)
5 Поле Дата с ссылкой на Календарь
10 Поле ссылка на другой модуль
15 Список с возможностью выбора одного из значений
16 Раскрывающийся список. Значения в раскрывающемся списке могут отличаться от модуля к модулю и не зависят от роли (без роли) на основе текущего пользователя.
19 Текстовая область для ввода нескольких строк текста (н-р: "Описание", "Решения")
53 Поле “Ответственный” (раскрывающийся список, где выбирается имя пользователя или группа).
70 Дата и время. Должен использоваться для создания таких полей, как время создания/ изменения Модуля


Тип представления для поля.

 $name_filed->uitype = 1;

Отобразить поле в кратком виде карточки.

 $name_filed->summaryfield =1;

Название столбца в соответствующей таблице.

 $name_filed->column = $name_field->name;

Тип данных в столбце таблицы.

 $name_filed->columntype = 'VARCHAR(255)';

Тип вводимых данных

 $name_filed->typeofdata = 'V~M';

Тип вводимых данных должен соответствовать типу данных в БД.

‘V’- VARCHAR;
‘M’- поле обязательно для заполнения (‘О’ - поле необязательно для заполнения).

Подробнее можно посмотреть по ссылке: https://wiki.vtiger.com/index.php/TypeOfData .

Добавление созданного поля в соответствующий блок.

 $info_block->addField($name_filed);

Одно из обязательных полей должно быть установлено в качестве идентификатора модуля. Значение данного поля (связанный Модуль) будет подставлено в поле-ссылку основного Модуля. Идентификация модуля осуществляется методом setEntityIdentifier, который вызывается только один раз.
Идентификация модуля.

 $moduleInstance->setEntityIdentifier($name_filed);

Создание поля со списком возможных значений

Пример поля со списком возможных значений (см. рис. 2).

Рис. 2: Раскрывающийся список


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

 $status_field = new Vtiger_Field();
 $status_field->name = 'is_active_status';
 $status_field->label = 'Статус';
 $status_field->uitype = 16;
 $status_field->column = $status_field->name;
 $status_field->columntype = 'VARCHAR(255)';
 $status_field->typeofdata = 'V~M';
 $info_block->addField($status_field);
 $status_field->setPicklistValues(Array('Активно', 'Неактивно'));

Если поле имеет тип PickList (uitype равно одному из перечисленных значений: 15, 16, 33, 55, 111), то вы можете задать начальные значения:

 $status_field->setPicklistValues(Array('Активно', 'Неактивно'));

где метод setPicklistValues принимает на вход массив возможных значений.

Создание поля-ссылки на связанный Модуль

Пример поля-ссылки (uitype равно 10) на связанный Модуль (см. рис.3).

Рис. 3: Поле-ссылка


При выборе Review.png открывается дополнительное окно, отображающее записи Модуля, который связан с данным полем. При необходимости можно добавить новую запись в Модуль, при нажатии на кнопку Plus.png.

В отличии от предыдущих примеров в коде присутствует метод setRelatedModule.

 $order_field = new Vtiger_Field();
 $order_field->name = 'salesorderid';
 $order_field->label = 'Sales order';
 $order_field->uitype = 10;
 $order_field->summaryfield =1;
 $order_field->column = $order_field->name;
 $order_field->columntype = 'INT(19)';
 $order_field->typeofdata = 'I~M';
 $info_block->addField($order_field);
 $order_field->setRelatedModules(Array('SalesOrder'));

Для того, чтобы в поле можно было указать ссылку на связанный модуль нужно использовать метод setRelatedModules(Array('SalesOrder')), который принимает на вход массив с названиями модулей.

Создание стандартного поля

Существуют стандартные поля, которые содержатся почти в каждом модуле, например: Ответственный, Создано, Изменено. Добавим в наш Модуль “MyModule” стандартное поле “Ответственный”. Добавление таких полей происходит следующим образом:

 $responsible_field = new Vtiger_Field();
 $responsible_field->name = 'responsible';
 $responsible_field->label = 'Ответственный';
 $responsible_field->table = 'vtiger_crmentity';
 $responsible_field->column = 'smownerid';
 $responsible_field->uitype = 53;
 $responsible_field->typeofdata = 'V~M';
 $info_block->addField($responsible_field);

В свойство “table” поля “responsible_field” указываем конкретную таблицу "vtiger_crmentity", которая содержит информацию о том, какое поле было создано, в каком модуле, когда и т.п.

Таблица 'vtiger_crmentity' содержит следующие атрибуты
Название столбца Тип в таблице
crmid int(19)
smcreatorid int(19)
smownerid int(19)
modifiedby int(19)
setype varchar(30)
description text
createdtime datetime
modifiedtime datetime
viewedtime datetime
status varchar(50)
version int(19)
presence int(1)
deleted int(1)
label varchar(255)
Vt important.png Важно
При создании поля название столбца должно полностью совпадать с названием столбца из таблицы (в нашем случае: $responsible_field->column = 'smownerid';).

Создание поля Дата

Создание поля Дата происходит аналогично примеру создания текстового поля:

 $date_field = new Vtiger_Field();
 $date_field->name = 'date';
 $date_field->label = 'Date';
 $date_field->uitype = 5;
 $date_field->column = $date_field->name;
 $date_field->columntype = 'DATE';
 $date_field->typeofdata = 'D~O';
 $info_block->addField($date_field);

Добавление связанного списка к Модулю

Пример связанного списка Модуля (см. рис.4).

Рис. 4: Связанный список Модуля


Существуют следующие типы связей между модулями:

Типы связей можно просмотреть в таблице “vtiger_relatedlists” в поле “name”.
Для установки связи двух Модулей используется функция:

 Vtiger_Module->setRelatedList(<TARGET MODULE>[, <HEADER LABEL>, <ALLOWED ACTIONS>,<CALLBACK FUNCTION NAME>]);

где:

<TARGET MODULE> - название связываемого модуля;
<HEADER LABEL> - название ссылки на связанный список;
<ALLOWED ACTIONS> - кнопки которые будут показаны в соответствующем окне зависимого списка. По умолчанию вместо кнопок используется “false” - соответствующих кнопок не будет;
<CALLBACK FUNCTION NAME> - функция, осуществляющая связь между Модулями (по умолчанию используется “get_related_list”).

В нашем примере создадим отношение многие ко многим между модулями “MyModule” и “Contacts” – Related list.
Создание объекта типа “Contacts”.

 $contactModule = Vtiger_Module::getInstance('Contacts');

Надпись возле списка.

 $relLabel ='Contacts';

Установка связи основного Модуля с зависимым Модулем.

 $moduleInstance->setRelatedList( $contactModule, $relLabel, Array('ADD','SELECT'));

Методу setRelatedList в качестве параметров передаются:

Добавление фильтра

Пример фильтра “Все Контакты” (см. рис.5).

Рис. 5: Фильтр “Все Контакты”


Класс Vtiger_Filter предлагает API для работы с модулем в настраиваемом представлении или фильтре. Список записей контролируется с помощью этих фильтров, т.е. при открытии данного модуля будут отображать только те поля, которые были добавлены в фильтр и по этим же полям будет происходить поиск.

Приведенный ниже пример описывает способ настройки фильтра для модуля:

Создание нового фильтра.

 $filter1 = new Vtiger_Filter();

Название фильтра.

 $filter1->name = 'All';

Установка фильтра по умолчанию.

 $filter1->isdefault = true;

Добавление созданного фильтра в Модуль.

 $moduleInstance->addFilter($filter1);

Добавление полей в фильтр.

 $filter1->addField($name_filed)->addField($order_field, 1)->addField($status_field, 2);

Для добавления полей в фильтр используется метод AddField. В качестве параметров ему передаются: объект поля и необязательное значение порядка (индекс), при котором поле должно появиться в списке.


Для работы нового модуля следует добавить файл в каталоге modules/<MODULENAME>/<MODULENAME>.php. Название файла должно совпадать с названием модуля (н-р: modules/MyModule/MyModule.php). В данном файле должен быть определен главный класс модуля, унаследованный от класса Vtiger_CRMEntity. Кроме того, в нем должны быть определены обязательный свойства приведенные ниже, необходимые для работы модуля.

  <?php
      include_once 'modules/Vtiger/CRMEntity.php';
  
      class MyModule extends Vtiger_CRMEntity {
      
          //таблица с полями Модуля
          var $table_name = 'vtiger_mymodule';

          //название ключевого поля в таблице 
          var $table_index = 'mymoduleid';     
 
          var $customFieldTable = Array('vtiger_mymodulecf', 'mymoduleid');
 
          var $tab_name = Array('vtiger_crmentity', 'vtiger_mymodule', 'vtiger_mymodulecf');
      
          var $tab_name_index = Array('vtiger_crmentity' => 'crmid',
                                      'vtiger_mymodule' => 'mymoduleid',
                                      'vtiger_mymodulecf' => 'mymoduleid');
      }

где:

указывается таблица для поддержки пользовательских полей:
 var $customFieldTable = Array('vtiger_mymodulecf', 'mymoduleid');
указывается с какими таблицами работает данный модуль:
 var $tab_name = Array('vtiger_crmentity', 'vtiger_mymodule', 'vtiger_mymodulecf');

указываются ключевые поля таблиц:

 var $tab_name_index = Array('vtiger_crmentity' => 'crmid','vtiger_mymodule' => 'mymoduleid','vtiger_mymodulecf' => 'mymoduleid');

Также нужны файлы локализации, в каталоге languages/, например languages/ru_ru/<MODULENAME>.php


Vt note.png Примечание
Для локализации названий полей, блоков, а также записей раскрывающихся списков необходимо создать файлы локализации в каталоге "languages", например languages/ru_ru/<MODULENAME>.php (код файла представлен ниже) и в каталоге "renamed" надо создать файл <MODULENAME>.php со следующим содержимым: <?php
  
  <?php
      $languageStrings = array(
          'MyModule'                     => 'Мой Модуль', 
	  'SINGLE_MyModule'              => 'Мой Модуль', 
	  'LBL_ADD_RECORD'               => 'Добавить запись в мой Модуль',
	  'LBL_RECORDS_LIST'             => 'Список записей в моем Модуле', 
	  'LBL_MYMODULE_INFORMATION'     => 'Информация о Модуле', 
	  'LBL_MYMODULE_DESCRIPTION'     => 'Описание', 
	  'Name'                         => 'Имя', 
	  'Is_active_status'             => 'Статус', 
	  'Sales order'                  => 'Заказ', 
	  'Date'                         => 'Дата', 
	  'Responsible'                  => 'Ответственный', 
	  'Description'                  => 'Описание', 
      );

    // Начать исправление
    include 'renamed/MyModule.php';


Кроме того, можно получить zip-архив, который можно использовать для установки через Менеджер Модулей:

 $package = new Vtiger_Package(); 
 $package->export($moduleInstance,'test/vtlib','MyModule.zip',false);

где:

$moduleInstance - экземпляр Модуля для экспорта
test/vtlib - каталог, в котором должен быть создан архив модуля
MyModule.zip - название архива модуля
false - отключение загрузки архива


Теперь можно создать модуль. Для этого необходимо запустить на исполнение написанный php-скрипт. В результате его работы, будет создан новый модуль, и кроме того будет создан архив test/vtlib/MyModule.zip, который можно использовать для инсталляции на других системах через Менеджер Модулей.

Vt important.png Важно
После того, как будет создан модуль, необходимо для версии SalesPlatform Vtiger CRM 7 дополнительно создать таблицу "vtiger_mymodule_user_field" при помощи следующего запроса:
CREATE TABLE IF NOT EXISTS `vtiger_mymodule_user_field` (
`recordid` int(25) NOT NULL,
`userid` int(25) NOT NULL,
`starred` varchar(100) utf8_general_ci,
PRIMARY KEY (`recordid`)) ;

Готовый скрипт

  <?php
      include_once 'vtlib/Vtiger/Module.php';
      require_once('vtlib/Vtiger/Package.php');
  
      $Vtiger_Utils_Log = true;
  
      $MODULENAME = 'MyModule';

      $oldInstance = Vtiger_Module::getInstance($MODULENAME);
      if ($oldInstance) $oldInstance->delete();

      $moduleInstance = new Vtiger_Module();
      $moduleInstance->name = $MODULENAME;
      $moduleInstance->parent = 'Tools';
      $moduleInstance->save();
      $moduleInstance->initTables();
  
      $info_block = new Vtiger_Block();
      $info_block->label = 'LBL_' . strtoupper($moduleInstance->name) . '_INFORMATION';
      $moduleInstance->addBlock($info_block);
  
      $contactModule = Vtiger_Module::getInstance('Contacts');
      $relLabel ='Contacts';
      $moduleInstance->setRelatedList( $contactModule, $relLabel, Array('ADD', 'SELECT'));
  
      $name_filed = new Vtiger_Field();
      $name_filed->name = 'name';
      $name_filed->label = 'Name';
      $name_filed->uitype = 2;
      $name_filed->summaryfield =1;
      $name_filed->column = $name_filed->name;
      $name_filed->columntype = 'VARCHAR(255)';
      $name_filed->typeofdata = 'V~M';
      $info_block->addField($name_filed);
      $moduleInstance->setEntityIdentifier($name_filed);
  
      $status_field = new Vtiger_Field();
      $status_field->name = 'is_active_status';
      $status_field->label = 'Status';
      $status_field->uitype = 16;
      $status_field->summaryfield =1;
      $status_field->column = $status_field->name;
      $status_field->columntype = 'VARCHAR(255)';
      $status_field->typeofdata = 'V~M';
      $info_block->addField($status_field);
      $status_field->setPicklistValues(Array('Активно', 'Неактивно'));
  
      $order_field = new Vtiger_Field();
      $order_field->name = 'salesorderid';
      $order_field->label = 'Sales order';
      $order_field->uitype = 10;
      $order_field->summaryfield =1;
      $order_field->column = $order_field->name;
      $order_field->columntype = 'INT(19)';
      $order_field->typeofdata = 'I~M';
      $info_block->addField($order_field);
      $order_field->setRelatedModules(Array('SalesOrder'));
  
      $date_field = new Vtiger_Field();
      $date_field->name = 'date';
      $date_field->label = 'Date';
      $date_field->uitype = 5;
      $date_field->column = $date_field->name;
      $date_field->columntype = 'DATE';
      $date_field->typeofdata = 'D~O';
      $info_block->addField($date_field);
  
      $responsible_field = new Vtiger_Field();
      $responsible_field->name = 'responsible';
      $responsible_field->label = 'Ответственный';
      $responsible_field->table = 'vtiger_crmentity';
      $responsible_field->column = 'smownerid';
      $responsible_field->uitype = 53;
      $responsible_field->typeofdata = 'V~M';
      $info_block->addField($responsible_field);
   
      //second block
      $description_block = new Vtiger_Block();
      $description_block->label = 'LBL_' . strtoupper($moduleInstance->name) . '_DESCRIPTION';
      $moduleInstance->addBlock($description_block);
  
      $description_field = new Vtiger_Field();
      $description_field->name = 'description';
      $description_field->label = 'Description';
      $description_field->column = $description_field->name;
      $description_field->columntype = 'VARCHAR(255)';
      $description_field->uitype = 19;
      $description_field->typeofdata = 'V~O';
      $description_block->addField($description_field);
  
      $filter1 = new Vtiger_Filter();
      $filter1->name = 'All';
      $filter1->isdefault = true;
      $moduleInstance->addFilter($filter1);
      $filter1->addField($name_filed)->addField($order_field,1)->addField($status_field, 2);
  
      //настройка совместного доступа (права доступа устанавливаются по умолчанию). 
      $moduleInstance->setDefaultSharing();
  
      //инициализация Веб-сервиса (автоматический вызов API)
      $moduleInstance->initWebservice();   
  
      $package = new Vtiger_Package();
      $package->export($moduleInstance, 'test/vtlib', 'MyModule.zip', false);


В результате у Вас должен создаться Модуль “MyModule” в разделе “Инструменты” (см. рис. 6). У Модуля присутствует связанный список “Контакты” (см. рис.8,9).

Рис. 6: Модуль “MyModule”
Рис. 7: Страница добавления записи
Рис. 8: Ссылка на связанный список “Контакты”
Рис. 9: Связанный список “Контакты”



Главная страница руководства

Личные инструменты
Пространства имён
Варианты
Действия
Навигация
Документация
Разработчикам
Присоединяйтесь!
Инструменты