チュートリアル ─ Tutorials

このページでは、Custom DataBase Tables（以降「CDBT」と称します）プラグインをWordPressにインストールして独自に作成したテーブルを公開するまでの手順を紹介します。
あなたはこの文書を通読することでCDBTによるテーブル管理が自由にできるようになるでしょう。また、あなたが既にある程度CDBTについて精通しているならば、この文書はあなたの知識の整理の手助けになるでしょう。

Notice:このチュートリアルはCDBTバージョン2.0.11をベースにして記載しています（2016年4月15日現在）。
トピックス

1. インストール方法

CDBTプラグインのインストール前にあなたのWordPressの動作環境を確認します。CDBTプラグインのバージョン2はPHP5.4以上でないと動作しないからです。
あなたのサーバのPHPのバージョンについてはphpinfo()などを利用して確認してください。

CDBTプラグインは次の4ステップでインストールできます:

  1. WordPress.org公式リポジトリから最新のパッケージをダウンロードします。
  2. ZIPパッケージを展開します。
  3. あなたのWordPressがインストールされているサーバのプラグインディレクトリにフォルダとファイルをアップロードします。通常は、インストールパス下の/wp-content/plugins/になります。
  4. WordPressの管理画面にブラウザでアクセスして「プラグイン」メニューの「インストール済みプラグイン」からCDBTを有効化します。

もしくは、WordPressの管理画面の「プラグイン」画面から「新規追加」をクリックし、「プラグインの検索」に『CDBT』と入力後に表示されるプラグインカードから「インストール」することもできます。
詳しくは導入 ─ Introductionも参照してみてください。

これで終わりです！

2. 以前のバージョンからのアップグレード

あなたのインストール済みのCDBTプラグインにアップグレード可能なバージョンがある場合、WordPressの管理画面のダッシュボードに更新通知が表示されます。
その場合は、CDBTプラグインのアップグレードは次のステップで行います:

  1. WordPressの管理画面にブラウザでアクセスして「ダッシュボード」メニューの「更新」ページに表示されているCustom DataBase Tablesのチェックボックスにチェックを入れて「プラグインを更新」を押します。
    プラグインのアップグレード

これで終わりです！

3. プラグインのダウングレード方法

あなたのサーバーのPHPバージョンが5.4より前のバージョンだった場合、WordPressにCDBTバージョン2のインストールを行うと有効化した後にエラーが発生します。
その場合は、次のステップでプラグインのダウングレードを行ってください:

  1. WordPress.org公式リポジトリの開発者用タブからバージョン1の最終版（2016年4月15日時点では1.1.15）パッケージをダウンロードします。
  2. ZIPパッケージを展開します。
  3. あなたのサーバーの既にインストールされているCDBTプラグインをディレクトリごと削除します。通常のインストールディレクトリは/wp-content/plugins/custom-database-tables/になります。
  4. 展開したZIPパッケージのファイルとフォルダをプラグインディレクトリにアップロードします。
  5. WordPressの管理画面にブラウザでアクセスして「プラグイン」メニューの「インストール済みプラグイン」からCDBTを有効化します。

ダウングレードを行った場合でも、あなたが既に設定したプラグインオプションや作成したテーブルは変更されません。

4. 新しいテーブルを作る

CDBTプラグインで新しいテーブルを作成するには、WordPressの管理画面の「CDBT」メニューから「テーブル管理」ページの「テーブル作成」タブを開きます。

テーブルの新規作成（1）

このページで、あなたが新しく作成したいテーブルの各種設定を行います。
設定項目の詳しい説明はテーブル作成 ─ Create Tableを参照してください。

このチュートリアルでは、サンプルとして汎用的な製品データベース用のテーブルと製品評価テーブルの2つを作成して、製品の評価ページをWordPressで公開するプロジェクトを体験してみます。

まず、製品情報を格納する製品管理テーブルを作成します。テーブル名はwp_productsとします。他の項目はデフォルトのままで、「テーブル作成SQL」欄の「テーブルクリエイター」を起動します。起動したら、下記のようにテーブルを設計します。

製品管理テーブル: テーブルクリエイター

設計が終わったら「SQLを適用する」をクリックします。「テーブル作成SQL」欄に下記のSQLが生成されます。

CREATE TABLE `wp_products` ( 
`ID` bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT COMMENT 'ID', 
`product_name` varchar(200) NOT NULL COMMENT 'Product Name', 
`supplier` varchar(200) COMMENT 'Supplier', 
`category` enum('undefined','category-a','category-b','category-c','category-d','category-e') NOT NULL COMMENT 'Category', 
`price` int(11) UNSIGNED NOT NULL DEFAULT 0 COMMENT 'Price', 
`image` mediumblob COMMENT 'Image', 
`reference_url` varchar(255) COMMENT 'Reference URL', 
`description` text COMMENT 'Description', 
`created` datetime NOT NULL DEFAULT '0000-00-00 00:00:00' COMMENT 'Created Datetime', 
`updated` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 'Updated Datetime', 
PRIMARY KEY(`ID`)  ) 
ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 AUTO_INCREMENT=1;

続いて、作成テーブルのプラグイン用の設定を行います。サンプルの製品管理テーブルへの製品登録やデータ編集はログインしていないユーザーにもアクセス権を与えることにします。下記のようにデータ閲覧・データ登録・データ編集のすべてについてゲストユーザー以上にアクセス権を与えます。

製品管理テーブル: アクセス権

これで製品管理テーブルの設定は完了です。「テーブル作成」をクリックします。

次に製品の評価データを収集する製品評価テーブルを作成します。テーブル名はwp_product reputeとします。ここでは、製品評価の仕組みとして評価した日時等は管理しないことにします。そのため、自動追加カラムはプライマリーキーのみにします。それ以外の設定値はデフォルトのままです。

製品評価テーブル: 基本設定

テーブルクリエイターを起動して、下記のようにテーブルを設計します。

製品評価テーブル: テーブルクリエイター

設計後のSQLは下記のようになります:

CREATE TABLE `wp_product_repute` ( 
`ID` bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT COMMENT 'ID', 
`product_id` bigint(20) UNSIGNED NOT NULL COMMENT 'Product ID', 
`rater` varchar(100) COMMENT 'Rater', 
`score` tinyint(4) UNSIGNED NOT NULL DEFAULT 1 COMMENT 'Score', 
`comment` text COMMENT 'Evaluation Comment', 
PRIMARY KEY(`ID`)  ) 
ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 AUTO_INCREMENT=1;

製品評価テーブルについてもユーザーのアクセス権は製品管理テーブルと同じ設定にします。

製品評価テーブル: アクセス権

以上の設定で「テーブル作成」をクリックします。
これで、製品管理テーブルと製品評価テーブルができました。次にこの2つのテーブルをリレーション（連携）させます。つまり、製品評価テーブルのproduct_idカラムには製品管理テーブルのプライマリーキーであるIDカラムに存在する値しか指定できないように外部キー制約を追加します。

テーブル編集

テーブル管理の「テーブル編集」タブを開き、外部キー制約を追加するwp_product_reputeテーブルを選択して「編集テーブルの変更」をクリックします。

「テーブル本体スキーマの変更」セクションの「カスタムSQL（ALTER TABLE）」欄、「SQL直接編集」タブのテキストエリアに外部キー制約追加のSQLを入力します。

テーブル編集: 外部キー追加

入力するSQLは下記を参照:

ALTER TABLE wp_product_repute ADD FOREIGN KEY index_pid (product_id) REFERENCES wp_products (ID) ON DELETE CASCADE ON UPDATE CASCADE;

これで新規テーブルの準備は完了です。

5. ショートコードを作る

新しく作成したテーブルをWEBページに出力するためのショートコードを作成します。
CDBTプラグインで新しいショートコードを作成するには、WordPressの管理画面の「CDBT」メニューから「ショートコード管理」ページの「ショートコード登録」タブを開きます。

ショートコードの新規作成（1）

このページで、あなたが新しく作成したいショートコードの各種設定を行います。

このチュートリアルでは製品管理テーブルのデータを一覧表示するための[[cdbt-view]]のショートコードと、製品管理テーブルに製品データを登録するための[[cdbt-entry]]のショートコード、および製品評価テーブルに評価を入力してもらうための[[cdbt-entry]]のショートコードの３つを作成します。

まず一つ目のショートコード[[cdbt-view]]を作成します。「ショートコード登録」タブで「ベースショートコード名」にcdbt-viewを、「対象テーブル名」にwp_productsをそれぞれ選択します。すると、参考情報としてwp_productテーブルのカラム情報が表示されます。

ショートコードの新規作成（2）

「ショートコードの高度な設定」セクションでの設定項目は下記の通りです。

ショートコードの新規作成（3）
Notice:「カラムの表示順」に表示するカラムの順序を指定すると、その順序通りにカラムが表示され、指定しなかったカラムは非表示になります。この設定は「表示するカラム」や「除外するカラム」の指定より優先され、「表示するカラム」と「除外するカラム」の設定値は無効になります。

各設定値の詳しい説明はショートコード登録の項を参照してください。

設定が完了したら「ショートコードを保存」ボタンをクリックしてカスタムショートコードとして保存します。

続いて二つ目のショートコード[[cdbt-entry]]を作成します。やり方は一つ目の時と同じで、「ベースショートコード名」にcdbt-entryを、「対象テーブル名」にwp_productsをそれぞれ選択します。そして、「ショートコードの高度な設定」セクションでの設定項目は下記の通りです。

ショートコードの新規作成（4）
Notice:テーブル作成時に自動追加カラムを指定した場合、登録日時のcreatedカラムだけは入力フォームとして出力されます。そのため、登録日時を非表示にしたい時は「非表示化カラム」に指定する必要があります。

ショートコードの作成は「ショートコードプレビュー」を利用して、現在の設定によるショートコード出力を確認しながら作成できます。ただし、[[cdbt-view]]や[[cdbt-edit]]のショートコードはテーブル内にデータが存在しないと表示されないため、プレビューを利用する場合はあらかじめいくつかのデータを登録しておく必要があります。

これで二つ目のショートコードの設定は完了です。「ショートコードを保存」ボタンをクリックしてカスタムショートコードとして保存します。

最後に三つめのショートコード、製品評価テーブル用の[[cdbt-entry]]を作成します。やり方は二つ目の時と同様に、「ベースショートコード名」にcdbt-entryを、「対象テーブル名」にwp_product_reputeをそれぞれ選択します。そして、「ショートコードの高度な設定」セクションでの設定項目は下記の通りです。

ショートコードの新規作成（5）

設定後、「ショートコードを保存」ボタンをクリックしてカスタムショートコードとして保存します。

これで必要な三つのショートコードの作成が完了しました。

6. ショートコードを設置する

作成したショートコードをあなたのサイトのページに設置します。
まず、設置するショートコードの記述を確認します。そのためには「ショートコード管理」の「ショートコード一覧」タブを開きます。

ショートコード一覧

前章で作成した三つのショートコードが一覧表示されているので、「ショートコード名／エイリアスコード」列のエイリアスコードをすべて控えておきます。

次にWordPressの新規投稿画面を開き、下図のような投稿を作成します。

新規投稿作成（1）

投稿本文（テキスト）は下記の通りです:

Currently registered product list:

[cdbt-view table="wp_products" csid="1"]

<hr />

Product Registration Form:

[cdbt-entry table="wp_products" csid="2"]

さっそく「公開」して表示を確認してみます。

製品管理ページ表示
Notice:このチュートリアルで使用しているテーマは「Twenty Sixteen」です。

まだ製品管理テーブルにデータを登録していないので、[[cdbt-view]]のショートコード部分が表示されませんが、このページから製品データを登録できるようになっています。
実際にいくつかサンプルの製品データを登録してみます。

製品管理ページ: サンプルデータ投入後

続いて、製品評価用のページを作成ってみます。再びWordPressの新規投稿画面を開き、下図のような投稿を作成します。

新規投稿作成（2）

投稿本文（テキスト）は下記の通りです:

Currently registered product list:

[cdbt-view table="wp_products" csid="1"]

<hr />

Product Evaluation Form:

[cdbt-entry table="wp_product_repute" csid="3"]

「公開」して表示してみます。

製品評価ページ

これで製品管理ページと製品評価ページが出来上がりました。

しかし、製品データの閲覧や製品評価の入力についてはかなり使い勝手が悪い状態です。例えば、この時点で製品評価フォームにProduct IDに99などの製品管理テーブルのIDカラムにない値を指定してデータ登録を行った場合、外部キー制約に違反して登録に失敗してしまいます。

7. ショートコードをカスタマイズする

この章では、出力されたショートコードの見た目や処理をカスタマイズして、CDBTプラグインによるサービスの実用化の例を紹介して行きます。あなたのプロジェクトの参考にしてみてください。

7-1. データ一覧の見た目をカスタマイズする

[[cdbt-view]]や[[cdbt-edit]]で出力されるデータ一覧の表示をカスタマイズします。
チュートリアルのサンプルショートコードで表示される現在のテーブル構造は下記のようになっています。

Image Product Name Supplier Category Price Description Reference URL
画像ファイル 製品名 供給元 カテゴリー名 価格 説明 参照URL

この表示を下記のように変更します。

Image Product Name Supplier Category Price Description Repute
画像ファイル 参照URLへのリンク付き製品名 供給元 カテゴリー名 単位「$」付き価格 ポップアップ形式の説明リンク 平均の評価スコア

また、カテゴリー名によって行の背景色も変更してみます。

[[cdbt-view]]や[[cdbt-edit]]で表示されるデータ一覧の表示をカスタマイズする時には、CDBTプラグインに用意されているcdbt_shortcode_custom_columnsフィルターとcdbt_shortcode_custom_component_optionsフィルターを使います。それぞれのフィルター処理をテーマのfunctions.phpに追加します（本チュートリアルで利用しているテーマは「Twenty Sixteen」です）。

function custom_wp_products_crud_get_data_sql( $sql, $table_name, $sql_clauses ) {
  if ( in_array( get_post()->post_title, array( 'Product evaluation page', 'Product registration page' ) ) && 'wp_products' === $table_name ) {
    if ( strpos( $sql_clauses[0], 'image' ) !== false ) {
      // Join of table (outer join)
      $_overwrite_sql = <<<SQL
SELECT p.image,p.product_name,p.supplier,p.category,p.price,p.description,p.reference_url,AVG(r.score) as repute 
FROM wp_products p
LEFT OUTER JOIN wp_product_repute r ON p.ID=r.product_id 
GROUP BY p.ID 
ORDER BY p.product_name ASC 
SQL;
      $sql = $_overwrite_sql;
    }
  }
  return $sql;
}
add_filter( 'cdbt_crud_get_data_sql', 'custom_wp_products_crud_get_data_sql', 10, 3 );

まずcdbt_crud_get_data_sqlフィルターを使い、wp_productsテーブルに製品評価テーブルの各product_idごとのscoreカラムの平均値をreputeカラムとして外部結合（OUTER JOIN）します。これにより、製品管理ページのショートコード[[cdbt-view]]で新カラムreputeを取り扱うことができるようになります。

function custom_wp_products_cdbt_shortcode_custom_columns( $columns, $shortcode_name, $table ) {
  if ( in_array( get_post()->post_title, array( 'Product evaluation page', 'Product registration page' ) ) && in_array( $shortcode_name, array( 'cdbt-view', 'cdbt-edit' ) ) && 'wp_products' === $table ) {
    foreach ( $columns as $_i => $_column ) {
      $_custom_column = '';
      switch( $_column['property'] ) {
        case 'product_name':
          // Add a tag for link
          $_custom_column = 'rowData.reference_url != "" ? $("<a/>").attr("href",_.unescape(rowData.reference_url)).attr("target","_blank").text(_.unescape(rowData.product_name)) : rowData.product_name';
          break;
        case 'price':
          // Add string of unit as prefix
          $_custom_column = '"$ " + rowData.price';
          break;
        case 'description':
          // Add a popup link
          $_custom_column = 'rowData.description != "" ? $("<a/>").attr("href","javascript:;").attr("class","collapse-col-data btn btn-default btn-sm").data("raw",_.unescape(rowData.description)).text("More") : "-"';
          break;
        case 'reference_url':
          // Do not show
          unset( $columns[$_i] );
          break;
      }
      if ( ! empty( $_custom_column ) ) 
        $columns[$_i]['customColumnRenderer'] = $_custom_column;
    }
    // Add new column
    $columns = array_merge( $columns, array( 
      array(
        'label' => 'Repute', 
        'property' => 'repute', 
        'sortable' => true, 
        'sortDirection' => 'asc', 
        'dataNumric' => true, 
        'truncateStrings' => '0', 
        'className' => '', 
        'customColumnRenderer' => 'rowData.repute != null ? Number(rowData.repute) : "Unrated"'
      )
    ) );
  }

  return $columns;
}
add_filter( 'cdbt_shortcode_custom_columns', 'custom_wp_products_cdbt_shortcode_custom_columns', 10, 3 );

function custom_wp_products_cdbt_shortcode_custom_component_options( $component_options, $shortcode_name, $table ){
  if ( in_array( get_post()->post_title, array( 'Product evaluation page', 'Product registration page' ) ) && in_array( $shortcode_name, array( 'cdbt-view', 'cdbt-edit' ) ) && 'wp_products' === $table ) {
    $_custom_script = <<<EJS
var bgcolor = '#ececec', txtcolor = '#333';
switch( helpers.rowData.category ){
  case 'category-a':
    bgcolor = '#8fc31f';
    break;
  case 'category-b':
    bgcolor = '#fff100';
    break;
  case 'category-c':
    bgcolor = '#e60012';
    txtcolor = '#fff';
    break;
  case 'category-d':
    bgcolor = '#f39800';
    break;
  case 'category-e':
    bgcolor = '#e4007f';
    txtcolor = '#fff';
    break;
}
item.css({ backgroundColor: bgcolor, color: txtcolor });
EJS;
    if ( ! isset( $component_options['customRowScripts'] ) ) {
      $component_options['customRowScripts'] = array( $_custom_script );
    } else {
      $component_options['customRowScripts'][] = $_custom_script;
    }
  }

  return $component_options;
}
add_filter( 'cdbt_shortcode_custom_component_options', 'custom_wp_products_cdbt_shortcode_custom_component_options', 10, 3 );

そして、上記のフィルターフックにてショートコードで出力される一覧表の列と行についてカスタマイズを行います。
このカスタマイズが反映されたショートコード[[cdbt-view]]は下記のように表示されます。

カスタマイズ後のcdbt-view

7-2. データ登録フォームをカスタマイズする

[[cdbt-entry]]で出力されるデータ登録フォームの表示をカスタマイズします。
登録フォームの表示をカスタマイズする時には、CDBTプラグインに用意されているcdbt_shortcode_custom_formsフィルターを使い、処理をテーマのfunctions.phpに追加します。

本チュートリアルでは、製品評価フォームに対して次のようなカスタマイズを行ってみます。

  • 評価対象を入力するproduct_idフィールドについて、製品管理テーブルに存在する製品IDのみが入力されるように選択式フィールドに変更します。
  • 入力項目の並び順を変更します。
  • 評価フィールドを10段階評価の選択式フィールドに変更します。
  • 評価コメントフィールドの初期サイズを変更し、補足テキストを追加します。
  • 各フィールドの項目ラベルを変更します。 
function custom_wp_product_repute_cdbt_shortcode_custom_forms( $elements_options, $shortcode_name, $table ){
  if ( 'Product evaluation page' === get_post()->post_title && 'cdbt-entry' === $shortcode_name && 'wp_product_repute' === $table ) {
    global $cdbt;
    $result = $cdbt->get_data( 'wp_products', ['ID','product_name'], [], ['product_name'=>'ASC'], 'ARRAY_A' );
    $values = [];
    foreach ( $result as $_i => $_v ) {
      $values[] = $_v['product_name'] .':'. $_v['ID'];
    }
    foreach ( $elements_options as $_i => $_option ) {
      if ( 'product_id' === $_option['elementName'] ) {
        $elements_options[$_i]['elementLabel'] = __('Product Name');
        $elements_options[$_i]['elementType'] = 'select';
        $elements_options[$_i]['selectableList'] = implode( ',', $values );
        $elements_options[$_i]['helperText'] = __('Please choose the name of product to evaluate.');
        $_new_elements_options[0] = $elements_options[$_i];
      }
      if ( 'rater' === $_option['elementName'] ) {
        $elements_options[$_i]['elementLabel'] = __('Your Name');
        $elements_options[$_i]['elementSize'] = 6;
        $_new_elements_options[2] = $elements_options[$_i];
      }
      if ( 'score' === $_option['elementName'] ) {
        $elements_options[$_i]['elementLabel'] = __('Your Score');
        $elements_options[$_i]['elementType'] = 'select';
        $elements_options[$_i]['selectableList'] = '1:1,2:2,3:3,4:4,5:5,6:6,7:7,8:8,9:9,10:10';
        $elements_options[$_i]['defaultValue'] = '5';
        $elements_options[$_i]['helperText'] = __('On a scale of one to ten, how would you rate that product?');
        $_new_elements_options[1] = $elements_options[$_i];
      }
      if ( 'comment' === $_option['elementName'] ) {
        $elements_options[$_i]['helperText'] = __('Please enter here if you have any comments.');
        $elements_options[$_i]['elementExtras'] = array( 'rows' => 4 );
        $_new_elements_options[3] = $elements_options[$_i];
      }
    }
    $_new_orders = array( 1, 3, 2, 4 );
    array_multisort( $_new_orders, $elements_options );
  }
  return $elements_options;
}
add_filter( 'cdbt_shortcode_custom_forms', 'custom_wp_product_repute_cdbt_shortcode_custom_forms', 10, 3 );

このカスタマイズが反映されたショートコード[[cdbt-entry]]は下記のように表示されます。

カスタマイズ後のcdbt-entry

これでサンプルの製品管理／製品評価プロジェクトが完成しました。

このサンプルプロジェクトは、デモサイト「http://demo.ka2.org」で公開中です。
下記のデモページもあわせてご参照ください。

これでチュートリアルは終了です。
早速、あなたのプロジェクトを進めてみましょう。