displayParamsで指定可能なパラメータ(3)

SugarCRM

3回で終わらせる予定だったこのまとめですが、予想以上にパラメータが多くて終われませんｗ現在調査済みの範囲ですべてなら、次のエントリあたりでまとめ終わると思います。未知のパラメータが芋づる式に増えるようならもうしらんorz

さて、今回紹介するパラメータですが、今までとはちょっと毛色が違くて実際の表示部分にはほとんど関与しません。内容的にはコールバック関数周りで指定可能なパラメータとなります。恐らくパラメータの一覧を出しただけでは、ただでさえわかりにくい文章がさらにわかりづらくなると思います。なので、まずは簡単に実際の画面で説明します。

図は取引先と取引先担当者(Contacts)の編集画面です（標準のものです）。取引先では、二つの住所：billing_address(請求先住所)とshipping_address(出荷先住所)を入力することが出来ます。取引先担当者の編集画面では、同じようにprimary_address(主となる住所)とalt_address(他の住所)を入力することが出来ます。また、取引先担当者の画面では取引先を選択すると、デフォルトでは自動的にphone_work(会社電話)とprimary_address_street(主となる住所)に、選択された取引先のphone_office(会社電話)とshipping_address_street(請求先住所)が埋め込まれます。


取引先


取引先担当者



今回紹介するパラメータは、まさにこの動作をカスタマイズするときに指定するパラメータとなります。指定可能なパラメータは、

  • どのフォームで(formName)
  • どのコールバック関数で(call_back_bunction)
  • どののようなフィールドマッピングで(key, copy, copyPhone, field_to_name_array, billingKey, shippingKey, additionalFields)

を指定するものとなります。

それでは、いつものようにパラメータ一覧をまとめてみます。説明文中の"アドレスのプリフィックス"とはアドレスフィールドがxxx_address_streetの場合には、'xxx'の部分となります。

formName

  • 説明
    • フィールド入力の対象となるフォーム名を指定する。デフォルトは"EditView"。
  • 定義例
    • なし
  • 利用/実装しているテンプレート
    • include/Smarty/plugins/function.sugar_field.php
    • include/SugarFields/Fields/Relate/SugarFieldRelate.php
    • include/SugarFields/Fields/Parent/SugarFieldParent.php

call_back_function

  • 説明
    • relateフィールドに対する選択ボタンクリック時のコールバック関数を指定する。デフォルトは'set_return'。
  • 定義例
    • なし
  • 実装/利用しているテンプレート
    • include/SugarFields/Fields/Relate/SugarFieldRelate.php

key

  • 説明
    • addressフィールドに指定した場合
    • relateフィールドに指定しかつ、関連モジュールがAccountsの場合(ポップアップ先がAccountsの場合)
      • 後述の'copy'パラメータと同時に使用し、アドレスフィールドのコピー元のプレフィックスを指定する。配列で複数指定することも可能。
  • 定義例
    • modules/Contacts/metadata/editviewdefs.php
  • 利用/実装しているテンプレート
    • include/SugarFields/Fields/Relate/SugarFieldRelate.php
    • include/SugarFields/Fields/Address/EditView.tpl
    • include/SugarFields/Fields/Address/SugarFieldAddress.php
    • include/SugarFields/Fields/Address/en_us.EditView.tpl

copy

  • 説明
    • addressフィールドに指定した場合
    • relateフィールドに指定しかつ、関連モジュールがAccountsの場合(ポップアップ先がAccountsの場合)
      • 先の'key'パラメータと同時に使用し、アドレスフィールドのコピー先のプレフィックスを指定する。配列で複数指定することも可能。
  • 定義例
    • modules/Contacts/metadata/editviewdefs.php
  • 利用/実装しているテンプレート
    • include/SugarFields/Fields/Relate/SugarFieldRelate.php
    • include/SugarFields/Fields/Address/EditView.tpl
    • include/SugarFields/Fields/Address/SugarFieldAddress.php
    • include/SugarFields/Fields/Address/en_us.EditView.tpl

copyPhone

  • 説明
    • 選択された取引先のphone_officeフィールドの値をphone_workフィールドにコピーする
    • relateフィールドでかつ関連先が取引先の場合のみ有効
  • 定義例
    • なし
  • 利用/実装しているテンプレート
    • include/SugarFields/Fields/Relate/SugarFieldRelate.php

billingKey

  • 説明
    • 値を直接入力した時に、入力された取引先(Accounts)のbilling_addressをコピーするアドレスフィールドのプレフィックスを指定。
    • relateフィールドでかつ関連先が取引先の場合のみ有効
  • 定義例
    • modules/Contacts/metadata/editviewdefs.php
  • 利用/実装しているテンプレート
    • include/QuickSearchDefaults.php
    • include/TemplateHandler/TemplateHandler.php

shippingKey

  • 説明
    • 値を直接入力した時に、入力された取引先(Accounts)のshipping_addressをコピーするアドレスフィールドのプレフィックスを指定。
    • relateフィールドでかつ関連先が取引先の場合のみ有効
  • 定義例
    • modules/Contacts/metadata/editviewdefs.php
  • 利用/実装しているテンプレート
    • include/QuickSearchDefaults.php
    • include/TemplateHandler/TemplateHandler.php

additionalFields

  • 説明
    • 直接入力でフィールドの値を決定後、指定したフィールドの値を現在のどのフィールドに対応させるかを指定する。
  • 定義例
    • なし
  • 利用/実装しているテンプレート
    • include/QuickSearchDefaults.php
    • include/TemplateHandler/TemplateHandler.php

field_to_name_array

  • 説明
    • relateフィールドに対し、ポップアップ先フィールドと現在の画面のフィールドのマッピングを行う。指定は連想配列で行う。
    • ここで定義されたマッピングに応じて、コールバック関数によりフィールド値の埋め込みが行われる。
    • 'key', 'copy'と同時に指定した場合、本パラメータは無効となる。
  • 定義例
    • なし（ただし、modules/Employees/metadata/editviewdefs.phpではcustomCode中に指定あり)
  • 利用/実装しているテンプレート
    • include/SugarFields/Fields/Relate/SugarFieldRelate.php
    • include/SugarFields/Fields/Parent/SugarFieldParent.php

上述のパラメータは、基本的にrelateフィールドに対するdisplayParamsで宣言します。'key', 'copy', 'additionalFields', 'field_to_name_array'について、簡単な例を以下に挙げます。

例1) 取引先(Accounts)のbilling/shipping_addressを取引先担当者(Contacts)のprimary/alt_addressにコピーする。

デフォルトのmodules/Contacts/metadata/editviewdefs.phpでは、取引先フィールドが次のように定義されています。

    array (
      array('name'=>'account_name', 
            'displayParams'=>array(
                              'key'=>'billing', 
                              'copy'=>'primary', 
                              'billingKey'=>'primary',
                              'additionalFields'=>array('phone_office'=>'phone_work')
                             )
       ),
      ....
    ),

この定義では、billingがprimaryにコピーされるだけなので、key/copyをそれぞれ配列で定義し、複数アドレスでコピーされるように変更します。

    array (
      array('name'=>'account_name', 
            'displayParams'=>array(
                             'key'=>array('billing','shipping') ,
                              'copy'=>array('primary','alt') ,
                              'billingKey'=>'primary',
                              'additionalFields'=>array('phone_office'=>'phone_work')
                             )
       ),
      ....
    ),

例2 取引先選択後、FAX番号もコピーされるようにする。

field_to_name_arrayを利用します。このパラメータを利用するときには、すべてのマッピングを記述する必要があります。また、'key', 'copy'パラメータと同時に利用することはできませんので、該当パラメータは削除します。
重要なことはさらに2点あります。ひとつは、field_to_name_arrayはポップアップ経由でしか値の埋め込みが行われないので、直接入力に対応するにはadditionalFieldsを同時に指定する必要があります。二つ目は、ポップアプ経由で選択された取引先レコードのフィールド情報は、modules/Accounts/metadata/popupdefs.phpのlistviewdefsパラメータ内で宣言されている必要があります。
以上をふまえると修正するファイルはAccountsとContactsの2種類となります。

modules/Accounts/metadata/popupdefs.php

$popupMeta = array('moduleMain' => 'Account',
                      ....
                        'listviewdefs' => array(
                                            'NAME' => array(
                                                'width' => '40',
                                                'label' => 'LBL_LIST_ACCOUNT_NAME',
                                                'link' => true,
                                                'default' => true,
                                                ),
                                      ....
                                            'PHONE_FAX' => array(
                                                'width' => '40',
                                                'label' => 'LBL_PHONE_FAX',
                                                'default' => false,
                                                ),

modules/Contacts/metadata/editviewdefs.php

    array (
      array('name'=>'account_name', 
            'displayParams'=>array(
                'billingKey'=>'primary',
                'field_to_name_array' => array(
                    'id' => 'account_id',
                    'name' => 'account_name',
                    'billing_address_street' => 'primary_address_street',
                    'billing_address_city' => 'primary_address_city',
                    'billing_address_state' => 'primary_address_state',
                    'billing_address_postalcode' => 'primary_address_postalcode',
                    'billing_address_country' => 'primary_address_country',
                    'phone_fax' => 'phone_fax'
                    'additionalFields'=>array('phone_office'=>'phone_work', 'phone_fax' => 'phone_fax')
                 )
            )
       ),
      ....
    ),

本エントリで紹介したパラメータについては、知っていると知らないのではカスタマイズの労力がだいぶ違うと思うので、ぜひ活用してください。

ではでは