An overview of the RGraph datagrid object

`

Video transcript

Here's the transcript of the video that you can see above. It talks about the datagrid object in RGraph that you can use to easily show data tables and standardise them across your entire website.

In this video I'm going to talk about the RGraph datagrid component that was initially added in version 6.21 and then significantly improved and extended in version 6.22. It's an easy way to show data tables to your users. It's very customisable with standard CSS and extensible with a raft of events and API calls that are available. It can be quickly and easily 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.

`

Here's an example of the datagrid with the search feature enabled, resizable columns (which by default are persistent - though you can change that if you wish) and paging. All of these can be disabled if they're not required. It also shows how you can have HTML in the columns if you want - though this is not the default and is something that you'll need to enable. The button below the datagrid can be used to reset the column sizes back to the defaults, demonstrating one of the API calls that are available. Everything is documented on the datagrid documentation page.

And below the datagrid, there's the code that goes into generating it. The two RGraph libraries are included, the DIV container is defined and then the code that generates the datagrid is defined.

The style of the datagrid object code is much the same as the other RGraph objects, mainly being key/value properties. The style property is interesting though, as it allows you to specify CSS for the datagrid in much the same way as you'd write regular CSS. Though here, the ID of the container DIV (that you give when you create the datagrid) is prepended to each rule in order to help prevent any naming clashes.

There are lots more options that are available to you, so all you have to do is take a look through the API documentation.

`

Lets have a brief overview of those options now. The first set of properties that we have are the row-focused properties and the first of those is the rowsIDs property. This can be used to give each row its own unique ID. This ID is then given to various events via the meta information that's given to the event. You can also get this metadata from the RGraph registry if you prefer. There's an example of doing so in the datagrid API documentation.

You can set the datagrid to check either a checkbox or select a radio button in the row when it's clicked. A common thing to allow users to have easier interaction with your datagrid. There can be multiple checkboxes or radio buttons in each row.

The column properties allow you to specify headers or footers for the datagrid - the headers are what you click on to facilitate sorting and if you don't give any headers, then the datagrid will not be sortable. The headers sit within a THEAD HTML tag and similarly, the footers sit within a TFOOT tag.

The widths of the columns can be given with the columnsWidths property. Normally, you might not want to specify the column widths - particularly if you're allowing the columns to be resized. But if you're showing something like an ID number in the first column, then you might want this column to be narrower than the others.

The columnsHTML property allows you to use HTML in the datagrid, which is not permitted by default. By doing this you could show an image in a column for example. This property can be a range of column indexes. See the documentation for details on column ranges - there's a section dedicated to explaining them.

The columnsCssClass property allows you to add your own CSS class to a column (both the TH and the TD tags). This can help you when styling your datagrid. This property can be a string or an array of strings. If it's an array, then the CSS class is added to the corresponding columns TH or TD tag.

The columnsFormatted property controls whether a particular column has numerical formatting applied to it. If it does, then the columnsUnitsPre, columnsUnitsPost, columnsPoint, columnsThousand and columnsDecimals properties are all used together in order to format the column in question as you specify.

The columnsFormatter property can be used to format both numerical and string-based values and present them for display to the user. For numeric values, you can format it in the same way that you would any other number - perhaps adding commas or adding a postfix to the number so that it's not as large and is more readable. For string type values, the value could be a timestamp that came out of a database and looks like this: 2008-10-02T09:56:23, but you could format it and make the value far more readable so that it looks like this instead: 9:56am, 2nd October 2008

The columnsResizable options allow you to adjust the sizing of the columns as you see fit. Ellipses are shown when the column is too small for the data within it. By default, the column sizes aren't persistent as a result of resizing but you can change this with the columnsResizablePersistent option. You can also disable resizing for a column if you want, using the columnsResizableHandles property (this can be a range of column indexes).

And the last columns option is the columnsDescriptions property, which allows you to add ARIA descriptions to each column if you want, which enhance the accessibility of the datagrid.

Then we come to the sorting options for the datagrid, which allow you to control how the sort functionality behaves. It can be done on all of the columns by default (though columns can be disabled if you want), and you can click a column header to sort by that column in ascending order, click the same column again to change to descending order and then click the column one more time to return to the original, unsorted state. You can disable sorting on one or more columns if you want, and the sorting can be made persistent so that the column and direction order is remembered across page refreshes. The sortableInitial and sortableInitialDirection properties allow you to stipulate the initial sorting for the datagrid. And finally, the sotableCompare property allows you to give a function (or an array of functions) that handles the sorting. For example, you might want to sort a column by the day of the week instead of alphabetically. There's an example of a sort function that sorts by the last character in the cell in the API documentation.

The search feature that's part of the datagrid is quite versatile. It can be enabled by setting the search property to true and you'll then see a search box at the top left of your datagrid. The placeholder text can be customised and whether the search box gets focus or not when the page loads can also be set. You may not want the search box to get focus if your datagrid is off-screen when the page loads, because if it does get focus, then that can cause the page to jump. The searchExclude property can be used to exclude one or more columns from searching (for example, you might not want a column of ID numbers to be searchable). By default, the datagrid search is JavaScript-based and happens within the browser. This means that the URL is not updated and also that you can't link directly to a search. The searchUrl* properties however, allow you to change this to a server-based search so when you type something into the search box and press Enter, the URL is updated and a new page is requested from the server. You can then use the GET parameters that are given to do the search on your server and return the relevant results. The searchUrlRandom property can be used to avoid any caching issues and adds a random number on to the end of the URL.

Now lets talk about the types of search that are available. There are two different types of search that you can use from the same search box above the datagrid. The first is a standard word search with basic wildcard support. So you can just type in a word into the search box, either upper or lower case, and the datagrid will restrict the rows that are displayed to those that contain that word somewhere in the row. It may be a word by itself or it may be part of a larger word. With the basic word search you can use simple wildcards such as the asterisk and the question mark. The asterisk represents any number of characters, whilst the question mark represents only a single character. There's an implicit asterisk added to each side of the word so the phrase ichar would find the name Richard.

The other type of search that's available to you is a more advanced Regular Expression-based search. You can activate this type of search by enclosing your search phrase in forward-slashes - just like you do in JavaScript. You can then use the power that Regular Expressions give you in your search phrase and the datagrid will try to match the phrase against each row. Note that whilst basic wildcard searches are case-insensitive (ie anything is matched), the Regular Expression search is indeed case-sensitive - though you can change this by using the i flag after the closing forward-slash.

Moving on to the paging properties - these are properties that allow you to restrict the amount of data that's shown at once and provide links to see the rest (ie more pages of data). So your set of 65 rows may be split up into 3 pages of 25, 25 and 15 rows. Paging is enabled by default. The pagingPerPage property simply stipulates how many results you want to see on each page and the pagingCurrent property stipulates the start page (this overrides whatever the page stored in the web browsers localStorage area is). The pagingMaxPageLinks property can be used to stipulate how many page links are shown at once. The pagingPersistent property can be used to stipulate whether page information is stored in the window.localStorage area and thus maintained across page refreshes. You can use the pagingPosition and pagingLabel properties to control the aesthetics of the page information that, by default, is on the top right of the datagrid. The last paging properties are the pagingUrl* properties. These can be used to change the paging from being based on using the window.localStorage area to using the querystring. This means that you could set it so that the page number is retrieved from the ?page= querystring parameter.

Editing values on the datagrid is allowed when you set the editable property to true. This means that you can then edit the values on the datagrid by double-clicking on them. When you do this, the cell is changed such that a form input appears with the unformatted number set as the value. When the user has made their change and pressed Enter, there are events triggered which you can attach functions to to send the edits back to the server (the edit events are: beforeedit, beforeeditsave, aftereditsave, editcomplete and editcancelled). The editableColumns property allows you to specify a range of column indexes that you want to allow edits to - for example, you might only have a single column on the datagrid that you want to be editable.

The final set of properties are classed as miscellaneous but are no less important. In fact, the style property may be the property that will be used the most. It allows you to specify CSS rules that get applied to the datagrid, allowing you to tailor the appearance to fit your desired aesthetic. With this property, you stipulate an array of strings - each of those strings being a standard CSS rule that's applied to the document. The ID of the datagrid is prefixed to each rule to try to limit the rules that you give to this specific datagrid. A note about specificity: Your CSS rules should be as specific as you can make them. So, for example, if you want TD cells to have a certain color as the background, it's better to be verbose and specify a full CSS path such as "TABLE TBODY TR TD" rather than just "TD". This will lead to fewer moments where you're left staring at the screen, wondering why your CSS is not working!

The description and caption options are similar - the description option allows you to add an ARIA description, and the caption option allows you to add a standard caption tag to the datagrid's underlying table. Note though, the caption tag can sometimes be skipped by screen-readers, so you may want to opt instead for a regular HTML heading.

The last option is the events option. Like the other RGraph objects, this allows you to add your own functions as event listeners to any of the datagrid events. It's an object and the properties are the event names - such as draw, rowclick, cellclick or editcomplete whilst the values of those properties are functions that will run when the events are fired. As well as functions, the values can also be arrays of functions for when you want more than one to run for a particular event. We'll get into events more a bit later in the video.

Now let's move on to the methods that are available to you. These allow you to easily work with the datagrid and add, remove or retrieve data as required. The methods that are available to you are:

The get and set methods are standard accessors that you can use to get and set properties of the datagrid - just like the other RGraph objects. The getData() method returns the datagrid data to you. The raw data in the object is not just a regular array, so if you want just the data, you should use this method to get it. Similarly, the row() and column() methods return a row or column of the data to you. The index can be negative - in which case the indexing is counted from the end of the data and if the given index doesn't exist, then null is returned.

The setData function allows you to set data on the datagrid. This method alters the data and sets up the internal data structure that the datagrid uses, so you should use this method instead of setting the data on the datagrid directly.

As well as containing extra metadata - the data property may not be in the original, unsorted order. So if that's what you want, then you can use the getUnsortedData() method. Similar to this, the getOriginalIndex() method returns the original, unsorted index of the index that you give it.

The resetData() method resets the data back to the original, unsorted state. After it does this, the resetdata event is fired.

The append(), prepend(), insert() and delete() methods allow you to edit the data on the datagrid - adding and taking away from it as required. Each of these methods fires the relevant event after it has finished.

The find function allows you to search through your data for a specific item. You can use a basic string search, or you can instead use a regular expression to do the matching. Normally, this function will stop when it finds the first match, but you can change this by specifying the all option as the second argument.

The clear() function clears the container DIV and removes the datagrid from the document. There are two events that pertain to this function, and they are the beforeclear and clear events. The redraw() method also clears the datagrid but then redraws it as well. It too fires two events, and they are the beforedraw and redraw events.

The resetSortData() method allows you to reset the sort data back to the original, unsorted state and the exec() method is the same as the exec() method on the other RGraph functions, allowing you to run code there and then - not waiting for a particular event to occur. The on() method is present for compatibility with other RGraph objects and is the old way to add events to the datagrid. This method is largely redundant now with the newer events property that's now available.

The last method that's available to you is the parseCellIdentifier() method. This method takes an Excel-style cell identifier - such as A2, C7 or BD77 - and provides you with the corresponding row and cell index in the form of an object with two properties - row and column.

Now let's talk about the events that the datagrid makes available to you. These events allow you to attach your own code to a particular event so that you can act accordingly and trigger your own logic, allowing you to integrate the datagrid closely into your website or application. The events are added to the datagrid object by using the events property that was mentioned previously, and the available events are:

The beforedraw, firstdraw, draw, beforeredraw and redraw events fire when the datagrid is drawn or redrawn. The beforeclear and clear events happen when the datagrid is cleared. The resetdata event fires when the resetData() method is called. The beforesort and sort events happen when the datagrid is sorted. The append, prepend, insert and delete events fire when the relevant method is called to modify the data. The rowclick and cellclick events fire when a row or cell is clicked. There's metadata available to these two events that's passed to your event listener function as the second argument. This metadata will allow you to act accordingly when the events are fired.

The beforeedit, beforeeditsave, aftereditsave, editcomplete and editcancelled events are all fired in the process of making edits to the datagrid if editing is enabled. Again, there's metadata available to you that's passed as the second argument to your event listener function, and it will help you make decisions and act accordingly.

And finally, the resizebegin, resize and resizeend events all happen in the process of resizing a column.

The final thing that we're going to talk about is integrating the datagrid with forms. The DIV tag that the datagrid is added to can sit anywhere on the page, and that includes it being part of a form. As well as that, if you stipulate that one or more of the columns in the datagrid contains HTML, then the datagrid itself can contain HTML and therefore form elements. So, as part of the data array that you give to the datagrid, you could give the HTML checkbox INPUT tag, set the columnsHTML property appropriately and see a checkbox in the first field of the datagrid. Add a submit button below the datagrid, and you can provide a way for your users to make a choice. There are examples of datagrids in forms and the relevant source code on the datagrid documentation page on the website. You could use the style option to provide the correct CSS that makes it look as though the checkboxes are on the left-hand side of the table, despite still being part of the main table, and there's example CSS for that too. Common functionality when you have this sort of layout is to provide a button to check all of the checkboxes at once, and there's an example of that along with the relevant source code.

So that's the datagrid that's now part of the RGraph library. The documentation page is essential reading if you intend to use the datagrid on your website. There're also a few FAQs at the bottom of the page that are worth looking at.

If you have any problems with the datagrid or questions about it, then feel free to post a question in the RGraph support forum and I'll get back to you with an answer.

See you in the next video!