Previous topic

Gauge

Next topic

ListSwitcher

DOCUMENTATION
Last updated 18-May-2016

Grid

With the Grid widget you can display a table with data and a toolbar. It also allows you to present active tabulated data, namely, paging navigation, filtering, sorting, and row selection.

Test Grid in browser

See JS API for all methods and properties

../../../../../_images/grid.png

Toolbar

A Toolbar is defined using the Toolbar widget (more detailed information see in Toolbar).

You can add a Toolbar as a child element. Depending on the way your widgets are declared, a child element is defined as follows:

  • a nested array (in case of declaration with help of the loader);
  • using the addChild method (in case of programmatic declaration);
  • a hierarchy of widgets corresponding to the hierarchy of DOMNodes (declarative syntax).

More detailed information on widget declaration see in Widget Declaration.

For all methods and properties see JS API

You can prohibit clicking a toolbar button if no record is selected in the table. To do this, you need to specify one of to properties whwn declaring aps/ToolbarButton:

  • requireSingleItem

    if this property value is set to true, the button will be enabled for clicking when a single row is selected in the table.

  • requireItems

    if this property value is set to true, the button will be enabled for clicking only when one or several rows are selected in the table.

Tabulated data

The appearance and functionality of the widget related to tabulated data is determined by the following settings: columns, rows selection mode, paging navigation, and information messages.

Data for a table are defined with help of the Store component (For details see Model API), which may be specified through the store property or using the setStore method.

Columns

The settings for table columns are specified by the columns property and described by an array of objects. Each object describes one column and it may contain:

  • name property

    Contains a column header.

  • field property

    It contains a full name of a data object property which needs to be displayed in this column. Nesting of properties is specified by a “dot” symbol. For example: “hardware.cpu.number”.

  • sortable property

    Determines an ability to sort by this column. The default value is true.

  • filter property

    It is used if you need to set an ability to perform filtering by this column. It must contain an object which may have the following properties:

    • title

      Text that will be displayed on the filtering toolbar next to the entry field.

    • options

      If this property is not specified, the filtering toolbar displays a simple TextBox. If specified - it displays a drop-down list. It is specified by an array of objects describing selection options in the drop-down list. For details see Select. The first option of the drop-down list is always the “any” item, which is added automatically.

    • value

      If this property is specified, a filter by this value will be applied during table generation.

    Example:

    {
        "options":  [{value: 'bla', label: 'bla'}],
        "title":    "ID"
    }
    
  • renderCell method

    It is used for displaying complex pictures in table cells. If this method is not defined for a column, then a cell displays as usual text the data from a data object field specified by the field property. If this method is defined, then when rendering a cell in this column the renderCell method will be called. The description of the entire current row will be passed to the method as the first argument, and the data from the data object field specified by the field property - as the second argument. The value returned by the method will be inserted into the table cell. The following values are supported: DOMNode, widget or HTML.

    Example:

    renderCell: function(row, data){
       if(!data) return "";
    
       switch(data.status)
       {
           case 0:
              return "<div class='b-indent'>
                          <span class='b-indent-icon'>
                             <img alt=\"\" src=\"subscription-status-ok.png\">
                          </span>
                          <a href=\"javascript:void(0)\">" + data.text +
                          "</a>
                          <span class='hint hint-info'>
                             <span>
                                (?)
                             </span>
                          </span>
                      </div>";
           case 1:
              return "<div class='b-indent status-overused'>
                          <span class='b-indent-icon'>
                             <img alt=\"\" src=\"subscription-status-suspended.png\">
                          </span>
                          <a href=\"javascript:void(0)\">" + data.text +
                          "</a>
                          <span class='hint hint-info'>
                             <span>
                                (?)
                             </span>
                          </span>
                      </div>";
       }
    }
    
  • visible property

    If this property value is set to false, the current column will not display in the table. However, the data from this column will be included into the first argument of the renderCell method of other columns.

  • escapeHTML property

    Escapes resulting HTML source. You can disable the feature by setting escapeHTML to false in the desired column. As a result, the renderCell method will process HTML source.

Rows selection

The selectionMode property defines the mode for rows selection in a table. The property may take on two values:

  • “multiple”

    It can be possible to select several rows simultaneously.

  • “single”

    Only a single row can be selected simultaneously.

The selectionArray property is provided for operations with the selected rows. An object of the “dojox/mvc/StatefulArray” type is stored in this property and all changes in the collection of the selected rows are completely synchronized with its values. To trace strings highlighted by the user, you can simply trace changes in selectionArray by means of a method watchElements:

grid.get("selectionArray").watchElements(function(index, removals, adds){
    console.log(
        "Grid changed",
        this /* selectionArray */,
        removals /* ids of removed rows */,
        adds /* ids of added rows */
    );
});

So you can programmatically select a row in a table by simply adding it into this object.

Likewise, removing a row from the object will remove visual highlighting of the row. If you want that right after a table is created some rows to be selected, simply pass a StatefulArray with the required set of row ids to the widget constructor.

Warning

When you select some records in a grid, they are placed to selectionArray. If you delete the selected records from the grid, you need to delete them explicitly from the selectionArray as well. You can do it as follows:

selectionArray.splice(arr.indexOf("a9885415-09fd-493a-a867-f656368c52f5"), 1);

In this example, the indexOf accepts the object ID as specified by the data source. The splice function accepts the index of the first string and the number of strings that must be removed.

You always can get the selectionArray object with help of the get method, but you will be able to define your object only when creating an aps/Grid widget. For operations with selected rows thereafter use the object passed to the constructor or received using the get method.

If working with the data model is not suitable for you for some reason, you can always get an associative array in which the keys will be the ids of all selected rows by calling the get method with the “selection” parameter.

Example:

RUN DEMO

    require([
      "aps/Memory",
      "aps/Container",
      "aps/Grid",
      "dojox/mvc/StatefulArray",
      "aps/PageContainer",
      "aps/ready!"
    ], function(Memory, Container, Grid, StatefulArray, PageContainer){
        "use strict";
        /* Array **data** must be initialized here */
var store = new Memory({ data: data, idProperty: "aps.id" });

        var layoutSimpleGrid = [   {"name": "ID",          "field": "aps.id"},
                      {"name": "Description", "field": "description"},
                      {"name": "Name",        "field": "name"},
                      {"name": "OS",          "field": "platform.os.name"}
        ];

        var page = new PageContainer({}, "simpleGrid");

        var con = new Container({ title: "Simple Grid" });

        var selectionArray = new StatefulArray([]);

        var simpleGrid = new Grid({
          columns:          layoutSimpleGrid,
          store:            store,
          selectionMode:    "multiple",
          selectionArray:   selectionArray
        });

        con.addChild(simpleGrid);
        page.addChild(con);

        page.startup();

        setTimeout(function(){ selectionArray.push("d58bdae7-ec62-4125-9666-c5215fc5d744"); }, 2000);
    });

Row sorting

With the sort property you can perform programmatic sorting of table rows. The sorting format is described by an object containing two properties:

  • attribute

    Contains a field name (not a column name!) by which the sorting is performed.

  • Descending

    Describes the sorting type in the boolean format.

To define the sorting start during widget creation, specify a property value when calling the constructor.

To cancel all sortings, you must specify a null array as a value of the sort property.

Example:

RUN DEMO

    require([
      "aps/Memory",
      "aps/Container",
      "aps/Grid",
      "dojox/mvc/StatefulArray",
      "aps/PageContainer",
      "aps/ready!"
    ], function(Memory, Container, Grid, StatefulArray, PageContainer){
        "use strict";
var store = new Memory({ data: data, idProperty: "aps.id" });

        var layoutSimpleGrid = [   {"name": "ID",          "field": "aps.id"},
                      {"name": "Description", "field": "description"},
                      {"name": "Name",        "field": "name"},
                      {"name": "OS",          "field": "platform.os.name"}
        ];

        var page = new PageContainer({}, "simpleGrid");

        var con = new Container({ title: "Simple Grid" });

        var selectionArray = new StatefulArray([]);

        var simpleGrid = new Grid({
          columns:          layoutSimpleGrid,
          store:            store,
          selectionMode:    "multiple",
          selectionArray:   selectionArray,
          sort:             { attribute: "platform.os.name", descending: true }
        });

        con.addChild(simpleGrid);
        page.addChild(con);

        page.startup();

        setTimeout(function(){ simpleGrid.set("sort", { attribute: "name", descending: true }); }, 2000);
    });

Paging navigation

The widget provides you an ability to paginate data. To navigate between pages, the widget displays navigation buttons, as well as numbers of pages nearest to the current page above and below the table with data.

The following properties are available for controlling the behavior of paging navigation:

  • showPaging

    If this property is set to false, then the paging controls are not shown. The default value of this property is true.

  • rowsPerPage

    The number of rows per page.

  • pageSizeOptions

    An array of available choices for selecting the number of rows per page. To provide an ability to display all rows at once, you need to specify as an array item “GRID_UNLIMITED”. The default values of this property are 10, 25, 100, “GRID_UNLIMITED”].

  • currentPage

    The number of the current page.

Information messages

With this widget you can set up output of the following information:

  • a message about successful completion of data loading;

    It is specified by the loadMessage property. The message outputs only if it’s defined.

  • a message about an error during data loading;

    It is specified by the errorMessage property. The message outputs only if it’s defined.

  • text in place of a table with data if an empty set of data is received from the server;

    It is specified by the noEntriesFound property. The default value is “no items found”.

If an error occurs while receiving table data from the source, the widget’s errorHandler() method will be called. The error object will be passed to the method as the argument.

Refreshing

Table data can be refreshed using the refresh() method. As a result of calling this method, the widget will repeat a request to the server for the table data of the current page taking into account all current settings: applied filters, sorting, etc. The method does not take any arguments.

Translation

In the dictionary, you can add translation of default text values contained in a widget by using one of the following options:

  • Translation by a common key independent of widget context. For example, the key might be ‘Please wait’.
  • Translation valid for the specified context where the widget is located. The context name must be presented in the key name in accordance with the schema ‘CommonKey_Context’. For example, if the context is *VPSedit, the key would by ‘Please wait_VPSedit’.
Key Context Default value
No item(s) found apsGrid No item(s) found
Number of entries per page: apsGrid Number of entries per page:
item(s) total apsGrid item(s) total
Search apsGrid Search
Reset Search apsGrid Reset Search

Saving Session State

The aps/Grid widget stores the number of records and sorting configuration used in the current session. When you open the same screen next time, the saved session state is restored. If you need to open the screen always in a predefined state, you should create needed settings in the screen code by means of the set method.

Examples

  • simple example

    RUN DEMO

        require([
          "aps/Memory",
          "aps/Container",
          "aps/Grid",
          "aps/PageContainer",
          "aps/ready!"
        ], function(Memory, Container, Grid, PageContainer){
            "use strict";
    var store = new Memory({ data: data, idProperty: "aps.id" });
    
            var layoutSimpleGrid = [{"name": "ID",          "field": "aps.id"},
                        {"name": "Description", "field": "description"},
                        {"name": "Name",        "field": "name"},
                        {
                          "name": "Memory",
                          "field": "hardware.memory",
                          "sortable": false
                        },
                        {"name": "Diskspace",   "field": "hardware.diskspace"},
                        {"name": "CPU Number",  "field": "hardware.cpu.number"},
                        {"name": "OS",          "field": "platform.os.name"}
            ];
    
            var page = new PageContainer({}, "simpleGrid");
    
            var con = new Container({ title: "Simple Grid" });
    
            var simpleGrid = new Grid({
                columns:       layoutSimpleGrid,
                store:         store
            });
    
            con.addChild(simpleGrid);
            page.addChild(con);
    
            page.startup();
        });
    
  • table with a toolbar

    RUN DEMO

        require([
          "aps/Memory",
          "aps/Container",
          "aps/Grid",
          "aps/Toolbar",
          "aps/ToolbarButton",
          "aps/PageContainer",
          "aps/ready!"
        ], function(Memory, Container, Grid, Toolbar, ToolbarButton, PageContainer){
            "use strict";
    var store = new Memory({ data: data, idProperty: "aps.id" });
    
            var layoutSimpleGrid = [{"name": "ID",          "field": "aps.id"},
                        {"name": "Description", "field": "description"},
                        {"name": "Name",        "field": "name"},
                        {
                          "name": "Memory",
                          "field": "hardware.memory",
                          "sortable": false
                        },
                        {"name": "Diskspace",   "field": "hardware.diskspace"},
                        {"name": "CPU Number",  "field": "hardware.cpu.number"},
                        {"name": "OS",          "field": "platform.os.name"}
            ];
    
            var page = new PageContainer({}, "gridToolbar");
    
            var con = new Container({ title: "Grid with toolbar" });
    
            var toolbar = new Toolbar();
    
            toolbar.addChild(new ToolbarButton({
               id:         "buttonAddNewCustomer",
               label:      "Add New Server",
               iconClass:  "sb-add-new-server",
               onClick:    function(){ alert("hello!"); }
            }));
    
            toolbar.addChild(new ToolbarButton({
               id:         "buttonExportCustomers",
               label:      "Export configuration",
               iconClass:  "sb-export",
               onClick:    function(){ alert("hello!"); }
            }));
    
            var gridWithToolbar = new Grid({
               columns:    layoutSimpleGrid,
               store:      store
            });
    
            gridWithToolbar.addChild(toolbar);
    
            con.addChild(gridWithToolbar);
            page.addChild(con);
    
            page.startup();
        });
    
  • table with a filtering toolbar

    RUN DEMO

        require(["aps/Memory", "aps/Container", "aps/Grid", "aps/PageContainer", "aps/ready!"],
          function(Memory, Container, Grid, PageContainer){
            "use strict";
    var store = new Memory({ data: data, idProperty: "aps.id" });
            var page = new PageContainer({}, "gridSearch");
            var con = new Container({ title: "Grid with search" });
            var layout = [{
                      "name":     "ID",
                      "field":    "aps.id",
                      "filter":   { "title": "ID" }
                  }, {
                      "name":     "Description",
                      "field":    "description"
                  }, {
                      "name":     "Name",
                      "field":    "name"
                  }, {
                      "name":     "Memory",
                      "field":    "hardware.memory"
                  }, {
                      "name":     "Diskspace",
                      "field":    "hardware.diskspace"
                  }, {
                      "name":     "CPU Number",
                      "field":    "hardware.cpu.number"
                  }, {
                      "name":     "OS",
                      "field":    "platform.os.name",
                      "filter":   {
                             "options":  [ { value: 'Linux', label: 'Linux'},
                                     { value: 'Windows', label: 'Windows'} ],
                             "title":    "OS"
                      }
            }];
    
            var gridWithSearch = new Grid({
               columns:       layout,
               store:         store
            });
    
            con.addChild(gridWithSearch);
            page.addChild(con);
    
            page.startup();
        });
    
  • table with an ability to select several rows at the same time

    RUN DEMO

        require([
            "aps/Memory",
            "aps/Container",
            "aps/Grid",
            "aps/PageContainer",
            "aps/ready!"
          ], function(Memory, Container, Grid, PageContainer){
            "use strict";
    var store = new Memory({ data: data, idProperty: "aps.id" });
    
            var layoutSimpleGrid = [{"name": "ID",          "field": "aps.id"},
                                    {"name": "Description", "field": "description"},
                                    {"name": "Name",        "field": "name"},
                                    {"name": "Memory",      "field": "hardware.memory",      "sortable": false},
                                    {"name": "Diskspace",   "field": "hardware.diskspace"},
                                    {"name": "CPU Number",  "field": "hardware.cpu.number"},
                                    {"name": "OS",          "field": "platform.os.name"}
            ];
    
            var page = new PageContainer({}, "gridMultipleSelectionDiv");
    
            var con = new Container({ title: "Grid with multiple selection" });
    
            var gridMultipleSelection = new Grid({
               columns:          layoutSimpleGrid,
               selectionMode:    "multiple",
               store:            store
            });
    
            con.addChild(gridMultipleSelection);
            page.addChild(con);
    
            page.startup();
        });
    
  • table with a number of rows per page that differs from default values

    RUN DEMO

        require([
          "aps/Memory",
          "aps/Container",
          "aps/Grid",
          "aps/PageContainer",
          "aps/ready!"
        ], function(Memory, Container, Grid, PageContainer){
            "use strict";
    var store = new Memory({ data: data, idProperty: "aps.id" });
    
            var layoutSimpleGrid = [{"name": "ID",          "field": "aps.id"},
                        {"name": "Description", "field": "description"},
                        {"name": "Name",        "field": "name"},
                        {
                          "name": "Memory",
                          "field": "hardware.memory",
                          "sortable": false
                        },
                        {"name": "Diskspace",   "field": "hardware.diskspace"},
                        {"name": "CPU Number",  "field": "hardware.cpu.number"},
                        {"name": "OS",          "field": "platform.os.name"}
            ];
    
            var page = new PageContainer({}, "gridChangeRowCountDiv");
    
            var con = new Container({ title: "Change row count" });
    
            var gridChangeRowCount = new Grid({
               rowsPerPage:   25,
               columns:       layoutSimpleGrid,
               store:         store
            });
    
            con.addChild(gridChangeRowCount);
            page.addChild(con);
    
            page.startup();
        });
    
  • declaration using the loader

    RUN DEMO

        require(["aps/Memory", "aps/load", "aps/ready!"],
          function(Memory, load){
            "use strict";
    var store = new Memory({ data: data, idProperty: "aps.id" });
    
            load(["aps/PageContainer", [
                  ["aps/Container", { title: "load from JSON" },
                    [[ "aps/Grid", {
                       columns: [  { name: "ID",             field: "aps.id" },
                             { name: "myRenderCell",   field: "hardware.memory" }],
                       store:   store
                    },
                    [[ "aps/Toolbar",
                       [[ "aps/ToolbarButton", {
                          label: "Add New Server",
                          iconClass:  "sb-add-new-server"
                        }],
                        [ "aps/ToolbarButton", {
                          label: "Export configuration",
                          iconClass:  "sb-export"
                        }]]
                    ]]
            ]]]]]);
        });
    
  • declarative definition

    RUN DEMO

      <script>
        require(["aps/Memory", "dojo/parser", "aps/ready!"],
          function(Memory, parser){
            "use strict";
    window.store = new Memory({ data: data, idProperty: "aps.id" });
    
            parser.parse();
        });
      </script>
    
    
    
      <div dojoType="aps/PageContainer">
        <div dojoType="aps/Container" data-dojo-props="title: 'parse grid'">
          <div id="gridParse" data-dojo-type="aps/Grid" data-dojo-props="store: store" >
            <div dojoType="aps/Toolbar">
              <div
                id="buttonAddNewCustomerHTML"
                dojoType="aps/ToolbarButton"
                data-dojo-props="iconClass: 'sb-add-new-server'"
              >
                Add New Server
              </div>
              <div
                dojoType="aps/ToolbarButton"
                label="Export configuration"
                data-dojo-props="iconClass: 'sb-export'"
              >
                <script type="dojo/on" data-dojo-event="click">
                  alert("ura!");
                </script>
              </div>
            </div>
            <table>
              <tr>
                <th
                  data-dgrid-column="{'field': 'aps.id', 'title': 'Id', type: 'resourceName'}"
                ></th>
                <th
                  data-dgrid-column="{'field': 'hardware.memory', 'label': 'Ram' }"
                ></th>
                <th data-dgrid-column="{'field': 'hardware.diskspace', 'sortable': 'false'}">
                  Diskspace
                </th>
                <th field="hardware.cpu.number">
                  CPU
                </th>
                <th field="platform.os.name">
                  OS and Technology
                </th>
              </tr>
            </table>
          </div>
        </div>
      </div>
    
Gauge