Using Font Awesome in free jqGrid 4.8

Introduction.

jqGrid contains many places where different jQuery UI icons will be used. The icons have the size 16x16px and are implemented as PNG files. As the result the icons looks not nice after scaling on modern devices having large DPI size.

Some times ago I hoped that jQuery UI will create soon vector based icons too. I posted the question and the feature request, but the situation with jQuery UI icons is still on the same level as before.

The state of the problem in jqGrid 4.7 and earlier version

The code of jqGrid 4.7 and earlier contains the names of the most of the icons fixed codded in the code. It makes relatively complex to replace the icons to non-jQuery UI icons. See jQuery.jqGrid.fontAwesome4.css and jQuery.jqGrid.fontAwesome4.js the plugin and the answer and this one which I posted on the stackoverflow. The plugin solution have many restrictions.

The solution of the problem implemented in free jqGrid 4.8

Many parts of the code of jqGrid was changed to remove fix codding of classes names of jQuery UI icons. Now there are configuration under $.jgrid.icons where two sets of icons are defined: $.jgrid.icons.jQueryUI and $.jgrid.icons.fontAwesome. Both objects $.jgrid.icons.jQueryUI and $.jgrid.icons.fontAwesome contains identical structure. jqGrid has new parameter iconSet which default value is "jQueryUI". So jqGrid get the names of used icons from the branch $.jgrid.icons.jQueryUI.

To use Font Awesome in free jqGrid 4.8 one needs

1. Include the CSS file with the fonts

I recommend to use URL from some CDN, for example from netdna.bootstrapcdn.com:

<link rel="stylesheet" 
    href="//netdna.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">

Alternatively one can download standalone version of all requeied files from here and include in your project. See the documentation for more details.

2. add iconSet: "fontAwesome" option to the grid.

The usage of Font Awesome is recommended way for usage of free jqGrid. The default value of iconSet is "jQueryUI" instead of "fontAwesome" only because one require to include Font Awesome to be able to use iconSet: "fontAwesome" option. Only because of the compatibility reasons we use "jQueryUI" as default value of iconSet, but we recommend to include font-awesome.min.css in your project and to use iconSet: "fontAwesome" option.

Customization of fontAwesome

Any from the default settings inside of $.jgrid.icons.jQueryUI and $.jgrid.icons.fontAwesome can be easy overwritten by using $.extend(true, ...); method. It's very important to use deep version of jQuery.extend (with the first true) option. I explain the problem on an example.

The standard iconSet of fontAwesome uses fa-trash-o icon (see here) on three places of the configuration:

{
	common: "fa",
	pager: {
		...
	},
	sort: {
		...
	},
	gridMinimize: {
		...
	},
	nav: {
		common: "fa-lg fa-fw",
		edit: "fa-pencil",
		add: "fa-plus",
		del: "fa-trash-o", // <-- here
		search: "fa-search",
		refresh: "fa-refresh",
		view: "fa-file-o",
		save: "fa-floppy-o",
		cancel: "fa-ban",
		newbutton: "fa-external-link"
	},
	actions: {
		common: "ui-state-default fa-fw",
		edit: "fa-pencil",
		del: "fa-trash-o", // <-- here
		save: "fa-floppy-o",
		cancel: "fa-ban"
	},
	form: {
		close: "fa-times",
		prev: "fa-caret-left",
		next: "fa-caret-right",
		save: "fa-floppy-o",
		undo: "fa-undo",
		del: "fa-trash-o", // <-- here
		cancel: "fa-ban"
	},
	search: {
		...
	},
	subgrid: {
		...
	},
	grouping: {
		...
	},
	treeGrid: {
		...
	}
}

If one would use non-deep version of $.extend:

$.extend($.jgrid.icons.fontAwesome, {
    nav: { del: "fa-times" },
    actions: { del: "fa-times" },
    form: { del: "fa-times" }
});

then one will overwrite all properties of nav, actions and form. So no other icons defined in the parts of settings will be displayed:

The usage of "deep" extend

$.extend(true, $.jgrid.icons.fontAwesome, {
    nav: { del: "fa-times" },
    actions: { del: "fa-times" },
    form: { del: "fa-times" }
});

will produce the correct results:

Creating of custom iconSet

One can easy create custom iconSet based on the standard icon set "fontAwesome". It's better in many situations as overwriting the standard set.

It's important to understand that every property under $.jgrid.icons will be interpreted by free jqGrid as the name of icon set and the usage of iconSet parameter with the name will choose the set. So one can do the following:

$.extend(true, $.jgrid.icons, {
        customFontAwesome: $.extend(true, {}, $.jgrid.icons.fontAwesome, {
                               nav: { del: "fa-times" },
                               actions: { del: "fa-times" },
                               form: { del: "fa-times" }
                           })
});

In the way we make deep copy of the $.jgrid.icons.fontAwesome object, replace tree del icons and save the results in customFontAwesome part of $.jgrid.icons. So one can use iconSet: "customFontAwesome" to apply the custom icon set in the grid.

One spacial can is implemented in jqGrid to simplify customization of sorting icons. The standard sorting icons consists from two icon. Both icons will be displayed at the same time, but one from the icons are displayed disabled. Free jqGrid allow to use one sorting icon only. The below example shows how to use fa-sort-amount-asc and fa-sort-amount-desc icons.

$.extend(true, $.jgrid, {
    icons: {
        myFontAwesome: $.extend(true, {}, $.jgrid.icons.fontAwesome, {
                           sort: {
                               common: "",                //remove "fa-lg"
                               asc: "fa-sort-amount-asc", //replace "fa-sort-asc"
                               desc: "fa-sort-amount-desc"//replace "fa-sort-desc"
                           }
                       })
    }
});

Additionally to iconSet: "myFontAwesome" one should use showOneSortIcon: true option of jqGrid and autoResizing: { widthOfVisiblePartOfSortIcon: 13 }.

The demo shows the results of such customization:

(The new sorting icon is marked with red square on the picture above)