JavaScript/jQuery/DataTables

Last-modified: Tue, 12 Jun 2012 23:16:16 JST (1871d)

本家

jQueryのテーブル表示プラグイン。ライセンスはGPLv2 or BSD(サイトではBSD "3-point"と書かれてるけど、3-clause BSD license=修正BSDライセンスの事だと思う)

http://datatables.net

No 名前 OS
1 Firefox Linux,Windows,Mac
2 IE Windows
3 Google Chrome Linux,Windows,Mac
4 Safari Mac,Windows
5 Opera Linux,Windows,Mac


関連

機能

http://www.datatables.net/usage/features

パラメータ設定値デフォルト機能
bAutoWidthbooleantrue列幅自動調節機能の有効/無効
bDeferRenderbooleanfalse遅延描画。JSON(静的/動的)で巨大なテーブルデータを与える場合に特に有効
bFilterbooleantrueフィルタ設定フォームの有無
bInfobooleantrueテーブル情報(テーブル下に表示される表示行数)の表示/非表示
bJQueryUIbooleanfalsejQuery UI Themerollerの有効/無効
bLengthChangebooleantrue表示件数の変更を許可or禁止。許可する場合はbPaginateも必要
bPaginatebooleantrue表示件数変更のプルダウン表示の有無
bProcessingbooleanfalse"処理中"表示の有無。テーブルが大きい時用
bScrollInfinitebooleanfalse無限スクロール(要AJAX?)bPaginateとの併用不可(強制無効化)
bServerSidebooleanfalseServer-side processingを有効にする。その場合sAjaxSourceも指定が必要
bSortbooleantrueソート機能の有効/無効。カラム別に設定する場合はbSortableを使用する
bSortClassesbooleantrue各列に'sorting_1','sorting_2'というクラスを追加する機能
現在のソート対象列を識別する
bStateSavebooleanfalseクッキーを使ってページ表示設定を保存する
sScrollX文字列NULL(無効)水平方向のスクロール機能
CSSでサイズ指定に使われる単位(px等)または%で指定
sScrollY文字列NULL(無効)垂直方向のスクロール機能
CSSでサイズ指定に使われる単位(px等)または%で指定

オプション

http://www.datatables.net/usage/options

パラメータ名デフォルト機能
aaSorting2次配列[ [0,'asc'] ]初期ソート設定。列(0〜)とソート方向(desc,asc)を指定
aaSortingFixed2次配列-aaSorting同様の初期ソート設定。ただし、ソート設定を固定し変更出来なくする
aLengthMenu整数の配列[ 10, 25, 50, 100 ]表示件数を選択するドロップダウンメニューのエントリ
aoSearchColsobjectの配列NULL各列のフィルタ設定(oSearchの列Ver)。使用する場合、全ての列に設定が必要。
sSearchはフィルタ初期値、bEscapeRegex(オプション)は?
asStripeClasses任意の文字列の配列['odd','even']tr(行)要素に自動で追加されるclass名
指定した文字列が順番に割り当てられる。
asStripClasses
↑のtypo。1.9でdeprecated
bDestroybooleanfalse無効化?
bRetrievebooleanfalseDataTablesオブジェクトを取得する
bScrollCollapsebooleanfalse表示範囲を固定しない。垂直方向のスクロール有効かつフィルタ使用時、表示件数に合わせて表示を変える
iCookieDuration整数7200Cookieの有効時間(秒)
iDisplayLength整数10表示行数。bLengthChangeが有効な場合、ユーザー側で設定を上書きできる
iDisplayStart整数0Pagination有効時、表示開始行数を指定。例えば、10行/ページでiDisplayStart=30を指定すると3ページ目から表示する
iScrollLoadGap
oSearchobject{ "sSearch": "", "bRegex": false, "bSmart": true }フィルタ(検索窓)の初期値設定。
sSearch=フィルタの初期値(文字列)
bRegex=正規表現機能の有効/無効(boolean)
bSmart=文字列中の任意の部分にマッチさせる機能の有効/無効(boolean)。
少なくとも、sSearchは指定する必要がある。
sAjaxDataProp文字列aaDataテーブルのデータをAJAAで取得する際のJSON変数名
sAjaxSource文字列(URL)NULLテーブルのデータをAJAXで取得する際のURL
sCookiePrefix文字列SpryMedia_DataTables_bStateSave有効時に使用するCookieのprefix
sDom文字列lfrtip (bJQueryUI無効時)
<"H"lfr>t<"F"ip> (bJQueryUI有効時)
初期化時に有効にする機能を指定
l:表示件数変更
f:検索フィルタ
t:?
i:情報表示
p:ページネーション
r:「処理中」(pRocessing)表示
sPaginationType文字列two_buttonページネーションの種類。two_button(進む/戻るの2ボタン)、full_numbers(全ページ数字表示)のどちらか
sScrollXInner文字列なし(無効)テーブルの幅を大きくする。自動調整よりも大きくしたい場合に指定。値はCSSのサイズ指定で使用される単位(px,%等)

API(Method)

テーブルに対する操作いろいろ。DataTablesオブジェクト(初期化処理の戻り値)のメソッド
http://datatables.net/api
http://datatables.net/docs/DataTables/1.9.1/

メソッド引数
(oTable=DataTablesオブジェクト)
機能
$(sSelector,oOpt,sSel,sOrd,sLim)sSelector:jQueryと同様のセレクタ文字列
node: TR要素
ojQuery:jQueryオブジェクト
oOpts: ?
sSel:
sOrd:
sLim:
oTable.$('tr#row2').css({'background-color':'red'});行(TR要素)を選択してjQueryオブジェクトを返す。jQueryのセレクタと同種の機能
$(node,oOpt,sSel,sOrd,sLim)oTable.fnGetPosition( oTable.fnGetNodes(1) )
$(ojQuery,oOpt,sSel,sOrd,sLim)oTable.fnGetPosition( $("td#hoge").get(0)
fnAddData(array,bRedraw)array:追加するデータ。1次配列or2次配列
bRedraw:データ追加時に再描画するかどうか(省略時true)
oTable.fnAddData(['1','foo'])テーブルにデータを追加する
oTable.fnAddData([ ['1','foo'], ['2','foo'] ])
fnAddData(object,bRedraw)object:オブジェクト
fnAddData(aobject,bRedraw)aobject:オブジェクトの配列
fnAdjustColumnSizing(bRedraw)bRedraw(bool):調整後再描画すかどうか(省略時true)oTable.fnAdjustColumnSizing(true)列幅を再計算する。
fnClearTable(bRedraw)bRedraw(bool):データクリア後再描画するかどうか(省略時true)oTable.fnClearTable(true)データ(tbody部分)をクリアする
fnClose(node)node:テーブルの行オブジェクトoTable.fnClose(oTable.fnGetNodes(0))
oTable.fnClose(this)
引数で指定した行をCloseする。fnOpenの逆の処理
fnDeleteRow(iRow,function,bRedraw)iRow:削除対象行番号(0開始)
oRow:削除するTR要素。fnGetNodesの戻り値
function:コールバック関数(省略時null)
bRedraw:削除時に再描画するかどうか(省略時true)
oTable.fnDeleteRow(0,null,true)指定したRow(行)を削除する
fnDeleteRow(oRow,function,bRedraw)oTable.fnDeleteRow(oTable.fnGetNodes(3))
fnDestroy(bWholeTable)bWholeTable:テーブル要素を削除するかどうか(省略時false)oTable.fnDestroy(false)テーブルの状態をDataTables初期化前に戻す
引数trueの場合、DOMからtable自体を削除する
fnDraw(bReFilterSort)bReFilterSort:フィルタとソートを再適用するかどうか(省略時true)oTable.fnDraw(true)テーブルを再描画する
fnFilter(sFilter,iRow,bRegex,bSFilter,bDisp,bInCase)sFilter:フィルタ文字列
iRow:検索対象列指定。省略時null(全ての列が対象)
bRegex:正規表現の有効or無効(省略時false)
bSFilter:スマートフィルタの有効or無効(省略時true)
bDisp:検索窓への表示するかどうか(省略時true)
bInCase:大文字小文字の区別。省略時true(区別しない)
oTable.fnFilter("hoge",null,false,true,false,true);フィルタを設定する。
fnGetData(iRow,iCol)iRow:行番号(0開始)
oRow:TR要素。fnGetNodesの戻り値
iCol:列番号(0開始)
oTable.fnGetData(1,3)指定したセルのデータを取得する
列番号を省略した場合指定行の全データ、列と行番号の両方を省略するとテーブルの全データが返される
fnGetData(oRow,iCol)oTable.fnGetData(this)
fnGetNodes(iRow)iRow:行番号(0開始)oTable.fnGetNodes(2)
oTable.fnGetNodes()
引数で指定した行番号(0開始)のTR要素を取得する。
引数を指定しない場合、全TR要素の配列を返す
fnGetPosition(node)node:TR,TH,TD要素のどれかfnGetPosition(oTable.fnGetNodes(1))
fnGetPosition($("td#hoge").get(0))
fnGetPosition(this)
引数で与えたオブジェクトの位置を返す
objectがTR要素の場合、行番号が返される(0開始)
TD/TH要素の場合、[行番号,列番号,列番号(非表示含まず)]の配列が返される(いずれも0開始)
fnIsOpen(node)node:TR要素oTable.fnIsOpen(oTable.fnGetNodes(0))
oTable.fnIsOpen(this)
引数で指定した行がfnOpenを呼んだ状態かどうかをチェックする
fnOpen(node)node:TR要素oTable.fnOpen(oTable.fnGetNodes(0));
oTable.fnOpen(this)
引数で指定した行の直ぐ下に1行挿入する。挿入される行はセルが横方向に全て連結している。
確認等の一時的なメッセージ表示を想定している機能
fnPageChangeページ移動
fnSetColumnVis(iCol,bVis,bRedraw)iCol:操作対象の列(0開始)
bVis:操作。true(表示),false(非表示)
bRedraw:操作後、再描画するかどうか(省略時true)
oTable.fnSetColumnVis(1,false,true);指定カラム(列)の表示/非表示切り替え
fnSettingsDataTablesの設定オブジェクトを取得する
fnSort引数で指定したソート処理を行う
fnSortListener
fnUpdate
fnVersionCheck(sVer)sVer:比較するバージョン文字列oTable.fnVersionCheck("1.9.0")DataTablesのバージョンが引数で指定したバージョン以上かどうかをチェックする
指定バージョン以上でtrue,未満でfalseを返す。

カラム(列)毎の設定

http://www.datatables.net/usage/columns
カラム別に異なるパラメータを設定するオプション。以下の2種類のプロパティの何れかで指定する。

  • aoColumnDefs
    指定したカラムのみにパラメータを設定する(全カラムを指定する事も可能)
    値はオブジェクトの配列で1つ1つは以下のような書式。列パラメータ及び値のペアは複数同時指定可能。最後の要素は常にaTargets
    { "列パラメータ名": "パラメータ値" [,"列パラメータ名": "パラメータ値" ...] , "aTargets": "対象列" }
    対象列のは以下の4種類を配列で指定
    文字列列に設定されたクラス名
    0以上の正の整数左から1列目を"0"、2列目を"1"…とする列指定
    -1以下の負の整数右から1列目を"-1"、2列目を"-2"…とする列指定
    "_all"全ての列を表す。
  • aoColumns
    全ての列にパラメータを設定する。配列の要素の数と列数は一致している必要がある。デフォルトから変更したくない列に対してはパラメータとして"null"を指定。
    "aoColumns": [ {1列目の設定},{2列目の設定}... ]

カラム(列)のパラメータ

パラメータ設定値デフォルト機能
aDataSort配列-ソート時に連動させるカラムを整数値の配列で指定する。(左端から0,1,2...)
先頭の値は適用させる列番号を指定する(じゃないとクリックした列以外でソートされるので混乱する)
asSorting配列[ 'asc', 'desc' ]デフォルトのソート方向&選択可能なソート方向の指定
1個だけ指定するとデフォルト且つ、その方向にのみソート可能
2個以上指定すると、先頭がデフォルトでクリックする度に順番にソート方向が設定される
例:"desc","asc","asc"とした場合、最初はdescでクリックする度にdesc→asc→asc→desc→(以下略)になる
aTargets配列-aoColumnDefsで適用対象列を指定する際に使用するパラメータ
(というか、それ以外には使い道無い)
bSearchablebooleantrueフィルタの対象列とするか否か
bSortablebooleantrueソート機能の有効無効
bUseRenderedbooleantrue廃止予定。mRender/mDataで代用
bVisiblebooleantrue列の表示/非表示
fnRender廃止予定。mRender/mDataで代用
fnCreatedCell関数-各セルを生成した時に呼ばれる関数を定義。4つの引数が与えられる
function (nTd, sData, oData, iRow, iCol)
  nTd:<TD>要素
  sData:セル内の値
  oData:所属する行の値全部
  iRow:行番号
  iCol:列番号
iDataSort整数現在ソート対象となっている列ソートを行う時に実際にクリックされた列とは異なる列をソートする場合に指定
非表示になっている列でソートさせる場合に使用
mDataProp--mDataに改名(1.9.2)
mData整数-対応させるDataSource(JSONの配列形式)の各列の添字。指定しない場合、0から順に各カラムに割り当てられる(デフォルト)
使用例→JavaScript/jQuery/DataTables/AjaxSource_jEditable
文字列-対応させるDataSource(JSONのハッシュ形式)のキー
配列&ハッシュ混在でネストしているような場合は追加でmRenderも設定
関数-DataTablesが各セルの値をset/get等をする際の関数function(data,type,val) を定義する
  data{array or object}:行の値全部
  type:セルに対する操作。'set','filter','display','type','sort',undefined
  undefinedが与えられた場合、未加工の生データを返すこと
  val:第2引数='set'の場合にセルに入力される値

静的と動的(DataSource=Ajax)で動きが異なるっぽい
動的なテーブルの場合、'set'より先にtype&val無し(dataのみ)で呼ばれてしまうのでdataから該当するカラムの値をreturnする必要がある
null-sDefaultContentを適用する。
mRender整数-mDataで指定した値が配列の場合にカラムに対応させる添字
ただし、ハッシュオブジェクトの配列の場合は↓の文字列指定を参照
文字列-mDataで指定した値がハッシュの場合にカラムに対応させるキーを指定
ハッシュオブジェクトの配列の場合
  1.["区切り文字"]."キー":指定したキーを区切り文字で連結したもの。区切り文字のデフォルトは","
  2."添字"."キー": 添字で指定した要素の"キー"に対応する値
関数-
sCellType'TD' or 'TH''TD'列に所属するセルの種類を指定する
sClass文字列null列のセルに対しCSSのクラスを定義する
sDefaultContent文字列nullセルの中身が空の場合に使われるデフォルト値
sName文字数" "(空文字)Server-side processing専用。列に対応させる値をJSON(ハッシュ形式)のキーを指定する。(mDataの文字列指定と同じ?)
sSortDataType文字列'std'ソート方法。セルの中身がtext,select,checkbox等の場合にそれらの状態でソートしたい場合に指定
sTitle文字列現在の列のTHセルの値列のタイトル
sType文字列自動認識ソートに使用する比較条件。"string","numeric","date","html"のどれか
sWidth文字列自動調整列の幅を明示的に指定する。指定できる文字列はCSSと同じ("20%","30px","10em" etc.)

サンプル

  • フィルタ無効,ページ無効,件数表示無効,1列目の幅80px指定,1列目のデフォルトソート方向降順かつ、ソート変更順序を降順→昇順→昇順
    $(document).ready(function(){
      $('#testtable_col').dataTable({
          "bFilter": false,
          "bInfo": false,
          "bPaginate": false,
          "aoColumnDefs" : [
                          { "sWidth" : "80px", "asSorting" : ['desc','asc','asc'], "aTargets" : [ 0 ] },
          ]
      });
    });
    
    No 名前 OS
    1 Firefox Linux,Windows,Mac
    2 IE Windows
    3 Google Chrome Linux,Windows,Mac
    4 Safari Mac,Windows
    5 Opera Linux,Windows,Mac

自動で挿入されるタグ

テーブルの外に自動で入るタグ。Paginationの部分だけは要カスタマイズ(特にtwo_buttonの場合)
http://datatables.net/styling/ids_classes

以下はtableのidが"ajaxtable"の場合の例


datatables_implicit_divs.png


  • 全体を包むDIV要素:id="テーブルID_wrapper", class="dataTables_wrapper"
  • 表示件数のプルダウンの部分:id="テーブルID_length", class="dataTables_length"
  • 検索窓の部分:id="テーブルID_filter", class="dataTables_filter"
  • 処理中に"Processing..."と表示される部分:id="テーブルID_processing", class="dataTables_processing"
    (※通常はhiddenになっているので見えない)
  • 現在の位置を表示する部分:id="テーブルID_info", class="dataTables_info"
  • Paginating情報については次項

Pagination関連タグ

初期化時に"sPaginationType"に設定するパラメータで以下の2種類がある。

  • two_button(デフォルト)
    前後のページに1ページずつ移動するボタンを表示。ページが少ない時用
  • full_numbers
    カレントページの前後、先頭&最終ページおよび前後のページへのリンクで表示。ページ数が多い時用

Ver1.8.xのtwo_buttonはアイコンを表示する位置に以下のDIVタグが生成されるので、CSSで背景画像を指定しておく(設定しておかないと何も表示されないので操作不能)。Ver1.9.xからはDIV→Aタグに変更、文字(Previous/Next)が表示されるように変更

  • Ver1.8.x
    -クリック可能時クリック不能時
    前ページ<div class="paginate_enabled_previous"><div class="paginate_disabled_previous">
    次ページ<div class="paginate_enabled_next"><div class="paginate_disabled_next">
    テーブル個別に指定する場合は上記DIVの親DIVのid(="テーブルID_paginate")を組み合わせて指定する。
    例:
    <div id="ajaxtable_paginate" class="dataTables_paginate paging_two_button">
      <div id="ajaxtable_previous" class="paginate_disabled_previous">
    
    ↓CSSの指定は以下
    div#ajaxtable_paginate div.paginate_disabled_previous {
            width: 20px;
            height: 20px;
            float: left;
            background-image : url("/img/left-disable.png");
    }
    

Server-side processing(AJAX)

http://www.datatables.net/usage/server-side

http://datatables.net/examples/data_sources/server_side.html

セレクタで指定したtable要素のtbody部分を書き換える。(theadは静的、tbodyは中身空でOK)

  • ブラウザからサーバへ送られるリクエスト
    名前意味
    iDisplayStart整数表示開始位置
    iDisplayLength整数表示行数
    iColumns整数カラムの数
    sSearch文字列フィルタフォームの文字列
    bEscapeRegex真偽値フィルタで正規表現が有効かどうか
    bSortable_(int)真偽値各列がソート可能に設定されているかどうか
    bSearchable_(int)真偽値各列が検索可能に設定されているかどうか
    sSearch_(int)文字列各列のフィルタフォームの文字列
    bEscapeRegex_(int)真偽値各列のフィルタフォームで正規表現が有効かどうか
    iSortingCols整数ソート中の列の数
    iSortCol_(int)整数各列が現在ソート中かどうか(データベース側の列との対応は自前で作る必要あり)
    sSortDir_(int)文字列各列のソート方向(desc,asc)
    sEcho文字列DataTablesがレンダリングに使う?
  • サーバからのリプライ
    名前意味
    iTotalRecords整数リプライに含まれるレコード数
    iTotalDisplayRecords整数フィルタ適用後の表示件数
    sEcho文字列リクエスト時に送られたsEchoと同じものが返される
    sColumns文字列列名をカンマ区切りにした文字列
    aaData2次配列テーブルの実データ
  • 関連初期パラメータ
    パラメータ設定値デフォルト機能
    bServerSide真偽値falseServer-side機能を有効/無効。使用する場合、"sAjaxSource"も指定必須
    fnServerData関数$.getJSONサーバからリプライを処理する関数
    sAjaxSource文字列(URL)NULLデータ受け取りに使用するURL

Last-modified: Tue, 12 Jun 2012 23:16:16 JST (1871d)