Blog

2014年3月25日火曜日

vTigerCRM6にて既存のモジュールにフィールドを追加してみる

時刻: 17:00 ラベル: , ,
既存のモジュールに対して新たにカスタムフィールド（項目）を追加する方法をご紹介します。
追加の方法と書いていますが、追加だけでなく削除の方法も合わせて書きますので少々長めの投稿となってしまいます。

vTigerCRM6は、全てのフィールドはRBACで制御されていますので、力技でコードを弄ろうとすると痛い目を見ましたる場合があり、そのためvTigerCRMの作法に則って追加する必要があります。

作法といっても知ってしまえば大したものでもないので紹介させていただきます。

まず、vTigerCRMの管理画面を触ったことのある人は分かると思いますが、項目の追加方法は幾つかあります。

まず一つ目は、標準の管理画面から変更する方法。

管理画面→スタジオ→フィールドの編集で、サクッと追加可能です。


ただ、こちらで追加可能なのは以下の種類の項目だけです。
  • テキスト
  • 少数付き数値
  • 整数
  • パーセント
  • 通貨
  • 日付
  • 電子メール
  • 電話
  • Picklist（選択コンボ ボックス）
  • URL
  • チェックボックス
  • テキスト エリア
  • 複数選択コンボ ボックス
  • Skype
  • 時刻
vTigerCRMにこれ以外にも多くの種類のフィールド（例えば他モジュールへの参照項目等）が存在するのですが、そちらを追加するにはプログラムを書かなければなりません。

プログラムを書くといっても、vTigerCRMに直接変更を加えるのではなく、vTigerCRMへ項目の追加する指示をだすプログラムを書くといったイメージです。
それにはvTlibというvTigerCRMをカスタマイズする為のライブラリを使用する必要があります。

それではまず、vTlibをつかったソースの流れを簡単に説明します。
  1. １．変更を加えるモジュールを指定する。
  2. ２．項目を追加するブロックを指定する。
  3. ３．フィールドを追加する。
大雑把に書くと上記のような3ステップが必要になります。
ブロックってなに？って方は以下のキャプチャをご確認ください。


各モジュールに対して、項目はブロックという単位で管理されています。
上の図で言えばオレンジ色で囲まれている箇所がブロックになります。
画面を見ればすぐ分かると思いますが、項目を追加する際は、どのブロックに追加するの？を指定しなければならないというだけですね。
ちなみにブロックの追加は、上述のフィールドの編集画面から追加削除が可能です。
また、後ほど説明しますが、URLの赤色で囲まれている箇所がモジュール名になります。

それでは、実際のコードを以下に記します。 以下は、価格表（PriceBooks）モジュールに対して三つのタイプのフィールドを追加しています。 
<?php
// ０．ログを出力する
$Vtiger_Utils_Log = true;
include_once('vtlib/Vtiger/Menu.php');
include_once('vtlib/Vtiger/Module.php');

// １．モジュールを指定
$module =  Vtiger_Module::getInstance('PriceBooks');

// ２．ブロックを指定
$block = Vtiger_Block::getInstance('LBL_DESCRIPTION_INFORMATION',$module);

// ３．テキスト型のフィールドを追加
$field = new Vtiger_Field();
$field->label = 'テストフィールド';　//表示名
$field->name = 'test_field';　　　　 //フィールド名
$field->table = 'vtiger_notes';　　　//項目を追加するテーブル名
$field->column = 'test_field';　　　 //テーブルに追加するカラム名
$field->columntype = 'VARCHAR(255)'; //カラム名の型
$field->uitype = 2;　　　　　　　　　//UIタイプ
$field->typeofdata = 'V~O';　　　　　//vTigerCRM上でのデータタイプ
$block->addField($field);　　　　　　//追加します

// ４．他のモジュールを参照させるタイプのフィールドを追加
$field2 = new Vtiger_Field();
$field2->label = '関連モジュールフィールド';　
$field2->name = 'related_field';
$field2->table = 'vtiger_notes';
$field2->column = 'related_field';
$field2->columntype = 'INT(19)';
$field2->uitype = 10;
$field2->typeofdata = 'V~O';

$block->addField($field2);

$field2->setRelatedModules(Array('Contacts', 'Leads')); //関連モジュールを指定

// ５．単項目選択型のフィールドを追加
$field3 = new Vtiger_Field();
$field3->label = '選択項目フィールド';
$field3->name = 'pick_field';
$field3->table = 'vtiger_notes';
$field3->column = 'pick_field';
$field3->columntype = 'VARCHAR(128)';
$field3->uitype = 16;
$field3->typeofdata = 'V~O';
$field3->setPicklistValues( Array ('Value1', 'Value2') );//選択項目を指定

$block->addField($field3);

?>
上から順に説明していきますと、 １では、まず項目を追加するモジュールを指定します。
指定する際はモジュール名が必要となりますが、モジュール名はの赤字で囲んだところがモジュール名になります。
この例での"価格表"はあくまで表示上の名前であり、これは英語やエスパニョール等言語が変われば変更されます。
今回は価格表をに対して変更を行うためPriceBooksと指定します。

２では、PriceBooksのどのブロックに対して追加を行うのか指定します。
こちらもブロックの名称で指定しますが、こちらも表示上の名前ではなくブロックの正式名？となりますが、どうやって確認するのか？というと、こちらもDBをみたり言語設定ファイルをみたりと幾つか方法があります。
ここでは、折角なのでvTlibを使用して取り出してみます。
<?php
// Turn on debugging level
$Vtiger_Utils_Log = true;
include_once('vtlib/Vtiger/Menu.php');
include_once('vtlib/Vtiger/Module.php');

$module =  Vtiger_Module::getInstance('PriceBooks');

$blocks = Vtiger_Block::getAllForModule($module);

foreach ($blocks as $key=> $value){

 print $value->label;
 
};
?>
こちらを実行すると以下のようにブロックの名称が取得できます。 
LBL_PRICEBOOK_INFORMATION
LBL_CUSTOM_INFORMATION
LBL_DESCRIPTION_INFORMATION

３、４、５は実際にフィールドの追加を行っています。
ソース内のコメントを見ていただければ大体分かっていただけるとは思いますが以下に補足を。
まず、UITypeに関してですが、こちらは本家のWiki等を参照する必要があります。
正直私も最初「何のこっちゃこの表は」状態でしたが見方がわかれば次第に慣れます。

今回は作成に必要な分だけを簡単にご紹介します。
ただ、それでもそこそこ大きな表になりますので別のページに作成しました。
vTigerCRM6のUIType一覧

UITypeに関しては、シンキングリードの田村様から色々と情報も頂きましたので、最終的にはちゃんと纏めた情報を記載していきたいと思っています。

次にtypeofdataに関してですが、V~OとかV~Mという書き方をします。
~の前の情報にはそれぞれのUItypeに応じた値を設定する必要があるためvTigerCRM6のUIType一覧を参照してください。
VはVarchar、NはNumber、IはIntegerの略です。
~の後ろに関してはOはOptional、MはMandatoryの略で、追加する項目を必須項目とするか否かを決められます。
ただし一部のUITypeではデフォルトで必須であることが指定されているものもあります。

４の関連モジュールの追加に関して一つ注意が必要です。
setRelatedModulesにて関連するモジュールを指定していますが、addFieldを呼び出した後でないと正しく動作しません。
個人的にすっごく嵌りましたので皆さん気をつけましょう。

５に関しては、setPicklistValuesで選択項目を追加しています。
こちらに関しては、選択項目を全てここで登録しなくても、管理画面から登録したほうが楽かもしれませんね。

さて、こちらのコードを実行すると上手くいくと以下のようなメッセージが出力されます。

Creating Field test_field ... DONE
Module language mapping for テストフィールド ... CHECK
Setting related_field relation with Contacts ... DONE
Setting related_field relation with Leads ... DONE
Creating Field related_field ... DONE
Module language mapping for 関連モジュールフィールド ... CHECK
Creating Field pick_field ... DONE
Module language mapping for 選択項目フィールド ... CHECK

こちらが表示されたら上手く言っているはずですのでvTigerCRMから画面を確認しましょう。

最後は、上記で作成したフィールドの削除方法を紹介します。
削除方法もvTlibを使ったコードを書きます。 
<?php
$Vtiger_Utils_Log = true;
require_once('vtlib/Vtiger/Module.php');

$moduleInstance = Vtiger_Module::getInstance('PriceBooks');

$field = Vtiger_Field::getInstance('test_field', $moduleInstance);
$field->delete();

$field2 = Vtiger_Field::getInstance('related_field', $moduleInstance);
$field2->delete();

$field3 = Vtiger_Field::getInstance('pick_field', $moduleInstance);
$field3->delete();

?>
実行すると以下のメッセージが出力されます。 

Deleteing Field test_field ... DONE
Deleteing Field related_field ... DONE
Deleteing Field pick_field ... DONE

以上となります。 以上、簡単ですが既存モジュールへの項目の追加方法を紹介させていいただきました。

vTigerCRMのモジュールのカスタマイズに関しては、今はModule Designerが非常に熱いですね。
Module Designerが安定してくれればモジュールの作成とカスタマイズは非常に簡単ものになるかと思います。
ただ、現在のvTlibを使ったモジュールのカスタマイズ方法を覚えていたほうがトラブルの回避になるかなと思います。
是非とも上記を参考にバックアップをとったうえで試してみてください。

そして、ここまで書いてて気がつきましたが、先にモジュールの作成方法の紹介したほうがよかったんじゃないかと思っていきました。

そんなわけで次は、モジュールの作成方法を紹介したいと思いいます。

リクエスト等あればFacebookへ是非コメントをお願いいたします。
そして、いいね！してくれたら喜んじゃいますのでよろしくお願いいたします。

CRM TOUCHのサイトはこちら
vTigerCRMの日本語の情報に関してはこちら