【Drupal】入力フォーム画面を表示するカスタムモジュールの作成

経緯

カスタムモジュール作成には、フォーム画面を必要とすることが多いと思います。なので、簡易的なフォーム画面を作成し、その流れを書こうと思いました。

環境

OS : Windows 7 32bit

Drupal : Drupal Version 7.37

XAMPP : XAMPP Version 5.5.24

Apache : Apache Version 2.4.12

MySQL : MySQL Server Version 5.6.24

PHP : PHP Version 5.6.8

前提

下記の項目について、なんとなく理解していることを前提とします。

フックについての理解
カスタムモジュール作成の流れ

概要

作成するモジュール内容は、コンテンツの部分に入力フォームと送信ボタンを表示するカスタムモジュールです。送信ボタン押下時に、入力フォームが未入力ならばエラー処理をします。そうでない場合は、入力内容を画面へ表示するようにします。

手順

モジュールは下記の手順で作成します。

hook_menu関数で画面のPathとURLリクエスト処理を定義
hook_form関数でフォームの情報を定義
form_id_validate関数で入力値の検証
form_id_submit関数で送信時の処理

具体例

まずは具体例であるソースコードを表示し、後からソースコードの簡単な解説していこうと思います。

下記はモジュールの情報を定義しているモジュール名.infoファイルです。ファイル名はexample_form.infoにしています。

; モジュール名
name = Example Form
; モジュールの概要
description = Example.
; Drupalコアのバージョン
core = 7.x
; パッケージ名
package = Example

下記はモジュールの動作を定義しているモジュール名.moduleファイルです。ファイル名はexample_form.moduleにしています。

<?php

/**
 * @file
 * 入力フォームを表示するモジュール
 */

/**
 * Implements hook_menu().
 */
function example_form_menu() {
  // 文字列を適切な言語へ変換
  $form_title = t('Form Page');
  $form_description = t('入力フォームを表示する画面');
  // 入力フォームを表示する画面のPathとアクセス時の挙動
  $items['example/form'] = array(
    // ページ名
    'title' => $form_title,
    // ページ概要
    'description' => $form_description,
    // ユーザがページを訪問した際に呼び出されるコールバック関数
    'page callback' => 'drupal_get_form',
    // ユーザがページを訪問した際に呼び出されるコールバック関数の引数
    'page arguments' => array('example_form_form'),
    // アクセス時に呼び出されるコールバック関数
    'access callback' => TRUE,
  );
  return $items;
}

/**
 * Implements hook_form().
 */
function example_form_form($form, &$form_state) {
  // 文字列を適切な言語へ変換
  $form_id_title = t('Id');
  $form_name_title = t('Name');
  $form_submit_value = t('送信');
  // フォームの初期化
  $form = array();
  // ID入力フォーム
  $form['id'] = array(
    // フォームのタイプ
    '#type' => 'textfield',
    // フォームのタイトル
    '#title' => $form_id_title,
  );
  // 名前入力フォーム
  $form['name'] = array(
    // フォームのタイプ
    '#type' => 'textfield',
    // フォームのタイトル
    '#title' => $form_name_title,
  );
  // 送信ボタン
  $form['submit'] = array(
    // フォームのタイプ
    '#type' => 'submit',
    // フォームのタイトル
    '#name' => 'submit',
    // ボタンに表示される値
    '#value' => $form_submit_value,
  );
  return $form;
}

/**
 * Implements form_id_validate().
 */
function example_form_form_validate($form, &$form_state) {
  // 入力されているかの検証
  if (!$form_state['values']['id'] || !$form_state['values']['name']){
   // 文字列を適切な言語へ変換
   $form_error_not_entered = t('It is not entered.');
   // 未入力ならばエラー処理
    form_set_error('submit', $form_error_not_entered);
  }
}

/**
 * Implements form_id_submit().
 */
function example_form_form_submit($form, &$form_state) {
  // 文字列を適切な言語へ変換
  $form_values_id = t('ID : @id', array('@id' => $form_state['values']['id']));
  $form_values_name = t('Name : @name', array('@name' => $form_state['values']['name']));
  // 文字の表示
  drupal_set_message($form_values_id);
  drupal_set_message($form_values_name);
}

表示される画面は下記のようになっています。

f:id:buravo46:20150630120926p:plain

解説

それでは手順に沿ってソースコードの解説をしていこうと思います。

1. `hook_menu`関数で画面のPathとURLリクエスト処理を定義

まずはt関数を使用して、画面に表示する文字列を現在の言語に変換しておきます。

次は、入力フォームを表示するための画面PathとURLリクエスト時の処理を定義します。ここで気を付けたいのが、'page callback'で定義している'drupal_get_form'関数のことです。この関数は指定したフォームIDのフォームをHTMLとして出力し返り値として渡す関数です。フォームIDとはフォームの関数名のことです。具体例だと、example_form_form関数のことになります。 'page arguments'では'drupal_get_form'関数の引数であるフォームIDを渡しています。

これで画面へアクセスするとフォームが生成されるようになりました。

2. `hook_form`関数でフォームの情報を定義

hook_form関数ではID,名前の入力フォームと送信ボタンを定義しています。フォームのタイプは'#type'で定義することができます。'textfield'だとテキストを入力するフィールドを定義してくれます。それ以外にも、チェックボックスの'checkbox'や選択リストの'select'、Submitボタンの'submit'などがあります。

3. `form_id_validate`関数で入力値の検証

form_id_validate関数では、入力された値の検証をしています。 form_idの部分をフォームIDにすることで使用することができます。具体例だとexample_form_form_validate関数となります。入力された値を$form_state['values']['フォーム配列のキー名']で取得し、存在していなければform_set_error関数でエラー処理をしています。

4. `form_id_submit`関数で送信時の処理

form_id_submit関数ではSubmitボタン押下時の処理をしています。 form_idの部分をフォームIDにすることで使用することができます。具体例だとexample_form_form_submit関数となります。

ここではt('ID : @id', array('@id' => $form_state['values']['id']));といったt関数の使い方をしています。 t関数はt('ID : ' . $form_state['values']['id']);というような使い方は推奨していないので、 t('ID : @キー名', array('@キー名' => $form_state['values']['キー名']));というように記述する必要があります。

drupal_set_message関数は画面上に一時的なメッセージを表示する関数です。この関数を使って、入力された内容を表示しています。

これで、入力フォーム画面を表示することができます。

まとめ

今回は入力フォームを表示するカスタムモジュールを作成しました。 Submitボタン押下時に検証や送信の処理を簡単にしてくれるform_id_validate関数やform_id_submit関数は中々便利です。カスタムモジュール内で完結できそうな簡易的なフォーム画面ならこれで良いかもしれませんね。