drupa_get_form, drupal_prepare_form, drupal_retrieve_formの違い

やりたいこと：FormAPIよい定義されたフォームを必要な時にphpコードより呼び出したいです

• 環境：Drupal7.54
• FormAPIでフォームを定義すると、通常はhook_menuよりページとして呼び出されます（一般的な使い方）
• Drupalのモジュールを改造するときに、HTMLタグでフォームを作成するより、FormAPIでフォームを生成するのは楽で、修正にも簡単でできます

関数：drupal_get_formでFormAPIより定義したフォームを簡単に呼び出し、レンダリングすることができます

• 例：Panelsでページを構成するときに、PanelsPHPを利用してフォームを作成したいです
  
• カスタムモジュールのどこか（module_load_includeでフォーム定義のファイルをロード）にフォームが定義すれば呼び出すことができます

    module_load_include('inc', 'node', 'node.pages');  // フォームの定義場所指定    
    $form = drupal_get_form('text_module_form');
    print drupal_render( $form );

   

Drupalのhook_menu()がカスタムページ作成時によく使用されます

• Drupalのサイトにページを追加する手段はいろいろあります
• モジュールでページを追加し、メニューをGUIで設定することができます
  • モジュール（Views）で検索結果をページとして表示することができます（主に表示系のページ、入力フォームはなし）
  • モジュール（Panels）で各種要素を集めてページを作成します（主に表示系のページ、入力フォームなし）
  • モジュール（Web Form）でコンタクト/アンケートなどのフォームページを作成（フォーム系、入力して、データをサーバーに送信して保存）
• プログラミングでページを作成する場合にhook_menu()を実装する必要があります
  • hook_menu()を実装時に、いろいろなパラメーター設定が紛らわしくて、注意する必要があります
  • Drupalのhook_menuでのURL設定にワイドカードの利用
  • Drupalのhook_menuでのユーザーロール別アクセス権限管理
  • 今回は、「page callback」パラメーターを詳細を説明します

Drupalのhook_menu()のパラメーター「page callback」が直接にページの呼び出しと「drupal_get_form」を介してページを呼び出す

• ここは、ajaxで動作するチェックボックスを例として上げます
  • チェックボックスをクリックすると、ajaxでサーバーと交信する

    function ajax_add_to_my_vocabulary($form,&$form_state, $entity){
    
        global $user ;
    
        //  データがすでに存在するか否かのチェック
        $my_voca_result = db_query("SELECT entity_id FROM my_ch_vocabulary WHERE vid=".$entity->vid . " AND uid=".$user->uid)->fetchAll();
        //   ajaxコールバック時に使用するパラメーター
        $form_state['has_my_voca_result'] = count($my_voca_result)>0 ? true:false ;
        $form_state['ch_vocabulary'] = $entity ;  
    
        //　ajaxのチェックボックスフォーム定義
        $form['ch_voca_form']=array(
            '#type' => 'checkbox',
            '#disabled' => $user->uid == 0 ? true : false ,
            '#title' => count($my_voca_result)>0 ? t('<span id="ch-voca-check-op-'.$vid.'">Remove</span>') : t('<span id="ch-voca-check-op-'.$entity->vid.'">Add</span>'),
            '#default_value' => count($my_voca_result)>0 ? 1 : 0,
            '#ajax' => array(
                'callback' => 'add_to_my_vocabulary_callback',
                'wrapper' => 'ch-voca-check-op-'.$entity->vid,
                'method' => 'replace',
                'effect' => 'fade',
            ),
        );
        return $form ;
    }
    
    // ajaxのコールバック関数
    function add_to_my_vocabulary_in_views($form, $form_state){
    
        global $user;
    
        $entity = $form_state['ch_vocabulary'] ;
    
        // DBにデータがある場合に削除処理
        if( $form_state['has_my_voca_result'] ) {
            db_delete( 'my_ch_vocabulary' )->condition( 'vid', $entity->vid )->condition('uid', $user->uid )->execute();
            //  チェックボックスのラベルを「Add」に変更
            return t('<span id="ch-voca-check-op-'.$vid.'">Add</span>');
        }
    
        //　データがなければ、ch_vocabuaryをmy_vocabuaryにコピー
        $my_voca = entity_create('my_ch_vocabulary', array('vid'=>$entity->vid));
        $my_voca_wrapper = entity_metadata_wrapper( 'my_ch_vocabulary', $my_voca );
        $my_voca_wrapper->vocabulary->set( $ch_voca->vocabulary ) ;
        ....   //各種フィールド、プロパティのセット
        $my_voca_wrapper->save();   //　コピーされたデータの保存
    
        //  チェックボックスのラベルを「Remove」に変更
        return  t('<span id="ch-voca-check-op-'.$vid.'">Remove</span>');
    }

• hook_menu()が直接にajaxのチェックボックスフォームを呼び出す場合、ajaxの動作しません

  YOUR_MODULE_NAME_menu(){
    $items['your/path/%entity'] = array(
          'title' => 'Copy and Remove',
          'page callback' => 'ajax_add_to_my_vocabulary',
          'page arguments' => array(array(), array(), 2) ,
          'access arguments' => array('create my vocabulary'),
    );
  }

  • ajaxのチェックボックスフォーム「ajax_add_to_my_vocabulary」が表示されますが、<form>要素がなくて、ajaxの動作はしません
    
• hook_menu()が"drupal_get_form"を介してにajaxのチェックボックスフォームを呼び出す場合、ajaxの動作は正常です

  YOUR_MODULE_NAME_menu(){
   　$items['your/path/%entity'] = array(
  　　　'title' => 'Copy and Remove', 
  　　　'page callback' => 'drupal_get_form', 
  　　　'page arguments' => array('ajax_add_to_my_vocabulary', 2) , 
  　　　'access arguments' => array('create my vocabulary'), 
  　　); 
  }

  • 作成されたフォームに"<form>"要素およびajaxの要素が含まれているのでajaxが正常に動作します
    

結論：表示系ページは直接に呼び出し、入力フォーム系は"drupal_get_form"を介して呼び出す

• hook_menu()を実装時に、呼び出すページの性質によりページの呼び出す方法を決めます
  • 表示系ページ（データ更新なし）の場合は直接に呼び出せばよいです
  • 入力フォーム系のページは"drupal_get_form"を介して呼び出します
• 表示系か、フォーム系かを区別せず、いつも"drupal_get_form"を介して呼び出しても構わないです
• "drupal_get_form"がフォーム構築のプロセスが含まているので、フォームの要素構築するには必要です
  • drupa_get_form, drupal_prepare_form, drupal_retrieve_formの違い
  • これを使用する場合少し（どのぐらいは測定していないが）遅いかもしれないです