New style of usage options of internal methods

Introduction

jqGrid have many methods, which are specific for editing mode, searching, filtering and so on. Especially newcomer have problem to understand where exactly the options should be inserted.

Just two examples. The first one is in the usage of form editing. For example the options to Submit the results of editing by Enter and to close the editing dialog by Esc can be found in the documentation of options the method editGridRow. So one would like to use savekey: [true, 13], closeOnEscape: true, closeAfterEdit: true, closeAfterAdd: true. The problem is just it's not so easy for a newcomer to find the exact place where to place the options. Additionally it can be required to use the same options in multiple places of the grid.

Let us one want to use the described above options savekey: [true, 13], closeOnEscape: true, closeAfterEdit: true, closeAfterAdd: true for form editing in the grid. To make the user easy to use form editing we want to start editing in tree ways: by adding navigator icons by navGrid, by adding inline buttons by formatter: "actions" and by calling the method editGridRow directly inside of ondblClickRow callback. The corresponding code will be like

$("#grid").jqGrid({
    ...
    colModel: [
        {name: "act", formatter: "actions", width: 55, align: "center", fixed: true,
            resizable: false, sortable: false, search: false, editable: false, viewable: false,
            formatoptions: {
                editformbutton: true,
                editOptions: {
                    savekey: [true, 13],
                    closeOnEscape: true,
                    closeAfterEdit: true
            }} },
        ...
    ],
    pager: "#pager",
    ondblClickRow: function (rowid) {
        $(this).jqGrid("editGridRow", rowid, {
            savekey: [true, 13],
            closeOnEscape: true,
            closeAfterEdit: true
        });
    }
}).jqGrid("navGrid", "#pager", {},
    { // edit options
        savekey: [true, 13],
        closeOnEscape: true,
        closeAfterEdit: true
    },
    { // add options
        savekey: [true, 13],
        closeOnEscape: true,
        closeAfterAdd: true
    });

One sees duplicates in the code. By introducing variable for editing options one can reduce the size of the code:

var myFormEditOpt = {
        savekey: [true, 13],
        closeOnEscape: true,
        closeAfterAdd: true,
        closeAfterEdit: true
    };
$("#grid").jqGrid({
    ...
    colModel: [
        {name: "act", formatter: "actions", width: 55, align: "center", fixed: true,
            resizable: false, sortable: false, search: false, editable: false, viewable: false,
            formatoptions: {
                editformbutton: true,
                editOptions: myFormEditOpt} },
        ...
    ],
    pager: "#pager",
    ondblClickRow: function (rowid) {
        $(this).jqGrid("editGridRow", rowid, myFormEditOpt);
    }
}).jqGrid("navGrid", "#pager", {search: false}, myFormEditOpt, myFormEditOpt);

The code will be smaller and easier to maintain, but there are at least two small problems:

1. The variable myFormEditOpt with form editing options of the grid is not associated to the grid.
2. One still have to know the exact place of action formatter and the options of navGrid where the options needed be inserted.

Solution of the problem in free jqGrid 4.8

The most internal methods of jqGrid are modified so that there could get the default values of all options and callbacks from some jqGrid option. For example the method editGridRow allows to specify the options under formEditing option of jqGrid:

$("#grid").jqGrid({
    ...
    colModel: [
        {name: "act", template: "actions",
            formatoptions: { editformbutton: true } },
        ...
    ],
    pager: true,
    formEditing: {
        savekey: [true, 13],
        closeOnEscape: true,
        closeAfterAdd: true,
        closeAfterEdit: true
    },
    ondblClickRow: function (rowid) {
        $(this).jqGrid("editGridRow", rowid);
    }
}).jqGrid("navGrid", {search: false});

The code will be shorter and more easy to use. The options specified in formEditing will be used in all direct and indirect calls of editGridRow in the grid. Additionally jqGrid allows to use pager: true to generate the pager div with unique id automatically and the method navGrid just uses all pagers defined in the grid to place the navigator bar. Such small changes makes the code a little shorter too.

The specify options of navGrid one can uses new navOptions option of jqGrid.

The option actionsNavOptions allows to specify options options of formatter: "actions". So that above code could be rewritten as

$("#grid").jqGrid({
    ...
    colModel: [
        {name: "act", template: "actions" },
        ...
    ],
    pager: true,
    formEditing: {
        savekey: [true, 13],
        closeOnEscape: true,
        closeAfterAdd: true,
        closeAfterEdit: true
    },
    actionsNavOptions: { editformbutton: true },
    navOptions: { search: false },
    ondblClickRow: function (rowid) {
        $(this).jqGrid("editGridRow", rowid);
    }
}).jqGrid("navGrid");

It's your choice whether to use actionsNavOptions or formatoptions.

In the same way formViewing and formDeleting allows to specify options of View and Delete forms and searching to specify options of Searching dialog of Searching toolbar.

The new jqGrid option inlineEditing allows to specify parameters of inline editing. So to set keys: true one can just use

$("#grid").jqGrid({
    ...
    colModel: [
        {name: "act", template: "actions" },
        ...
    ],
    pager: true,
    inlineEditing: { keys: true }
}).jqGrid("inlineNav");

instead of

$("#grid").jqGrid({
    ...
    colModel: [
        {name: "act", formatter: "actions", width: 55, align: "center", fixed: true,
            resizable: false, sortable: false, search: false, editable: false, viewable: false,
            formatoptions: { keys: true } },
        ...
    ],
    pager: "#pager"
}).jqGrid("navGrid", "#pager", {add: false, edit: false, del: false, search: false, refresh: false}).
.jqGrid("inlineNav", "#pager", {editParams: {keys: true}, addParams: {addRowParams: {keys: true}} });

One sees that the code in free jqGrid 4.8 is shorter. Some unneeded technical details like creating of empty navigator bar by call of navGrid will be done automatically. The pager option is also optional for inlineNav.