Documentation

CraigStuntz edited this page Sep 14, 2010 · 3 revisions

Installation

Develop your site using jqGrid as usual. The plugin won’t work until your grid works! Now it’s time to add browser history support.

  1. Get the latest jQuery.BBQ and add a reference to the js file to your page.
  2. Add a reference to grid.history.js (from this project) to your page.

Your page might contain HTML like this:

    <script type="text/javascript" src="jquery-1.4.2.min.js"></script>
    <script type="text/javascript" src="jquery.ba-bbq.min.js"></script>
    <script type="text/javascript" src="grid.locale-en.js"></script>
    <script type="text/javascript" src="jquery.jqGrid.min.js"></script>
    <script type="text/javascript" src="MyStuff.js"></script>
    <script type="text/javascript" src="grid.history.js"></script>
</body>
</html>

Opting In to the History Plugin

Go to where you create your grid; you’ll have JavaScript like this:

 $("#someTable").jqGrid({ //...

Change it to:

 $("#someTable").jqGridHistory({ //...

Now your grid should have back and forward button support for the following parameters:

  1. Current page index
  2. Number of rows per page
  3. Sort index (field)
  4. Sort direction (asc or desc)

Still not working? Look at the demo site.

How It Works

The grid history plug-in essentially does two things:

  1. After the grid is loaded, it changes the fragment portion of the URI (sometimes called the hash) to store certain grid options, if those options are not at the default value.
  2. When the hash changes, it updates the grid, if necessary.

Let’s examine (1) in more detail. Go look at the demo page for the history plug-in. Notice that the URI is:

http://craigstuntz.github.com/jqGrid/Demo.html

Now click the “next page” button at the bottom of the right-hand (“With History”) grid. The URI will change to:

http://craigstuntz.github.com/jqGrid/Demo.html#page=2

Because the grid’s page option is no longer at the default value of 1, it is stored in the fragment/hash of the URI. Now click the Back button in your browser. The URI will change back to the original value. Modern browsers will, at this point, fire a hashchange JavaScript event. BBQ will simulate this for older browsers. The plugin will notice that the page value in the fragment has changed (in this case, it disappeared), change the options on your grid, and trigger a reload of the grid data.

Deep Linking

Beyond support for the Back and Forward buttons in your browser, the history plugin allows “deep linking” into your data. For example, the link above will take you directly to the second page of the right-hand grid in the demo, rather than defaulting to the first page, as usual.

This feature is especially useful in an edit scenario. Let’s say you’re on page 3 in a grid, and you click a link to edit the current record. Using the standard Post/Redirect/Get pattern, the edit page would like to redirect you back to where you came from after a successful HTTP POST. By including the page number in the URI, this is now possible.

Customization

How to Persist Additional Grid Options

Let’s say that you get your grid’s data from a server method which accepts a query string parameter called “foo” that determines which data is returned. You use custom UI controls to set “foo”, much like paging, and you insert the value of “foo” into the grid’s postData object . Obviously, this plugin doesn’t have any support for your custom “foo” parameter, but you can add it yourself. When you create your grid, add a history section to your options:

        grid.jqGridHistory({
            colNames: [ //...
            colModel: [{ //...
            history: {
                persist: $.jgrid.history.persist.concat("postData.foo")
            }, //...

Here we are telling the history plugin to track changes to postData.foo in addition to the default options it normally tracks.

As this implies, you can change what is tracked globally (for all grids created subsequently) as follows:

$.jgrid.history.persist = $.jgrid.history.persist.concat("postData.foo");

Supporting Multiple Grids on One Page

Obviously, using a URI fragment like this:

#page=1

… won’t work for multiple grids on one page, because the plugin would not know which grid to update when the fragment changes. If you need to support browser history for multiple grids on the same page, set the hashPrefix option on the grid’s history property:

        grid.jqGridHistory({
            colNames: [ //...
            colModel: [{ //...
            history: {
                hashPrefix: "someGrid."
            }, //...

Now the fragment/hash will be of the form:

pre. #someGrid.page=1&someOtherGrid.page=3

There is also a global hashPrefix, which you can optionally set:

$.jgrid.history.gloabalHashPrefix = "history."

If you heavily use the hash/fragment of your URI, then you can use this global prefixes a kind of “namespace” to prevent the grid history plugin from interfering with the rest of your code. Also, you can rewrite the $.jgrid.history.hashPrefix function for even more customizability.

Keeping URIs Clean

In order to keep your URIs as clean as possible, grid option values are not placed into the fragment/hash unless they are set to a value which is not the default.

The “default value” is generally presumed to be whatever value you set when you created your grid. That is generally true. But you might create a grid with a non-default value for some option. In that case, you can tell the history plug-in which value to use this the “default.”

        grid.jqGridHistory({
            colNames: [ //...
            colModel: [{ //...
            history: {
                defaults: {
                    "postData.foo": "bar"
                },
                persist: $.jgrid.history.persist.concat("postData.foo")
            }, //...

Customizing Grid Property Getting and Setting

There are a few grid properties which cannot be read or set via the grid’s options or setGridParam techniques (e.g., width, search, custom plugins). If you want to persist these properties/settings, then you can replace the implementation of $jgrid.[get|set]PropertyValue. See the source code for more information on this.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.