Skip to content

# Grid Settings

## Grid Options

### Custom SQL Query

By default, when we define the `->table` property, it fetches all the possible columns of table. We can provide custom SQL query in `->select_command` property to pick columns available for grid. We can use complex multi-join sub-queries in it.

    $g->select_command = "SELECT i.id, invdate , c.name,
                            i.note, i.total, i.closed FROM invheader i
                            INNER JOIN clients c ON c.client_id = i.client_id";

### Grid Settings

You can use following options for `->set_options($opt)` function.

### Records per Page

Number of records to show on page

    $opt["rowNum"] = 10;

### Options to show in paging records

    $opt["rowList"] = array(10,20,30);

    // you can also set 'All' for all records
    $opt["rowList"] = array(10,20,30,'All');

    // empty array will hide dropdown
    $opt["rowList"] = array();

### Show Row numbers

To show row numbers before each records, and set that column's width

    $opt["rownumbers"] = true;
    $opt["rownumWidth"] = 30;

### Show Paging Buttons

To show/remove Paging navigation buttons

    $opt["pgbuttons"] = false;

### Set Initial Page

To set initial page (e.g. as page 2) of grid

    $opt["page"] = 2;

    // to set last page, set some big number
    $opt["page"] = 9999;

In order to use direct url of certain page, you can use $_GET. e.g. grid.php?p=2

    $opt["page"] = $_GET["p"];

### Show Paging text

To show/remove Paging text e.g. Page 1 of 10

    $opt["pgtext"] = null;

Enable or Disable total records text on grid

    $opt["viewrecords"] = true;

### Fit Columns

If set to true, and resizing the width of a column, the adjacent column (to the right) will resize so that the overall grid width is maintained (e.g., reducing the width of column 2 by 30px will increase the size of column 3 by 30px). In this case there is no horizontal scrolbar. Note: this option is not compatible with shrinkToFit option - i.e if shrinkToFit is set to false, forceFit is ignored.

    $opt["forceFit"] = true;

### Extend Columns to Grid Width

This option describes the type of calculation of the initial width of each column against with the width of the grid. If the value is true and the value in width option is set then: Every column width is scaled according to the defined option width.

    $opt["shrinkToFit"] = true;

### Column Layout

The autocolumn property split dialog fields in desired column layout. For e.g. for 2 column layout, set:

    $opt["autocolumn"] = 2;

### Autowidth

Expand grid to screen width

    $opt["autowidth"] = true;

### Resizable Grid

Show corner (lower-right) resizable option on grid

    $opt["resizable"] = true; // defaults to false

### Responsive Switch

Auto resize grid with browser resize

    $opt["autoresize"] = true; // defaults to false

### Initially Hidden Grid

If set to true the grid initially is hidden. The data is not loaded (no request is sent) and only the caption layer is shown. When the show/hide button is clicked the first time to show grid, the request is sent to the server, the data is loaded, and grid is shown. From this point we have a regular grid. This option has effect only if the caption property is not empty and the hidegrid property (see below) is set to true.

    $opt["hiddengrid"] = true;

### Show Hide Grid button

Enables or disables the show/hide grid button, which appears on the right side of the Caption layer. Takes effect only if the caption property is not an empty string.

    $opt["hidegrid"] = true;

### Grid Height

The height of the grid. Can be set as percentage or any valid measured value

    // set in pixels
    $opt["height"] = "400";

    // to remove vertical scroll bar
    $opt["height"] = "100%";

In order to make grid height based on parent container, use following. The `list1` should be replaced with your grid id.

    // in grid options
    $opt["loadComplete"] = "function(){
        var gid = 'list1';
        var h_offset = jQuery('.ui-jqgrid-titlebar').outerHeight()
                                +jQuery('.ui-jqgrid-hdiv').outerHeight()
                                +jQuery('.ui-jqgrid-toppager').outerHeight()
                                +jQuery('.ui-jqgrid-pager').outerHeight();

        jQuery('#'+gid).jqGrid('setGridHeight', jQuery('#gbox_'+gid).parent().innerHeight()-h_offset);
    }";

The parent container div must have fixed height (static or set dynamically)

    <div style="height:750px">
        <?php echo $out ?>
    </div>

### Grid Width

If this option is not set, the width of the grid is a sum of the widths of the columns defined

    $opt["width"] = "600";

### Loading Text

The text which appear when requesting and sorting data. Defaults to `Loading...`

    $opt["loadtext"] = "Loading...";

### Toolbar Position

This option defines the toolbar of the grid. This is array with two values in which the first value enables the toolbar and the second defines the position relative to body Layer. Possible values "top" or "bottom" or "both"

    $opt["toolbar"] = "top";

### Multiselect Records

Allow you to multi-select through checkboxes

    $opt["multiselect"] = true;

Allow you to multi-select through checkboxes and not whole row

    $opt["multiboxonly"] = true;

This parameter have sense only multiselect option is set to true. The possible values are: shiftKey, altKey, ctrlKey

    $opt["multikey"] = true;

### Alternate Row Color

Set a zebra-striped grid, boolean

    $opt["altRows"] = true;

### Initial Grid Sorting

Default sort grid by this field, Sort ASC or DESC

    $opt["sortname"] = 'id';
    $opt["sortorder"] = "desc";

To sort on multiple fields (at time of loading)

    // Date will be sorted desc, and ID asc.
    $opt["sortname"] = "date DESC,id";
    $opt["sortorder"] = "ASC";

To sort first click in DESC sequence, set:

    $opt["firstsortorder"] = "desc";

This will make SQL: ORDER BY date DESC,id ASC

### Grid Multi-Column Sorting

In case of multi sort when first time clicked the sort is asc (or descending) the next click sort to opposite direction the third click of the column remove the sorting from that column. Your first column must have similar records to see the change of second level sorting and onwards.

    $opt["multiSort"] = true;

### Grid Caption

This will set grid caption.

    $opt["caption"] = "Invoice Data";

In order to remove caption bar, set it to blank.

    $opt["caption"] = "";

### Lazy Loading of Pages

Creates dynamic scrolling grids. When enabled, the pager elements are disabled and we can use the vertical scrollbar to load data. useful for big datasets

    $opt["scroll"] = true;

### RTL or LTR

Makes grid right to left, for rtl languages e.g. arabic. Default is ltr

    $opt["direction"] = "rtl";

### Tooltips

Enable tooltips for icons and long text: true/false

    $opt["tooltip"] = true;

### Hotkeys

Enable or disable hotkeys for add, edit or delete operations: true/false It only work for first grid on page.

    $opt["hotkeys"] = true;

### Excel Mode Switch

Inline cell editing, like spreadsheet

    $opt["cellEdit"] = true;

### Reload after Edit

To reload whole grid after editing

    $opt["reloadedit"] = true;

### Display Pager on Top

Display Top Pager bar

    $opt["toppager"] = true;

### URL for Ajax calls

URL for grid page (for ajax calls), defaults to REQUEST_URI. It works with http & https. Used when passing extra querystring data, e.g.

    $opt["url"] = "http://domain/page.php?test=1";

### Grid Dialog Customizations

Set Add and Edit form & View dialog width. This can be used with combination of css customization of dialog forms.

    $opt["add_options"] = array('width'=>'420');
    $opt["edit_options"] = array('width'=>'420');
    $opt["view_options"] = array('width'=>'420');

Just like width in dialog options, you can also set other for e.g.

    $opt["add_options"] = array('width'=>'420',
                                "closeAfterAdd"=>true, // close dialog after add/edit
                                "clearAfterAdd"=>true, // clear fields after add/edit - default true
                                "top"=>"200", // absolute top position of dialog
                                "left"=>"200" // absolute left position of dialog
                                );

    $opt["edit_options"] = array('width'=>'420',
                                "closeAfterEdit"=>true, // close dialog after add/edit
                                "top"=>"200", // absolute top position of dialog
                                "left"=>"200" // absolute left position of dialog
                                );

To specify exact top/left position (as above), you need to set:

    $opt["form"]["position"] = "";
    $opt["add_options"]["jqModal"] = true;

On small screen devices when any column is hidden due to responsive behavior, by default a column with "..." text is added which opens view dialog showing all columns. To disable it you can set:

    $opt["view_options"]["rowButton"] = false;

### Dialog Title Customization

To change the title of Add Dialog

    $opt["add_options"]["addCaption"] = "Add Customer";

To change the title of Edit Dialog

    $opt["edit_options"]["editCaption"] = "Edit Customer";

To change the title of View Dialog

    $opt["view_options"]["caption"] = "View Customer";

### Dialog Success Message

You can also customize the success messages that appear after add/edit/del operations.

    $opt["add_options"]["success_msg"] = "Post added";
    $opt["edit_options"]["success_msg"] = "Post updated";
    $opt["delete_options"]["success_msg"] = "Post deleted";

    // for bulk editing
    $opt["edit_options"]["success_msg_bulk"] = "Post(s) updated";
    ...
    $g->set_options($opt);

To remove these success messages, you can set:

    $opt["add_options"]["afterSubmit"] = 'function(response) { return [true,""]; }';
    $opt["edit_options"]["afterSubmit"] = 'function(response) { return [true,""]; }';
    $opt["delete_options"]["afterSubmit"] = 'function(response) { return [true,""]; }';

### Dialog Submit Confirmation

This option work only in editing mode. If Set to true this option will work only when a submit button is clicked and if any data is changed in the form. If the data is changed a dilog message appear where the user is asked to confirm the changes or cancel it.

    $opt["edit_options"]["checkOnSubmit"] = true;

### Dialog Display Position

To Set Form to position on center of screen

    $opt["form"]["position"] = "center";

### Show Dialog Navigation buttons

Enable form Prev | Next record navigation

    $opt["form"]["nav"] = true;

Refer demos/appearance/dialog-layout.php for demo.

### Row Action Icons or Text

You can enable / disable the row action icons, by setting it true or false. It is enabled by default in latest version.

    $opt["actionicon"] = false;
    ...
    $g->set_options($opt);

### Global Column Setting

If we want to set some column property across all columns of grid, without individually setting them with column definition, We can use `cmTemplate` property.

    $opt["shrinkToFit"] = false;
    $opt["autowidth"] = true;
    $opt["cmTemplate"] = array("width"=>"400");
    ...
    $g->set_options($opt);

Above will set each column width to 400.

### Grid Actions

We can also switch actions to enable or disable them on grid. It is controlled by `->set_actions()` function.

Possible values are `true` or `false`.

Operations | Description
--- | ---
`add` | Enable / Disable add operation on grid. Defaults to `true`.
`edit` | Enable / Disable edit operation on grid. Defaults to `true`.
`bulkedit` | Enable / Disable bulk edit operation on grid. Defaults to `false`.
`delete` | Enable / Disable delete operation on grid. Defaults to `true`.
`view` | Enable / Disable view operation on grid. Defaults to `true`.
`clone` | Enable / Disable clone operation on grid. Defaults to `false`.
`rowactions` | Enable / Disable inline edit/del/save option. Defaults to `true`.
`export` | Enable / Disable export to excel option. Defaults to `false`.
`import` | Enable / Disable import data option. Defaults to `false`.
`autofilter` | Enable / Disable autofilter toolbar for search on top. Defaults to `true`.
`showhidecolumns` | Enable / Disable button to hide certain columns from client side. Defaults to `true`.
`inlineadd` | Enable / Disable button to perform insertion inline. Defaults to `false`.
`search` | Search property can have 3 values, `simple`, `advance` or `false` to hide.

Code:

    $g->set_actions(array(
                            "add"=>true,
                            "edit"=>true,
                            "clone"=>true,
                            "bulkedit"=>true,
                            "delete"=>true,
                            "view"=>true,
                            "rowactions"=>true,
                            "export"=>true,
                            "import"=>true,
                            "autofilter" => true,
                            "search" => "simple",
                            "inlineadd" => true,
                            "showhidecolumns" => true
                        )
                    );