Drupal 開発のベストプラクティスがわかる Examples モジュール

今回は Drupal （ドルーパル）のモジュール開発に役立つ Examples モジュールをご紹介したいと思います。

まずはじめに Examples モジュールとは何ぞやという説明をした後に具体的な使い方をご紹介していきます。

Examples モジュールとは

Examples モジュールは Drupal モジュールを開発する際に参考にできるさまざまなベストプラクティスがつまったモジュールです（正確には Examples モジュールではなく Examples 「プロジェクト」です）。 本番サイトで利用する類のものではなく、あくまでも開発者が自身の開発の参考にするための「動作するサンプルコード」の集まりのモジュールとなっています。

たとえば block_example page_example form_eample といった xx_example モジュールがたくさん含まれており、ドキュメントを読むだけではなかなかわかりづらい Drupal 機能開発の「ほんとのところ」を学ぶのに最適なモジュールです。

本記事執筆時点の Drupal 7 向けの最新版 7.x-1.x-dev には以下の xx_example モジュールが含まれています。

• action_example
• ajax_example
• batch_example
• block_example
• cache_example
• contextual_links_example
• cron_example
• dbtng_example
• email_example
• entity_example
• field_example
• field_permission_example
• file_example
• filter_example
• form_example
• image_example
• js_example
• menu_example
• node_access_example
• node_example
• nodeapi_example
• page_example
• pager_example
• queue_example
• rdf_example
• render_example
• simpletest_example
• tabledrag_example
• tablesort_example
• theming_example
• token_example
• trigger_example
• vertical_tabs_example
• xmlrpc_example

xx の部分がそれぞれのサンプルの内容を端的に表していて、たとえば ajax なら AJAX のサンプル、 queue ならキューのサンプル、といった感じになっています。 では以下では block_example を例に基本的な使い方を見ていきましょう。 今回は Drupal 7 を対象とします。

Examples モジュールの使い方

インストール / 有効化

まずは Examples プロジェクト全体をダウンロードしてきて、 Examples モジュールを有効化します。

• Examples for Developers | Drupal.org

モジュールのインストール / 有効化の方法がわからない場合は、別記事で Drupal のモジュールの一般的なインストール / 有効化方法について解説していますので、そちらをご参考にしていただければと思います。

• Drupal のモジュールのインストール方法

Drush を使えば次のコマンドでダウンロード / 有効化できるでしょう。

$ drush en examples

個別モジュールの有効化

つづいて個別のモジュールを有効化します。

管理画面から有効化する場合はモジュール管理ページ（パスは /admin/modules ）を開いて「 Block Example 」という項目を探してチェックを入れ、ページ下部の「設定を保存」をクリックしましょう。 ページが更新されたときに「 Block Example 」のチェックが入った状態になっていれば有効化は完了です。

動作とコードの確認

モジュールが有効化されたので、モジュールの実際の動作をコードとあわせて見ていきましょう。

サイトのフロントページ（ホーム）を開くと、次の画像のような新しいブロックが追加されているのが確認できるかと思います。

> UPPERCASE THIS PLEASE

block_example モジュールは Drupal のブロック（ WordPress やその他の CMS でいうところのウィジェット）をいくつか定義しているモジュールで、このブロックもそのうちのひとつです。

ブロックの管理ページ（ /admin/structure/block ）を開いてみましょう。 ブロック一覧を見ると、この「 UPPERCASE... 」というブロックが管理画面上でも追加されていることが確認できます。 管理画面上の名前は「 Example: uppercase this please 」という風になっています。

このように、有効化すれば Drupal サイト上で実際に動作するコード例がモジュールとしてまとめられています。

このブロックに対応するコードの方も少し見てみましょう。

block_example.module を開くと、元のコードを確認することができます。 たとえば今回の場合であれば以下の部分が「 UPPERCASE... 」に関わっているコードです。 hook_block_info() hook_block_view() hook_block_view_alter() を実装すればこのブロックのような挙動が実現できるということがわかります。

/**
 * Implements hook_block_info().
 *
 * This hook declares what blocks are provided by the module.
 */
function block_example_block_info() {
  // This hook returns an array, each component of which is an array of block
  // information. The array keys are the 'delta' values used in other block
  // hooks.

  // ...中略...

  $blocks['example_uppercase'] = array(
    // info: The name of the block.
    'info' => t('Example: uppercase this please'),
    'status' => TRUE,
    'region' => 'sidebar_first',
  );

  return $blocks;
}



/**
 * Implements hook_block_view().
 *
 * This hook generates the contents of the blocks themselves.
 */
function block_example_block_view($delta = '') {
  // The $delta parameter tells us which block is being requested.
  switch ($delta) {

    // ...中略...

    case 'example_uppercase':
      $block['subject'] = t("uppercase this please");
      $block['content'] = t("This block's title will be changed to uppercase. Any other block with 'uppercase' in the subject or title will also be altered. If you change this block's title through the UI to omit the word 'uppercase', it will still be altered to uppercase as the subject key has not been changed.");
      break;
  }
  return $block;
}



/**
 * Implements hook_block_view_alter().
 *
 * This hook allows you to modify the output of any block in the system.
 *
 * ...中略...
 */
function block_example_block_view_alter(&$data, $block) {
  // We'll search for the string 'uppercase'.
  if ((!empty($block->title) && stristr($block->title, 'uppercase')) || (!empty($data['subject']) && stristr($data['subject'], 'uppercase'))) {
    // This will uppercase the default title.
    $data['subject'] = isset($data['subject']) ? drupal_strtoupper($data['subject']) : '';
    // This will uppercase a title set in the UI.
    $block->title = isset($block->title) ? drupal_strtoupper($block->title) : '';
  }
}

block_example モジュールはこの他にもいくつかのブロックを提供しており、ブロックの基本的な利用パターンをひととおり学ぶことができるようになっています。 ブロック管理ページ上で有効化すると、他のブロックの挙動もかんたんに確認することができます。

使い方については以上です。

今回は個別具体的な block_example のお話でしたが、基本的な利用の流れは他の xx_example モジュールでも同じです。

ちなみに、 xx_example モジュールをインストールすると、パス /examples/xx_exampleに各モジュールの導入ページが追加されます（たとえば block_example の場合は /examples/block_example ）。 モジュールによってはこのページがたいへん便利ですので、まずはそのページにアクセスして挙動を調べてみるのもひとつかと思います。

以上です。 いかがだったでしょうか？

終わりに

今回は Drupal モジュール開発のベストプラクティスを学ぶのに便利な学習用モジュール Examples をご紹介しました。 これから Drupal 開発を始めようという方にもある程度 Drupal 開発には慣れたという方にもたいへん便利なモジュールですので、よろしければ導入してみてお試しいただければと思います。

最後に注意点をひとつ。 Examples モジュールにはコメントが豊富に含まれていますが、 Drupal のコンセプトや全体的な流れを理解するにはこれだけでは不十分です。 やはり基本となるモジュールの作り方やコアの動作の仕組み、フックシステムなどをある程度理解しておいて初めて具体的なサンプルコードが役に立つというところがあるかと思います。 ですので、いきなり Examples をダウンロードして中身を覗くのではなく、基本コンセプトについては Drupal.org のドキュメントやその他ブログなどを読みつつ、ある程度理解できたら Examples で確認するーードキュメントとサンプルの間の行き来をしながら学んでいくのが最もスムーズで成果が出やすい方法かと思います。