The datagrid component

• Introduction
• Example
• Properties
• Methods
• Events
• Customising the datagrid with CSS
• Integrating the datagrid with forms
• Frequently asked questions

Introduction

The datagrid component is new to RGraph in version 6.21 and is a very easy way to show data to your users. It's very customisable with standard css and extensible with a whole host of events and api calls that are available. It can be quickly integrated into your pages and forms so it allows you to quickly and easily build your website and standardise the look of data tables across all of your pages.

Example

Here's a basic example of the datagrid with resizable columns which can be sorted by clicking on the column headers. There's a button underneath the datagrid which resets the column widths back to the default by using an api call.

<script src="RGraph.common.core.js" ></script>
<script src="RGraph.common.datagrid.js" ></script>


<script>
    data = [
        ['Richard','Monday',  124],
        ['Jane',  'Tuesday',    152],
        ['Lucy',  'Wednesday',    98],
        ['Jerry', 'Thursday',95],
        ['Alex',  'Friday',     103],
        ['Freddy','Saturday',     111],
        ['Peter', 'Sunday',    56],
    ];
    
    myGrid = new RGraph.Datagrid({
        id: 'myGrid',
        data: data,
        options: {
            columnsHeaders: ['Name','Day of week','Amount'],
            columnsResizable: true,
            columnsResizablePersistent: true,
            columnsUnitsPre: ['','','<b>&pound;'],
            columnsUnitsPost: ['','','</b>'],
            columnsHTML:[,,true]
        }
    }).draw();
</script>

Properties

You can use these properties to control how the datagrid appears. You can set them by including them in the options section of the configuration as shown above.

• Column properties
• Sorting properties
• Editable properties
• Selectable rows properties
• Miscellaneous properties

columnsFormatter: function (opt)
{
    console.log(opt);
    return opt.number;

},

var f1 = function (opt)
{
    // This is the formatter function for the THIRD column
    console.log(opt);
    return opt.number;
}

var f2 = function (opt)
{
    // This is the formatter function for the SIXTH column
    console.log(opt);
    return opt.number;
}

//...

columnsFormatter: [,,f1,,,f2]

// An example of a custom sort function which sorts
// the rows by the last character in the cell.
// Because an array encapsulates the function -
// this function will only be used for the first
// column. Normal sorting is used for the other
// columns.
// 
// @param object obj       The chart object
// @param number column    A number representing the column index
//                         (starts at zero).
// @param number direction The direction to be sorted in. 1
//                         means ascending and -1 means
//                         descending.
// @param mixed  a         The first value to compare.
// @param mixed  b         The second value to compare.
// 
sortableCompare: [function (obj, column, direction, a, b)
{
    a = a.substr(-1).charCodeAt(0);
    b = b.substr(-1).charCodeAt(0);

    return direction > 0 ? a - b : b - a;
}]

.on('editcomplete', function (obj)
{
    var meta = RGraph.Registry.get('cell-edit-meta');
    var data = obj.getData();
    
    console.log(data[meta.row]);
});

style: [
    'th:nth-child(2) {font-weight: bold; color: red;background-color: #ddd;}',
    'td:nth-child(2) {font-weight: bold; color: red;background-color: #ddd;}'
]

style: [
    'div#myGrid table.rgraph-datagrid th:nth-child(2) {font-weight: bold; color: red;background-color: #ddd;}',
    'div#myGrid table.rgraph-datagrid td:nth-child(2) {font-weight: bold; color: red;background-color: #ddd;}'
]

Methods

You can use these functions to do various things allowing you to control and manipulate the datagrid.

obj.find('Jerry');              // Find the first instance of the word Jerry
obj.find('Jerry', {all: true}); // Find all instances of the word Jerry
obj.find(/^jer/i);              // Regular expression find
obj.find(/^jer/i, {all: true}); // Use a Regular expression and find all of the matches

obj.find('Jerry', {all: true}); // These two functions are the same
obj.findAll('Jerry');           // These two functions are the same

.on('draw', function (obj)
{
    // Put your code here. Depending on the event, you can sometimes
    // get meta information from the RGraph registry. See the list
    // of event types below for more detail.
});

Events

These events are available to enable you to integrate your own code with the datagrid. You can use the on function to attach them to your chart as is shown in the example below.

<script>
    new RGraph.Datagrid({
        id: 'myGrid',
        ata: [
            ['15th March 2006',    'Jane',   19],
            ['8th August 2006',    'Freddy'],23,
            ['21st September 2006','Rod',    41],
            ['5th December 2006',  'Peter',  12],
            ['21st February 2007', 'Gary',   24],
            ['24th March 2007',    'Jamie',  37]
        ],
        options: {
            columnsHeaders: ['Date','Competitor','Score']
        }
    }).on('draw', function (obj) {
        alert('Hello!');
    }).draw();
</script>

.on('rowclick', function (obj)
{
    var meta = RGraph.Registry.get('row-click-meta');

    var object  = meta.object; // The RGraph object
    var event   = meta.event;  // The standard event object
    var element = meta.element;// THe HTML element
    var html    = meta.html;   // The innerHTML of the row
    var row     = meta.row;    // The index of the row
    var value   = meta.value;  // All of the values of the row
})

.on('cellclick', function (obj)
{
    var meta = RGraph.Registry.get('cell-click-meta');

    var object  = meta.object; // The RGraph object
    var event   = meta.event;  // The standard event object
    var element = meta.element;// THe HTML element
    var html    = meta.html;   // The innerHTML of the cell
    var row     = meta.row;    // The index of the row
    var column  = meta.column; // The index of the column
    var value   = meta.value;  // The value of the cell
})

.on('beforeedit', function (obj)
{
    var meta = RGraph.Registry.get('cell-edit-meta');

    var object  = meta.object; // The RGraph object
    var value   = meta.value;  // The value of the cell
    var cell    = meta.cell;   // The HTML  cell
    var row     = meta.row;    // The index of the row
    var column  = meta.column; // The index of the column
})

.on('beforeedit', function (obj)
{
    var meta = RGraph.Registry.get('cell-edit-meta');

    var object  = meta.object; // The RGraph object
    var value   = meta.value;  // The value of the cell that's about to be saved
    var cell    = meta.cell;   // The HTML  cell
    var row     = meta.row;    // The index of the row
    var column  = meta.column; // The index of the column
})

.on('afteredit', function (obj)
{
    var meta = RGraph.Registry.get('cell-edit-meta');

    var object  = meta.object; // The RGraph object
    var value   = meta.value;  // The value of the cell that's about to be saved
    var cell    = meta.cell;   // The HTML  cell
    var row     = meta.row;    // The index of the row
    var column  = meta.column; // The index of the column
})

.on('editcancelled', function (obj)
{
    var meta = RGraph.Registry.get('cell-edit-meta');

    var object  = meta.object; // The RGraph object
    var value   = meta.value;  // The value of the cell that's about to be saved
    var cell    = meta.cell;   // The HTML  cell
    var row     = meta.row;    // The index of the row
    var column  = meta.column; // The index of the column
})

Customising the datagrid with CSS

At its most basic level, the datagrid is an html table utilising standard tags. You can see the structure in the FAQ question below. This means that you can use standard css selectors to change the way that things look to the user. For example:

<style>
    /*
    * Remember that you may need to use the !important modifier
    * if you're overriding the default styles.
    */
    div#myGrid table.rgraph-datagrid tr.rgraph-datagrid-row-hover {
        background-color: #00f1 !important;
    }




    /*
    * If you have multiple datagrids on a page then you can also do
    * this to provide the row highlighting for all of them in one
    * go.
    */
    .rgraph-datagrid-row-hover {
        background-color: #00f1 !important;
    }
</style>

Or if you want to highlight a particular row you can make use of the css nth-child pseudo-selector like this:

<style>
        /* Highlight the third row (in CSS the counting begins at 1) */
        div#myGrid table.rgraph-datagrid tr:nth-child(3) {
            background-color: yellow !important;
        }
    </style>

Using the style property to set CSS

As well as setting your css the normal way - using style html tags - you can also use the style property of the datagrid. Here's an example:

style: [
    'tr:nth-child(2) td:nth-child(2):hover {color: red; font-weight: bold;}',
    // ...
],

You shouldn't worry too much about naming clashes though because, if not present, the rule is made more specific by adding the id of the div tag to it. So the above rule is actually transformed into the following:

style: [
    'div#myGrid table.rgraph-datagrid tr:nth-child(2) td:nth-child(2):hover {color: red; font-weight: bold;}',
    // ...
],

Integrating the datagrid with forms

Integrating the datagrid with a form on your webpage can make it very useful when presenting the user with a choice and getting an answer from them. Consider the following example:

This is the html code for this datagrid. Notice that it sits within a form tag and there's a submit button just below where the datagrid will be rendered.

<form action="datagrid.html" method="post">
    <div style="margin-left: auto; margin-right: auto; width: 600px">
        <div style="width: 600px" id="myGrid"></div>
        <input type="submit" name="submit" value="Update" style="font-size: 20pt; cursor: pointer"/>
    </div>
</form>

And here's the code for the datagrid. Notice that the columnsHTML option has been given and is set to an array that contains just one number - 0 This means that the first column (the numbering begins at zero) is allowed to have html in it. So a checkbox will be shown and not the html tag for the checkbox.

<script>
    data = [
        ['<input type="checkbox" name="players[]" value="15" style="transform: scale(1.5)" />', 'Mary','1st October 1985','Winner by default'],
        ['<input type="checkbox" name="players[]" value="2" style="transform: scale(1.5)" />', 'Freddy','27th July 1980','3rd place - runner up'],
        ['<input type="checkbox" name="players[]" value="43" style="transform: scale(1.5)" />', 'Jamie','6th March 1967','2nd place - finalist'],
        ['<input type="checkbox" name="players[]" value="21" style="transform: scale(1.5)" />', 'Gary','7th April 1982','1st place - winner'],
    ];
    myGrid = new RGraph.Datagrid({
        id: 'myGrid',
        data: data,
        options: {
            columnsHeaders: ['', 'Person','Date of event','Final position'],
            columnsHTML: [0],
            columnsWidths: [30],
            sortable: false
        }
    }).draw();

    /////////////////////////////////////////////////////////////
    // The following code is OPTIONAL - it allows you to click //
    // the entire row to select and unselect the checkbox as   //
    // well as the checkbox itself.                            //
    /////////////////////////////////////////////////////////////

    //(function ()
    //{
    //    // 
    //    // Get all of the rows in the datagrid and add click event
    //    // listeners that check the checkbox in that row.
    //    //
    //    var els  = document.querySelectorAll('div#myGrid1 table tbody tr');
    //   
    //    for (var i=0; i<els.length; ++i) {
    //   
    //        els[i].addEventListener('click', function (e)
    //        {
    //            var tr    = e.currentTarget;
    //            var input = tr.querySelector('input[type=checkbox]');
    //       
    //            input.checked = !input.checked;
    //        }, false);
    //   
    //        //
    //        // If the checkbox is clicked on directly - cancel any
    //        // propagation up the event tree.
    //        //
    //        var el  = els[i].querySelector('input[type=checkbox]');
    //        
    //        el.addEventListener('click', function (e)
    //        {
    //            e.stopPropagation();
    //        }, false);
    //    }
    //})();
</script>

But what if you didn't want the first column to have the same styling as the rest of the table? Well, you could do that with a snippet of css, utilising the nth-child pseudo-selector and moving the submit button to the right a small amount accordingly - so that it lines up with, what is now, the main table. Here's the updated example along with the necessary css code:

The necessary css markup:

<style>
    div#myGrid-container input[type=submit]{
        margin-left: 30px;
    }

    div#myGrid input[type=checkbox] {
        cursor: pointer;
    }
    
    div#myGrid th:nth-child(1n+2) {
        background-color: black !important;
        color: white !important;
    }
    
    div#myGrid thead th:nth-child(1),
    div#myGrid tbody td:nth-child(1) {
        background-color: white !important;
    }
    
    div#myGrid thead th:nth-child(1) div,
    div#myGrid tbody td:nth-child(1) div {
        border: none !important;
    }
</style>

The html markup and the javascript code is the same as the example above - so you can use that.

Adding a "select all" button to your datagrid

If you're adding checkboxes to your datagrid then one thing that you may want is an easy way for your users to check all of those checkboxes at once. This is quite easy and just requires a little javascript function like this:

<script>
    //
    // A function that facilitates the easy selection of all of
    // the checkboxes on the datagrid in one go.
    //
    function selectAll ()
    {
        var checkboxes = document.querySelectorAll('div#myGrid input[type=checkbox]');
        
        checkboxes.forEach((value,key,array) =>
        {
            value.checked = !window.allCheckboxesCheckedState;
        });
        
        window.allCheckboxesCheckedState = !window.allCheckboxesCheckedState;
    }
</script>

<button onclick="selectAll()">Select all</button>

Frequently asked questions

• What is the structure of the resulting table?
• How do I make the rows highlighted when they're hovered over?
• How can I add scrolling to my datagrid?
• How do I hide my ID column?
• How do I make my checkboxes toggle when the row is clicked?

What is the structure of the resulting table?

The RGraph datagrid produces a standard html table element with the following structure:

<div id="myGrid">
    <table class="rgraph-datagrid">
        
        <!-- Column headers -->
        <thead>
            <tr>
                <th><div class="rgraph-datagrid-cell-content">Name</div></th>
                <th><div class="rgraph-datagrid-cell-content">Day</div></th>
                <th><div class="rgraph-datagrid-cell-content">Amount</div></th>
            </tr>
        </thead>
        
        <!-- Data rows -->
        <tbody>
        
            <!-- First row -->
            <tr>
                <td><div class="rgraph-datagrid-cell-content">Richard</div></td>
                <td><div class="rgraph-datagrid-cell-content">Monday</div></td>
                <td><div class="rgraph-datagrid-cell-content">23</div></td>
            </tr>

            <!-- Second row -->
            <tr>
                <td><div class="rgraph-datagrid-cell-content">David</div></td>
                <td><div class="rgraph-datagrid-cell-content">Tuesday</div></td>
                <td><div class="rgraph-datagrid-cell-content">46</div></td>
            </tr>
        </tbody>
        
        <!-- Column footers -->
        <tfoot>
            <tr>
                <td><div class="rgraph-datagrid-cell-content"></div></td>
                <td><div class="rgraph-datagrid-cell-content"></div></td>
                <td><div class="rgraph-datagrid-cell-content"></div></td>
            </tr>
        </tfoot>
    </table>
</div>

How do I make the rows highlighted when they're hovered over?

You can do this by adding a small bit of css to your page. To be specific to a single datagrid you could add this:

<style>
    /* Add row highlighting to a single datagrid */
    div#myGrid table.rgraph-datagrid tr.rgraph-datagrid-row-hover {
        background-color: #00f1 !important;
    }
</style>

Or to add row highlighting to all of the datagrid instances on the page you can use a css: selector that's a broader match like this:

<style>
    /* Add row highlighting to all of the datagrids on the page */
    .rgraph-datagrid-row-hover {
        background-color: #00f1 !important;
    }
</style>

How can I add scrolling to my datagrid?

If you have a lot of data that you want to show in the datagrid but don't want it to take up a large amount of vertical space then there is something that you can do and that's to add scrolling to the datagrid body. This is demonstrated by the datagrid that's shown above and you can also see a demo in the download archive. It's done by adding a small amount of css to your page and that is as follows:

<style>
    div#myGrid table.rgraph-datagrid {
        display: block;
    }

    div#myGrid table.rgraph-datagrid tbody {
        max-height: 150px;
        overflow-x:hidden;
        overflow-y:auto;
        display: block;
        width: 100%;
    }
</style>

How do I hide the ID column on my grid?

What if you have a set of data and the first column is an id that perhaps is coming from your database? Maybe it's just not practical to not select that column in the first place but you don't want that information displayed to the user. Well instead of messing with the data you can just hide that column with a little css. Here's the datagrid before the css has been applied with the id column still visible.

And here's the css that hides the first column. It also centers the datagrid in its container (there's a tiny bit of space left on either side and this is because of the now missing column).

<style>
    div#myGrid table {
        margin-left: auto;
        margin-right: auto;
    }

    div#myGrid table.rgraph-datagrid tr :where(th, td):nth-child(1) {
        display: none;
    }
</style>

And here's the resulting datagrid which has now got the first column hidden.

<script>
        myGrid6 = new RGraph.Datagrid({
            id: 'myGrid6',
            data: [
                [435, 'Richard','Web developer',25000],
                [884, 'Jane', 'Customer Service Operative',18000],
                [463,'Martha','Sales executive',23000],
                [135,'Janet','Office admin',21000]
            ],
            options: {
                columnsHeaders: ['','Name','Occupation','Salary'],
                
                // Reduce the size of the first column
                columnsWidths: [5],
                
                style: [
                    // Center the datagrid in its div
                    'table {margin-left: auto;margin-right: auto;}',
                    
                    // Hide the first column (which has the ID numbers in)
                    'tr :where(td, th):nth-child(1) {display: none;}'
                    
                    'tr th div {background-color: black; color: white;}',
                    'tr th span {color: white;}'
                ]
            }
        }).draw();
    </script>

How do I make my checkboxes toggle when the row is clicked?

The datagrid example that's shown above shows you how to do this and has an example of the necessary code beneath the datagrid. The commented-out code (in green) is the javascript that's necessary to add to your page.