DrupalのEntityを定義する簡単な例－４：複数のバンドルの作成/拡張フィールド追加

Entityの管理フォーム：一覧表示/追加/削除/更新 操作ができるようにする

• 前回紹介した（DrupalのEntityを定義する簡単な例 ）では、データを直接にDBに書き込むか、Feedsでcsvフォーマットデータをインポートする方法となります
  • 前回の例に一つEntityプロパティを追加します（sys_name）
  • これはコンテンツタイプなどを追加するときによく見られる名前とシステム名のペアです
  • 今回の例では：名前は「room_number」、システム名は「sys_name」にします
  • DBにもこのフィールドを追加します（カスタムモジュールのinstallファイルにあるスキーマに記入しました）
• モジュール（Entity API）がEnitityに関する管理フォームが提供しています
  • 今回のカスタムモジュール（entity_example_2.zip）をダウンロードして、テストサイトにインストールし、動作を確認できます
  • 作成されたEntity一覧の表示
    
  • Entityの新規作成/編集/追加操作もあります
    

Entityの管理フォームを表示させるため「EntityAPIControllerExportable」を使用します

• Entityを定義（hook_entity_info() ）する部分に「controller class」を「EntityAPIControllerExportable」を使用します

      $services['room'] = array(
          'label' => t('Room'),                       // エンティティ名
          'entity class' => 'Entity',                 // デフォルトクラスの使用
          'controller class' => 'RoomController',     //　EntityAPIControllerExportableの使用
  //        'controller class' => 'EntityAPIController',//　<-前回使用したもの： デフォルトクラスの使用
          'base table' => 'room',                     // DB上のテーブル名
          ・・・・・・・
      );
  
  // Entityの「controller class」のコールバッククラス
  class RoomController extends EntityAPIControllerExportable {
      public function __construct($entityType) {
          parent::__construct($entityType);
      }
  
      /**
       * Create a room - we first set up the values that are specific
       * to our room schema but then also go through the EntityAPIController
       * function.
       */
      public function create(array $values = array()) {
          // Add values that are specific to our Room
          $values += array(
              'rid' => '',
              'is_new' => TRUE,
              'type' => '',
              'room_number' => '',
              'sys_name' => '',
          );
          $room = parent::create($values);
          return $room;
      }
  }

• Entity管理フォームをコンテンツ管理ページ（例）に挿入するために「admin ui」パラメターを定義します

  /**
   * Implements hook_entity_info().
   */
  function entity_example_entity_info()
  {
      $services['room'] = array(
          'label' => t('Room'),                       // エンティティ名
          'entity class' => 'Entity',                 // デフォルトクラスの使用
  　　　・・・・・
          'module' => 'entity_example',
          'metadata controller class' => 'EntityExampleMetadataController',
          'admin ui' => array(
              'path' => 'admin/structure/rooms',
              'file' => 'rooms.admin.inc',
              'controller class' => 'RoomsUIController',
          ),
  
      );
  
      return $services;
  }

• 管理UI定義は「rooms.admin.inc」ファイルに書きこみます（room.module内で記述することもできます）

  /**
   * UI controller.
   */
  class RoomsUIController extends EntityDefaultUIController {
  
    /**
     * Overrides hook_menu() defaults.
     */
    public function hook_menu() {
      $items = parent::hook_menu();
  	$items[$this->path]['description'] = t('Manage rooms. including adding
  		and removing fields and the display of fields.');
      return $items;
    }
  }
  
  /**
   * Generates the room editing form.
   */
  function room_form($form, &$form_state, $room, $op = 'edit') {
  
    if ($op == 'clone') {
      $room->sys_name .= ' (cloned)';
      $room->room_number = '';
    }
  
    $form['room_number'] = array(
      '#title' => t('Room Number'),
      '#type' => 'textfield',
      '#default_value' => isset($room->room_number)?$room->room_number : "",
      '#description' => t('Entry the Room number.'),
      '#required' => TRUE,
      '#size' => 30,
    );
  
    // Machine-readable type name.
    $form['sys_name'] = array(
      '#type' => 'machine_name',
      '#default_value' => isset($room->sys_name) ? $room->sys_name : '',
      '#maxlength' => 32,
      '#machine_name' => array(
        'exists' => 'room_get_sys_names',
        'source' => array('label'),
      ),
      '#description' => t('A unique machine-readable name for this model type. It must only contain lowercase letters, numbers, and underscores.'),
    );
  
    $form['type'] = array(
        '#title' => t('Room Type'),
        '#type' => 'textfield',
        '#default_value' => isset($room->type) ? $room->type : "",
        '#description' => t('Entry the Room type.'),
        '#required' => TRUE,
        '#size' => 60,
    );
  
  
    $form['actions'] = array('#type' => 'actions');
    $form['actions']['submit'] = array(
      '#type' => 'submit',
      '#value' => t('Save Room'),
      '#weight' => 40,
    );
  
    return $form;
  }
  
  /**
   * Form API submit callback for the type form.
   */
  function room_form_submit(&$form, &$form_state) {
    $room = entity_ui_form_submit_build_entity($form, $form_state);
    $room->save();
    $form_state['redirect'] = 'admin/structure/rooms';
  }
  
  

• 以上の定義で、Entityの管理操作ができるようになります

Entityを定義する簡単な例：Roomエンティティ（Entityのサンプロモジュール：entity_example）

• Entityをプログラミングで定義するには、最初簡単なこと、必要最小限のことを定義します
• ここで、ルーム（Room）エンティティ（Entity）を例として紹介します(サンプルモジュールをダウンロードしてください)
  

Roomエンティティ：Entityの定義 ＋ データインポート ＋ Entityの参照

• Roomのテストデータ（dsvフォーマット）： 

  • ルームナンバー：　room_number

  • ルームタイプ:： type

    rid,room_number,type
    1,1001,シングル
    2,1002,シングル
    3,1003,シングル
    4,2001,ダブル
    5,3001,ダブル

• データベース上に「room」テーブルを作成、または、モジュールのinstallファイルでスキーマを定義して、モジュールがインストール時に自動的に作成されます

  /**
   * Implement hook_schema()
   */
  function entity_example_schema(){
      $schema['room']=array(
          'description' => 'Rooms',
          'fields' => array(
              'rid' => array(
                  'type' => 'serial',
                  'description' => 'Room Id'
              ),
              'type' => array(
                  'type' => 'varchar',
                  'length' => '255',
                  'description' => 'Room Type'
              ),
              'room_number' => array(
                  'type' => 'varchar',
                  'length' => '25',
                  'description' => 'Room Number'
              ),
  
          ),
          'primary key' => array('rid'),
  
      );
  
      return $schema;
  }

• モジュールファイル（.module）にRoomエンティティを定義します

  /**
   * Implements hook_entity_info().
   */
  /**
   * Implements hook_entity_info().
   */
  function entity_example_entity_info()
  {
  
     $services['room'] = array(
          'label' => t('Room'),                       // エンティティ名
          'entity class' => 'Entity',                 // デフォルトクラスの使用
          'controller class' => 'EntityAPIController',//　デフォルトクラスの使用
          'base table' => 'room',                     // DB上のテーブル名
          'fieldable' => TRUE,                        // 余分のフィールド追加可能
          'entity keys' => array(                     // ルームIDをエンティティのキー.
              'id' => 'rid',
              'label' => 'room_number',               //　コールバック関数が優先
          ),
          'view modes' => array(
              'full' => array(
                  'label' => t('Default'),
                  'custom settings' => FALSE,
              ),
          ),
          'bundles' => array(),                       // bundleはこのエンティティ自身
  //        'label callback' => 'room_label',   　　　　// 指定しないとラベルの取得ができない
          'access callback' => 'room_access' ,        // default:'value user_access'動作しない
          'module' => 'entity_example',
          'metadata controller class' => 'EntityExampleMetadataController',
  
      );
  
      return $services;
  }
  
  /**
   * Extend the defaults.
   */
  class EntityExampleMetadataController extends EntityDefaultMetadataController {
      public function entityPropertyInfo() {
          $info = parent::entityPropertyInfo();
          $properties = &$info[$this->type]['properties'];
          $properties['type'] = array(
              'label' => t('Room type'),
              'schema field' => 'type',
              'getter callback' => 'entity_property_getter_method',
              'setter callback' => 'entity_property_verbatim_set',
              'required' => TRUE,
              'description' => t('Room type of the room'),
          );
          $properties['room_number'] = array(
              'label' => t('Room Number'),
              'schema field' => 'room_number',
              'getter callback' => 'entity_property_getter_method',
              'setter callback' => 'entity_property_verbatim_set',
              'required' => TRUE,
              'description' => t('The number of the room'),
          )
          return $info;
      }
  }
  
  function room_access($op, $room = NULL, $account = NULL) {
      // 全員アクセス可能にする
      return TRUE;
  }
  
  

• これだけで、Entityの定義が完了しました
• モジュール（Feeds）でRoomサンプルデータをDBにインポートします
  • モジュール（Feeds Entity Processor）のインストール/有効化が必要
• 実際にRoomエンティティが動作しているかをテストします
  • 任意のコンテンツタイプ（例：記事）Roomフィールドを追加します（Entity参照タイプ）
  • Entity参照タイプのターゲットを「Room」にします
  • 一つの記事を作成して、Roomエンティティの動作を確認します

Enity定義の注意点：アクセス権限、エンティティのラベル定義を正しく定義します

• 上記例として、Entityの必要な最低限な定義となります
• ネットでEntity定義例がありますが、アクセス権限、エンティティのラベルなどの権限が間違いやすいです
• アクセス権限（access callback）で定義しないと、エンティティのラベルがうまく表示されないです
  
• エンティティのラベルを2か所で定義できます
  • entity_keys: DB上にどのフィールドがラベルとして利用するかを指定します
  • label callback :　ユーザー必要応じて、ラベルを生成するコールバック関数
  • コールバック関数がentity_keys設定より優先です
    

エンティティ（Entity）に一つ以上のバンドル（Bundle）の定義ができます（カスタムモジュールentity_room.zip）

• エンティティ（Enityt）の定義（hook_entity_info）にバンドル（bundle）定義があります（'bundle'=>array()）
  • バンドル定義に空の配列（bundle =>array()）として定義する場合エンティティ（Entity）名と同じバンドルが自動的に定義されます
• 一つエンティティに複数のバンドル定義ができます（カスタムモジュールentity_room.zip をダウンロード）
  • 例： roomエンティティに、シングルタイプルーム（single room）とツインタイプルーム(twin room)のバンドル(bundle)があります
    
  • 複数のバンドル定義するエンティティは以下のようです

    /**
     * Implements hook_entity_info().
     */
    function entity_room_entity_info()
    {
        $room_info['room'] = array(
            'label' => t('Room'),
            'entity class' => 'Entity',
            'controller class' => 'DrupalDefaultEntityController',
            'base table' => 'room',
            'fieldable' => TRUE,
            'entity keys' => array(
                'id' => 'rid',
                'label' => 'room_number',
                'bundle' => 'room_type',     // DB上にroom_typeフィールドでバンドルを区別
            ),
            'bundles' => array(
                'single_room'=> array(
                    'label' => 'Single Room',
                    'admin' => array(
                        'path' => 'admin/structure/single-room/manage',
                    ),
                ),
                'twin_room'=> array(
                    'label' => 'Twin Room',
                    'admin' => array(
                        'path' => 'admin/structure/twin-room/manage',
                    ),
                ),
            ),
            'access callback' => 'access_room',
            'module' => 'entity_room',
        );
    
        return $room_info;
    }
    

バンドルのフィールド管理パス、権限の設定が必要です

• 各バンドル（Bundle）にそれぞれの拡張フィールド管理ができます
• そのため、各バンドルの拡張フィールドの管理画面を分ける必要があります
  • single room: 'path' => 'admin/structure/single-room/manage',
  • twin room: 'path' => 'admin/structure/twin-room/manage',
• 各バンドルに対してエンティティでアクセス権限一括設定ができます
  • 'access callback' => 'access_room',

バンドルオブジェクトを区別するためentity_keysにbundleパラメーターの設定が必要

• 一エンティティ（Entity）ごとに、DB上では一テーブルとなります
  • 上記例はroomテーブル（entity_room.installを参考）
• 複数のバンドルを定義するので、当然どのようにバンドルを区別するか、そのキーが必要となります
  • 上記例は、バンドルを区別するroom_typeフィールドを追加しました
• DB上のバンドル識別フィールドをentity_keysに設定する必要があります
  • 上記では、'bundle' => 'room_type',
• このキーを設定しないと、実際にバンドルオブジェクトの取得はできないです

hook_field_extra_fields(). を実装して、バンドルの拡張フィールド にエンティティのプロパティ項目を追加

• バンドルの拡張フィールド管理画面に、エンティティのプロパティがありません（継承関係でバンドルが下位になっています）
• プロパティをフィールドように見せるために hook_field_extra_fields(). を実装します（実際にフィールド管理画面でプロパティの編集はできない）

  /**
   * Implements hook_field_extra_fields().
   * Field管理にRoomのプロパティ項目を追加（編集不可）
   */
  function entity_room_field_extra_fields()
  {
      $return = array();
      //　For Single Room Bundle
      $return['room']['single_room'] = array(
          'form' => array(
              'room_type' => array(
                  'label' => t('Room Type'),
                  'description' => t('The type of the room'),
                  'weight' => 1,
              ),
              'room_number' => array(
                  'label' => t('Room Number'),
                  'description' => t('The number of the room'),
                  'weight' => 2,
              ),
          ),
      );
      //　For Twin Room Bundle
      $return['room']['twin_room'] = array(
          'form' => array(
              'room_type' => array(
                  'label' => t('Room Type'),
                  'description' => t('The type of the room'),
                  'weight' => 1,
              ),
              'room_number' => array(
                  'label' => t('Room Number'),
                  'description' => t('The number of the room'),
                  'weight' => 2,
              ),
          ),
      );
  
      return $return;
  }
  

エンティティの取得、作成などの操作にhook_menu()を実装して行います

• エンティティの取得、作成などはhook_menu()を実装します
• エンティティ作成、表示にはFormAPIなどを実装しています

  /**
   * Implements hook_menu().
   */
  function entity_room_menu()
  {
      // シングル ルーム 管理画面
      $items['admin/structure/single-room/manage'] = array(
          'title' => t('Single Room Admin'),
          'description' => 'Manage Single Room structure',
          'page callback' => 'room_info',
          'page arguments' => array('Single Room') ,
          'access arguments' => array('administer rooms'),
      );
      $items['single-room/add'] = array(
          'title' => t('Add Single Room'),
          'page callback' => 'room_add',
          'page arguments' => array('single_room'),
          'access arguments' => array('create room'),
      );
  
      // ツインルーム管理が画面
      $items['admin/structure/twin-room/manage'] = array(
          'title' => 'Twin Room Admin',
          'description' => 'Manage Twin Room structure',
          'page callback' => 'room_info' ,
          'page arguments' => array('Twin Room'),
          'access arguments' => array('administer rooms'),
      );
      $items['twin-room/add'] = array(
          'title' => t('Add Twin Room'),
          'page callback' => 'room_add',
          'page arguments' => array('twin_room'),
          'access arguments' => array('create room'),
      );
  
      // Roomの表示
      $items['room/%room'] = array(
          'title callback' => 'room_page_title',
          'title arguments' => array(1),
          'page callback' => 'room_page_view',
          'page arguments' => array(1),
          'access arguments' => array('view rooms'),
          'type' => MENU_CALLBACK,
      );
  
      return $items;
  }
  
  /**
   * Implements hook_permission().
   */
  function entity_room_permission()
  {
      return array(
          'administer rooms' =>  array(
              'title' => t('Administer rooms'),
              'restrict access' => TRUE,
          ),
          'create room' =>  array(
              'title' => t('Create room'),
          ),
          'view rooms' => array(
              'title' => t('View Rooms'),
          )
      );
  }
  
  /**
   * 全員にRoomエンティティの無条件アクセス権限
   */
  function access_room(){
      return true ;
  }
  
  /**
   * create "add room" form
   */
  function room_add($type) {
      $room = (object) array (
          'rid' => '',
          'room_type' => $type,
          'room_number' => '',
      );
  
      return drupal_get_form('room_add_form', $room);
  }
  function room_add_form($form, &$form_state, $room) {
      $form['room_type'] = array(
          '#type' => 'textfield',
          '#title' => t('Room Type'),
          '#default_value' => $room->room_type,
          '#disabled' => true,
          '#required' => TRUE,
      );
  
      $form['room_number'] = array(
          '#type' => 'textfield',
          '#title' => t('Room Number'),
          '#required' => TRUE,
      );
  
      field_attach_form('room', $room, $form, $form_state);
  
      $form['submit'] = array(
          '#type' => 'submit',
          '#value' => t('Save'),
          '#weight' => 10,
      );
  
  
      return $form;
  }
  
  function room_add_form_validate($form, &$form_state) {
      $room_submisttion = (object) $form_state['values'];
      field_attach_form_validate($form_state['values']['room_type'], $room_submisttion, $form, $form_state);
  }
  
  function room_add_form_submit($form, &$form_state) {
      $room_submission = (object) $form_state['values'];
      field_attach_submit($form_state['values']['room_type'], $room_submission, $form, $form_state);
      $room = room_save($room_submission);
      $form_state['redirect'] = "room/$room->rid";
  }
  
  function room_save(&$room) {
      drupal_write_record('room', $room);
      field_attach_insert('room', $room);
      return $room;
  }
  
  
  function room_info($type) {
      return t('Welcome to the administration page for your '.$type.'!');
  }
  
  function room_page_title($room){
      return $room->room_number."(".$room->room_type.")";
  }
  
  function room_page_view($room, $view_mode = 'full'){
  
      $room->content = array();
  
      // Build fields content.
      field_attach_prepare_view('room', array($room->rid => $room), $view_mode);
      entity_prepare_view('room', array($room->rid => $room));
      $room->content += field_attach_view('room', $room, $view_mode);
  
      return $room->content;
  }
  
  function room_uri( $room ){
      return array(
          'path' => 'room/'.$room->rid ,
      );
  }
  
  class RoomController extends EntityAPIController{
  //class RoomController extends DrupalDefaultEntityController{
      public function __construct($entityType) {
          parent::__construct($entityType);
      }
  
      // Entityオブジェクト保存
      public function save($room) {
          drupal_write_record('room', $room);
          field_attach_insert('room', $room);
          return $room;
      }
  
  }
  
  /**
   * hook_menuのURL引数のオブジェクト取得
   */
  function room_load($rid = NULL, $reset = FALSE){
  
      $rids = (isset ($rid) ? array($rid) : array());
      $room = room_load_multiple($rids, $reset);
      return $room ? reset ($room) : FALSE;
  }
  
  function room_load_multiple($rids = array(), $conditions = array(), $reset = FALSE){
      return entity_load('room', $rids, $conditions, $reset);
  }