Drupalのhook_menuでのURL設定にワイドカードの利用

やりたいこと：一つのURLで複数のステップフォームを作成したいです

• 背景：Drupal7.54、FormAPIでマルチステップフォームの作成
• FormAPIで簡単にフォームを作成します(例：Drupalの関数（drupal_get_form）を利用してFormAPIで作成したフォームを任意の場所でPHPに呼び出されることができます )
• 一つのURLで複数のステップフォームを作成する要望があります

FormAPIでマルチステップフォーム作成の要点：「$form_state」でステップの定義、「form_submit()」関数内でステップの判別とフォームの再構築

• FormAPIでマルチステップフォームを作成時に二つの要点ああります
• 「$form_state」オブジェクトに任意のステップ識別変数を追加します（例：$form_state['ｐａｇｅｒ']）
  • もちろん、$form_state['ｓｔｏｒａgｅ']の利用も可能です
  • 各ステップのフォームで識別文字列を定義します（例：$form_state['pager']='page_1'）
• 各ステップフォームの送信/次へボタンが押されたら、イベントをキャッチするform_submit（）関数内でステップの判別、フォームの再構築を行います
  • ステップの判別：　if($form_state['ｐａｇｅr']=='page_1')
  • 次のステップのフォーム定義：　$form_state['ｐａｇｅr']=='page_2'
  • フォームの再構築：　$form_state['rebuild']==TRUE
    
  • マルチステップのサンプルプログラム（送信ボタンを押すとステップ１とステップ２を交替で表示する）

    /**
     *  メニューでURLの定義
     */
    function your_module_menu() {
      $items['form/multiple-step'] = array(
          'title' => t('Multiple Step Form Test'),
          'page callback' => 'drupal_get_form',
          'page arguments' => array('multiple_step_form'),
          'access arguments' => array('access content'),
      );
      return $items;
    }
    
    /**
     *  マルチステップフォームの定義
     */
    function multiple_step_form($form, &$form_state){
    	switch( $form_state['pager'] ) {
            case  'page_1'  :
            return page_one_form();
            break;
    
            case  'page_2'  :
            return page_two_form();
            break;
    	}
    }
    
    /**
     *  ステップ１ フォームの定義
     */
    function page_one_form( $form, &$form_state ){
    　// ステップの定義
      $form_state['pager'] = "page_1";
    　// 任一のメッセージ表示
      $form['message_field'] = array(
          '#type' => 'markup',
          '#markup' => 'Form Step 1',
      );
      // サブミットボタン
      $form['submit'] = array(
          '#type' => 'submit',
          '#value' => '送信',
      );
    　// サブミットボタンのイベントハンドラー
      $form['#submit'][] = 'page_one_form_submit';
    
      return $form;}
    }
    
    /**
     *  ステップ２ フォームの定義
     */
    function page_two_form( $form, &$form_state ){
      // ステップの定義
    　$form_state['pager'] = "page_two";
    　// 任一のメッセージ表示
      $form['test_form']=array(
          '#type' => 'item',
          '#title' => 'Multiple Step Form',
          '#markup' => '<p>Step ２</p>',
      );
    　// サブミットボタン
      $form['submit'] = array(
          '#type' => 'submit',
          '#value' => '送信',
      );
    　// サブミットボタンのイベントハンドラー
      $form['#submit'][] = 'page_two_form_submit';
      return $form;
    }
    
    /**
     *  ステップ１のボタンイベントハンドラー
     */
    function page_one_form_submit($form, &$form_state){
      $form_state['pager']['card_page']= "page_two";
      $form_state['rebuild'] = true;
      return ;
    }
    
    /**
     *  ステップ２のボタンイベントハンドラー
     */
    function page_two_form_submit($form, &$form_state){
      $form_state['pager']['card_page']= "page_one";
      $form_state['rebuild'] = true;
      return ;
    }

    
     

やりたいこと：Drupalのフォーム（FormAPI）でajaxを実装して各フォーム要素を動的に制御したいです

• 環境：Drupal7.54
• フォーム（FormAPI）で各要素の表示/非表示などの制御が簡単にできます（Drupalのフォーム(Form API)の「#states」で各フォーム要素の動作制御が可能）。
  • フォームを作成時にJavascriptを意識しなくてよい
  • 事前にフォームの要素を用意して表示/非表示のようなお動作制御
  • データ取得するなどの動作制御はできません
• ajaxで高等な動作（データ取得など）制御ができるので、FormAPIもこれ基盤を用意して、簡単に実装できます。

FormAPIで「#ajax」の記述（ポイント：callback、wrapper）だけで良いのでJavascriptの意識必要はありません

• FormAPIがajaxのインターフェースを用意しています。Form記述で「#ajax」要素を追加すれば、Javascriptなどのコーティングはいらないです
  • callbak：ajaxのリクエストが来た時に呼び出される関数
  • wrapper：ajaxのサーバー処理完了後に結果を画面に表示させる場所の指定
• 簡単の例:テキスト入力フォームを生成して、入力したメッセージを画面のどこかに再表示させるajax処理
  
• ajaxの記述はFormAPIの実装時に追加します。

  /**
   *  Implementation of hook_menu()
   *  新規フォームを表示するページのメニュー設定
   */
  function my_module_name_menu() {
    $items['test/form'] = array(
        'title' => 'Ajaxテスト',
        'page callback' => 'drupal_get_form',
        'page arguments' => array('my_sample_form'),
        'access arguments' => array('access content'),
    );
  }
  
  /**
   * フォームの各要素の記述
   */
  function my_sample_form($form, &$form_state){
    // メッセージ入力フィールド
    $form['message'] = array(
        '#type' => 'textfield',
        '#title' => t('メッセージを入力'),
    );
  
    // 入力されたメッセージをajaxで表示する場所
    $form['msg_wrapper'] = array(
        '#type' => 'markup',
        '#markup' => "",
        '#prefix' => '<div id="msg-wrapper">',
        '#suffix' => '</div>',
    );
  
    // サブミットボタン
    $form['submit'] = array(
        '#type' => 'submit',
        '#value' => '送信',
        '#ajax' => array(
            'callback' => 'test_sample_form_ajax_callback',
            'wrapper' => 'msg-wrapper',
            'effect' => 'fade',
        ),
    );
  
    return $form;
  }
  
  /**
   * ajaxに呼び出される関数
   */
  function test_sample_form_ajax_callback($form, $form_state) {
    // 入力されたメッセージを指定した場所にセット
    $form['msg_wrapper']['#markup'] = '入力されたメッセージ：' .
                check_plain($form_state['values']['message']) ;
    // 置換する部品を返す
    return $form['msg_wrapper'] ;
  }

  
   

drupal_get_formがよく見かける

• hook_menu()のプロパティ’page callback’がよく’drupal_get_form’を呼び出します

  function node_menu() {
    $items['admin/content'] = array(
      'title' => 'Content', 
      'description' => 'Find and manage content.', 
      'page callback' => 'drupal_get_form', 
      'page arguments' => array('node_admin_content'), 
      'access arguments' => array('access content overview'), 
      'weight' => -10, 
      'file' => 'node.admin.inc',
    );
  
    // …
  
    return $items;
  }

• ほかにdrupal_prepare_form, drupal_retrieve_form関数がよく見かけますが、drupal_get_fromとの違いは？

drupal_get_formがretrieving、processing過程を含め、HTMLフォームの取得に対して、drupal_retrieve_formはフォームの構造のみを取得する

• drupal_get_formが最初にキャッシュにこのフォームがあるか否かをチェックして、フォームを取得する
  • もしキャッシュにある場合、form_get_formを呼び出してフォームを返す。
  • もしキャッシュにない場合、drupal_retrieve_formを呼び出してフォームの構造（array、HTMLではない）を取得し、drupal_prepare_formでフォームを返す
• Drupal7のForm APIのワークフローの詳細説明
  

hook_menuで定義したアクセスURLに、ワイドカード’%’(任意の文字、数字)の使用ができます。例えば、あるページのURI： 「/user/123/fbconnect」、このページにuid=123のユーザーのfbconnectを表示するページとなります。ユーザーにより、uidは変わります。

実際にhook_menuでは、連想配列のキー：　$items['user/%/fbconnect']　で表現します。ここで、ワードカード’%’が使用されています。

ワイドカードが二つのパタン

パタン１：　ワイドカードのみの

• このパタンは比較的に単純で、分かりやすいです
• URLにあるワイドカードの部分を直接に「page callback」関数に定義された関数の引数として渡します。

  function [my-module-name]_menu() {
    $items['user/%/fboauth'] = array(            //ワイドカード'%'の使用
      'title' => t('Facebook settings'),
      'page callback' => 'fboauth_user_form',  //ページ定義関数の呼び出し
      'page arguments' => array(1),               //パスの1番目（0から）を引数に
      ・・・・,
    );
  
  function fboauth_user_form($uid){             //URIの1番目にあるワードカードを引数に
    $user = user_load($uid);
    ・・・
  }

• URIに指定された（'page arugments'=>array(1)）部分(%：uid)をページ定義関数（fboauth_user_form($uid)）の引数にします

パタン２：　ワイドカード＋ファンクション名

• このパタンは「Auto-loader Whitcarts」と言います
• 例：　$items['user/%user/fboauth'] = array(　・・・・・　）ではワイドカード'%'とファンクションuserと一緒に定義されています。
• パスにあるワイドカードの部分を呼びされたページ定義関数に直接に渡すのではないです
• ワイドカードを引数として、定義されたファンクションよりUserオブジェクトをロードして、ページ定義関数に渡します
  
• 上記の例では、Drupalの固有関数（user）を利用していたため、独自にそのローダー関数の定義は不要となります。
• 以下の例では、独自のローダー（custom_obj_load()）を定義しています
  
• スペシャルオブジェクトローダーの関数名は： ワードカードの後ろに定義したオブジェクト名（ここは： custom_obj）＋'_load' => custom_obj_load($obj_id)となります

hook_menuで定義したページへのアクセス権限設定は「access callback」と「access arguments」で行います。特定なユーザーロール、特定なユーザーのみなどの制御が可能となります。特に、ユーザーのアクセス権限管理ページ（ホーム » 管理 » ユーザー » 権限）で各ページのアクセス権限管理が一般的で、よく利用されます。hook_menuがこのアクセス権限管理の実装方法を纏めます。

やりたいこと

• ​アクセス権限管理ページ（ホーム » 管理 » ユーザー » 権限）へのユーザー権限管理実装
• 管理者がユーザーのロールよりカスタマイズしたページへのアクセス管理ができます

アクセス権限：既存とカスタム2種類

• 'access callback'と'access arguments'設定より特定なユーザーアクセスを制御します
  • 'access callback' => 'user_access'、 'access arguments' => array('access content')　コンテンツの参照権限（すべてのユーザがこの権限を有するべき）
  • 'access arguments'の設定値はアクセス権限一覧を参考してください
• hook_permissionを実装して、権限管理ページ（Home » Administration » People » Permissions）でアクセス権限を管理します
  • ​下記の例で詳細に実装方法を説明します

'access callback'と'access arguments'の違い

• 'access callback'： 関数名（例：'user_view_access'）として設定、関数（'user_view_access'）が呼び出され、ユーザーがこのページにアクセス権限があるか否かを判断する機能となります
  • 初期値（'access callback'が定義されていない場合）： 'user_access'
  • 例：'access callback' => TRUE が設定された場合、すべてのユーザーがアクセス可能、この時'access arguments'の設定は不要
  • '例：'access callback' => 'user_is_logged_in' の場合、関数user_is_logged_inが呼び出され、True/Falseの判断結果を 'access callback'に返します
• 'access arguments'： 配列構造、特定の権限/ロールを'access callback'に設定された関数に、引数として渡す機能となります
  • ​'access callback' => 'user_access' , 'access arguments' => array('administer users')　で設定した場合以下の権限設定となります
    • ​create entries
    • delete any entry
    • delete own entries
    • edit any entry
    • edit own entries
  •  配列に整数の設定（例：'access arguments' => array(1)）ができます。この場合、URLのパラメータを参照して、​'access callback'に設定された関数に渡します
    • ​URL例： 'foo/bar/user'
    • array(0)は'foo'、array(1)は'bar'、array(2)は'user'を引数として'access callback'に設定された関数渡します

「access arguments」設定とhook_permissonでアクセス権限を制御

• 「access arguments」関数に、hook_permissionを実装したファンクションを渡すこともできます
  • 例：　'access arguments'  => array('authorize fbauth_connect') 
  • hook_permissionを実装したファンクションは以下のようで（実に簡単の数行だけ）

    /**
     * Implements hook_permission().
     */
    function [my-module-name]_permission() {
      return array(
          'authorize fbauth_connect' => array(
              'title' => t('Connect Facebook account and store access token'),
          ),
      );
    }
    

  • ​アクセス権限管理ページ（ホーム » 管理 » ユーザー » 権限）に、このページへのアクセス権限管理が現れます
    
  • アクセス権限管理ページで、ユーザーのロールより定義したページへのアクセス管理ができます。