drupal_add_tabledrag

~ drupal_add_tabledrag 和訳 ~
7 common.inc

drupal_add_tabledrag($table_id, $action, $relationship, $group, $subgroup = NULL, $source = NULL, $hidden = TRUE, $limit = 0)

テーブル(表)要素にテーブルドラッグの javascript(マウスドラッグにより列の並び替えを行うスクリプト)を追加します。

ドラッグ可能なテーブルは、エンドユーザーが操作する必要のある、並べ替え可能なあらゆるリストに使用することができます。ドラッグ可能なテーブルは、テーブルの個々のセルに配置されたフォーム要素を、柔軟に操作します。

ウェイトを入力するセレクトボックスや、親子関係を含むフォーム要素などをドラッグ&ドロップのテーブルにセットするには、フォーム要素をテーブルの中に配置するようにします。そのテーブルにはID を指定してください。theme_table を使って ID を指定するには次のようにします。:

$output = theme('table', array('header' => $header, 'rows' => $rows, 'attributes' => array('id' => 'my-module-table')));
return $output;

フォームの生成に関しては、テーブルの同じカラムに出力されるグループ化された要素には、それを識別するためのクラスを指定します。

例えばテーブルで単一のカラムに対して並べ替えを行う場合、テーマ関数内ではこのように表現します。

$form['my_elements'][$delta]['weight']['#attributes']['class'] = array('my-elements-weight');

テーブルの各行には、ドラッグハンドルを有効化させるため、"draggable" クラスを指定します。

$row = array(...);
$rows[] = array(
  'data' => $row,
  'class' => array('draggable'),
);

ツリー構造が存在する場合、'tabledrag-leaf' と 'tabledrag-root' のクラスが使用できます。

  • 'tabledrag-leaf' クラスを持つ行は、その下に階層を持つことが出来ません。
  • 'tabledrag-root' クラスを持つ行は、他の行の下にネストすることが出来ません。

drupal_add_tabledrag は次のようにコールします。

drupal_add_tabledrag('my-module-table', 'order', 'sibling', 'my-elements-weight');

もう少し複雑なケースとしては、単一のカラムがいくつかのグループに分かれている場合(ブロック管理ページ 'admin/structure/block' のリージョンのような場合)、これを識別するためのサブグループ用のクラスが必要です。

$form['my_elements'][$region][$delta]['weight']['#attributes']['class'] = array('my-elements-weight', 'my-elements-weight-' . $region);

上のコードでは $group として 'my-element-weight' を渡し、追加の $subgroup として 'my-element-weight-' . $region を渡しています。これは各リージョンにおいてそれぞれ drupal_add_tabledrag をコールする必要があることを示しています。

foreach ($regions as $region) {
  drupal_add_tabledrag('my-module-table', 'order', 'sibling', 'my-elements-weight', 'my-elements-weight-' . $region);
}

ツリー構造がある場合は、各行の親子関係、兄弟関係の情報に基づいてネストされるため、サブグループの指定は必要ありません。親子関係のテーブルについて詳しくは theme_menu_overview_form() を参照してください。

この関数は .tpl.php ファイル、テーマ関数、テンプレートプリプロセス関数などのテーマレイヤーでコールされることに注意してください。フォームの生成段階ではありません。drupal_add_js() 関数によって直接、これと同じ javascript をページに追加することが出来ますが、この関数によってテンプレートファイルをクリーンで読み易く保つことが出来ます。また tabledrag.js を誤って重複コールしてしまうことも防ぎます。

パラメータ

  • $table_id: テーブルソートの対象となるテーブルのID を示す文字列です。対象のテーブルは <table id="my-module-table"> のように ID が指定されている必要があります。
  • $action: フォームに対してのアクションを示す文字列です。'match'、'depth' もしくは 'order' を指定します。'mutch' は一般的に、親子関係に使用されます。'order' は一般的に、グループ化されたフォーム要素同士のウエイトを操作するのに使用されます。'depth' はフォーム要素のインデントを操作します。
  • $relationship: $action 変数を実行する対象を示す文字列です。'parent'、'sibling'、'group'そして 'self' のいずれかを指定します。'parent' はツリー構造の上位のフィールド、'sibling' は同じ行グループの前後のフィールド、'self' はドラッグした行自身に対して影響します。'group' はドラッグした行に加えて、その子孫にあたる行に影響します。
  • $group: アクションを実行するフォーム要素に指定されているクラス。
  • $subgroup: (オプション)グループのサブグループがある場合、それを識別するためのクラスを示す文字列です。
  • $source: (オプション)$action が 'much' の場合、$subgroup の値を合わせる基準となるフィールドを識別するためのクラスを示す文字列です。
  • $hidden: (オプション)javascript がロードされたとき、対象の行が非表示になっている場合があります。非表示にすべきでない場合はここで FALSE を指定します。
  • $limit: (オプション)親子関係の上限を指定します。

参照

ファイル

includes/common.inc, line 4845
Drupal のモジュールが参照する共通の関数。
コア: 
Drupal7