概略

更新日: 2018-09-07

w2gridはローカルデータやリモートデータを使ってグリッドを生成することができます。 gridはw2uiの中で最も複雑で柔軟性のある機能です。グリッドのデータ検索、列のソート、インライン編集等を定義して利用できます。

デモ1

gridの簡単な使い方は以下の通りです。必要最低限のHTML、JavaScriptで表示しています。以下の例ではローカルでデータを使っており、サーバのデータは取得していません。

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" type="text/css" href="http://w2ui.com/src/w2ui-1.4.min.css" />
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
    <script type="text/javascript" src="http://w2ui.com/src/w2ui-1.4.min.js"></script>
</head>
<body>
    <div id="myGrid" style="height: 450px"></div>
</body>
<script>
$('#myGrid').w2grid({ 
    name   : 'myGrid',
    columns: [
        { field: 'fname', caption: 'First Name', size: '30%' },
        { field: 'lname', caption: 'Last Name', size: '30%' },
        { field: 'email', caption: 'Email', size: '40%' },
        { field: 'sdate', caption: 'Start Date', size: '120px' },
    ],
    records: [
        { recid: 1, fname: 'John', lname: 'Doe', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 2, fname: 'Stuart', lname: 'Motzart', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 3, fname: 'Jin', lname: 'Franson', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 4, fname: 'Susan', lname: 'Ottie', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 5, fname: 'Kelly', lname: 'Silver', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 6, fname: 'Francis', lname: 'Gatos', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 7, fname: 'Mark', lname: 'Welldo', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 8, fname: 'Thomas', lname: 'Bahh', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 9, fname: 'Sergei', lname: 'Rachmaninov', email: 'jdoe@gmail.com', sdate: '4/3/2012' }
    ]
});
</script>
</html>

デモ2

次の例はデモ1と似ていますが、サーバからデータを取得するパターンです。サーバに"data/records.json"が存在し、JSON形式のデータを返すことを前提としています。

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" type="text/css" href="http://w2ui.com/src/w2ui-1.4.min.css" />
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
    <script type="text/javascript" src="http://w2ui.com/src/w2ui-1.4.min.js"></script>
</head>
<body>
    <div id="myGrid" style="height: 450px"></div>
</body>
<script>
$('#myGrid').w2grid({
    name   : 'myGrid',
    url    : 'data/records.json',
    columns: [
        { field: 'fname', caption: 'First Name', size: '30%' },
        { field: 'lname', caption: 'Last Name', size: '30%' },
        { field: 'email', caption: 'Email', size: '40%' },
        { field: 'sdate', caption: 'Start Date', size: '120px' },
    ]
});
</script>
</html>

データ構造

グリッドはHTTP POSTでリクエストを送信することでサーバと通信します。各リクエストで全てのパラメータを送信されるわけではありませんので注意して下さい。ユーザーが検索や、ソート等を実行しなければ、そのパラメータは送信されない可能性があります。.postDataプロパティで定義されたパラメータは全て送信されます。

{
    "cmd"         : "get-records",
    "limit"       : 50,
    "offset"      : 0,
    "selected"    : [1, 2],
    "searchLogic" : "AND",
    "search": [
        { "field": "fname", "type": "text", "value": "vit", "operator": "is" },
        { "field": "age", "type": "int", "value": [10, 20], "operator": "between" }
    ],
    "sort": [
        { "field": "fname", "direction": "ASC" },
        { "field": "Lname", "direction": "DESC" }
    ]
}

上記の場合、送信パラメータは以下のようになります。

&cmd: get-records
&limit: 50
&offset: 0
&selected[]: 1
&selected[]: 2
&searchLogic: AND
&search[0][field]: fname
&search[0][type]: text
&search[0][operator]: is
&search[0][value]: vit
&search[1][field]: age
&search[1][type]: int
&search[1][operator]: between
&search[1][value][]: 10
&search[1][value][]: 20
&sort[0][field]: fname
&sort[0][direction]: asc
&sort[1][field]: lname
&sort[1][direction]: desc

サーバから取得したデータは以下のようなJSON形式のデータが必要です。 JSON構造はjQuery.extendによってグリッドにマージされます。これにより、サーバから返ってきたプロパティを適用することができます。

{
    "status"  : "success",
    "total"   : 36,
    "records" : [
        { "recid": 1, "field-1": "value-1", ... "field-N": "value-N" },
        ...
        { "recid": N, "field-1": "value-1", ... "field-N": "value-N" }
    ]
}

サーバがJSONでないデータ(例えばXML)を返す場合でも、.onRequestメソッドや、.onLoadメソッドを使ってデータ変換することができます。もしサーバサイドからエラーを返したい場合は以下のように指定します。

{
    "status"  : "error",
    "message" : "Error Message"
}

レコード削除

いくつかのレコードを選択してツールバーの「delete」ボタンをクリックしたり、.delete()メソッドを呼んだ時のように、レコード削除をリクエストする場合、送信パラメータは以下のように指定します。

{
    "cmd"      : "delete-records",
    "selected" : [1, 2],
}

削除に直接関係の無い他のフィールドも送信します。もしエラーが無ければ、レスポンスは以下のように指定します。

{
    "status" : "success"
}

そして、レスポンスを受けたらすぐに、レコードを更新するための2番目のリクエストを送信します。もしサーバから以下のレスポンスが来た場合、グリッドはエラーを表示します。レコードは更新しません。

{
    "status"  : "error",
    "message" : "Error Message"
}

レコード保存

インライン編集をオンにすると、データ変更をすることができます。ユーザーがデータを編集して「Save」ボタンをクリックしたら、以下のパラメータを送信します。

{
    "cmd"     : "save-records",
    "changes" : [],
}

変更箇所は変更されたレコードのキーと値を持った配列です。もしエラーが無ければ、レスポンスは以下のように指定します。

{
    "status": "success"
}

もし以下のレスポンスが来た場合、エラーを表示します。

{
    "status"  : "error",
    "message" : "Error Message"
}

このコンテンツはvitmalinaによるw2ui.gridドキュメントを翻訳/改変したものです。