improvement of formatter: "showlink"

Introduction. Predefined formatter: "showlink"

jqGrid contains predefined formatter: "showlink" which allows to construct anchor HTML element <a> based on the input value of the cell and some additional options specified in formatoptions. The following options can be included in formatoptions: baseLinkUrl, showAction, addParam, target, idName. The old versions of jqGrid (till 4.7) allows to construct the <a> element in the following form (see here):

"<a " + (op.target ? "target=" + op.target : "") +
    ' href="' + (op.baseLinkUrl + op.showAction + '?' +
        op.idName + '=' + opts.rowId + op.addParam) + '">' +
    cellval + "</a>"

The state of the problem in jqGrid 4.7 and earlier version

One can see some problems in the construct. I include just some examples of the existing problem:

1. The value of href is static. One can't place rowid, for example, inside of URL to access RESTfull services.
2. Symbols ? and = will be always added.
3. There are no way to encode the inserted values by calling of encodeURIComponent function for example. So one can have problems if rowids contains special characters.
4. The value cellval will be displayed to the user as it be. One have no way to construct dynamic URL for example and to place some another text inside of <a>...</a>.
5. One can't use the values from another columns to construct the URL or the text displayed in the anchor.

Because of the restrictions one have to use frequently custom formatters to generate the link instead of usage formatter: "showlink".

The improvements of formatter: "showlink" implemented in free jqGrid 4.8

New version of formatter: "showlink" supports of course all old options formatoptions properties, but the properties can be functions. All the callback functions get the object parameter, which contains the information, which can be helpful to construct the results. The parameter have the following properties:

• cellValue - the cell value
• rowid - the rowid
• rowData - object which contains information all columns of the row. It's the same object which one have as parameter of custom formatter.
• options - object which contains formatoptions. One can for example include some custom properties in formatoptions (which can be different for different columns, for example). One can use the options inside of your implementations.

Additionally one can specify null as the value of idName option. If idName is null and addParam are empty string, null or false then ? and any symbols after ? (like =) will be added. It allows to construct pure URL without any URL parameters.

One more small feature: the idName and rowid will be inserted in the URL encoded using encodeURIComponent.

Additional options of formatoptions:

• hrefDefaultValue with default value "#". It will be inserted as the value of href if both baseLinkUrl and showAction are empty.
• rowId function which can be used to build id value other as the rowid. The rowid must be unique, so one build in some situations rowid based on some native ids of different tables of the database, by usage "_" for example between the ids. The function rowId can get the required part of from the rowid which one want to use as id parameter in the URL.

All callbacks should return strings with exception addParam which can return object which properties build parameters of the URL.

EXAMPLES: Let us the input data for the column are strings "client1", "client2", ... Ids of the rows are values like 10, 20, 30, ...

{ id: 10,  name: "client1",  amount: 0,      closed: false,  ship_via: "TN" },
{ id: 20,  name: "client2",  amount: 351.75, closed: true,   ship_via: "FE" },
{ id: 20,  name: "client2",  amount: 350,    closed: false,  ship_via: "DH" },
...

Below are some settings of formatoptions and the resulting anchors which generates formatter: "showlink":

1. One uses

formatoptions: {baseLinkUrl: "/myApp/Clients"}

without any additional options. It places anchors like

<a href="/myApp/Clients?id=10">Client1</a>
<a href="/myApp/Clients?id=20">Client2</a>

2. One uses

formatoptions: {
    baseLinkUrl: function: (options) {
        return "/myApp/Clients/" + encodeURIComponent(options.rowid);
    },
    idName: null
}

It generates anchors like

<a href="/myApp/Clients/10">Client1</a>
<a href="/myApp/Clients/20">Client2</a>

3. One uses

formatoptions: {
    baseLinkUrl: function: (options) {
        return "/myApp/Clients/" + encodeURIComponent(options.rowid);
    },
    idName: null,
    addParam: function (options) {
        var rowData = options.rowData;
        return $.param({
            amount: rowData.amount,
            shipped: rowData.ship_via
        });
    },
    cellValue: function (options) {
        return '<span title="click to edit">Editing '+ options.cellValue + '</span>';
    }
}

It generates anchors like

<a href="/myApp/Clients/10?amount=0&shipped=TN"><span title="click to edit">Editing Client1</span></a>
<a href="/myApp/Clients/20?amount=351.75&shipped=FE"><span title="click to edit">Editing Client2</span></a>

4. One can remove $.param call from the implementation od addParam callback from the previous example

addParam: function (options) {
    var rowData = options.rowData;
    return {
        amount: rowData.amount,
        shipped: rowData.ship_via
    };
}

jqGrid will generate identical code as before. The advantage of the form is in the case when one use non-empty idName. The code

formatoptions: {
    baseLinkUrl: function: (options) {
        return "/myApp/Clients";
    },
    addParam: function (options) {
        var rowData = options.rowData;
        return $.param({
            amount: rowData.amount,
            shipped: rowData.ship_via
        });
    }
}

will generates the following anchors

<a href="/myApp/Clients?id=10amount=0&shipped=TN">Client1</a>
<a href="/myApp/Clients?id=20amount=351.75&shipped=FE">Client2</a>

where there is no & symbol between id value and the name of the next parameters amount. To fix the problem one have to use either returns object instead of string

addParam: function (options) {
    var rowData = options.rowData;
    return {
        amount: rowData.amount,
        shipped: rowData.ship_via
    };
}

and jqGrid calls $.param(...) with the object itself and pretend results with ampersand (if idName is not null) or to use

addParam: function (options) {
    var rowData = options.rowData;
    return "&" + $.param({
        amount: rowData.amount,
        shipped: rowData.ship_via
    });
}

OnClick callback should also described here