chown -R $procusername $scriptdir/tcpdf/cache; chmod u+w $scriptdir/tcpdf/cache/
You may specify a function for each column to render the available data in a specific manner which will be called when the table is drawn. In this example I've appended the rendering engine version to the rendering engine name in the first column, and hidden the version column.
$(document).ready(function() { - $('#example').dataTable( { - "aoColumnDefs": [ - { - "fnRender": function ( oObj ) { - return oObj.aData[0] +' '+ oObj.aData[3]; - }, - "aTargets": [ 0 ] - }, - { "bVisible": false, "aTargets": [ 3 ] }, - { "sClass": "center", "aTargets": [ 4 ] } - ] - } ); -} );
Complex headers (using colspan / rowspan) can be used to group columns of similar information in DataTables, creating a very powerful visual effect. In addition to the basic behaviour, DataTables can also take colspan and rowspans into account when working with hidden columns. The colspan and rowspan attributes for each cell are automatically calculated and rendered on the page for you. This also allows the ColVis extra for DataTables to work great with hidden columns.
$(document).ready(function() { - $('#example').dataTable( { - "aoColumnDefs": [ - { "bVisible": false, "aTargets": [2] } - ] - } ); -} );
As is described by the basic DOM positioning example you can use the sDom initialisation parameter to move DataTables features around the table to where you want them. However you can also use sDom to create multiple instances of these table controls. Simply include the feature's identification letter where you want it to appear, as many times as you wish, and the controls will all sync up.
This is shown in the demo below where for four key build-in features are duplicated above and below the table. Note that obviously the table ('t') should be included only once.
$(document).ready(function() { - $('#example').dataTable( { - "sDom": '<"top"iflp<"clear">>rt<"bottom"iflp<"clear">>' - } ); -} );
DataTables inserts DOM elements around the table to control DataTables features, and you can make use of this mechanism as well to insert your own custom elements. In this example a DIV with a class of 'toolbar' is created using sDom, and then HTML is inserted into the created DIV once the table has been initialised. You could put whatever HTML you want into the toolbar and add event handlers etc.
For more complex DOM manipulation around the table, you might want to consider making use of DataTables feature plug-in API, which is used for TableTools and other DataTables plug-ins.
$(document).ready(function() { - $('#example').dataTable( { - "sDom": '<"toolbar">frtip' - } ); - $("div.toolbar").html('Custom tool bar! Text/images etc.'); -} );
Events assigned to the table can be exceptionally useful for user interaction, however you must be aware that DataTables will add and remove rows from the DOM as they are needed (i.e. when paging only the visible elements are actually available in the DOM). As such, this can lead to the odd hiccup when working with events. One of the best ways of dealing with this is through the use of live events, as shown in this example.
$(document).ready(function() { - /* Init DataTables */ - $('#example').dataTable(); - - /* Add events */ - $('#example tbody tr').live('click', function () { - var sTitle; - var nTds = $('td', this); - var sBrowser = $(nTds[1]).text(); - var sGrade = $(nTds[4]).text(); - - if ( sGrade == "A" ) - sTitle = sBrowser+' will provide a first class (A) level of CSS support.'; - else if ( sGrade == "C" ) - sTitle = sBrowser+' will provide a core (C) level of CSS support.'; - else if ( sGrade == "X" ) - sTitle = sBrowser+' does not provide CSS support or has a broken implementation. Block CSS.'; - else - sTitle = sBrowser+' will provide an undefined level of CSS support.'; - - alert( sTitle ) - } ); -} );
Events which are assigned to the table elements are retained by DataTables such that they will still work as you would expect, even after changing the sort order etc. (no need to reapply the event handlers). You can do this at any time, although if you apply the handlers after the table has been initialised there is an extra set. Rather then queriing the DOM to get all rows (since they aren't there) you need to use the fnGetNodes() API function. This is shown in this example.
$(document).ready(function() { - /* - * First step is to create title attributes for the rows in the table - * This isn't needed if the required 'title' attribute is already set in the HTML in the - * DOM - */ - $('#example tbody tr').each( function() { - var sTitle; - var nTds = $('td', this); - var sBrowser = $(nTds[1]).text(); - var sGrade = $(nTds[4]).text(); - - if ( sGrade == "A" ) - sTitle = sBrowser+' will provide a first class (A) level of CSS support.'; - else if ( sGrade == "C" ) - sTitle = sBrowser+' will provide a core (C) level of CSS support.'; - else if ( sGrade == "X" ) - sTitle = sBrowser+' does not provide CSS support or has a broken implementation. Block CSS.'; - else - sTitle = sBrowser+' will provide an undefined level of CSS support.'; - - this.setAttribute( 'title', sTitle ); - } ); - - /* Init DataTables */ - var oTable = $('#example').dataTable(); - - /* Apply the tooltips */ - $( oTable.fnGetNodes() ).tooltip( { - "delay": 0, - "track": true, - "fade": 250 - } ); -} );
Events which are assigned to the table elements are retained by DataTables such that they will still work as you would expect, even after changing the sort order etc. (no need to reapply the event handlers). If you apply the event handlers before you initialise DataTables, you just do this in the normal way. This is shown in this example where the call $('#example tbody tr[title]').tooltip(); is made before the table is initialised.
$(document).ready(function() { - /* - * First step is to create title attributes for the rows in the table - * This isn't needed if the required 'title' attribute is already set in the HTML in the - * DOM - */ - $('#example tbody tr').each( function() { - var sTitle; - var nTds = $('td', this); - var sBrowser = $(nTds[1]).text(); - var sGrade = $(nTds[4]).text(); - - if ( sGrade == "A" ) - sTitle = sBrowser+' will provide a first class (A) level of CSS support.'; - else if ( sGrade == "C" ) - sTitle = sBrowser+' will provide a core (C) level of CSS support.'; - else if ( sGrade == "X" ) - sTitle = sBrowser+' does not provide CSS support or has a broken implementation. Block CSS.'; - else - sTitle = sBrowser+' will provide an undefined level of CSS support.'; - - this.setAttribute( 'title', sTitle ); - } ); - - /* Apply the tooltips */ - $('#example tbody tr[title]').tooltip( { - "delay": 0, - "track": true, - "fade": 250 - } ); - - /* Init DataTables */ - $('#example').dataTable(); -} );
DataTables using the header and footer callback manipulation functions (fnHeaderCallback() and fnFooterCallback()) you can perform some powerful and useful data manipulation. The example given below shows how a callback function can be used to total up visible (and hidden) data, taking into account all of DataTable's features (pagination, filtering etc).
Warning! The market share information given in this table is fabricated using a combination of (mild) judgement, the BBC Browser Statistics information and statistics from TheCounter.com. THe lowest usage given to anyone browser is 0.01 for reasons of this example.
$(document).ready(function() { - $('#example').dataTable( { - "fnFooterCallback": function ( nRow, aaData, iStart, iEnd, aiDisplay ) { - /* - * Calculate the total market share for all browsers in this table (ie inc. outside - * the pagination) - */ - var iTotalMarket = 0; - for ( var i=0 ; i<aaData.length ; i++ ) - { - iTotalMarket += aaData[i][4]*1; - } - - /* Calculate the market share for browsers on this page */ - var iPageMarket = 0; - for ( var i=iStart ; i<iEnd ; i++ ) - { - iPageMarket += aaData[ aiDisplay[i] ][4]*1; - } - - /* Modify the footer row to match what we want */ - var nCells = nRow.getElementsByTagName('th'); - nCells[1].innerHTML = parseInt(iPageMarket * 100)/100 + - '% ('+ parseInt(iTotalMarket * 100)/100 +'% total)'; - } - } ); -} );
When highlighting rows using CSS :hover, you need to be aware of the sorting class which is applied to elements in the column currently being sorted (assuming it is enabled - it is by default). This example shows how to consider this in CSS, with highlighting for each row, and a little tint for the sorting column to maintain it's visibility as the column currently being sorted upon.
Javascript:
$(document).ready(function() { - $('#example').dataTable(); -} );
CSS (note that for this example the selector ".ex_highlight" is used to limit the CSS here to just this example.
.ex_highlight #example tbody tr.even:hover, #example tbody tr.even td.highlighted { - background-color: #ECFFB3; -} - -.ex_highlight #example tbody tr.odd:hover, #example tbody tr.odd td.highlighted { - background-color: #E6FF99; -} - -.ex_highlight_row #example tr.even:hover { - background-color: #ECFFB3; -} - -.ex_highlight_row #example tr.even:hover td.sorting_1 { - background-color: #DDFF75; -} - -.ex_highlight_row #example tr.even:hover td.sorting_2 { - background-color: #E7FF9E; -} - -.ex_highlight_row #example tr.even:hover td.sorting_3 { - background-color: #E2FF89; -} - -.ex_highlight_row #example tr.odd:hover { - background-color: #E6FF99; -} - -.ex_highlight_row #example tr.odd:hover td.sorting_1 { - background-color: #D6FF5C; -} - -.ex_highlight_row #example tr.odd:hover td.sorting_2 { - background-color: #E0FF84; -} - -.ex_highlight_row #example tr.odd:hover td.sorting_3 { - background-color: #DBFF70; -} -
DataTables will attempt to automatically detect the data types that your table contains, allowing it to accurately sort and filter this data. This example shows automatic type detection of HTML information - note that the sorting is correct on the second column for the visible information. Additional data types can be added through plug-ins. -
Note that prior to DataTables 1.7 the HTML type was not automatically detected, and it was necessary to specify the sType for the column - this is now not needed as seen in this example. If you do want to be able to sort and filter on the HTML information you can specify the sType for the column as 'string'.
As well as being able to pass language information to DataTables through the initialisation object, you can also store the language information in a file, which DataTables will then read. Useful if you are using server-side processes to switch language. The following example shows DataTables reading a German language file.
$(document).ready(function() { - $('#example').dataTable( { - "oLanguage": { - "sUrl": "media/language/de_DE.txt" - } - } ); -} );
It is possible to easily customise the options shown in the length menu (by default at the top left of the table) using the aLengthMenu initialisation option. This parameter is either a 1D array of options which will be used for both the displayed option and the value, or a 2D array (shown in this example) which will use the array in the first position as the value, and the array in the second position as the displayed options (useful for language strings such as 'All').
$(document).ready(function() { - $('#example').dataTable( { - "aLengthMenu": [[10, 25, 50, -1], [10, 25, 50, "All"]] - } ); -} );
The following example shows how a callback function can be used to format a particular row at draw time. For each row that is generated for display, the fnRowCallback() function is called. It is passed the row node which can then be modified and returned. In this case a trivial example of making the 'grade' column bold if the grade is 'A' is shown (note that this could also be performed using the fnRender() function, but this is just for example).
$(document).ready(function() { - $('#example').dataTable( { - "fnRowCallback": function( nRow, aData, iDisplayIndex ) { - /* Append the grade to the default row class name */ - if ( aData[4] == "A" ) - { - $('td:eq(4)', nRow).html( '<b>A</b>' ); - } - return nRow; - }, - "aoColumnDefs": [ { - "sClass": "center", - "aTargets": [ -1, -2 ] - } ] - } ); -} );
Although DataTables doesn't have row grouping built-in (picking one of the many methods available would overly limit the plug-in it was felt), it is most certainly possible to give the look and feel of row grouping. In the example below the 'group' is the browser engine, which is based on the information in the first column (set to hidden). The grouping indicator is added by the fnDrawCallback function, which will parse through the rows which are displayed, and enter a TR element where a new group is found.
$(document).ready(function() { - oTable = $('#example').dataTable({ - "fnDrawCallback": function ( oSettings ) { - if ( oSettings.aiDisplay.length == 0 ) - { - return; - } - - var nTrs = $('#example tbody tr'); - var iColspan = nTrs[0].getElementsByTagName('td').length; - var sLastGroup = ""; - for ( var i=0 ; i<nTrs.length ; i++ ) - { - var iDisplayIndex = oSettings._iDisplayStart + i; - var sGroup = oSettings.aoData[ oSettings.aiDisplay[iDisplayIndex] ]._aData[0]; - if ( sGroup != sLastGroup ) - { - var nGroup = document.createElement( 'tr' ); - var nCell = document.createElement( 'td' ); - nCell.colSpan = iColspan; - nCell.className = "group"; - nCell.innerHTML = sGroup; - nGroup.appendChild( nCell ); - nTrs[i].parentNode.insertBefore( nGroup, nTrs[i] ); - sLastGroup = sGroup; - } - } - }, - "aoColumnDefs": [ - { "bVisible": false, "aTargets": [ 0 ] } - ], - "aaSortingFixed": [[ 0, 'asc' ]], - "aaSorting": [[ 1, 'asc' ]], - "sDom": 'lfr<"giveHeight"t>ip' - }); -} );
At times you may wish to change the default sorting direction for columns (all or some of them) to be 'descending' rather than DataTables' default ascending. This can be done through the use of the aoColumns[].asSorting initialisation parameter. This parameter also allows you to limit the sorting to a single direction, or you could add complex behaviour to the sorting interaction.
The example below shows:
It's worth noting that I don't have a good use case for when you might what to use the complex behaviour that is possible with this, but it is there should you want to use it!
$(document).ready(function() { - $('#example').dataTable( { - "aoColumns": [ - null, - { "asSorting": [ "asc" ] }, - { "asSorting": [ "desc", "asc", "asc" ] }, - { "asSorting": [ "desc" ] }, - null - ] - } ); -} );
Although DataTables is built from the principle of progressive enhancement, it is often useful to be able to construct a table from an AJAX source. This can be done in one of two ways - either using the aData initialisation parameter which takes an array of data, or using the sAjaxSource initialisation parameter which will have DataTables go to that source with an XHR call and load data from there. This example shows the latter method in action. DataTables expects an object with an array called "aaData" with the data source.
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "sAjaxSource": "sources/arrays.txt" - } ); -} );
The code below shows the latest JSON data that has been returned from the server in response to the Ajax request made by DataTables. This will update as further requests are made.
By default DataTables will read the data to show in the table from the aaData property of the object returned from the server. By using the initialisation option sAjaxDataProp you can customise this to whatever you wish. This examples shows it being set to 'demo'. Note that this option will also work with server-side processing. Additionally, it is possible to set sAjaxDataProp to be an empty string, which results in DataTables treating the given data source as the table data array (rather than as property of an object).
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "sAjaxSource": "sources/custom_prop.txt", - "sAjaxDataProp": "demo" - } ); -} );
The ability of DataTables to read arbitrary object properties as a column data source is extended to n levels of objects, through the use of standard Javascript dotted object notation. For example in this example "platform.details.0" refers to the first element of the array "details", of the object "platform", for each column. Any level of 'dots' can be used.
$(document).ready(function() { - var oTable = $('#example').dataTable( { - "bProcessing": true, - "sAjaxSource": "sources/deep.txt", - "aoColumns": [ - { "mDataProp": "engine" }, - { "mDataProp": "browser" }, - { "mDataProp": "platform.inner" }, - { "mDataProp": "platform.details.0" }, - { "mDataProp": "platform.details.1" } - ] - } ); -} );
When working with large data sources, you might seek to improve the speed at which DataTables runs. One method to do this is to make use of the build in deferred rendering. Rather than have DataTables create all TR and TD nodes required for the table when the data is loaded, when deferred rendering is enabled, DataTables will only create the nodes required for each individual display - these nodes are then retained incase they are needed again. This can give a significant performance increase, since a lot less work is done at initialisation time.
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "sAjaxSource": "sources/arrays.txt", - "bDeferRender": true - } ); -} );
In some tables it can be useful to not need to specify any data source for a column, as it's content is automatically generated (for example using fnRender). This is fairly common with add, edit and delete columns for a CRUD interface. You can now use the mDataProp set to null to specify that the column has no data source. DataTables will render this column as empty.
$(document).ready(function() { - var oTable = $('#example').dataTable( { - "bProcessing": true, - "sAjaxSource": "sources/arrays.txt", - "aoColumns": [ - null, - null, - null, - null, - null, - { "mDataProp": null } - ] - } ); -} );
By default, DataTables will expect an array of arrays for its data source, with each cell in the table being exactly described in the data source. However, this can often be quite limiting, or not suitable for a particular data source, so it is possible to specify which property of a source object that DataTables should read for each column. In this example the Ajax source returns an array of objects (one object for each row), and will then read the required property for each column.
$(document).ready(function() { - var oTable = $('#example').dataTable( { - "bProcessing": true, - "sAjaxSource": "sources/objects.txt", - "aoColumns": [ - { "mDataProp": "engine" }, - { "mDataProp": "browser" }, - { "mDataProp": "platform" }, - { "mDataProp": "version" }, - { "mDataProp": "grade" } - ] - } ); -} );
While the ability of DataTables to read arbitrary objects properties as a data source for any column is very powerful, it actually goes further than single level object properties; it is possible to read a data source for a column from a deeply nested array or property. This is specified in typical Javascript dotted object notation. For example "details.0" (used in this example) refers to the first property in an array called "details". "details.1" refers to the second property, etc. Object properties can also be used - for example "details.version" is perfectly valid, if that property is available in your data source.
$(document).ready(function() { - var oTable = $('#example').dataTable( { - "bProcessing": true, - "sAjaxSource": "sources/objects_subarrays.txt", - "aoColumns": [ - { "mDataProp": "engine" }, - { "mDataProp": "browser" }, - { "mDataProp": "platform" }, - { "mDataProp": "details.0" }, - { "mDataProp": "details.1" } - ] - } ); -} );
DataTables adding rows in DataTables is done by assigning the DataTables jQuery object to a variable when initialising it, and then using it's API methods to add a new row. Deleting rows can be done in a similar manner.
Click to add a new row
/* Global var for counter */ -var giCount = 1; - -$(document).ready(function() { - $('#example').dataTable(); -} ); - -function fnClickAddRow() { - $('#example').dataTable().fnAddData( [ - giCount+".1", - giCount+".2", - giCount+".3", - giCount+".4" ] ); - - giCount++; -}
There are times when you may wish to call API functions inside the DataTables callback functions (for example fnInitComplete, fnRowCallback etc). The complicating issue with this is that the object hasn't fully initialised, so you can't assign the result to something like oTable and then use oTable in the callback. However, this is catered for by the execution scope of the callback function. Here 'this' is the DataTables object that is created for the table.
In this example you will be able to see that this.fnGetNodes() is used, and also the value of this stored in the variable 'that' so it can be used inside the jQuery click function, where the execution scope has been changed to the td element!). The action here is to apply the filter with the value of what is in each cell.
$(document).ready(function() { - $('#example').dataTable( { - "fnInitComplete": function () { - var - that = this, - nTrs = this.fnGetNodes(); - $('td', nTrs).click( function () { - that.fnFilter( this.innerHTML ); - } ); - } - } ); -} );
A fairly common requirement for highly interactive tables which are displayed on the web is to have a column which with a 'counter' for the row number. This column should not be sortable, and change dynamically as the sorting and filtering applied to the table is altered by the end user.
This example shows how this can be achieved with DataTables, where the first column is the counter column, and is updated when sorting or filtering occurs. Also the first column is marked as un-sortable and initial sorting is applied only on the second column.
$(document).ready(function() { - $('#example').dataTable( { - "fnDrawCallback": function ( oSettings ) { - /* Need to redo the counters if filtered or sorted */ - if ( oSettings.bSorted || oSettings.bFiltered ) - { - for ( var i=0, iLen=oSettings.aiDisplay.length ; i<iLen ; i++ ) - { - $('td:eq(0)', oSettings.aoData[ oSettings.aiDisplay[i] ].nTr ).html( i+1 ); - } - } - }, - "aoColumnDefs": [ - { "bSortable": false, "aTargets": [ 0 ] } - ], - "aaSorting": [[ 1, 'asc' ]] - } ); -} );
Using DataTables in-combination with the excellent jEditable plugin for jQuery allows you to produce a table which can have individual cells edited. The table can then be updated such that filtering, sorting etc. will all work as expected. This is showing in the demo below.
The example shows how a table element can be edited (you could limit to a particular column if you wish using the selector), posted to the server (for saving in a database or whatever) and then placed back into the DataTable. The server's processing in this example simply appends the string '(server updated)' to indicate that something has happened on the server.
Note also that this example makes use of the information in the 'ID' attribute of the TR element. This is useful in order to tell the server what row is being updated - this can readily be expended to include column information as required. Further to this, it is worth noting that to use this type of example with DataTables' server-side processing option, you must use fnDrawCallback to apply the event listeners on each draw.
$(document).ready(function() { - /* Init DataTables */ - var oTable = $('#example').dataTable(); - - /* Apply the jEditable handlers to the table */ - $('td', oTable.fnGetNodes()).editable( '../examples_support/editable_ajax.php', { - "callback": function( sValue, y ) { - var aPos = oTable.fnGetPosition( this ); - oTable.fnUpdate( sValue, aPos[0], aPos[1] ); - }, - "submitdata": function ( value, settings ) { - return { - "row_id": this.parentNode.getAttribute('id'), - "column": oTable.fnGetPosition( this )[2] - }; - }, - "height": "14px" - } ); -} );
The following example shows how form elements can be used within a DataTables enhanced table. The trick here is that DataTables does not include the DOM elements which are not currently being displayed, therefore you need to add a submit event handler to gather together all of the input elements from the table, and then use the handy jQuery serialize() function to string together the data. It can then be posted to the server as you wish.
var oTable; - -$(document).ready(function() { - $('#form').submit( function() { - var sData = $('input', oTable.fnGetNodes()).serialize(); - alert( "The following data would have been submitted to the server: \n\n"+sData ); - return false; - } ); - - oTable = $('#example').dataTable(); -} );
The highlighting of rows and columns have be quite useful for attracting attention to where the user's cursor is in the data array. Of course the highlighting of a row is easy enough using CSS, but for column highlighting, you need to use a little bit of Javascript. This example shows that in action on a DataTables enhanced table - this type of effect would be particularly effective on tables with dense information.
$(document).ready(function() { - var oTable = $('#example').dataTable( { - "bSortClasses": false - } ); - - $('td', oTable.fnGetNodes()).hover( function() { - var iCol = $('td').index(this) % 5; - var nTrs = oTable.fnGetNodes(); - $('td:nth-child('+(iCol+1)+')', nTrs).addClass( 'highlighted' ); - }, function() { - $('td.highlighted', oTable.fnGetNodes()).removeClass('highlighted'); - } ); -} );
The filtering functionality that is provided by DataTables is very useful for quickly search through the information in the table - however the search is global, and you (or the end user) may wish to filter only on a particular column of data. To met this need the DataTables fnFilter() API function allow you to specify a column to limit to search to. Note that this works in-combination with the global search filter. Further note that because the input elements are outside of the control of DataTables, with state saving enabled, stored values are not automatically restored - please see this post in the forum for how to do this.
The example below shows a table which has a text input box for each column in the footer element of the table. This allows the data in each column to be quickly filtered upon by the end user.
var asInitVals = new Array(); - -$(document).ready(function() { - var oTable = $('#example').dataTable( { - "oLanguage": { - "sSearch": "Search all columns:" - } - } ); - - $("tfoot input").keyup( function () { - /* Filter on the column (the index) of this element */ - oTable.fnFilter( this.value, $("tfoot input").index(this) ); - } ); - - - - /* - * Support functions to provide a little bit of 'user friendlyness' to the textboxes in - * the footer - */ - $("tfoot input").each( function (i) { - asInitVals[i] = this.value; - } ); - - $("tfoot input").focus( function () { - if ( this.className == "search_init" ) - { - this.className = ""; - this.value = ""; - } - } ); - - $("tfoot input").blur( function (i) { - if ( this.value == "" ) - { - this.className = "search_init"; - this.value = asInitVals[$("tfoot input").index(this)]; - } - } ); -} );
Note that in the above code, the support functions are provided to ensure that the end user knows what data is being filtered upon. fnFilter() is the function of primary import here.
This example is almost identical to individual column example and provides the same functionality, but using <select> menus rather than input elements. The API plug-in function fnGetColumnData from Benedikt Forchhammer provides much of the logic processing required, and integration with a table is almost trivial.
One possible interaction chance would be to make use of fnGetColumnData's ability to get filtered data, so you could have the possible filtering values in the select menus to update to only those in the table, rather than all values.
(function($) { -/* - * Function: fnGetColumnData - * Purpose: Return an array of table values from a particular column. - * Returns: array string: 1d data array - * Inputs: object:oSettings - dataTable settings object. This is always the last argument past to the function - * int:iColumn - the id of the column to extract the data from - * bool:bUnique - optional - if set to false duplicated values are not filtered out - * bool:bFiltered - optional - if set to false all the table data is used (not only the filtered) - * bool:bIgnoreEmpty - optional - if set to false empty values are not filtered from the result array - * Author: Benedikt Forchhammer <b.forchhammer /AT\ mind2.de> - */ -$.fn.dataTableExt.oApi.fnGetColumnData = function ( oSettings, iColumn, bUnique, bFiltered, bIgnoreEmpty ) { - // check that we have a column id - if ( typeof iColumn == "undefined" ) return new Array(); - - // by default we only wany unique data - if ( typeof bUnique == "undefined" ) bUnique = true; - - // by default we do want to only look at filtered data - if ( typeof bFiltered == "undefined" ) bFiltered = true; - - // by default we do not wany to include empty values - if ( typeof bIgnoreEmpty == "undefined" ) bIgnoreEmpty = true; - - // list of rows which we're going to loop through - var aiRows; - - // use only filtered rows - if (bFiltered == true) aiRows = oSettings.aiDisplay; - // use all rows - else aiRows = oSettings.aiDisplayMaster; // all row numbers - - // set up data array - var asResultData = new Array(); - - for (var i=0,c=aiRows.length; i<c; i++) { - iRow = aiRows[i]; - var aData = this.fnGetData(iRow); - var sValue = aData[iColumn]; - - // ignore empty values? - if (bIgnoreEmpty == true && sValue.length == 0) continue; - - // ignore unique values? - else if (bUnique == true && jQuery.inArray(sValue, asResultData) > -1) continue; - - // else push the value onto the result data array - else asResultData.push(sValue); - } - - return asResultData; -}}(jQuery)); - - -function fnCreateSelect( aData ) -{ - var r='<select><option value=""></option>', i, iLen=aData.length; - for ( i=0 ; i<iLen ; i++ ) - { - r += '<option value="'+aData[i]+'">'+aData[i]+'</option>'; - } - return r+'</select>'; -} - - -$(document).ready(function() { - /* Initialise the DataTable */ - var oTable = $('#example').dataTable( { - "oLanguage": { - "sSearch": "Search all columns:" - } - } ); - - /* Add a select menu for each TH element in the table footer */ - $("tfoot th").each( function ( i ) { - this.innerHTML = fnCreateSelect( oTable.fnGetColumnData(i) ); - $('select', this).change( function () { - oTable.fnFilter( $(this).val(), i ); - } ); - } ); -} );
Filtering a table is one of the most common user interactions with a DataTables table, and DataTables provides a number of methods for you to control this interaction. There is a global filter, and a filter for each individual column. The global filter acts on each column.
Each filter (global or column) can be marked as a regular expression (allowing you to create very complex interactions) and as a smart filter or not. When smart filtering is enabled on a particular filter, DataTables will modify the user input string to a complex regular expression which can make filtering more intuitive.
This example allows you to "play" with the various filtering options that DataTables provides.
function fnFilterGlobal () -{ - $('#example').dataTable().fnFilter( - $("#global_filter").val(), - null, - $("#global_regex")[0].checked, - $("#global_smart")[0].checked - ); -} - -function fnFilterColumn ( i ) -{ - $('#example').dataTable().fnFilter( - $("#col"+(i+1)+"_filter").val(), - i, - $("#col"+(i+1)+"_regex")[0].checked, - $("#col"+(i+1)+"_smart")[0].checked - ); -} - -$(document).ready(function() { - $('#example').dataTable(); - - $("#global_filter").keyup( fnFilterGlobal ); - $("#global_regex").click( fnFilterGlobal ); - $("#global_smart").click( fnFilterGlobal ); - - $("#col1_filter").keyup( function() { fnFilterColumn( 0 ); } ); - $("#col1_regex").click( function() { fnFilterColumn( 0 ); } ); - $("#col1_smart").click( function() { fnFilterColumn( 0 ); } ); - - // ... etc for the other four columns -} );
DataTables has most features enabled by default, so all you need to do to use it with one of your own tables is to call the construction function (as shown below).
/* Formating function for row details */ -function fnFormatDetails ( oTable, nTr ) -{ - var aData = oTable.fnGetData( nTr ); - var sOut = '<table cellpadding="5" cellspacing="0" border="0" style="padding-left:50px;">'; - sOut += '<tr><td>Rendering engine:</td><td>'+aData[1]+' '+aData[4]+'</td></tr>'; - sOut += '<tr><td>Link to source:</td><td>Could provide a link here</td></tr>'; - sOut += '<tr><td>Extra info:</td><td>And any further details here (images etc)</td></tr>'; - sOut += '</table>'; - - return sOut; -} - -$(document).ready(function() { - /* - * Insert a 'details' column to the table - */ - var nCloneTh = document.createElement( 'th' ); - var nCloneTd = document.createElement( 'td' ); - nCloneTd.innerHTML = '<img src="../examples_support/details_open.png">'; - nCloneTd.className = "center"; - - $('#example thead tr').each( function () { - this.insertBefore( nCloneTh, this.childNodes[0] ); - } ); - - $('#example tbody tr').each( function () { - this.insertBefore( nCloneTd.cloneNode( true ), this.childNodes[0] ); - } ); - - /* - * Initialse DataTables, with no sorting on the 'details' column - */ - var oTable = $('#example').dataTable( { - "aoColumnDefs": [ - { "bSortable": false, "aTargets": [ 0 ] } - ], - "aaSorting": [[1, 'asc']] - }); - - /* Add event listener for opening and closing details - * Note that the indicator for showing which row is open is not controlled by DataTables, - * rather it is done here - */ - $('#example tbody td img').live('click', function () { - var nTr = this.parentNode.parentNode; - if ( this.src.match('details_close') ) - { - /* This row is already open - close it */ - this.src = "../examples_support/details_open.png"; - oTable.fnClose( nTr ); - } - else - { - /* Open this row */ - this.src = "../examples_support/details_close.png"; - oTable.fnOpen( nTr, fnFormatDetails(oTable, nTr), 'details' ); - } - } ); -} );
It can be quite useful at times to provide the user with the option to select rows in a DataTable. This can be done using the API functions that DataTables provides. The example below uses the fnRowCallback() function to add a 'click' listener to each row, which will highlight the required row when selected. The indexes of the selected rows are then provided through the custom function fnGetSelected() for later processing.
$(document).ready(function() { - /* Add a click handler to the rows - this could be used as a callback */ - $('#example tr').click( function() { - if ( $(this).hasClass('row_selected') ) - $(this).removeClass('row_selected'); - else - $(this).addClass('row_selected'); - } ); - - /* Init the table */ - var oTable = $('#example').dataTable( ); -} ); - -/* - * I don't actually use this here, but it is provided as it might be useful and demonstrates - * getting the TR nodes from DataTables - */ -function fnGetSelected( oTableLocal ) -{ - var aReturn = new Array(); - var aTrs = oTableLocal.fnGetNodes(); - - for ( var i=0 ; i<aTrs.length ; i++ ) - { - if ( $(aTrs[i]).hasClass('row_selected') ) - { - aReturn.push( aTrs[i] ); - } - } - return aReturn; -}
Delete selected row
var oTable; -var giRedraw = false; - -$(document).ready(function() { - /* Add a click handler to the rows - this could be used as a callback */ - $("#example tbody").click(function(event) { - $(oTable.fnSettings().aoData).each(function (){ - $(this.nTr).removeClass('row_selected'); - }); - $(event.target.parentNode).addClass('row_selected'); - }); - - /* Add a click handler for the delete row */ - $('#delete').click( function() { - var anSelected = fnGetSelected( oTable ); - oTable.fnDeleteRow( anSelected[0] ); - } ); - - /* Init the table */ - oTable = $('#example').dataTable( ); -} ); - - -/* Get the rows which are currently selected */ -function fnGetSelected( oTableLocal ) -{ - var aReturn = new Array(); - var aTrs = oTableLocal.fnGetNodes(); - - for ( var i=0 ; i<aTrs.length ; i++ ) - { - if ( $(aTrs[i]).hasClass('row_selected') ) - { - aReturn.push( aTrs[i] ); - } - } - return aReturn; -}
This example shows how you can make use of the fnSetColumnVis() API function to show and hide columns in a table dynamically, after the table has been initialised (we've also got scrolling enabled here, although that is not required for the API function to work).
$(document).ready(function() { - $('#example').dataTable( { - "sScrollY": "200px", - "bPaginate": false - } ); -} ); - -function fnShowHide( iCol ) -{ - /* Get the DataTables object again - this is not a recreation, just a get of the object */ - var oTable = $('#example').dataTable(); - - var bVis = oTable.fnSettings().aoColumns[iCol].bVisible; - oTable.fnSetColumnVis( iCol, bVis ? false : true ); -}
This example shows how DataTables with scrolling can be used together with jQuery UI tabs (or indeed any other method whereby the table is in a hidden (display:none) element when it is initialised). The reason this requires special consideration, is that when DataTables is initialised and it is in a hidden element, the browser doesn't have any measurements with which to give DataTables, and this will require in the misalignment of columns when scrolling is enabled.
The method to get around this is to call the fnAdjustColumnSizing API function. This function will calculate the column widths that are needed based on the current data and then redraw the table - which is exactly what is needed when the table becomes visible for the first time. For this we use the 'show' method provided by jQuery UI tables. We check to see if the DataTable has been created or not (note the extra selector for 'div.dataTables_scrollBody', this is added when the DataTable is initialised). If the table has been initialised, we re-size it. An optimisation could be added to re-size only of the first showing of the table.
$(document).ready(function() { - $("#tabs").tabs( { - "show": function(event, ui) { - var oTable = $('div.dataTables_scrollBody>table.display', ui.panel).dataTable(); - if ( oTable.length > 0 ) { - oTable.fnAdjustColumnSizing(); - } - } - } ); - - $('table.display').dataTable( { - "sScrollY": "200px", - "bScrollCollapse": true, - "bPaginate": false, - "bJQueryUI": true, - "aoColumnDefs": [ - { "sWidth": "10%", "aTargets": [ -1 ] } - ] - } ); -} );
The page controls which are used by default in DataTables (forward and backward buttons only) are great for most situations, but there are cases where you may wish to customise the controls presented to the end user. This is made simple by DataTables through its extensible pagination mechanism. There are two types of pagination controls built into DataTables: two_button (default) and full_numbers. To switch between these two types, use the sPaginationType initialisation parameter. You can add additional types of pagination control by extending the $.fn.dataTableExt.oPagination object.
Note also that the number of pages which are shown with direct links (the 1, 2, 3...) can be changed by setting the variable jQuery.fn.dataTableExt.oPagination.iFullNumbersShowPages (default 5). Odd numbers are best to keep the display even.
The example below shows the full_numbers type of pagination, where 'first', 'previous', 'next' and 'last' buttons are presented, as well as the five pages around the current page.
$(document).ready(function() { - $('#example').dataTable( { - "sPaginationType": "full_numbers" - } ); -} );
When using tables to display data, you will often wish to display column information in groups. DataTables fully supports colspan and rowspans in the header, assigning the required sorting listeners to the TH element suitable for that column. Each column must have one TH cell (and only one) which is unique to it for the listeners to be added. The example shown below has the core browser information grouped together.
When customising DataTables for your own usage, you might find that the default position of the feature elements (filter input etc) is not quite to your liking. To address this issue DataTables takes inspiration from the CSS 3 Advanced Layout Module and provides the sDom initialisation parameter which can be set to indicate where you which particular features to appear in the DOM. You can also specify div wrapping containers (with classes) to provide complete layout flexibility. The syntax available is:
In the example below I've moved the table information to the top of the table, and all the interaction elements to the bottom, each wrapper in a container div.
$(document).ready(function() { - $('#example').dataTable( { - "sDom": '<"top"i>rt<"bottom"flp><"clear">' - } ); -} );
Disabling features that you don't wish to use for a particular table is easily done by setting a variable in the initialisation object. In the following example only the filter feature is left enabled (although I've explicitly declared it as enabled).
$(document).ready(function() { - $('#example').dataTable( { - "bPaginate": false, - "bLengthChange": false, - "bFilter": true, - "bSort": false, - "bInfo": false, - "bAutoWidth": false - } ); -} );
There are times when you might find it useful to display only a sub-set of the information that was available in the original table. For example you might want to reduce the amount of data shown on screen to make it clearer for the user. This hidden data can still be filtered upon allowing the user access to that data (for example 'tag' information for a row entry), or this can be disabled. In the table below both the platform and engine version columns have been hidden, the former is searchable, the latter is not.
$(document).ready(function() { - $('#example').dataTable( { - "aoColumnDefs": [ - { "bSearchable": false, "bVisible": false, "aTargets": [ 2 ] }, - { "bVisible": false, "aTargets": [ 3 ] } - ] } ); - } );
Changing the language information displayed by DataTables is as simple as passing in a language object to the dataTable constructor. The example above shows a different set of English language definitions to be used, rather than the defaults.
$(document).ready(function() { -$('#example').dataTable( { - "oLanguage": { - "sLengthMenu": "Display _MENU_ records per page", - "sZeroRecords": "Nothing found - sorry", - "sInfo": "Showing _START_ to _END_ of _TOTAL_ records", - "sInfoEmpty": "Showing 0 to 0 of 0 records", - "sInfoFiltered": "(filtered from _MAX_ total records)" - } - } ); -} );
As you would expect with a desktop application, DataTables allows you to sort by multiple columns at the same time. This multiple sorting mechanism is always active if the bSort initialiser is true (it is by default) and the end user can activate it by 'shift' clicking on the column they want to add to the sort. You can also pass in an array of information using the aaSorting initialiser, as I have done in the example below there the first column is sorted as the primary column and the second one then used if the elements in the first column match. As many columns as you wish can be added to the sort.
DataTables also provides a method to add your own sorting functions, to extend those built into DataTables. This can be very useful if you wish to sort on data formats such as currency and non-Javascript standard date formats (this natural sort algorithm is a popular useage). This is achieved by extending the jQuery.fn.dataTableExt object with ascending and descending sort functions. In the example below I've added case sensitive sorting functions.
/* Define two custom functions (asc and desc) for string sorting */ -jQuery.fn.dataTableExt.oSort['string-case-asc'] = function(x,y) { - return ((x < y) ? -1 : ((x > y) ? 1 : 0)); -}; - -jQuery.fn.dataTableExt.oSort['string-case-desc'] = function(x,y) { - return ((x < y) ? 1 : ((x > y) ? -1 : 0)); -}; - -$(document).ready(function() { - /* Build the DataTable with third column using our custom sort functions */ - $('#example').dataTable( { - "aaSorting": [ [0,'asc'], [1,'asc'] ], - "aoColumns": [ - null, - null, - { "sType": 'string-case' }, - null, - null - ] - } ); -} );
Using standard jQuery selector syntax with DataTables it is trivial to initialise multiple tables with a single line of Javascript, as shown below. All tables are completely independent, but share the parameters passed thought the initialiser object (for example if you specific the Spanish language file, all tables will be shown in Spanish).
Trident based browsers
Gecko based browsers
WebKit based browsers (note no platform)
$(document).ready(function() { - $('.dataTable').dataTable(); -} );
This DataTables horizontal scrolling example shows horizontal scrolling on a DataTable, which is very useful for when you have a wide table, with a large number of columns to display, but want to constrain it to a limited horizontal display area. To enable x scrolling simply set the sScrollX parameter to be whatever you want the container wrapper's width to be (any CSS measurement is acceptable, or just a number which is treated as pixels). Note also that sScrollXInner is used here to force the table to be wider than is strictly needed. You may or may not want to include this parameter depending on your application.
Also shown in this example is the use of a 'collapsing scroll table' by using bScrollCollapse. When this parameter is set to true, the table size will 'collapse' down to match the number of rows, if the table height is smaller than the scrollable area.
$(document).ready(function() { - $('#example').dataTable( { - "sScrollX": "100%", - "sScrollXInner": "110%", - "bScrollCollapse": true - } ); -} );
In this example you can see DataTables doing horizontal and vertical scrolling at the same time. Note also that pagination is enabled, and the scrolling accounts for this.
$(document).ready(function() { - $('#example').dataTable( { - "sScrollY": 200, - "sScrollX": "100%", - "sScrollXInner": "110%" - } ); -} );
This example shows the DataTables table body scrolling in the vertical direction. This can generally be seen as an alternative method to pagination for displaying a large table in a fairly small vertical area, and as such pagination has been disabled here (note that this is not mandatory, it will work just fine with pagination enabled as well!). The example is set up to show grid lines using CSS, which is useful for alignment, both for testing and end user usability. To enable y scrolling simply set the sScrollY parameter to be whatever you want the container wrapper's height to be (any CSS measurement is acceptable, or just a number which is treated as pixels).
$(document).ready(function() { - $('#example').dataTable( { - "sScrollY": "200px", - "bPaginate": false - } ); -} );
This example shows the DataTables table body scrolling in the vertical direction with infinite scrolling. The idea of infinite scrolling means that data will be added to the table dynamically, as and when needed by the user scrolling the table. A sub-set of the data is loaded initially, and more added as needed (technically of course, it is not "infinite" since it will stop loading data at the end of the data set!). Note that pagination much be enabled for infinite scrolling to work, but the pagination controls will not be shown (they could be, but can cause very confusing user interaction).
DataTables' infinite scroll can be used with any of the four data sources supported, and they do not require any modification to work (including server-side scripts).
$(document).ready(function() { - $('#example').dataTable( { - "bScrollInfinite": true, - "bScrollCollapse": true, - "sScrollY": "200px" - } ); -} );
This example is an extension of the vertical scrolling example, showing DataTables ability to be themed by jQuery UI's ThemeRoller.
$(document).ready(function() { - $('#example').dataTable( { - "sScrollY": 200, - "bJQueryUI": true, - "sPaginationType": "full_numbers" - } ); -} );
DataTables can use cookies in the end user's web-browser in order to store it's state after each change in drawing. What this means is that if the user were to reload the page, the table should remain exactly as it was (length, filtering, pagination and sorting). This feature is disabled by default, but can be easily enabled using the bStateSave initialisation parameter as shown in this example. Note also that the duration of the cookie can be set using the iCookieDuration initialisation parameter (which is in seconds).
$(document).ready(function() { - $('#example').dataTable( { - "bStateSave": true - } ); -} );
With DataTables you can alter the sorting characteristics of the table at initialisation time. Using the aaSorting initialisation parameter, you can get the table exactly how you want to present the information. The aaSorting parameter is an array of arrays where the first value is the column to sort on, and the second is 'asc' or 'desc' as required (it is a double array for multi-column sorting). The table below is sorted (descending) by the CSS grade. Note also that the 'Engine version' column is automatically detected as a numeric column and sorted accordingly. Finally, also note that "asSorting" has been defined for the column in question for this example. The reason for this is that DataTables uses ["asc","desc"] for sorting order by default, but we would in this case prefer "desc" to be given first priority.
$(document).ready(function() { - $('#example').dataTable( { - "aaSorting": [[ 4, "desc" ]] - } ); -} );
Styling widgets such as DataTables can often take a considerable amount of time to fully integrate it into your site/application, with the demo styles as a base. This holds true for all widgets, and the jQuery UI team have addressed this issue by introducing themes through their excellent ThemeRoller. DataTables has full support for ThemeRoller created themes, all you need to do is enable the bJQueryUI flag in the initialisation object, and the required mark-up and classes will be added by DataTables.
$(document).ready(function() { - oTable = $('#example').dataTable({ - "bJQueryUI": true, - "sPaginationType": "full_numbers" - }); -} );
Although DataTables is built from the principle of progressive enhancement, it is often useful to be able to construct a table from an AJAX source. This can be done in one of two ways - either using the aaData initialisation parameter which takes an array of data, or using the sAjaxSource initialisation parameter which will have DataTables go to that source with an XHR call and load data from there. This example shows the latter method in action. DataTables expects an object with an array called "aaData" with the data source.
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "sAjaxSource": '../ajax/sources/arrays.txt' - } ); -} );
The foundation for DataTables is progressive enhancement, so it is very adept at reading table information directly from the DOM. Therefore, if your user's browser is capable the user will get a DataTables enhanced experience. Otherwise they get the plain HTML.
At times you will wish to be able to create a table from dynamic information passed directly to DataTables, rather than having it read from the document. This is achieved using the "aaData" array in the initialisation object. A table node must first be created before the initialiser is called (as shown in the code below). This is also useful for optimisation - if you are able to format the data as required, this method can save a lot of DOM parsing to create a table.
$(document).ready(function() { - $('#demo').html( '<table cellpadding="0" cellspacing="0" border="0" class="display" id="example"></table>' ); - $('#example').dataTable( { - "aaData": [ - /* Reduced data set */ - [ "Trident", "Internet Explorer 4.0", "Win 95+", 4, "X" ], - [ "Trident", "Internet Explorer 5.0", "Win 95+", 5, "C" ], - [ "Trident", "Internet Explorer 5.5", "Win 95+", 5.5, "A" ], - [ "Trident", "Internet Explorer 6.0", "Win 98+", 6, "A" ], - [ "Trident", "Internet Explorer 7.0", "Win XP SP2+", 7, "A" ], - [ "Gecko", "Firefox 1.5", "Win 98+ / OSX.2+", 1.8, "A" ], - [ "Gecko", "Firefox 2", "Win 98+ / OSX.2+", 1.8, "A" ], - [ "Gecko", "Firefox 3", "Win 2k+ / OSX.3+", 1.9, "A" ], - [ "Webkit", "Safari 1.2", "OSX.3", 125.5, "A" ], - [ "Webkit", "Safari 1.3", "OSX.3", 312.8, "A" ], - [ "Webkit", "Safari 2.0", "OSX.4+", 419.3, "A" ], - [ "Webkit", "Safari 3.0", "OSX.4+", 522.1, "A" ] - ], - "aoColumns": [ - { "sTitle": "Engine" }, - { "sTitle": "Browser" }, - { "sTitle": "Platform" }, - { "sTitle": "Version", "sClass": "center" }, - { - "sTitle": "Grade", - "sClass": "center", - "fnRender": function(obj) { - var sReturn = obj.aData[ obj.iDataColumn ]; - if ( sReturn == "A" ) { - sReturn = "<b>A</b>"; - } - return sReturn; - } - } - ] - } ); -} );
There are many ways to get your data into DataTables, and if you are working with seriously large databases, you might want to consider using the server-side options that DataTables provides. Basically all of the paging, filtering, sorting etc that DataTables does can be handed off to a server (or any other data source - Google Gears or Adobe Air for example!) and DataTables is just an events and display module.
The example here shows a very simple display of the CSS data (used in all my other examples), but in this instance coming from the server on each draw. Filtering, multi-column sorting etc all work as you would expect.
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "../server_side/scripts/server_processing.php" - } ); -} );
<?php - /* - * Script: DataTables server-side script for PHP and MySQL - * Copyright: 2010 - Allan Jardine - * License: GPL v2 or BSD (3-point) - */ - - /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * Easy set variables - */ - - /* Array of database columns which should be read and sent back to DataTables. Use a space where - * you want to insert a non-database field (for example a counter or static image) - */ - $aColumns = array( 'engine', 'browser', 'platform', 'version', 'grade' ); - - /* Indexed column (used for fast and accurate table cardinality) */ - $sIndexColumn = "id"; - - /* DB table to use */ - $sTable = "ajax"; - - /* Database connection information */ - $gaSql['user'] = ""; - $gaSql['password'] = ""; - $gaSql['db'] = ""; - $gaSql['server'] = "localhost"; - - - /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * If you just want to use the basic configuration for DataTables with PHP server-side, there is - * no need to edit below this line - */ - - /* - * MySQL connection - */ - $gaSql['link'] = mysql_pconnect( $gaSql['server'], $gaSql['user'], $gaSql['password'] ) or - die( 'Could not open connection to server' ); - - mysql_select_db( $gaSql['db'], $gaSql['link'] ) or - die( 'Could not select database '. $gaSql['db'] ); - - - /* - * Paging - */ - $sLimit = ""; - if ( isset( $_GET['iDisplayStart'] ) && $_GET['iDisplayLength'] != '-1' ) - { - $sLimit = "LIMIT ".mysql_real_escape_string( $_GET['iDisplayStart'] ).", ". - mysql_real_escape_string( $_GET['iDisplayLength'] ); - } - - - /* - * Ordering - */ - if ( isset( $_GET['iSortCol_0'] ) ) - { - $sOrder = "ORDER BY "; - for ( $i=0 ; $i<intval( $_GET['iSortingCols'] ) ; $i++ ) - { - if ( $_GET[ 'bSortable_'.intval($_GET['iSortCol_'.$i]) ] == "true" ) - { - $sOrder .= $aColumns[ intval( $_GET['iSortCol_'.$i] ) ]." - ".mysql_real_escape_string( $_GET['sSortDir_'.$i] ) .", "; - } - } - - $sOrder = substr_replace( $sOrder, "", -2 ); - if ( $sOrder == "ORDER BY" ) - { - $sOrder = ""; - } - } - - - /* - * Filtering - * NOTE this does not match the built-in DataTables filtering which does it - * word by word on any field. It's possible to do here, but concerned about efficiency - * on very large tables, and MySQL's regex functionality is very limited - */ - $sWhere = ""; - if ( $_GET['sSearch'] != "" ) - { - $sWhere = "WHERE ("; - for ( $i=0 ; $i<count($aColumns) ; $i++ ) - { - $sWhere .= $aColumns[$i]." LIKE '%".mysql_real_escape_string( $_GET['sSearch'] )."%' OR "; - } - $sWhere = substr_replace( $sWhere, "", -3 ); - $sWhere .= ')'; - } - - /* Individual column filtering */ - for ( $i=0 ; $i<count($aColumns) ; $i++ ) - { - if ( $_GET['bSearchable_'.$i] == "true" && $_GET['sSearch_'.$i] != '' ) - { - if ( $sWhere == "" ) - { - $sWhere = "WHERE "; - } - else - { - $sWhere .= " AND "; - } - $sWhere .= $aColumns[$i]." LIKE '%".mysql_real_escape_string($_GET['sSearch_'.$i])."%' "; - } - } - - - /* - * SQL queries - * Get data to display - */ - $sQuery = " - SELECT SQL_CALC_FOUND_ROWS ".str_replace(" , ", " ", implode(", ", $aColumns))." - FROM $sTable - $sWhere - $sOrder - $sLimit - "; - $rResult = mysql_query( $sQuery, $gaSql['link'] ) or die(mysql_error()); - - /* Data set length after filtering */ - $sQuery = " - SELECT FOUND_ROWS() - "; - $rResultFilterTotal = mysql_query( $sQuery, $gaSql['link'] ) or die(mysql_error()); - $aResultFilterTotal = mysql_fetch_array($rResultFilterTotal); - $iFilteredTotal = $aResultFilterTotal[0]; - - /* Total data set length */ - $sQuery = " - SELECT COUNT(".$sIndexColumn.") - FROM $sTable - "; - $rResultTotal = mysql_query( $sQuery, $gaSql['link'] ) or die(mysql_error()); - $aResultTotal = mysql_fetch_array($rResultTotal); - $iTotal = $aResultTotal[0]; - - - /* - * Output - */ - $output = array( - "sEcho" => intval($_GET['sEcho']), - "iTotalRecords" => $iTotal, - "iTotalDisplayRecords" => $iFilteredTotal, - "aaData" => array() - ); - - while ( $aRow = mysql_fetch_array( $rResult ) ) - { - $row = array(); - for ( $i=0 ; $i<count($aColumns) ; $i++ ) - { - if ( $aColumns[$i] == "version" ) - { - /* Special output formatting for 'version' column */ - $row[] = ($aRow[ $aColumns[$i] ]=="0") ? '-' : $aRow[ $aColumns[$i] ]; - } - else if ( $aColumns[$i] != ' ' ) - { - /* General output */ - $row[] = $aRow[ $aColumns[$i] ]; - } - } - $output['aaData'][] = $row; - } - - echo json_encode( $output ); -?>
This DataTables package comes with a number of examples of how you can use this software, and demonstrates the capabilities and flexibility of DataTables.
This example shows how you can use information available in the DOM to sort columns. Typically DataTables will read information to be sorted during it's initialisation phase, and this will not be updated based on user interaction, so sorting on columns which have, for example, form elements in them, may not reflect the current value of the input. To overcome this problem, you must update the data that DataTables will sort on, just prior to the sort. This method is much more efficient than actually sorting using the DOM, since only one DOM query is needed for each cell to be sorted.
The example below shows the first two columns as normal text with sorting as you would expect. The following columns all have a form input element of different kinds, and the information contained within is what DataTables will perform the sort on, based on the value at the time of the sort.
This is a fairly simple example, but it you aren't constrained to just using form input elements, you could use anything and customise your DOM queries to suit yourself. You could also update the sorting live as a user in entered data into a form using an event handler calling fnSort() or fnDraw().
/* Create an array with the values of all the input boxes in a column */ -$.fn.dataTableExt.afnSortData['dom-text'] = function ( oSettings, iColumn ) -{ - var aData = []; - $( 'td:eq('+iColumn+') input', oSettings.oApi._fnGetTrNodes(oSettings) ).each( function () { - aData.push( this.value ); - } ); - return aData; -} - -/* Create an array with the values of all the select options in a column */ -$.fn.dataTableExt.afnSortData['dom-select'] = function ( oSettings, iColumn ) -{ - var aData = []; - $( 'td:eq('+iColumn+') select', oSettings.oApi._fnGetTrNodes(oSettings) ).each( function () { - aData.push( $(this).val() ); - } ); - return aData; -} - -/* Create an array with the values of all the checkboxes in a column */ -$.fn.dataTableExt.afnSortData['dom-checkbox'] = function ( oSettings, iColumn ) -{ - var aData = []; - $( 'td:eq('+iColumn+') input', oSettings.oApi._fnGetTrNodes(oSettings) ).each( function () { - aData.push( this.checked==true ? "1" : "0" ); - } ); - return aData; -} - -/* Initialise the table with the required column sorting data types */ -$(document).ready(function() { - $('#example').dataTable( { - "aoColumns": [ - null, - null, - { "sSortDataType": "dom-text" }, - { "sSortDataType": "dom-text", "sType": "numeric" }, - { "sSortDataType": "dom-select" }, - { "sSortDataType": "dom-checkbox" } - ] - } ); -} );
It can be very useful to have DataTables default to it's built in type of HTML, rather than string, which a column does not fit the requirements of any other type. The way this method works is to put the 'html' type at the end of aTypes, which means it will be set as that type only if none of the other types match the data in question.
jQuery.fn.dataTableExt.aTypes.push( - function ( sData ) { - return 'html'; - } -); - -$(document).ready(function() { - $('#example').dataTable(); -} );
The two default pagination styles that DataTables comes with are great for basic tables, but you might which to add extra customisation or a bit of 'glitz'. This plug-in will scroll the table in an animated style.
/* Time between each scrolling frame */ -$.fn.dataTableExt.oPagination.iTweenTime = 100; - -$.fn.dataTableExt.oPagination.scrolling = { - "fnInit": function ( oSettings, nPaging, fnCallbackDraw ) - { - /* Store the next and previous elements in the oSettings object as they can be very - * usful for automation - particularly testing - */ - var nPrevious = document.createElement( 'div' ); - var nNext = document.createElement( 'div' ); - - if ( oSettings.sTableId !== '' ) - { - nPaging.setAttribute( 'id', oSettings.sTableId+'_paginate' ); - nPrevious.setAttribute( 'id', oSettings.sTableId+'_previous' ); - nNext.setAttribute( 'id', oSettings.sTableId+'_next' ); - } - - nPrevious.className = "paginate_disabled_previous"; - nNext.className = "paginate_disabled_next"; - - nPrevious.title = oSettings.oLanguage.oPaginate.sPrevious; - nNext.title = oSettings.oLanguage.oPaginate.sNext; - - nPaging.appendChild( nPrevious ); - nPaging.appendChild( nNext ); - - $(nPrevious).click( function() { - /* Disallow paging event during a current paging event */ - if ( typeof oSettings.iPagingLoopStart != 'undefined' && oSettings.iPagingLoopStart != -1 ) - { - return; - } - - oSettings.iPagingLoopStart = oSettings._iDisplayStart; - oSettings.iPagingEnd = oSettings._iDisplayStart - oSettings._iDisplayLength; - - /* Correct for underrun */ - if ( oSettings.iPagingEnd < 0 ) - { - oSettings.iPagingEnd = 0; - } - - var iTween = $.fn.dataTableExt.oPagination.iTweenTime; - var innerLoop = function () { - if ( oSettings.iPagingLoopStart > oSettings.iPagingEnd ) { - oSettings.iPagingLoopStart--; - oSettings._iDisplayStart = oSettings.iPagingLoopStart; - fnCallbackDraw( oSettings ); - setTimeout( function() { innerLoop(); }, iTween ); - } else { - oSettings.iPagingLoopStart = -1; - } - }; - innerLoop(); - } ); - - $(nNext).click( function() { - /* Disallow paging event during a current paging event */ - if ( typeof oSettings.iPagingLoopStart != 'undefined' && oSettings.iPagingLoopStart != -1 ) - { - return; - } - - oSettings.iPagingLoopStart = oSettings._iDisplayStart; - - /* Make sure we are not over running the display array */ - if ( oSettings._iDisplayStart + oSettings._iDisplayLength < oSettings.fnRecordsDisplay() ) - { - oSettings.iPagingEnd = oSettings._iDisplayStart + oSettings._iDisplayLength; - } - - var iTween = $.fn.dataTableExt.oPagination.iTweenTime; - var innerLoop = function () { - if ( oSettings.iPagingLoopStart < oSettings.iPagingEnd ) { - oSettings.iPagingLoopStart++; - oSettings._iDisplayStart = oSettings.iPagingLoopStart; - fnCallbackDraw( oSettings ); - setTimeout( function() { innerLoop(); }, iTween ); - } else { - oSettings.iPagingLoopStart = -1; - } - }; - innerLoop(); - } ); - - /* Take the brutal approach to cancelling text selection */ - $(nPrevious).bind( 'selectstart', function () { return false; } ); - $(nNext).bind( 'selectstart', function () { return false; } ); - }, - - "fnUpdate": function ( oSettings, fnCallbackDraw ) - { - if ( !oSettings.aanFeatures.p ) - { - return; - } - - /* Loop over each instance of the pager */ - var an = oSettings.aanFeatures.p; - for ( var i=0, iLen=an.length ; i<iLen ; i++ ) - { - if ( an[i].childNodes.length !== 0 ) - { - an[i].childNodes[0].className = - ( oSettings._iDisplayStart === 0 ) ? - oSettings.oClasses.sPagePrevDisabled : oSettings.oClasses.sPagePrevEnabled; - - an[i].childNodes[1].className = - ( oSettings.fnDisplayEnd() == oSettings.fnRecordsDisplay() ) ? - oSettings.oClasses.sPageNextDisabled : oSettings.oClasses.sPageNextEnabled; - } - } - } -} - -$(document).ready(function() { - $('#example').dataTable( { - "sPaginationType": "scrolling" - } ); -} );
DataTables presents a number of useful API functions to the calling code which can be used to manipulate the table data as required. But there are times when DataTables doesn't provide the API function that you want - so for this DataTables allows a method by which custom API functions can be defined (effectively a plug-in). This is done by adding functions the $.fn.dataTableExt.oApi object, which will be registered by DataTables. Each function is passed a single parameter, the settings object for the table in question.
In the example below, I present an API function which is used to obtain all of the TR rows which are currently not on display (useful for building a form from the table).
/* - * Function: fnGetHiddenTrNodes - * Purpose: Get all of the hidden TR nodes (i.e. the ones which aren't on display) - * Returns: array: - * Inputs: object:oSettings - DataTables settings object - */ -$.fn.dataTableExt.oApi.fnGetHiddenTrNodes = function ( oSettings ) -{ - /* Note the use of a DataTables 'private' function thought the 'oApi' object */ - var anNodes = this.oApi._fnGetTrNodes( oSettings ); - var anDisplay = $('tbody tr', oSettings.nTable); - - /* Remove nodes which are being displayed */ - for ( var i=0 ; i<anDisplay.length ; i++ ) - { - var iIndex = jQuery.inArray( anDisplay[i], anNodes ); - if ( iIndex != -1 ) - { - anNodes.splice( iIndex, 1 ); - } - } - - /* Fire back the array to the caller */ - return anNodes; -} - -/* Init the table and fire off a call to get the hidden nodes. */ -var oTable; -$(document).ready(function() { - var oTable = $('#example').dataTable(); - - $('#button').click( function () { - var nHidden = oTable.fnGetHiddenTrNodes(); - alert( nHidden.length +' nodes were returned' ); - } ); -} );
There may be occasions when you wish to filter data presented to the end user in your own manner, common examples are number range filtering (in between two numbers) and date range filtering. DataTables provide an API method to add your own filtering functions, $.fn.dataTableExt.afnFiltering. This is an array of functions (push your own onto it) which will will be run at table draw time to see if a particular row should be included or not.
/* Custom filtering function which will filter data in column four between two values */ -$.fn.dataTableExt.afnFiltering.push( - function( oSettings, aData, iDataIndex ) { - var iMin = document.getElementById('min').value * 1; - var iMax = document.getElementById('max').value * 1; - var iVersion = aData[3] == "-" ? 0 : aData[3]*1; - if ( iMin == "" && iMax == "" ) - { - return true; - } - else if ( iMin == "" && iVersion < iMax ) - { - return true; - } - else if ( iMin < iVersion && "" == iMax ) - { - return true; - } - else if ( iMin < iVersion && iVersion < iMax ) - { - return true; - } - return false; - } -); - -$(document).ready(function() { - /* Initialise datatables */ - var oTable = $('#example').dataTable(); - - /* Add event listeners to the two range filtering inputs */ - $('#min').keyup( function() { oTable.fnDraw(); } ); - $('#max').keyup( function() { oTable.fnDraw(); } ); -} );
When dealing with your own data formatting, it can often be very useful to have DataTables detect data types and sorting them accordingly for types which are not build into DataTables. For this reason plug-in support is provided to allow custom type detection and sorting.
This example shows sorting with a comma (',') for a decimal place. These plug-ins (and others can be found on DataTables.net.
/* Note 'unshift' does not work in IE6. A simply array concatenation would. This is used - * to give the custom type top priority - */ -jQuery.fn.dataTableExt.aTypes.unshift( - function ( sData ) - { - var sValidChars = "0123456789-,"; - var Char; - var bDecimal = false; - - /* Check the numeric part */ - for ( i=0 ; i<sData.length ; i++ ) - { - Char = sData.charAt(i); - if (sValidChars.indexOf(Char) == -1) - { - return null; - } - - /* Only allowed one decimal place... */ - if ( Char == "," ) - { - if ( bDecimal ) - { - return null; - } - bDecimal = true; - } - } - - return 'numeric-comma'; - } -); - -jQuery.fn.dataTableExt.oSort['numeric-comma-asc'] = function(a,b) { - var x = (a == "-") ? 0 : a.replace( /,/, "." ); - var y = (b == "-") ? 0 : b.replace( /,/, "." ); - x = parseFloat( x ); - y = parseFloat( y ); - return ((x < y) ? -1 : ((x > y) ? 1 : 0)); -}; - -jQuery.fn.dataTableExt.oSort['numeric-comma-desc'] = function(a,b) { - var x = (a == "-") ? 0 : a.replace( /,/, "." ); - var y = (b == "-") ? 0 : b.replace( /,/, "." ); - x = parseFloat( x ); - y = parseFloat( y ); - return ((x < y) ? 1 : ((x > y) ? -1 : 0)); -}; - -$(document).ready(function() { - $('#example').dataTable(); -} );
When dealing with your own data formats, it can be desirable to define how you want sorting to occur. Using plug-in sorting functions, you have have DataTables sort data in any manner you wish. You tell DataTables how to sort a column by using the sType parameter - if it is not given then DataTables will attempt to automatically detect the type based on it's built in formatting functions.
This example shows sorting with a comma (',') for a decimal place. This sorting plug-in (and others can be found on DataTables.net.
jQuery.fn.dataTableExt.oSort['numeric-comma-asc'] = function(a,b) { - var x = (a == "-") ? 0 : a.replace( /,/, "." ); - var y = (b == "-") ? 0 : b.replace( /,/, "." ); - x = parseFloat( x ); - y = parseFloat( y ); - return ((x < y) ? -1 : ((x > y) ? 1 : 0)); -}; - -jQuery.fn.dataTableExt.oSort['numeric-comma-desc'] = function(a,b) { - var x = (a == "-") ? 0 : a.replace( /,/, "." ); - var y = (b == "-") ? 0 : b.replace( /,/, "." ); - x = parseFloat( x ); - y = parseFloat( y ); - return ((x < y) ? 1 : ((x > y) ? -1 : 0)); -}; - -$(document).ready(function() { - $('#example').dataTable( { - "aoColumns": [ - null, - null, - null, - { "sType": "numeric-comma" }, - null - ] - } ); -} );
When using server-side processing it may be considerably easier on the server-side to output the data in an order which is not exactly that shown by the table to the end user. For this reason you can 'name' each column and this information will be sent to the server (comma delimited) as the variable 'sColumns' - this is the column information that DataTables expects to get back from a request.
Equally there you can defined an 'sColumns' in the JSON return which tells DataTables the order of the columns that has been returned. If the order is different from what it expects, then it will automatically re-order for you. The following example shows a server-side return which gives the columns "out of order".
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "scripts/ordering.php", - "aoColumns": [ - { "sName": "engine" }, - { "sName": "browser" }, - { "sName": "platform" }, - { "sName": "version" }, - { "sName": "grade" } - ] - } ); -} );
It can often be useful to send a little bit of extra information to the server when utilising DataTables' server-side processing option. This can be done by using the fnServerParams callback function which is called whenever an XHR is sent to the server. fnServerParams Takes a single parameter, the array of name/value pairs of parameters that are to be sent to the server. You can manipulate this as you require - typically adding another parameter, as shown in this example.
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "scripts/server_processing.php" - "fnServerParams": function ( aoData ) { - aoData.push( { "name": "more_data", "value": "my_value" } ); - } - } ); -} );
When using DataTables with server-side processing the default behaviour is to have DataTables automatically go the server and load the data, removing anything which might already be on the page. However, this behaviour might not always be desirable when the first page of the table has already been preloaded in the HTML. This is achieved by using the iDeferLoading initialisation property. It serves two purposes, firstly to include that deferred loading is required, but also to tell DataTables how many records there are in the full table, in this case 57 (this allows the information element and pagination to be displayed correctly).
In this example the preloaded data is hardcoded in, but you could use a PHP include or anything else to put the data in the table for the first page - DataTables won't process it at all, simply display it and be ready to load the next page / search / sort etc.
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "scripts/server_processing.php", - "iDeferLoading": 57 - } ); -} );
When using server-side processing and you wish to integrate the jEditable plug-in for jQuery with DataTables, you need to consider that each time data is returned from the server, DataTables will build new DOM elements - so these need the jEditable event handlers applied to them. This is down through use of the fnDrawCallback function.
$(document).ready(function() { - var oTable = $('#example').dataTable( { - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "scripts/server_processing.php", - "fnDrawCallback": function () { - $('#example tbody td').editable( '../examples_support/editable_ajax.php', { - "callback": function( sValue, y ) { - /* Redraw the table from the new data on the server */ - oTable.fnDraw(); - }, - "height": "14px" - } ); - } - } ); -} );
Often when using server-side processing you will find that it can be useful to have a specific ID on each row (the row ID from the database for example). By assigning the ID you want to apply to each row using the property DT_RowId of the data source object for each row, DataTables will automatically add it for you. Likewise there is a DT_RowClass option which will add your given class. This example shows both and is a trivial modification of the server-side script to add these two options, with no changes on the client-side.
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "scripts/id.php" - } ); -} );
JSONP is a method of using JSON data from any server, regardless of XSS protection that modern browsers use. It is very useful for being able to retrieve JSON data from any domain name you choose and is easy to integrate with DataTables, thanks to jQuery's Ajax handler, as shown in this example.
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "scripts/jsonp.php", - "fnServerData": function( sUrl, aoData, fnCallback ) { - $.ajax( { - "url": sUrl, - "data": aoData, - "success": fnCallback, - "dataType": "jsonp", - "cache": false - } ); - } - } ); -} );
The "native" data format that DataTables expects for server-side processing is a 2D array of data (rows by columns). However, this is often not flexible enough for either the server-side environment, or you might want to convey more information in the data source than is necessary to show in the table (row IDs from the database for example). For this DataTables supports the reading of data for objects as well as arrays.
In this example the server responds with an array of objects, and DataTables will look up each property that is specified by the mDataProp property given for each column
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "scripts/objects.php", - "aoColumns": [ - { "mDataProp": "engine" }, - { "mDataProp": "browser" }, - { "mDataProp": "platform" }, - { "mDataProp": "version" }, - { "mDataProp": "grade" } - ] - } ); -} );
When using server-side processing with DataTables, it can be quite intensive on your server having an Ajax call every time the user performs some kind of interaction - you can effectively DDOS your server with your own application!
This example shows how you might over-come this by modifying the request set to the server to retrieve more information than is actually required for a single page's display. This means that the user can page multiple times (5 times the display size is the default) before a request must be made of the server. Paging is typically the most common interaction performed with a DataTable, so this can be most beneficial to your server's resource usage. Of course the pipeline must be cleared for interactions other than paging (sorting, filtering etc), but that's the trade off that can be made (sending extra information is cheep - while another XHR is expensive).
var oCache = { - iCacheLower: -1 -}; - -function fnSetKey( aoData, sKey, mValue ) -{ - for ( var i=0, iLen=aoData.length ; i<iLen ; i++ ) - { - if ( aoData[i].name == sKey ) - { - aoData[i].value = mValue; - } - } -} - -function fnGetKey( aoData, sKey ) -{ - for ( var i=0, iLen=aoData.length ; i<iLen ; i++ ) - { - if ( aoData[i].name == sKey ) - { - return aoData[i].value; - } - } - return null; -} - -function fnDataTablesPipeline ( sSource, aoData, fnCallback ) { - var iPipe = 5; /* Ajust the pipe size */ - - var bNeedServer = false; - var sEcho = fnGetKey(aoData, "sEcho"); - var iRequestStart = fnGetKey(aoData, "iDisplayStart"); - var iRequestLength = fnGetKey(aoData, "iDisplayLength"); - var iRequestEnd = iRequestStart + iRequestLength; - oCache.iDisplayStart = iRequestStart; - - /* outside pipeline? */ - if ( oCache.iCacheLower < 0 || iRequestStart < oCache.iCacheLower || iRequestEnd > oCache.iCacheUpper ) - { - bNeedServer = true; - } - - /* sorting etc changed? */ - if ( oCache.lastRequest && !bNeedServer ) - { - for( var i=0, iLen=aoData.length ; i<iLen ; i++ ) - { - if ( aoData[i].name != "iDisplayStart" && aoData[i].name != "iDisplayLength" && aoData[i].name != "sEcho" ) - { - if ( aoData[i].value != oCache.lastRequest[i].value ) - { - bNeedServer = true; - break; - } - } - } - } - - /* Store the request for checking next time around */ - oCache.lastRequest = aoData.slice(); - - if ( bNeedServer ) - { - if ( iRequestStart < oCache.iCacheLower ) - { - iRequestStart = iRequestStart - (iRequestLength*(iPipe-1)); - if ( iRequestStart < 0 ) - { - iRequestStart = 0; - } - } - - oCache.iCacheLower = iRequestStart; - oCache.iCacheUpper = iRequestStart + (iRequestLength * iPipe); - oCache.iDisplayLength = fnGetKey( aoData, "iDisplayLength" ); - fnSetKey( aoData, "iDisplayStart", iRequestStart ); - fnSetKey( aoData, "iDisplayLength", iRequestLength*iPipe ); - - $.getJSON( sSource, aoData, function (json) { - /* Callback processing */ - oCache.lastJson = jQuery.extend(true, {}, json); - - if ( oCache.iCacheLower != oCache.iDisplayStart ) - { - json.aaData.splice( 0, oCache.iDisplayStart-oCache.iCacheLower ); - } - json.aaData.splice( oCache.iDisplayLength, json.aaData.length ); - - fnCallback(json) - } ); - } - else - { - json = jQuery.extend(true, {}, oCache.lastJson); - json.sEcho = sEcho; /* Update the echo for each response */ - json.aaData.splice( 0, iRequestStart-oCache.iCacheLower ); - json.aaData.splice( iRequestLength, json.aaData.length ); - fnCallback(json); - return; - } -} - -$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "scripts/server_processing.php", - "fnServerData": fnDataTablesPipeline - } ); -} );
The default HTTP method that DataTables uses to get data from the server-side if GET, however, there are times when you may wish to use POST. This is very easy using the fnServerData() initialisation parameter, as shown in this example.
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "scripts/post.php", - "fnServerData": function ( sSource, aoData, fnCallback ) { - $.ajax( { - "dataType": 'json', - "type": "POST", - "url": sSource, - "data": aoData, - "success": fnCallback - } ); - } - } ); -} );
This example shows how you might modify the client-side show/hide details rows example for use with DataTables 1.5's server-side processing option.
var oTable; - -/* Formating function for row details */ -function fnFormatDetails ( nTr ) -{ - var aData = oTable.fnGetData( nTr ); - var sOut = '<table cellpadding="5" cellspacing="0" border="0" style="padding-left:50px;">'; - sOut += '<tr><td>Rendering engine:</td><td>'+aData[2]+' '+aData[5]+'</td></tr>'; - sOut += '<tr><td>Link to source:</td><td>Could provide a link here</td></tr>'; - sOut += '<tr><td>Extra info:</td><td>And any further details here (images etc)</td></tr>'; - sOut += '</table>'; - - return sOut; -} - -$(document).ready(function() { - oTable = $('#example').dataTable( { - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "scripts/details_col.php", - "aoColumns": [ - { "sClass": "center", "bSortable": false }, - null, - null, - null, - { "sClass": "center" }, - { "sClass": "center" } - ], - "aaSorting": [[1, 'asc']] - } ); - - $('#example tbody td img').live( 'click', function () { - var nTr = this.parentNode.parentNode; - if ( this.src.match('details_close') ) - { - /* This row is already open - close it */ - this.src = "../examples_support/details_open.png"; - oTable.fnClose( nTr ); - } - else - { - /* Open this row */ - this.src = "../examples_support/details_close.png"; - oTable.fnOpen( nTr, fnFormatDetails(nTr), 'details' ); - } - } ); -} );
When you want to detail with user selectable rows and DataTables, it is relatively simple when using DOM based data - but if using server-side processing, DataTables doesn't retain state over pages / filters etc, leaving this to the server-side instead. As such, you will need to keep a track of which rows a user as selected and mark them as selected on each draw. This is shown in this demo, which uses a unique ID assigned to the TR element (this is done automatically through the use of the DT_RowId special property returned as part of the object given by the server for each row).
$(document).ready(function() { - var aSelected = []; - - /* Init the table */ - $("#example").dataTable({ - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "scripts/id.php", - "fnRowCallback": function( nRow, aData, iDisplayIndex ) { - if ( jQuery.inArray(aData.DT_RowId, aSelected) !== -1 ) { - $(nRow).addClass('row_selected'); - } - return nRow; - } - }); - - /* Click event handler */ - $('#example tbody tr').live('click', function () { - var id = this.id; - var index = jQuery.inArray(id, aSelected); - - if ( index === -1 ) { - aSelected.push( id ); - } else { - aSelected.splice( index, 1 ); - } - - $(this).toggleClass('row_selected'); - } ); -} );
$(document).ready(function() { - $('#example').dataTable( { - "bProcessing": true, - "bServerSide": true, - "sAjaxSource": "scripts/server_processing.php" - } ); -} );
Copied "+a+" row"+(1==a?"":"s")+" to the clipboard.
Please use your browser's print function to print this table. Press escape when finished.
Copyright © 2009-2011 Chris Leonello
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
For changes prior to 0.6.0 release, please see change log at http://bitbucket.org/cleonello/jqplot/changesets/
GNU GENERAL PUBLIC LICENSE Version 2, June 1991
Copyright © 1989, 1991 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
Preamble
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation’s software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author’s protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors’ reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone’s free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The “Program”, below, refers to any such program or work, and a “work based on the Program” means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term “modification”.) Each licensee is addressed as “you”.
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Program’s source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients’ exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and “any later version”, you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Much of the styling of jqPlot is done by css. The jqPlot css file is, unremarkably, jquery.jqplot.css and resides in the same directory as jqPlot itself.
There exist some styling related javascript properties on the plot objects themselves (like fontStyle, fontSize, etc.). These can be set with the options object at plot creation. Generally, setting these options is NOT the preferred way to customize the look of the plot. Use the css file instead. These options are deprecated and may disappear. The exceptions are certain background and color options which control attributes of something renderered on a canvas. This would be line color, grid background, etc. These must be set by the options object. For a list of available options, see jqPlot Options.
Objects in the plot that can be customized by css are given a css class like “.jqplot-*”. For example, the plot title will have a “.jqplot-title” class, the axes “.jqplot-axis”, etc.
Currently assigned classes in jqPlot are as follows:
Note that axes will be assigned 2 classes like: class=”.jqplot-axis .jqplot-xaxis”.
This document is out of date. While the options described here should still be relavent and valid, it has not been updated for many new options. Sorry for this inconvenience.
This document describes the options available to jqPlot. These are set with the third argument to the $.jqplot(‘target’, data, options) function. Options are using the following convention:
property: default, // notes
This document is not complete! Not all options are shown! Also, Options marked with * in the notes are post 0.7.1 additions. They will be available in the next release. Further information about the options can be found in the online API documentation. For details on how the options relate to the API documentation, see the Options Tutorial in the optionsTutorial.txt file.
options = -{ - seriesColors: [ "#4bb2c5", "#c5b47f", "#EAA228", "#579575", "#839557", "#958c12", - "#953579", "#4b5de4", "#d8b83f", "#ff5800", "#0085cc"], // colors that will - // be assigned to the series. If there are more series than colors, colors - // will wrap around and start at the beginning again. - - stackSeries: false, // if true, will create a stack plot. - // Currently supported by line and bar graphs. - - title: '', // Title for the plot. Can also be specified as an object like: - - title: { - text: '', // title for the plot, - show: true, - }, - - axesDefaults: { - show: false, // wether or not to renderer the axis. Determined automatically. - min: null, // minimum numerical value of the axis. Determined automatically. - max: null, // maximum numverical value of the axis. Determined automatically. - pad: 1.2, // a factor multiplied by the data range on the axis to give the - // axis range so that data points don't fall on the edges of the axis. - ticks: [], // a 1D [val1, val2, ...], or 2D [[val, label], [val, label], ...] - // array of ticks to use. Computed automatically. - numberTicks: undefined, - renderer: $.jqplot.LinearAxisRenderer, // renderer to use to draw the axis, - rendererOptions: {}, // options to pass to the renderer. LinearAxisRenderer - // has no options, - tickOptions: { - mark: 'outside', // Where to put the tick mark on the axis - // 'outside', 'inside' or 'cross', - showMark: true, - showGridline: true, // wether to draw a gridline (across the whole grid) at this tick, - markSize: 4, // length the tick will extend beyond the grid in pixels. For - // 'cross', length will be added above and below the grid boundary, - show: true, // wether to show the tick (mark and label), - showLabel: true, // wether to show the text label at the tick, - formatString: '', // format string to use with the axis tick formatter - } - showTicks: true, // wether or not to show the tick labels, - showTickMarks: true, // wether or not to show the tick marks - }, - - axes: { - xaxis: { - // same options as axesDefaults - }, - yaxis: { - // same options as axesDefaults - }, - x2axis: { - // same options as axesDefaults - }, - y2axis: { - // same options as axesDefaults - } - }, - - seriesDefaults: { - show: true, // wether to render the series. - xaxis: 'xaxis', // either 'xaxis' or 'x2axis'. - yaxis: 'yaxis', // either 'yaxis' or 'y2axis'. - label: '', // label to use in the legend for this line. - color: '', // CSS color spec to use for the line. Determined automatically. - lineWidth: 2.5, // Width of the line in pixels. - shadow: true, // show shadow or not. - shadowAngle: 45, // angle (degrees) of the shadow, clockwise from x axis. - shadowOffset: 1.25, // offset from the line of the shadow. - shadowDepth: 3, // Number of strokes to make when drawing shadow. Each - // stroke offset by shadowOffset from the last. - shadowAlpha: 0.1, // Opacity of the shadow. - showLine: true, // whether to render the line segments or not. - showMarker: true, // render the data point markers or not. - fill: false, // fill under the line, - fillAndStroke: false, // *stroke a line at top of fill area. - fillColor: undefined, // *custom fill color for filled lines (default is line color). - fillAlpha: undefined, // *custom alpha to apply to fillColor. - renderer: $.jqplot.LineRenderer], // renderer used to draw the series. - rendererOptions: {}, // options passed to the renderer. LineRenderer has no options. - markerRenderer: $.jqplot.MarkerRenderer, // renderer to use to draw the data - // point markers. - markerOptions: { - show: true, // wether to show data point markers. - style: 'filledCircle', // circle, diamond, square, filledCircle. - // filledDiamond or filledSquare. - lineWidth: 2, // width of the stroke drawing the marker. - size: 9, // size (diameter, edge length, etc.) of the marker. - color: '#666666' // color of marker, set to color of line by default. - shadow: true, // wether to draw shadow on marker or not. - shadowAngle: 45, // angle of the shadow. Clockwise from x axis. - shadowOffset: 1, // offset from the line of the shadow, - shadowDepth: 3, // Number of strokes to make when drawing shadow. Each stroke - // offset by shadowOffset from the last. - shadowAlpha: 0.07 // Opacity of the shadow - } - }, - - series:[ - {Each series has same options as seriesDefaults}, - {You can override each series individually here} - ], - - legend: { - show: false, - location: 'ne', // compass direction, nw, n, ne, e, se, s, sw, w. - xoffset: 12, // pixel offset of the legend box from the x (or x2) axis. - yoffset: 12, // pixel offset of the legend box from the y (or y2) axis. - }, - - grid: { - drawGridLines: true, // wether to draw lines across the grid or not. - gridLineColor: '#cccccc' // *Color of the grid lines. - background: '#fffdf6', // CSS color spec for background color of grid. - borderColor: '#999999', // CSS color spec for border around grid. - borderWidth: 2.0, // pixel width of border around grid. - shadow: true, // draw a shadow for grid. - shadowAngle: 45, // angle of the shadow. Clockwise from x axis. - shadowOffset: 1.5, // offset from the line of the shadow. - shadowWidth: 3, // width of the stroke for the shadow. - shadowDepth: 3, // Number of strokes to make when drawing shadow. - // Each stroke offset by shadowOffset from the last. - shadowAlpha: 0.07 // Opacity of the shadow - renderer: $.jqplot.CanvasGridRenderer, // renderer to use to draw the grid. - rendererOptions: {} // options to pass to the renderer. Note, the default - // CanvasGridRenderer takes no additional options. - }, - - // Plugin and renderer options. - - // BarRenderer. - // With BarRenderer, you can specify additional options in the rendererOptions object - // on the series or on the seriesDefaults object. Note, some options are respecified - // (like shadowDepth) to override lineRenderer defaults from which BarRenderer inherits. - - seriesDefaults: { - rendererOptions: { - barPadding: 8, // number of pixels between adjacent bars in the same - // group (same category or bin). - barMargin: 10, // number of pixels between adjacent groups of bars. - barDirection: 'vertical', // vertical or horizontal. - barWidth: null, // width of the bars. null to calculate automatically. - shadowOffset: 2, // offset from the bar edge to stroke the shadow. - shadowDepth: 5, // nuber of strokes to make for the shadow. - shadowAlpha: 0.8, // transparency of the shadow. - } - }, - - // Cursor - // Options are passed to the cursor plugin through the "cursor" object at the top - // level of the options object. - - cursor: { - style: 'crosshair', // A CSS spec for the cursor type to change the - // cursor to when over plot. - show: true, - showTooltip: true, // show a tooltip showing cursor position. - followMouse: false, // wether tooltip should follow the mouse or be stationary. - tooltipLocation: 'se', // location of the tooltip either relative to the mouse - // (followMouse=true) or relative to the plot. One of - // the compass directions, n, ne, e, se, etc. - tooltipOffset: 6, // pixel offset of the tooltip from the mouse or the axes. - showTooltipGridPosition: false, // show the grid pixel coordinates of the mouse - // in the tooltip. - showTooltipUnitPosition: true, // show the coordinates in data units of the mouse - // in the tooltip. - tooltipFormatString: '%.4P', // sprintf style format string for tooltip values. - useAxesFormatters: true, // wether to use the same formatter and formatStrings - // as used by the axes, or to use the formatString - // specified on the cursor with sprintf. - tooltipAxesGroups: [], // show only specified axes groups in tooltip. Would specify like: - // [['xaxis', 'yaxis'], ['xaxis', 'y2axis']]. By default, all axes - // combinations with for the series in the plot are shown. - - }, - - // Dragable - // Dragable options are specified with the "dragable" object at the top level - // of the options object. - - dragable: { - color: undefined, // custom color to use for the dragged point and dragged line - // section. default will use a transparent variant of the line color. - constrainTo: 'none', // Constrain dragging motion to an axis: 'x', 'y', or 'none'. - }, - - // Highlighter - // Highlighter options are specified with the "highlighter" object at the top level - // of the options object. - - highlighter: { - lineWidthAdjust: 2.5, // pixels to add to the size line stroking the data point marker - // when showing highlight. Only affects non filled data point markers. - sizeAdjust: 5, // pixels to add to the size of filled markers when drawing highlight. - showTooltip: true, // show a tooltip with data point values. - tooltipLocation: 'nw', // location of tooltip: n, ne, e, se, s, sw, w, nw. - fadeTooltip: true, // use fade effect to show/hide tooltip. - tooltipFadeSpeed: "fast"// slow, def, fast, or a number of milliseconds. - tooltipOffset: 2, // pixel offset of tooltip from the highlight. - tooltipAxes: 'both', // which axis values to display in the tooltip, x, y or both. - tooltipSeparator: ', ' // separator between values in the tooltip. - useAxesFormatters: true // use the same format string and formatters as used in the axes to - // display values in the tooltip. - tooltipFormatString: '%.5P' // sprintf format string for the tooltip. only used if - // useAxesFormatters is false. Will use sprintf formatter with - // this string, not the axes formatters. - }, - - // LogAxisRenderer - // LogAxisRenderer add 2 options to the axes object. These options are specified directly on - // the axes or axesDefaults object. - - axesDefaults: { - base: 10, // the logarithmic base. - tickDistribution: 'even', // 'even' or 'power'. 'even' will produce with even visiual (pixel) - // spacing on the axis. 'power' will produce ticks spaced by - // increasing powers of the log base. - }, - - // PieRenderer - // PieRenderer accepts options from the rendererOptions object of the series or seriesDefaults object. - - seriesDefaults: { - rendererOptions: { - diameter: undefined, // diameter of pie, auto computed by default. - padding: 20, // padding between pie and neighboring legend or plot margin. - sliceMargin: 0, // gap between slices. - fill: true, // render solid (filled) slices. - shadowOffset: 2, // offset of the shadow from the chart. - shadowDepth: 5, // Number of strokes to make when drawing shadow. Each stroke - // offset by shadowOffset from the last. - shadowAlpha: 0.07 // Opacity of the shadow - } - }, - - // Trendline - // Trendline takes options on the trendline object of the series or seriesDefaults object. - - seriesDefaults: { - trendline: { - show: true, // show the trend line - color: '#666666', // CSS color spec for the trend line. - label: '', // label for the trend line. - type: 'linear', // 'linear', 'exponential' or 'exp' - shadow: true, // show the trend line shadow. - lineWidth: 1.5, // width of the trend line. - shadowAngle: 45, // angle of the shadow. Clockwise from x axis. - shadowOffset: 1.5, // offset from the line of the shadow. - shadowDepth: 3, // Number of strokes to make when drawing shadow. - // Each stroke offset by shadowOffset from the last. - shadowAlpha: 0.07 // Opacity of the shadow - } - } -}
Renderer to place labels on the axes.
this.show = true
wether or not to show the tick (mark and label).
this.label = ''
The text or html for the label.
this.escapeHTML = false
true to escape HTML entities in the label.
A “tick” object showing the value of a tick/gridline on the plot.
this.mark = 'outside'
tick mark on the axis. One of ‘inside’, ‘outside’, ‘cross’, ‘’ or null.
this.showMark = true
wether or not to show the mark on the axis.
this.showGridline = true
wether or not to draw the gridline on the grid at this tick.
this.isMinorTick = false
if this is a minor tick.
this.size = 4
Length of the tick beyond the grid in pixels. DEPRECATED: This has been superceeded by markSize
this.markSize = 6
Length of the tick marks in pixels. For ‘cross’ style, length will be stoked above and below axis, so total length will be twice this.
wether or not to show the tick (mark and label). Setting this to false requires more testing. It is recommended to set showLabel and showMark to false instead.
this.showLabel = true
wether or not to show the label.
this.formatter = $.jqplot.DefaultTickFormatter
A class of a formatter for the tick text. sprintf by default.
this.prefix = ''
String to prepend to the tick label. Prefix is prepended to the formatted tick label.
this.formatString = ''
string passed to the formatter.
this.fontFamily
css spec for the font-family css attribute.
this.fontSize
css spec for the font-size css attribute.
this.textColor
css spec for the color attribute.
The default jqPlot grid renderer, creating a grid on a canvas element. The renderer has no additional options beyond the Grid class.
Pure JavaScript plotting plugin for jQuery.
1.0.0b2_r1012
Copyright © 2009-2011 Chris Leonello jqPlot is currently available for use in all personal or commercial projects under both the MIT and GPL version 2.0 licenses. This means that you can choose the license that best suits your project and use it accordingly.
See GPL Version 2 and MIT License contained within this distribution for further information.
The author would appreciate an email letting him know of any substantial use of jqPlot. You can reach the author at: chris at jqplot dot com or see http://www.jqplot.com/info.php. This is, of course, not required.
If you are feeling kind and generous, consider supporting the project by making a donation at: http://www.jqplot.com/donate.php.
version 2007.04.27 author Ash Searle http://hexmen.com/blog/2007/03/printf-sprintf/ http://hexmen.com/js/sprintf.js The author (Ash Searle) has placed this code in the public domain: “This code is unrestricted: you are free to use it however you like.”
jqPlot requires jQuery (1.4+ required for certain features). jQuery 1.4.2 is included in the distribution. To use jqPlot include jQuery, the jqPlot jQuery plugin, the jqPlot css file and optionally the excanvas script for IE support in your web page:
<!--[if lt IE 9]><script language="javascript" type="text/javascript" src="excanvas.js"></script><![endif]--> -<script language="javascript" type="text/javascript" src="jquery-1.4.4.min.js"></script> -<script language="javascript" type="text/javascript" src="jquery.jqplot.min.js"></script> -<link rel="stylesheet" type="text/css" href="jquery.jqplot.css" />
jqPlot can be customized by overriding the defaults of any of the objects which make up the plot. The general usage of jqplot is:
chart = $.jqplot('targetElemId', [dataArray,...], {optionsObject});
The options available to jqplot are detailed in jqPlot Options in the jqPlotOptions.txt file.
An actual call to $.jqplot() may look like the examples below:
chart = $.jqplot('chartdiv', [[[1, 2],[3,5.12],[5,13.1],[7,33.6],[9,85.9],[11,219.9]]]);
or
dataArray = [34,12,43,55,77]; -chart = $.jqplot('targetElemId', [dataArray, ...], {title:'My Plot', axes:{yaxis:{min:20, max:100}}});
For more inforrmation, see jqPlot Usage.
See jqPlot Usage
See jqPlot Options for a list of options available thorugh the options object (not complete yet!)
See Options Tutorial
See Change Log
jQuery function called by the user to create a plot.
An individual axis object. Cannot be instantiated directly, but created by the Plot oject. Axis properties can be set or overriden by the options passed in from the user.
Axes options are specified within an axes object at the top level of the plot options like so:
{ - axes: { - xaxis: {min: 5}, - yaxis: {min: 2, max: 8, numberTicks:4}, - x2axis: {pad: 1.5}, - y2axis: {ticks:[22, 44, 66, 88]} - } -}
There are 2 x axes, ‘xaxis’ and ‘x2axis’, and 9 yaxes, ‘yaxis’, ‘y2axis’. ‘y3axis’, ... Any or all of which may be specified.
this.show = false
Wether to display the axis on the graph.
this.tickRenderer = $.jqplot.AxisTickRenderer
A class of a rendering engine for creating the ticks labels displayed on the plot, See $.jqplot.AxisTickRenderer.
this.tickOptions = {}
Options that will be passed to the tickRenderer, see $.jqplot.AxisTickRenderer options.
this.labelRenderer = $.jqplot.AxisLabelRenderer
A class of a rendering engine for creating an axis label.
this.labelOptions = {}
Options passed to the label renderer.
this.label = null
Label for the axis
true to show the axis label.
this.min = null
minimum value of the axis (in data units, not pixels).
this.max = null
maximum value of the axis (in data units, not pixels).
this.autoscale = false
DEPRECATED the default scaling algorithm produces superior results.
this.pad = 1.2
Padding to extend the range above and below the data bounds. The data range is multiplied by this factor to determine minimum and maximum axis bounds. A value of 0 will be interpreted to mean no padding, and pad will be set to 1.0.
this.padMax = null
Padding to extend the range above data bounds. The top of the data range is multiplied by this factor to determine maximum axis bounds. A value of 0 will be interpreted to mean no padding, and padMax will be set to 1.0.
this.padMin = null
Padding to extend the range below data bounds. The bottom of the data range is multiplied by this factor to determine minimum axis bounds. A value of 0 will be interpreted to mean no padding, and padMin will be set to 1.0.
this.ticks = []
1D [val, val, ...] or 2D [[val, label], [val, label], ...] array of ticks for the axis. If no label is specified, the value is formatted into an appropriate label.
this.numberTicks
Desired number of ticks. Default is to compute automatically.
this.tickInterval
number of units between ticks. Mutually exclusive with numberTicks.
this.renderer = $.jqplot.LinearAxisRenderer
A class of a rendering engine that handles tick generation, scaling input data to pixel grid units and drawing the axis element.
this.rendererOptions = {}
renderer specific options. See $.jqplot.LinearAxisRenderer for options.
this.showTicks = true
Wether to show the ticks (both marks and labels) or not. Will not override showMark and showLabel options if specified on the ticks themselves.
this.showTickMarks = true
Wether to show the tick marks (line crossing grid) or not. Overridden by showTicks and showMark option of tick itself.
this.showMinorTicks = true
Wether or not to show minor ticks. This is renderer dependent.
this.drawMajorGridlines = true
True to draw gridlines for major axis ticks.
this.drawMinorGridlines = false
True to draw gridlines for minor ticks.
this.drawMajorTickMarks = true
True to draw tick marks for major axis ticks.
this.drawMinorTickMarks = true
True to draw tick marks for minor ticks. This is renderer dependent.
this.useSeriesColor = false
Use the color of the first series associated with this axis for the tick marks and line bordering this axis.
this.borderWidth = null
width of line stroked at the border of the axis. Defaults to the width of the grid boarder.
this.borderColor = null
color of the border adjacent to the axis. Defaults to grid border color.
this.syncTicks = null
true to try and synchronize tick spacing across multiple axes so that ticks and grid lines line up. This has an impact on autoscaling algorithm, however. In general, autoscaling an individual axis will work better if it does not have to sync ticks.
this.tickSpacing = 75
Approximate pixel spacing between ticks on graph. Used during autoscaling. This number will be an upper bound, actual spacing will be less.
Legend object. Cannot be instantiated directly, but created by the Plot oject. Legend properties can be set or overriden by the options passed in from the user.
Wether to display the legend on the graph.
this.location = 'ne'
Placement of the legend. one of the compass directions: nw, n, ne, e, se, s, sw, w
this.labels = []
Array of labels to use. By default the renderer will look for labels on the series. Labels specified in this array will override labels specified on the series.
this.showLabels = true
true to show the label text on the legend.
this.showSwatches = true
true to show the color swatches on the legend.
this.placement = "insideGrid"
”insideGrid” places legend inside the grid area of the plot. “outsideGrid” places the legend outside the grid but inside the plot container, shrinking the grid to accomodate the legend. “inside” synonym for “insideGrid”, “outside” places the legend ouside the grid area, but does not shrink the grid which can cause the legend to overflow the plot container.
this.xoffset = 0
DEPRECATED. Set the margins on the legend using the marginTop, marginLeft, etc. properties or via CSS margin styling of the .jqplot-table-legend class.
this.yoffset = 0
this.border
css spec for the border around the legend box.
this.background
css spec for the background of the legend box.
css color spec for the legend text.
css font-family spec for the legend text.
css font-size spec for the legend text.
this.rowSpacing = '0.5em'
css padding-top spec for the rows in the legend.
renderer specific options passed to the renderer.
Wether to draw the legend before the series or not. Used with series specific legend renderers for pie, donut, mekko charts, etc.
this.marginTop = null
CSS margin for the legend DOM element. This will set an element CSS style for the margin which will override any style sheet setting. The default will be taken from the stylesheet.
this.marginRight = null
this.marginBottom = null
this.marginLeft = null
this.escapeHtml = false
True to escape special characters with their html entity equivalents in legend text. “<” becomes < and so on, so html tags are not rendered.
Plot Title object. Cannot be instantiated directly, but created by the Plot oject. Title properties can be set or overriden by the options passed in from the user.
this.text = text
text of the title;
wether or not to show the title
css font-family spec for the text.
css font-size spec for the text.
this.textAlign
css text-align spec for the text.
css color spec for the text.
this.renderer = $.jqplot.DivTitleRenderer
A class for creating a DOM element for the title, see $.jqplot.DivTitleRenderer.
True to escape special characters with their html entity equivalents in title text. “<” becomes < and so on, so html tags are not rendered.
An individual data series object. Cannot be instantiated directly, but created by the Plot oject. Series properties can be set or overriden by the options passed in from the user.
Properties will be assigned from a series array at the top level of the options. If you had two series and wanted to change the color and line width of the first and set the second to use the secondary y axis with no shadow and supply custom labels for each:
{ - series:[ - {color: '#ff4466', lineWidth: 5, label:'good line'}, - {yaxis: 'y2axis', shadow: false, label:'bad line'} - ] -}
wether or not to draw the series.
this.xaxis = 'xaxis'
which x axis to use with this series, either ‘xaxis’ or ‘x2axis’.
this.yaxis = 'yaxis'
which y axis to use with this series, either ‘yaxis’ or ‘y2axis’.
this.renderer = $.jqplot.LineRenderer
A class of a renderer which will draw the series, see $.jqplot.LineRenderer.
Options to pass on to the renderer.
Line label to use in the legend.
true to show label for this series in the legend.
this.color
css color spec for the series
this.negativeColor
css color spec used for filled (area) plots that are filled to zero and the “useNegativeColors” option is true.
this.lineWidth = 2.5
width of the line in pixels. May have different meanings depending on renderer.
this.lineJoin = 'round'
Canvas lineJoin style between segments of series.
this.lineCap = 'round'
Canvas lineCap style at ends of line.
this.linePattern = 'solid'
line pattern ‘dashed’, ‘dotted’, ‘solid’, some combination of ‘-’ and ‘.’ characters such as ‘.-.’ or a numerical array like [draw, skip, draw, skip, ...] such as [1, 10] to draw a dotted line, [1, 10, 20, 10] to draw a dot-dash line, and so on.
this.shadowAngle = 45
Shadow angle in degrees
this.shadowOffset = 1.25
Shadow offset from line in pixels
this.shadowDepth = 3
Number of times shadow is stroked, each stroke offset shadowOffset from the last.
this.shadowAlpha = '0.1'
Alpha channel transparency of shadow. 0 = transparent.
this.breakOnNull = false
Wether line segments should be be broken at null value. False will join point on either side of line.
this.markerRenderer = $.jqplot.MarkerRenderer
A class of a renderer which will draw marker (e.g. circle, square, ...) at the data points, see $.jqplot.MarkerRenderer.
this.markerOptions = {}
renderer specific options to pass to the markerRenderer, see $.jqplot.MarkerRenderer.
this.showLine = true
wether to actually draw the line or not. Series will still be renderered, even if no line is drawn.
this.showMarker = true
wether or not to show the markers at the data points.
this.index
0 based index of this series in the plot series array.
this.fill = false
true or false, wether to fill under lines or in bars. May not be implemented in all renderers.
this.fillColor
CSS color spec to use for fill under line. Defaults to line color.
this.fillAlpha
Alpha transparency to apply to the fill under the line. Use this to adjust alpha separate from fill color.
this.fillAndStroke = false
If true will stroke the line (with color this.color) as well as fill under it. Applies only when fill is true.
this.disableStack = false
true to not stack this series with other series in the plot. To render properly, non-stacked series must come after any stacked series in the plot’s data series array. So, the plot’s data series array would look like:
[stackedSeries1, stackedSeries2, ..., nonStackedSeries1, nonStackedSeries2, ...]
disableStack will put a gap in the stacking order of series, and subsequent stacked series will not fill down through the non-stacked series and will most likely not stack properly on top of the non-stacked series.
this.neighborThreshold = 4
how close or far (in pixels) the cursor must be from a point marker to detect the point.
this.fillToZero = false
true will force bar and filled series to fill toward zero on the fill Axis.
this.fillToValue = 0
fill a filled series to this value on the fill axis. Works in conjunction with fillToZero, so that must be true.
this.fillAxis = 'y'
Either ‘x’ or ‘y’. Which axis to fill the line toward if fillToZero is true. ‘y’ means fill up/down to 0 on the y axis for this series.
this.useNegativeColors = true
true to color negative values differently in filled and bar charts.
Object representing the grid on which the plot is drawn. The grid in this context is the area bounded by the axes, the area which will contain the series. Note, the series are drawn on their own canvas. The Grid object cannot be instantiated directly, but is created by the Plot oject. Grid properties can be set or overriden by the options passed in from the user.
this.drawGridlines = true
wether to draw the gridlines on the plot.
this.gridLineColor = '#cccccc'
color of the grid lines.
this.gridLineWidth = 1.0
width of the grid lines.
this.background = '#fffdf6'
css spec for the background color.
this.borderColor = '#999999'
css spec for the color of the grid border.
this.borderWidth = 2.0
width of the border in pixels.
this.drawBorder = true
True to draw border around grid.
this.shadow = true
wether to show a shadow behind the grid.
shadow angle in degrees
this.shadowOffset = 1.5
Offset of each shadow stroke from the border in pixels
this.shadowWidth = 3
width of the stoke for the shadow
this.shadowColor = null
an optional css color spec for the shadow in ‘rgba(n, n, n, n)’ form
this.shadowAlpha = '0.07'
this.renderer = $.jqplot.CanvasGridRenderer
Instance of a renderer which will actually render the grid, see $.jqplot.CanvasGridRenderer.
Options to pass on to the renderer, see $.jqplot.CanvasGridRenderer.
Plot object returned by call to $.jqplot. Handles parsing user options, creating sub objects (Axes, legend, title, series) and rendering the plot.
These properties are specified at the top of the options object like so:
{ - axesDefaults:{min:0}, - series:[{color:'#6633dd'}], - title: 'A Plot' -}
this.animate = false
True to animate the series on initial plot draw (renderer dependent). Actual animation functionality must be supported in the renderer.
this.animateReplot = false
True to animate series after a call to the replot() method. Use with caution! Replots can happen very frequently under certain circumstances (e.g. resizing, dragging points) and animation in these situations can cause problems.
this.axes = {xaxis: new Axis('xaxis'), yaxis: new Axis('yaxis'), x2axis: new Axis('x2axis'), y2axis: new Axis('y2axis'), y3axis: new Axis('y3axis'), y4axis: new Axis('y4axis'), y5axis: new Axis('y5axis'), y6axis: new Axis('y6axis'), y7axis: new Axis('y7axis'), y8axis: new Axis('y8axis'), y9axis: new Axis('y9axis'), yMidAxis: new Axis('yMidAxis')}
up to 4 axes are supported, each with it’s own options, See Axis for axis specific options.
this.data = []
user’s data. Data should NOT be specified in the options object, but be passed in as the second argument to the $.jqplot() function. The data property is described here soley for reference. The data should be in the form of an array of 2D or 1D arrays like
[ [[x1, y1], [x2, y2],...], [y1, y2, ...] ].
this.dataRenderer
A callable which can be used to preprocess data passed into the plot. Will be called with 2 arguments, the plot data and a reference to the plot.
this.dataRendererOptions
Options that will be passed to the dataRenderer. Can be of any type.
default options that will be applied to all axes. see Axis for axes options.
seriesDefaults: {}, series:[] }
default options that will be applied to all series. see Series for series options.
this.defaultAxisStart = 1
1-D data series are internally converted into 2-D [x,y] data point arrays by jqPlot. This is the default starting value for the missing x or y value. The added data will be a monotonically increasing series (e.g. [1, 2, 3, ...]) starting at this value.
this.fillBetween = { series1: null, series2: null, color: null, baseSeries: 0, fill: true }
Fill between 2 line series in a plot. Options object: { series1: first index (0 based) of series in fill series2: second index (0 based) of series in fill color: color of fill [default fillColor of series1] baseSeries: fill will be drawn below this series (0 based index) fill: false to turn off fill [default true]. }
css spec for the font-size attribute. Default for the entire plot.
this.grid = new Grid()
See Grid for grid specific options.
this.legend = new Legend()
see <$.jqplot.TableLegendRenderer>
Options to set up a mock plot with a data loading indicator if no data is specified.
this.series = []
Array of series object options. see Series for series specific options.
this.seriesColors = $.jqplot.config.defaultColors
Ann array of CSS color specifications that will be applied, in order, to the series in the plot. Colors will wrap around so, if their are more series than colors, colors will be reused starting at the beginning. For pie charts, this specifies the colors of the slices.
this.sortData = true
false to not sort the data passed in by the user. Many bar, stakced and other graphs as well as many plugins depend on having sorted data.
this.stackSeries = false
true or false, creates a stack or “mountain” plot. Not all series renderers may implement this option.
this.title = new Title()
Title object. See Title for specific options. As a shortcut, you can specify the title option as just a string like: title: ‘My Plot’ and this will create a new title object with the specified text.
this.init = function(target,data,options)
sets the plot target, checks data and applies user options to plot.
this.resetAxesScale = function(axes,options)
Reset the specified axes min, max, numberTicks and tickInterval properties to null or reset these properties on all axes if no list of axes is provided.
this.reInitialize = function ()
reinitialize plot for replotting. not called directly.
this.destroy = function()
Releases all resources occupied by the plot
this.replot = function(options)
Does a reinitialization of the plot followed by a redraw. Method could be used to interactively change plot characteristics and then replot.
this.redraw = function(clear)
Empties the plot target div and redraws the plot. This enables plot data and properties to be changed and then to comletely clear the plot and redraw. redraw will not reinitialize any plot elements. That is, axes will not be autoscaled and defaults will not be reapplied to any plot elements. redraw is used primarily with zooming.
this.draw = function()
Draws all elements of the plot into the container. Does not clear the container before drawing.
this.drawSeries = function(options,idx)
Redraws all or just one series on the plot. No axis scaling is performed and no other elements on the plot are redrawn. options is an options object to pass on to the series renderers. It can be an empty object {}. idx is the series index to redraw if only one series is to be redrawn.
this.moveSeriesToFront = function (idx)
This method requires jQuery 1.4+ Moves the specified series canvas in front of all other series canvases. This effectively “draws” the specified series on top of all other series, although it is performed through DOM manipulation, no redrawing is performed.
this.moveSeriesToBack = function (idx)
This method requires jQuery 1.4+ Moves the specified series canvas behind all other series canvases.
this.restorePreviousSeriesOrder = function ()
This method requires jQuery 1.4+ Restore the series canvas order to its previous state. Useful to put a series back where it belongs after moving it to the front.
this.restoreOriginalSeriesOrder = function ()
This method requires jQuery 1.4+ Restore the series canvas order to its original order when the plot was created.
The default title renderer for jqPlot. This class has no options beyond the Title class.
The default line renderer for jqPlot, this class has no options beyond the Series class. Draws series as a line.
this.renderer.smooth = false
True to draw a smoothed (interpolated) line through the data points with automatically computed number of smoothing points. Set to an integer number > 2 to specify number of smoothing points to use between each data point.
this.renderer.constrainSmoothing = true
True to use a more accurate smoothing algorithm that will not overshoot any data points. False to allow overshoot but produce a smoother looking line.
this.renderer.bandData = []
Data used to draw error bands or confidence intervals above/below a line.
bandData can be input in 3 forms. jqPlot will figure out which is the low band line and which is the high band line for all forms:
A 2 dimensional array like [[yl1, yl2, ...], [yu1, yu2, ...]] where [yl1, yl2, ...] are y values of the lower line and [yu1, yu2, ...] are y values of the upper line. In this case there must be the same number of y data points as data points in the series and the bands will inherit the x values of the series.
A 2 dimensional array like [[[xl1, yl1], [xl2, yl2], ...], [[xh1, yh1], [xh2, yh2], ...]] where [xl1, yl1] are x,y data points for the lower line and [xh1, yh1] are x,y data points for the high line. x values do not have to correspond to the x values of the series and can be of any arbitrary length.
Can be of form [[yl1, yu1], [yl2, yu2], [yl3, yu3], ...] where there must be 3 or more arrays and there must be the same number of arrays as there are data points in the series. In this case, [yl1, yu1] specifies the lower and upper y values for the 1st data point and so on. The bands will inherit the x values from the series.
Banding around line, e.g error bands or confidence intervals.
true to show the bands. If bandData or interval is supplied, show will be set to true by default.
color of lines at top and bottom of bands [default: series color].
True to show lines at top and bottom of bands [default: false].
True to fill area between bands [default: true].
css color spec for filled area. [default: series color].
interval: '3%' }
User specified interval above and below line for bands [default: ‘3%’’]. Can be a value like 3 or a string like ‘3%’ or an upper/lower array like [1, -2] or [‘2%’, ‘-1.5%’]
this.highlightMouseOver = true
True to highlight area on a filled plot when moused over. This must be false to enable highlightMouseDown to highlight when clicking on an area on a filled plot.
this.highlightMouseDown = false
True to highlight when a mouse button is pressed over an area on a filled plot. This will be disabled if highlightMouseOver is true.
this.highlightColor = null
color to use when highlighting an area on a filled plot.
The default jqPlot axis renderer, creating a numeric axis.
this.breakPoints = null
EXPERIMENTAL!! Use at your own risk! Works only with linear axes and the default tick renderer. Array of [start, stop] points to create a broken axis. Broken axes have a “jump” in them, which is an immediate transition from a smaller value to a larger value. Currently, axis ticks MUST be manually assigned if using breakPoints by using the axis ticks array option.
this.breakTickLabel = "&asymp
Label to use at the axis break if breakPoints are specified.
this.drawBaseline = true
True to draw the axis baseline.
this.baselineWidth = null
width of the baseline in pixels.
this.baselineColor = null
CSS color spec for the baseline.
this.forceTickAt0 = false
This will ensure that there is always a tick mark at 0. If data range is strictly positive or negative, this will force 0 to be inside the axis bounds unless the appropriate axis pad (pad, padMin or padMax) is set to 0, then this will force an axis min or max value at 0. This has know effect when any of the following options are set: autoscale, min, max, numberTicks or tickInterval.
this.forceTickAt100 = false
This will ensure that there is always a tick mark at 100. If data range is strictly above or below 100, this will force 100 to be inside the axis bounds unless the appropriate axis pad (pad, padMin or padMax) is set to 0, then this will force an axis min or max value at 100. This has know effect when any of the following options are set: autoscale, min, max, numberTicks or tickInterval.
this.tickInset = 0
Controls the amount to inset the first and last ticks from the edges of the grid, in multiples of the tick interval. 0 is no inset, 0.5 is one half a tick interval, 1 is a full tick interval, etc.
this.minorTicks = 0
Number of ticks to add between “major” ticks. Major ticks are ticks supplied by user or auto computed. Minor ticks cannot be created by user.
this.alignTicks = false
true to align tick marks across opposed axes such as from the y2axis to yaxis.
The default jqPlot marker renderer, rendering the points on the line.
wether or not to show the marker.
this.style = 'filledCircle'
One of diamond, circle, square, x, plus, dash, filledDiamond, filledCircle, filledSquare
this.lineWidth = 2
size of the line for non-filled markers.
this.size = 9.0
Size of the marker (diameter or circle, length of edge of square, etc.)
this.color = '#666666'
color of marker. Will be set to color of series by default on init.
wether or not to draw a shadow on the line
this.shadowOffset = 1
this.shadowRenderer = new $.jqplot.ShadowRenderer()
Renderer that will draws the shadows on the marker.
this.shapeRenderer = new $.jqplot.ShapeRenderer()
Renderer that will draw the marker.
The default jqPlot shadow renderer, rendering shadows behind shapes.
this.angle = 45
Angle of the shadow in degrees. Measured counter-clockwise from the x axis.
this.offset = 1
Pixel offset at the given shadow angle of each shadow stroke from the last stroke.
this.alpha = 0.07
alpha transparency of shadow stroke.
this.lineWidth = 1.5
width of the shadow line stroke.
this.lineJoin = 'miter'
How line segments of the shadow are joined.
how ends of the shadow line are rendered.
whether to fill the shape.
this.depth = 3
how many times the shadow is stroked. Each stroke will be offset by offset at angle degrees.
this.isarc = false
wether the shadow is an arc or not.
$.jqplot.ShadowRenderer.prototype.draw = function(ctx,points,options)
draws an transparent black (i.e. gray) shadow.
The default jqPlot shape renderer. Given a set of points will plot them and either stroke a line (fill = false) or fill them (fill = true). If a filled shape is desired, closePath = true must also be set to close the shape.
this.fillRect = false
true to draw shape as a filled rectangle.
this.strokeRect = false
true to draw shape as a stroked rectangle.
this.clearRect = false
true to cear a rectangle.
this.strokeStyle = '#999999'
css color spec for the stoke style
this.fillStyle = '#999999'
css color spec for the fill style.
$.jqplot.ShapeRenderer.prototype.draw = function(ctx,points,options)
draws the shape.
Theme Engine provides a programatic way to change some of the more common jqplot styling options such as fonts, colors and grid options. A theme engine instance is created with each plot. The theme engine manages a collection of themes which can be modified, added to, or applied to the plot.
The themeEngine class is not instantiated directly. When a plot is initialized, the current plot options are scanned an a default theme named “Default” is created. This theme is used as the basis for other themes added to the theme engine and is always available.
A theme is a simple javascript object with styling parameters for various entities of the plot. A theme has the form:
{ - _name:f "Default", - target: { - backgroundColor: "transparent" - }, - legend: { - textColor: null, - fontFamily: null, - fontSize: null, - border: null, - background: null - }, - title: { - textColor: "rgb(102, 102, 102)", - fontFamily: "'Trebuchet MS',Arial,Helvetica,sans-serif", - fontSize: "19.2px", - textAlign: "center" - }, - seriesStyles: {}, - series: [{ - color: "#4bb2c5", - lineWidth: 2.5, - linePattern: "solid", - shadow: true, - fillColor: "#4bb2c5", - showMarker: true, - markerOptions: { - color: "#4bb2c5", - show: true, - style: 'filledCircle', - lineWidth: 1.5, - size: 4, - shadow: true - } - }], - grid: { - drawGridlines: true, - gridLineColor: "#cccccc", - gridLineWidth: 1, - backgroundColor: "#fffdf6", - borderColor: "#999999", - borderWidth: 2, - shadow: true - }, - axesStyles: { - label: {}, - ticks: {} - }, - axes: { - xaxis: { - borderColor: "#999999", - borderWidth: 2, - ticks: { - show: true, - showGridline: true, - showLabel: true, - showMark: true, - size: 4, - textColor: "", - whiteSpace: "nowrap", - fontSize: "12px", - fontFamily: "'Trebuchet MS',Arial,Helvetica,sans-serif" - }, - label: { - textColor: "rgb(102, 102, 102)", - whiteSpace: "normal", - fontSize: "14.6667px", - fontFamily: "'Trebuchet MS',Arial,Helvetica,sans-serif", - fontWeight: "400" - } - }, - yaxis: { - borderColor: "#999999", - borderWidth: 2, - ticks: { - show: true, - showGridline: true, - showLabel: true, - showMark: true, - size: 4, - textColor: "", - whiteSpace: "nowrap", - fontSize: "12px", - fontFamily: "'Trebuchet MS',Arial,Helvetica,sans-serif" - }, - label: { - textColor: null, - whiteSpace: null, - fontSize: null, - fontFamily: null, - fontWeight: null - } - }, - x2axis: {... - }, - ... - y9axis: {... - } - } -}
”seriesStyles” is a style object that will be applied to all series in the plot. It will forcibly override any styles applied on the individual series. “axesStyles” is a style object that will be applied to all axes in the plot. It will also forcibly override any styles on the individual axes.
The example shown above has series options for a line series. Options for other series types are shown below:
{ - color: "#4bb2c5", - seriesColors: ["#4bb2c5", "#EAA228", "#c5b47f", "#579575", "#839557", "#958c12", "#953579", "#4b5de4", "#d8b83f", "#ff5800", "#0085cc", "#c747a3", "#cddf54", "#FBD178", "#26B4E3", "#bd70c7"], - lineWidth: 2.5, - shadow: true, - barPadding: 2, - barMargin: 10, - barWidth: 15.09375, - highlightColors: ["rgb(129,201,214)", "rgb(129,201,214)", "rgb(129,201,214)", "rgb(129,201,214)", "rgb(129,201,214)", "rgb(129,201,214)", "rgb(129,201,214)", "rgb(129,201,214)"] -}
{ - seriesColors: ["#4bb2c5", "#EAA228", "#c5b47f", "#579575", "#839557", "#958c12", "#953579", "#4b5de4", "#d8b83f", "#ff5800", "#0085cc", "#c747a3", "#cddf54", "#FBD178", "#26B4E3", "#bd70c7"], - padding: 20, - sliceMargin: 0, - fill: true, - shadow: true, - startAngle: 0, - lineWidth: 2.5, - highlightColors: ["rgb(129,201,214)", "rgb(240,189,104)", "rgb(214,202,165)", "rgb(137,180,158)", "rgb(168,180,137)", "rgb(180,174,89)", "rgb(180,113,161)", "rgb(129,141,236)", "rgb(227,205,120)", "rgb(255,138,76)", "rgb(76,169,219)", "rgb(215,126,190)", "rgb(220,232,135)", "rgb(200,167,96)", "rgb(103,202,235)", "rgb(208,154,215)"] -}
{ - color: "#4bb2c5", - lineWidth: 2, - shadow: true, - padding: { - top: 20, - right: 20, - bottom: 20, - left: 20 - }, - sectionMargin: 6, - seriesColors: ["#4bb2c5", "#EAA228", "#c5b47f", "#579575", "#839557", "#958c12", "#953579", "#4b5de4", "#d8b83f", "#ff5800", "#0085cc", "#c747a3", "#cddf54", "#FBD178", "#26B4E3", "#bd70c7"], - highlightColors: ["rgb(147,208,220)", "rgb(242,199,126)", "rgb(220,210,178)", "rgb(154,191,172)", "rgb(180,191,154)", "rgb(191,186,112)", "rgb(191,133,174)", "rgb(147,157,238)", "rgb(231,212,139)", "rgb(255,154,102)", "rgb(102,181,224)", "rgb(221,144,199)", "rgb(225,235,152)", "rgb(200,167,96)", "rgb(124,210,238)", "rgb(215,169,221)"] -}
this.themes = {}
hash of themes managed by the theme engine. Indexed by theme name.
this.activeTheme=null
Pointer to currently active theme
$.jqplot.ThemeEngine.prototype.get = function(name)
Get and return the named theme or the active theme if no name given.
Theme instance of given name.
$.jqplot.ThemeEngine.prototype.getThemeNames = function()
Return the list of theme names in this manager in alpha-numerical order.
None
A the list of theme names in this manager in alpha-numerical order.
$.jqplot.ThemeEngine.prototype.getThemes = function()
Return a list of themes in alpha-numerical order by name.
A list of themes in alpha-numerical order by name.
$.jqplot.ThemeEngine.prototype.remove = function(name)
Remove the given theme from the themeEngine.
true on success, false on failure.
$.jqplot.ThemeEngine.prototype.newTheme = function(name,obj)
Create a new theme based on the default theme, adding it the themeEngine.
new Theme object.
$.jqplot.ThemeEngine.prototype.rename = function (oldName,newName)
Rename a theme.
$.jqplot.ThemeEngine.prototype.copy = function (sourceName,targetName,obj)
Create a copy of an existing theme in the themeEngine, adding it the themeEngine.
jQuery namespace to attach functions to jQuery elements.
This document will help you understand how jqPlot’s options relate to the API documentation and the jqPlot object itself. For a listing of options available to jqPlot, see jqPlot Options in the jqPlotOptions.txt file.
The key to effectively using jqPlot is understanding jqPlot’s options. The online documentation is API documentation. While it explains what attributes and methods various objects posses, it doesn’t explain how to use or set those attributes through options. This tutorial will help explain that.
Lets assume you are creating a plot like this:
chart = $.jqplot('chart', dataSeries, optionsObj);
First, note that you shouldn’t try to directly set attributes on the “chart” object (like chart.grid.shadow) after your call to $.jqplot(). At best this won’t do anything **(see below). You should pass options in via the “optionsObj”.
the optionsObj really represents the plot object (jqPlot object, not to be confused with the $.jqplot function which will create a jqPlot object). Attributes you specify on that object will be merged with attributes in the jqPlot object. The axes, legend, series, etc. are attributes on the jqPlot object. The jqPlot/optionsObj object looks something like (only some attributes shown):
jqPlot-| - |-seriesColors - |-textColor - |-fontFamily - |-fontSize - |-stackSeries - |-series(Array)-| - | |-Series1-| - | | |-lineWidth - | | |-linePattern - | | |-shadow - | | |-showLine - | | |-showMarker - | | |-color - | |-Series2... - | |-... - | |-SeriesN - | - |-grid(Object)-| - | |-drawGridLines - | |-background - | |-borderColor - | |-borderWidth - | |-shadow - | - |-title(Object)-| - | |-text - | |-show - | |-fontFamily - | |-fontSize - | |-textAlign - | |-textColor - | - |-axes(Object)-| - | |-xais-| - | | |-min - | | |-max - | | |-numberTicks - | | |-showTicks - | | |-showTickMarks - | | |-pad - | - | ... and so on
The optionsObj should follow the same construction as if it were a jqPlot object (with some exceptions/shortcuts I’ll mention in a moment). So generally, when you see something like “this.drawGridLines” in the grid properties in the docs, just replace “this” with “grid” in your options object. So it becomes optionsObj.grid.drawGridLines. Do likewise with the other objects in the plot, replacing “this”, with the respective attribute on the plot like “legend” or “title”. Series and Axes are handled a little different, because series is an array and axes has 4 distinct children “xaxis”, “yaxis”, “x2axis” and “y2axis”.
So, to remove the shadow from the grid and change the grid border size you would do:
optionObj = {grid:{shadow:false, borderWidth:9.0}};
To do the same as above but also make all the text in the plot red you would do:
optionObj = { - textColor:"#ff0000", - grid:{shadow:false, borderWidth:9.0} -}
Here is a more deeply nested example. Say you want to specify a min and max on your y axis and use a specific color for your second series. That would look like:
optionsObj = { - axes:{yaxis:{min:5, max:230}}, - series:[{},{color:"#33ff66"}] -}
Note that series options are an array in order of the series data you sent in to your plot. To get to the second series, you have to put an object (even if empty) in place of the first series.
There is a handy shortcut to assign options to all axes or all series at one go. Use axesDefaults and seriesDefaults. So, if you wanted both x and y axes to start at 0 and you wanted all series to not show markers, you could do:
optionsObj = {axesDefaults:{min:0}, seriesDefaults:{showMarker:false}}
Another shortcut is for the plot title. Normally, you would assign options to the title as an object. If you specify a title option as a string, it will assign that to the title.text property automatically. So these two are equivalent:
optionsObj = {title:{text:"My Plot"}}
and
optionsObj = {title:"My Plot"}
Where things need more explaination is with renderers, plugins and their options. Briefly, what’s renderer, what’s a plugin.
A renderer is an object that is used to draw something and gets attached to an existing object in the plot in order to draw it. A plugin does more than just provide drawing functionality to an object. It will do more like calculate a trend line, change the cursor, provide event driven functionality, etc. I consider renderers plugins, but plugins don’t have to be renderers.
So, how do you use renderers, plugins, and specify their options? Some common renderes are for bar charts and category axes. If you want to render your series as a bar chart with each set of bars showing up in a category on the x axis, you do:
optionsObj = { - seriesDefaults:{renderer:$.jqplot.BarRenderer}, - axes:{xaxis:{renderer:$.jqplot.CategoryAxisRenderer}} -}
This replaces the default renderer used for all series in the plot with a bar renderer and the x axis default renderer (but not any other axis) with a category renderer.
Now, how would I assign options to those renderers? The renderer’s attributes may not be present in the pre-existing jqPlot object, they may be specific to the renderer. This is done through the “rendererOptions” option on the appropriate object. So, if I wanted my bars to be 25 pixels wide, I would do:
optionsObj = { - seriesDefaults:{ - renderer:$.jqplot.BarRenderer}, - rendererOptions:{ - barWidth:25 - }, - axes:{xaxis:{renderer:$.jqplot.CategoryAxisRenderer}} -}
Again, this is using the “seriesDefaults” option, which will apply options to all series in the plot. You could do the same on any particular series in the plot through the “series” options array.
Plugins are free to add their own options. For example, the highlighter plugin has it’s own set of options that are unique to it. As a result, it responds to options placed in the “highlighter” attribute of your options object. So, if I wanted to change the highlighter tooltip to fade in and out slowly and be positioned directly above the point I’m highlighting:
optionsObj = { - highlighter:{tooltipFadeSpeed:'slow', tooltipLocation:'n'} -}
Other plugins, like dragable and trendlines, add their options in with the series. This is because both of those plugins can have different options for different series in the plot. So, if you wanted to specify the color of the dragable and constrain it to drag only on the x axis as well as specify the color of the trend line you could do:
series:[{ - dragable: { - color: '#ff3366', - constrainTo: 'x' - }, - trendline: { - color: '#cccccc' - } -}]
This would apply those options to the first series only. If you had 2 series and wanted to turn off dragging and trend lines on the second series, you could do:
series:[{ - dragable: { - color: '#ff3366', - constrainTo: 'x' - }, - trendline: { - color: '#cccccc' - } -}, { - isDragable: false, - trendline:{ - show: false - } -}]
Note, series dragability is turned off with the “isDragable” option directly on the series itself, not with a suboption of “dragable”. This may be improved in the future.
I hope this is helpful. A few key points to remember:
** Note: you can set attributes after the plot is created (like plot.grid.shadow = false), but you’ll have to issue the appropriate calls to possibly reinitialize and redraw the plot. jqPlot can definitely handle this to change the plot after creation (this is how the dragable plugin updates the plot data and the trend line plugin recomputes itself when data changes). This hasn’t been documented yet, however.
Renderer which draws lines as stacked bezier curves. Data for the line will not be specified as an array of [x, y] data point values, but as a an array of [start piont, bezier curve] So, the line is specified as: [[xstart, ystart], [cp1x, cp1y, cp2x, cp2y, xend, yend]].
$.jqplot.BezierCurveRenderer.prototype.setGridData = function(plot)
converts the user data values to grid coordinates and stores them in the gridData array. Called with scope of a series.
$.jqplot.BezierCurveRenderer.prototype.makeGridData = function(data,plot)
converts any arbitrary data values to grid coordinates and returns them. This method exists so that plugins can use a series’ linerenderer to generate grid data points without overwriting the grid data associated with that series. Called with scope of a series.
A plugin renderer for jqPlot to draw a bar plot. Draws series as a line.
this.barPadding = 8
Number of pixels between adjacent bars at the same axis value.
this.barMargin = 10
Number of pixels between groups of bars at adjacent axis values.
this.barDirection = 'vertical'
’vertical’ = up and down bars, ‘horizontal’ = side to side bars
this.barWidth = null
Width of the bar in pixels (auto by devaul). null = calculated automatically.
this.shadowOffset = 2
offset of the shadow from the slice and offset of each succesive stroke of the shadow from the last.
this.shadowDepth = 5
number of strokes to apply to the shadow, each stroke offset shadowOffset from the last.
this.shadowAlpha = 0.08
transparency of the shadow (0 = transparent, 1 = opaque)
this.waterfall = false
true to enable waterfall plot.
this.groups = 1
group bars into this many groups
this.varyBarColor = false
true to color each bar of a series separately rather than have every bar of a given series the same color. If used for non-stacked multiple series bar plots, user should specify a separate ‘seriesColors’ array for each series. Otherwise, each series will set their bars to the same color array. This option has no Effect for stacked bar charts and is disabled.
True to highlight slice when moused over. This must be false to enable highlightMouseDown to highlight when clicking on a slice.
True to highlight when a mouse button is pressed over a slice. This will be disabled if highlightMouseOver is true.
this.highlightColors = []
an array of colors to use when highlighting a bar.
this.transposedData = true
NOT IMPLEMENTED YET. True if this is a horizontal bar plot and x and y values are “transposed”. Tranposed, or “swapped”, data is required prior to rev. 894 builds of jqPlot with horizontal bars. Allows backward compatability of bar renderer horizontal bars with old style data sets.
Plugin renderer to draw a x-y block chart. A Block chart has data points displayed as colored squares with a text label inside. Data must be supplied in the form:
[[x1, y1, "label 1", {css}], [x2, y2, "label 2", {css}], ...]
The label and css object are optional. If the label is ommitted, the box will collapse unless a css height and/or width is specified.
The css object is an object specifying css properties such as:
{background:'#4f98a5', border:'3px solid gray', padding:'1px'}
Note that css properties specified with the data point override defaults specified with the series.
this.css = {padding:'2px', border:'1px solid #999', textAlign:'center'}
default css styles that will be applied to all data blocks. these values will be overridden by css styles supplied with the individulal data points.
true to escape html in the box label.
this.insertBreaks = true
true to turn spaces in data block label into html breaks <br />.
this.varyBlockColors = false
true to vary the color of each block in this series according to the seriesColors array. False to set each block to the color specified on this series. This has no effect if a css background color option is specified in the renderer css options.
this.moveBlock = function (idx,x,y,duration)
Moves an individual block. More efficient than redrawing the whole series by calling plot.drawSeries(). Properties: idx - the 0 based index of the block or point in this series. x - the x coordinate in data units (value on x axis) to move the block to. y - the y coordinate in data units (value on the y axis) to move the block to. duration - optional parameter to create an animated movement. Can be a number (higher is slower animation) or ‘fast’, ‘normal’ or ‘slow’. If not provided, the element is moved without any animation.
Plugin renderer to draw a bubble chart. A Bubble chart has data points displayed as colored circles with an optional text label inside. To use the bubble renderer, you must include the bubble renderer like:
<script language="javascript" type="text/javascript" src="../src/plugins/jqplot.bubbleRenderer.js"></script>
Data must be supplied in the form:
[[x1, y1, r1, <label or {label:'text', color:color}>], ...]
where the label or options object is optional.
Note that all bubble colors will be the same unless the “varyBubbleColors” option is set to true. Colors can be specified in the data array or in the seriesColors array option on the series. If no colors are defined, the default jqPlot series of 16 colors are used. Colors are automatically cycled around again if there are more bubbles than colors.
Bubbles are autoscaled by default to fit within the chart area while maintaining relative sizes. If the “autoscaleBubbles” option is set to false, the r(adius) values in the data array a treated as literal pixel values for the radii of the bubbles.
Properties are passed into the bubble renderer in the rendererOptions object of the series options like:
seriesDefaults: { - renderer: $.jqplot.BubbleRenderer, - rendererOptions: { - bubbleAlpha: 0.7, - varyBubbleColors: false - } -}
this.varyBubbleColors = true
True to vary the color of each bubble in this series according to the seriesColors array. False to set each bubble to the color specified on this series. This has no effect if a css background color option is specified in the renderer css options.
this.autoscaleBubbles = true
True to scale the bubble radius based on plot size. False will use the radius value as provided as a raw pixel value for bubble radius.
this.autoscaleMultiplier = 1.0
Multiplier the bubble size if autoscaleBubbles is true.
this.autoscalePointsFactor = -0.07
Factor which decreases bubble size based on how many bubbles on on the chart. 0 means no adjustment for number of bubbles. Negative values will decrease size of bubbles as more bubbles are added. Values between 0 and -0.2 should work well.
this.escapeHtml = true
True to escape html in bubble label text.
True to highlight bubbles when moused over. This must be false to enable highlightMouseDown to highlight when clicking on a slice.
True to highlight when a mouse button is pressed over a bubble. This will be disabled if highlightMouseOver is true.
An array of colors to use when highlighting a slice. Calculated automatically if not supplied.
this.bubbleAlpha = 1.0
Alpha transparency to apply to all bubbles in this series.
this.highlightAlpha = null
Alpha transparency to apply when highlighting bubble. Set to value of bubbleAlpha by default.
this.bubbleGradients = false
True to color the bubbles with gradient fills instead of flat colors. NOT AVAILABLE IN IE due to lack of excanvas support for radial gradient fills. will be ignored in IE.
True to show labels on bubbles (if any), false to not show.
Renderer to draw axis labels with a canvas element to support advanced featrues such as rotated text. This renderer uses a separate rendering engine to draw the text on the canvas. Two modes of rendering the text are available. If the browser has native font support for canvas fonts (currently Mozila 3.5 and Safari 4), you can enable text rendering with the canvas fillText method. You do so by setting the “enableFontSupport” option to true.
Browsers lacking native font support will have the text drawn on the canvas using the Hershey font metrics. Even if the “enableFontSupport” option is true non-supporting browsers will still render with the Hershey font.
this.angle = 0
angle of text, measured clockwise from x axis.
label for the axis.
this.fontFamily = '"Trebuchet MS", Arial, Helvetica, sans-serif'
CSS spec for the font-family css attribute. Applies only to browsers supporting native font rendering in the canvas tag. Currently Mozilla 3.5 and Safari 4.
this.fontSize = '11pt'
CSS spec for font size.
this.fontWeight = 'normal'
this.fontStretch = 1.0
Multiplier to condense or expand font width. Applies only to browsers which don’t support canvas native font rendering.
this.textColor = '#666666'
this.enableFontSupport = true
true to turn on native canvas font support in Mozilla 3.5+ and Safari 4+. If true, label will be drawn with canvas tag native support for fonts. If false, label will be drawn with Hershey font metrics.
this.pt2px = null
Point to pixel scaling factor, used for computing height of bounding box around a label. The labels text renderer has a default setting of 1.4, which should be suitable for most fonts. Leave as null to use default. If tops of letters appear clipped, increase this. If bounding box seems too big, decrease. This is an issue only with the native font renderering capabilities of Mozilla 3.5 and Safari 4 since they do not provide a method to determine the font height.
Renderer to draw axis ticks with a canvas element to support advanced featrues such as rotated text. This renderer uses a separate rendering engine to draw the text on the canvas. Two modes of rendering the text are available. If the browser has native font support for canvas fonts (currently Mozila 3.5 and Safari 4), you can enable text rendering with the canvas fillText method. You do so by setting the “enableFontSupport” option to true.
this.markSize = 4
this.labelPosition = 'auto'
’auto’, ‘start’, ‘middle’ or ‘end’. Whether tick label should be positioned so the start, middle, or end of the tick mark.
A class of a formatter for the tick text. The default $.jqplot.DefaultTickFormatter uses sprintf.
this.fontSize = '10pt'
CSS spec for fontWeight
true to turn on native canvas font support in Mozilla 3.5+ and Safari 4+. If true, tick label will be drawn with canvas tag native support for fonts. If false, tick label will be drawn with Hershey font metrics.
this.objects = []
Optional name for the overlay object. Can be later used to retrieve the object by name.
true to show (draw), false to not draw.
Width of the line.
Type of ending placed on the line [‘round’, ‘butt’, ‘square’]
color of the line
X axis to use for positioning/scaling the line.
Y axis to use for positioning/scaling the line.
Show a tooltip with data point values.
Controls how close to line cursor must be to show tooltip. Higher number = closer to line, lower number = farther from line. 1.0 = cursor must be over line.
Where to position tooltip, ‘n’, ‘ne’, ‘e’, ‘se’, ‘s’, ‘sw’, ‘w’, ‘nw’
true = fade in/out tooltip, flase = show/hide tooltip
’slow’, ‘def’, ‘fast’, or number of milliseconds.
Pixel offset of tooltip from the highlight.
tooltipFormatString: '%d, %d' }
Format string passed the x and y values of the cursor on the line. e.g., ‘Dogs: %.2f, Cats: %d’.
A straight line.
[x, y] coordinates for the start of the line.
stop: [] }
[x, y] coordinates for the end of the line.
A straight horizontal line.
y value to position the line
x value for the start of the line, null to scale to axis min.
x value for the end of the line, null to scale to axis max.
A straight dashed horizontal line.
dashPattern: [8,8] }
Array of line, space settings in pixels. Default is 8 pixel of line, 8 pixel of space. Note, limit to a 2 element array b/c of bug with higher order arrays.
A straight vertical line.
A straight dashed vertical line.
A plugin for jqPlot to render a category style axis, with equal pixel spacing between y data values of a series.
To use this renderer, include the plugin in your source
<script type="text/javascript" language="javascript" src="plugins/jqplot.categoryAxisRenderer.js"></script>
and supply the appropriate options to your plot
{axes:{xaxis:{renderer:$.jqplot.CategoryAxisRenderer}}}
this.sortMergedLabels = false
True to sort tick labels when labels are created by merging x axis values from multiple series. That is, say you have two series like:
line1 = [[2006, 4], [2008, 9], [2009, 16]]; -line2 = [[2006, 3], [2007, 7], [2008, 6]];
If no label array is specified, tick labels will be collected from the x values of the series. With sortMergedLabels set to true, tick labels will be:
[2006, 2007, 2008, 2009]
With sortMergedLabels set to false, tick labels will be:
[2006, 2008, 2009, 2007]
Note, this property is specified on the renderOptions for the axes when creating a plot:
axes:{xaxis:{renderer:$.jqplot.CategoryAxisRenderer, rendererOptions:{sortMergedLabels:true}}}
A class of a rendering engine for creating the ticks labels displayed on the plot, See $.jqplot.AxisTickRenderer. this.tickRenderer = $.jqplot.AxisTickRenderer; this.labelRenderer = $.jqplot.AxisLabelRenderer;
Data Renderer function which converts a custom JSON data object into jqPlot data format. Set this as a callable on the jqplot dataRenderer plot option:
plot = $.jqplot('mychart', [data], { dataRenderer: $.jqplot.ciParser, ... });
Where data is an object in JSON format or a JSON encoded string conforming to the City Index API spec.
Note that calling the renderer function is handled internally by jqPlot. The user does not have to call the function. The parameters described below will automatically be passed to the ciParser function.
data array in jqPlot format.
Plugin class representing the cursor as displayed on the plot.
this.style = 'crosshair'
CSS spec for cursor style
this.show = $.jqplot.config.enablePlugins
wether to show the cursor or not.
this.showTooltip = true
show a cursor position tooltip. Location of the tooltip will be controlled by followMouse and tooltipLocation.
this.followMouse = false
Tooltip follows the mouse, it is not at a fixed location. Tooltip will show on the grid at the location given by tooltipLocation, offset from the grid edge by tooltipOffset.
this.tooltipLocation = 'se'
Where to position tooltip. If followMouse is true, this is relative to the cursor, otherwise, it is relative to the grid. One of ‘n’, ‘ne’, ‘e’, ‘se’, ‘s’, ‘sw’, ‘w’, ‘nw’
this.tooltipOffset = 6
Pixel offset of tooltip from the grid boudaries or cursor center.
this.showTooltipGridPosition = false
show the grid pixel coordinates of the mouse.
this.showTooltipUnitPosition = true
show the unit (data) coordinates of the mouse.
this.showTooltipDataPosition = false
Used with showVerticalLine to show intersecting data points in the tooltip.
this.tooltipFormatString = '%.4P, %.4P'
sprintf format string for the tooltip. Uses Ash Searle’s javascript sprintf implementation found here: http://hexmen.com/blog/2007/03/printf-sprintf/ See http://perldoc.perl.org/functions/sprintf.html for reference Note, if showTooltipDataPosition is true, the default tooltipFormatString will be set to the cursorLegendFormatString, not the default given here.
this.useAxesFormatters = true
Use the x and y axes formatters to format the text in the tooltip.
this.tooltipAxisGroups = []
Show position for the specified axes. This is an array like [[‘xaxis’, ‘yaxis’], [‘xaxis’, ‘y2axis’]] Default is to compute automatically for all visible axes.
this.zoom = false
Enable plot zooming.
this.looseZoom = true
Will expand zoom range to provide more rounded tick values. Works only with linear, log and date axes.
this.clickReset = false
Will reset plot zoom if single click on plot without drag.
this.dblClickReset = true
Will reset plot zoom if double click on plot without drag.
this.showVerticalLine = false
draw a vertical line across the plot which follows the cursor. When the line is near a data point, a special legend and/or tooltip can be updated with the data values.
this.showHorizontalLine = false
draw a horizontal line across the plot which follows the cursor.
this.constrainZoomTo = 'none'
’none’, ‘x’ or ‘y’
this.intersectionThreshold = 2
pixel distance from data point or marker to consider cursor lines intersecting with point. If data point markers are not shown, this should be >= 1 or will often miss point intersections.
this.showCursorLegend = false
Replace the plot legend with an enhanced legend displaying intersection information.
this.cursorLegendFormatString = $.jqplot.Cursor.cursorLegendFormatString
Format string used in the cursor legend. If showTooltipDataPosition is true, this will also be the default format string used by tooltipFormatString.
this.constrainOutsideZoom = true
True to limit actual zoom area to edges of grid, even when zooming outside of plot area. That is, can’t zoom out by mousing outside plot.
this.showTooltipOutsideZoom = false
True will keep updating the tooltip when zooming of the grid.
$.jqplot.Cursor.zoomProxy = function(targetPlot,controllerPlot)
links targetPlot to controllerPlot so that plot zooming of targetPlot will be controlled by zooming on the controllerPlot. controllerPlot will not actually zoom, but acts as an overview plot. Note, the zoom options must be set to true for zoomProxy to work.
A plugin for a jqPlot to render an axis as a series of date values. This renderer has no options beyond those supplied by the Axis class. It supplies it’s own tick formatter, so the tickOptions.formatter option should not be overridden.
Thanks to Ken Synder for his enhanced Date instance methods which are included with this code http://kendsnyder.com/sandbox/date/.
<script type="text/javascript" language="javascript" src="plugins/jqplot.dateAxisRenderer.js"></script>
{axes:{xaxis:{renderer:$.jqplot.DateAxisRenderer}}}
Dates can be passed into the axis in almost any recognizable value and will be parsed. They will be rendered on the axis in the format specified by tickOptions.formatString. e.g. tickOptions.formatString = ‘%Y-%m-%d’.
Accecptable format codes are:
Code Result Description - == Years == -%Y 2008 Four-digit year -%y 08 Two-digit year - == Months == -%m 09 Two-digit month -%#m 9 One or two-digit month -%B September Full month name -%b Sep Abbreviated month name - == Days == -%d 05 Two-digit day of month -%#d 5 One or two-digit day of month -%e 5 One or two-digit day of month -%A Sunday Full name of the day of the week -%a Sun Abbreviated name of the day of the week -%w 0 Number of the day of the week (0 = Sunday, 6 = Saturday) -%o th The ordinal suffix string following the day of the month - == Hours == -%H 23 Hours in 24-hour format (two digits) -%#H 3 Hours in 24-hour integer format (one or two digits) -%I 11 Hours in 12-hour format (two digits) -%#I 3 Hours in 12-hour integer format (one or two digits) -%p PM AM or PM - == Minutes == -%M 09 Minutes (two digits) -%#M 9 Minutes (one or two digits) - == Seconds == -%S 02 Seconds (two digits) -%#S 2 Seconds (one or two digits) -%s 1206567625723 Unix timestamp (Seconds past 1970-01-01 00:00:00) - == Milliseconds == -%N 008 Milliseconds (three digits) -%#N 8 Milliseconds (one to three digits) - == Timezone == -%O 360 difference in minutes between local time and GMT -%Z Mountain Standard Time Name of timezone as reported by browser -%G -06:00 Hours and minutes between GMT - == Shortcuts == -%F 2008-03-26 %Y-%m-%d -%T 05:06:30 %H:%M:%S -%X 05:06:30 %H:%M:%S -%x 03/26/08 %m/%d/%y -%D 03/26/08 %m/%d/%y -%#c Wed Mar 26 15:31:00 2008 %a %b %e %H:%M:%S %Y -%v 3-Sep-2008 %e-%b-%Y -%R 15:31 %H:%M -%r 3:31:00 PM %I:%M:%S %p - == Characters == -%n \n Newline -%t \t Tab -%% % Percent Symbol
Plugin renderer to draw a donut chart. x values, if present, will be used as slice labels. y values give slice size.
To use this renderer, you need to include the donut renderer plugin, for example:
<script type="text/javascript" src="plugins/jqplot.donutRenderer.js"></script>
Properties described here are passed into the $.jqplot function as options on the series renderer. For example:
plot2 = $.jqplot('chart2', [s1, s2], { - seriesDefaults: { - renderer:$.jqplot.DonutRenderer, - rendererOptions:{ - sliceMargin: 2, - innerDiameter: 110, - startAngle: -90 - } - } -});
A donut plot will trigger events on the plot target according to user interaction. All events return the event object, the series index, the point (slice) index, and the point data for the appropriate slice.
this.diameter = null
Outer diameter of the donut, auto computed by default
this.innerDiameter = null
Inner diameter of the donut, auto calculated by default. If specified will override thickness value.
this.thickness = null
thickness of the donut, auto computed by default Overridden by if innerDiameter is specified.
this.padding = 20
padding between the donut and plot edges, legend, etc.
this.sliceMargin = 0
angular spacing between donut slices in degrees.
this.ringMargin = null
pixel distance between rings, or multiple series in a donut plot. null will compute ringMargin based on sliceMargin.
this.fill = true
true or false, wether to fil the slices.
this.shadowAlpha = 0.07
an array of colors to use when highlighting a slice.
this.dataLabels = 'percent'
Either ‘label’, ‘value’, ‘percent’ or an array of labels to place on the pie slices. Defaults to percentage of each pie slice.
this.showDataLabels = false
true to show data labels on slices.
this.dataLabelFormatString = null
Format string for data labels. If none, ‘%s’ is used for “label” and for arrays, ‘%d’ for value and ‘%d%%’ for percentage.
this.dataLabelThreshold = 3
this.dataLabelPositionFactor = 0.4
A Multiplier (0-1) of the pie radius which controls position of label on slice. Increasing will slide label toward edge of pie, decreasing will slide label toward center of pie.
this.dataLabelNudge = 0
Number of pixels to slide the label away from (+) or toward (-) the center of the pie.
this.startAngle = 0
Angle to start drawing donut in degrees. According to orientation of canvas coordinate system: 0 = on the positive x axis -90 = on the positive y axis. 90 = on the negaive y axis. 180 or - 180 = on the negative x axis.
Legend Renderer specific to donut plots. Set by default when user creates a donut plot.
this.numberRows = null
Maximum number of rows in the legend. 0 or null for unlimited.
this.numberColumns = null
Maximum number of columns in the legend. 0 or null for unlimited.
Plugin to make plotted points dragable by the user.
CSS color spec for the dragged point (and adjacent line segment or bar).
this.constrainTo = 'none'
Constrain dragging motion to an axis or to none. Allowable values are ‘none’, ‘x’, ‘y’
this.seriesToggle = 'normal'
false to not enable series on/off toggling on the legend. true or a fadein/fadeout speed (number of milliseconds or ‘fast’, ‘normal’, ‘slow’) to enable show/hide of series on click of legend item.
this.disableIEFading = true
true to toggle series with a show/hide method only and not allow fading in/out. This is to overcome poor performance of fade in some versions of IE.
Plugin renderer to draw a funnel chart. x values, if present, will be used as labels. y values give area size.
Funnel charts will draw a single series only.
To use this renderer, you need to include the funnel renderer plugin, for example:
<script type="text/javascript" src="plugins/jqplot.funnelRenderer.js"></script>
plot2 = $.jqplot('chart2', [s1, s2], { - seriesDefaults: { - renderer:$.jqplot.FunnelRenderer, - rendererOptions:{ - sectionMargin: 12, - widthRatio: 0.3 - } - } -});
IMPORTANT
The funnel renderer will reorder data in descending order so the largest value in the data set is first and displayed on top of the funnel. Data will then be displayed in descending order down the funnel. The area of each funnel section will correspond to the value of each data point relative to the sum of all values. That is section area is proportional to section value divided by sum of all section values.
If your data is not in descending order when passed into the plot, it will be reordered when stored in the series.data property. A copy of the unordered data is kept in the series._unorderedData property.
A funnel plot will trigger events on the plot target according to user interaction. All events return the event object, the series index, the point (section) index, and the point data for the appropriate section. Note the point index will referr to the ordered data, not the original unordered data.
this.padding = {top: 20, right: 20, bottom: 20, left: 20}
padding between the funnel and plot edges, legend, etc.
this.sectionMargin = 6
spacing between funnel sections in pixels.
true or false, wether to fill the areas.
offset of the shadow from the area and offset of each succesive stroke of the shadow from the last.
True to highlight area when moused over. This must be false to enable highlightMouseDown to highlight when clicking on a area.
True to highlight when a mouse button is pressed over a area. This will be disabled if highlightMouseOver is true.
array of colors to use when highlighting an area.
this.widthRatio = 0.2
The ratio of the width of the top of the funnel to the bottom. a ratio of 0 will make an upside down pyramid.
width of line if areas are stroked and not filled.
Legend Renderer specific to funnel plots. Set by default when the user creates a funnel plot.
Plugin which will highlight data points when they are moused over.
To use this plugin, include the js file in your source:
<script type="text/javascript" src="plugins/jqplot.highlighter.js"></script>
A tooltip providing information about the data point is enabled by default. To disable the tooltip, set “showTooltip” to false.
You can control what data is displayed in the tooltip with various options. The “tooltipAxes” option controls wether the x, y or both data values are displayed.
Some chart types (e.g. hi-low-close) have more than one y value per data point. To display the additional values in the tooltip, set the “yvalues” option to the desired number of y values present (3 for a hlc chart).
By default, data values will be formatted with the same formatting specifiers as used to format the axis ticks. A custom format code can be supplied with the tooltipFormatString option. This will apply to all values in the tooltip.
For more complete control, the “formatString” option can be set. This Allows conplete control over tooltip formatting. Values are passed to the format string in an order determined by the “tooltipAxes” and “yvalues” options. So, if you have a hi-low-close chart and you just want to display the hi-low-close values in the tooltip, you could set a formatString like:
highlighter: { - tooltipAxes: 'y', - yvalues: 3, - formatString:'<table class="jqplot-highlighter"> - <tr><td>hi:</td><td>%s</td></tr> - <tr><td>low:</td><td>%s</td></tr> - <tr><td>close:</td><td>%s</td></tr></table>' -}
true to show the highlight.
this.markerRenderer = new $.jqplot.MarkerRenderer({shadow:false})
Renderer used to draw the marker of the highlighted point. Renderer will assimilate attributes from the data point being highlighted, so no attributes need set on the renderer directly. Default is to turn off shadow drawing on the highlighted point.
true to show the marker
this.lineWidthAdjust = 2.5
Pixels to add to the lineWidth of the highlight.
this.sizeAdjust = 5
Pixels to add to the overall size of the highlight.
this.tooltipLocation = 'nw'
this.fadeTooltip = true
this.tooltipFadeSpeed = "fast"
this.tooltipOffset = 2
this.tooltipAxes = 'both'
Which axes to display in tooltip, ‘x’, ‘y’ or ‘both’, ‘xy’ or ‘yx’ ‘both’ and ‘xy’ are equivalent, ‘yx’ reverses order of labels.
this.tooltipFormatString = '%.5P'
sprintf format string for the tooltip. Uses Ash Searle’s javascript sprintf implementation found here: http://hexmen.com/blog/2007/03/printf-sprintf/ See http://perldoc.perl.org/functions/sprintf.html for reference. Additional “p” and “P” format specifiers added by Chris Leonello.
this.formatString = null
alternative to tooltipFormatString will format the whole tooltip text, populating with x, y values as indicated by tooltipAxes option. So, you could have a tooltip like: ‘Date: %s, number of cats: %d’ to format the whole tooltip at one go. If useAxesFormatters is true, values will be formatted according to Axes formatters and you can populate your tooltip string with %s placeholders.
this.yvalues = 1
Number of y values to expect in the data point array. Typically this is 1. Certain plots, like OHLC, will have more y values in each data point array.
this.bringSeriesToFront = false
This option requires jQuery 1.4+ True to bring the series of the highlighted point to the front of other series.
A plugin for a jqPlot to render a logarithmic axis.
<script type="text/javascript" language="javascript" src="plugins/jqplot.logAxisRenderer.js"></script>
{axes:{xaxis:{renderer:$.jqplot.LogAxisRenderer}}}
Default properties which will be applied directly to the series.
Properties
this.minorTicks = 'auto'
An axis renderer for a Mekko chart. Should be used with a Mekko chart where the mekkoRenderer is used on the series. Displays the Y axis as a range from 0 to 1 (0 to 100%) and the x axis with a tick for each series scaled to the sum of all the y values.
this.tickMode
How to space the ticks on the axis. ‘bar’ will place a tick at the width of each bar. This is the default for the x axis. ‘even’ will place ticks at even intervals. This is the default for x2 axis and y axis. y axis cannot be changed.
this.barLabelRenderer = $.jqplot.AxisLabelRenderer
renderer to use to draw labels under each bar.
this.barLabels = this.barLabels || []
array of labels to put under each bar.
this.barLabelOptions = {}
options object to pass to the bar label renderer.
Draws a Mekko style chart which shows 3 dimensional data on a 2 dimensional graph. the $.jqplot.MekkoAxisRenderer should be used with mekko charts. The mekko renderer overrides the default legend renderer with it’s own $.jqplot.MekkoLegendRenderer which allows more flexibility to specify number of rows and columns in the legend.
Data is specified per bar in the chart. You can specify data as an array of y values, or as an array of [label, value] pairs. Note that labels are used only on the first series. Labels on subsequent series are ignored:
bar1 = [['shirts', 8],['hats', 14],['shoes', 6],['gloves', 16],['dolls', 12]]; -bar2 = [15,6,9,13,6]; -bar3 = [['grumpy',4],['sneezy',2],['happy',7],['sleepy',9],['doc',7]];
If you want to place labels for each bar under the axis, you use the barLabels option on the axes. The bar labels can be styled with the “.jqplot-mekko-barLabel” css class.
barLabels = ['Mickey Mouse', 'Donald Duck', 'Goofy']; -axes:{xaxis:{barLabels:barLabels}}
color of the borders between areas on the chart
this.showBorders = true
True to draw borders lines between areas on the chart. False will draw borders lines with the same color as the area.
$.jqplot.MekkoRenderer.prototype.setGridData = function(plot)
converts the user data values to grid coordinates and stores them in the gridData array. Will convert user data into appropriate rectangles. Called with scope of a series.
$.jqplot.MekkoRenderer.prototype.makeGridData = function(data,plot)
Legend renderer used by mekko charts with options for controlling number or rows and columns as well as placement outside of plot area.
Plugin renderer to draw a meter gauge chart.
Data consists of a single series with 1 data point to position the gauge needle.
To use this renderer, you need to include the meter gauge renderer plugin, for example:
<script type="text/javascript" src="plugins/jqplot.meterGaugeRenderer.js"></script>
plot0 = $.jqplot('chart0',[[18]],{ - title: 'Network Speed', - seriesDefaults: { - renderer: $.jqplot.MeterGaugeRenderer, - rendererOptions: { - label: 'MB/s' - } - } -});
A meterGauge plot does not support events.
Outer diameter of the meterGauge, auto computed by default
this.padding = null
padding between the meterGauge and plot edges, auto calculated by default.
offset of the shadow from the gauge ring and offset of each succesive stroke of the shadow from the last.
this.shadowDepth = 4
this.background = "#efefef"
background color of the inside of the gauge.
this.ringColor = "#BBC6D0"
color of the outer ring, hub, and needle of the gauge.
this.tickColor = "989898"
color of the tick marks around the gauge.
this.ringWidth = null
width of the ring around the gauge. Auto computed by default.
this.min
Minimum value on the gauge. Auto computed by default
this.max
Maximum value on the gauge. Auto computed by default
Array of tick values. Auto computed by default.
true to show ticks around gauge.
this.showTickLabels = true
true to show tick labels next to ticks.
A gauge label like ‘kph’ or ‘Volts’
this.labelHeightAdjust = 0
Number of Pixels to offset the label up (-) or down (+) from its default position.
this.labelPosition = 'inside'
Where to position the label, either ‘inside’ or ‘bottom’.
this.intervals = []
Array of ranges to be drawn around the gauge. Array of form:
[value1, value2, ...]
indicating the values for the first, second, ... intervals.
this.intervalColors = [ "#4bb2c5", "#EAA228", "#c5b47f", "#579575", "#839557", "#958c12", "#953579", "#4b5de4", "#d8b83f", "#ff5800", "#0085cc", "#c747a3", "#cddf54", "#FBD178", "#26B4E3", "#bd70c7"]
Array of colors to use for the intervals.
this.intervalInnerRadius = null
Radius of the inner circle of the interval ring.
this.intervalOuterRadius = null
Radius of the outer circle of the interval ring.
this.tickSpacing = 30
Degrees between ticks. This is a target number, if incompatible span and ticks are supplied, a suitable spacing close to this value will be computed.
this.hubRadius = null
Radius of the hub at the bottom center of gauge which the needle attaches to. Auto computed by default
this.tickPadding = null
padding of the tick marks to the outer ring and the tick labels to marks. Auto computed by default.
this.needleThickness = null
Maximum thickness the needle. Auto computed by default.
this.needlePad = 6
Padding between needle and inner edge of the ring when the needle is at the min or max gauge value.
this.pegNeedle = true
True will stop needle just below/above the min/max values if data is below/above min/max, as if the meter is “pegged”.
jqPlot Plugin to draw Open Hi Low Close, Candlestick and Hi Low Close charts.
To use this plugin, include the renderer js file in your source:
<script type="text/javascript" src="plugins/jqplot.ohlcRenderer.js"></script>
You will most likely want to use a date axis renderer for the x axis also, so include the date axis render js file also:
<script type="text/javascript" src="plugins/jqplot.dateAxisRenderer.js"></script>
series: [{renderer:$.jqplot.OHLCRenderer}]
For OHLC and candlestick charts, data should be specified like so:
dat = [['07/06/2009',138.7,139.68,135.18,135.4], ['06/29/2009',143.46,144.66,139.79,140.02], ...]
If the data array has only 4 values per point instead of 5, the renderer will create a Hi Low Close chart instead. In that case, data should be supplied like:
dat = [['07/06/2009',139.68,135.18,135.4], ['06/29/2009',144.66,139.79,140.02], ...]
To generate a candlestick chart instead of an OHLC chart, set the “candlestick” option to true:
series: [{renderer:$.jqplot.OHLCRenderer, rendererOptions:{candleStick:true}}],
this.candleStick = false
true to render chart as candleStick. Must have an open price, cannot be a hlc chart.
this.tickLength = 'auto'
length of the line in pixels indicating open and close price. Default will auto calculate based on plot width and number of points displayed.
this.bodyWidth = 'auto'
width of the candlestick body in pixels. Default will auto calculate based on plot width and number of candlesticks displayed.
this.openColor = null
color of the open price tick mark. Default is series color.
this.closeColor = null
color of the close price tick mark. Default is series color.
this.wickColor = null
color of the hi-lo line thorugh the candlestick body. Default is the series color.
this.fillUpBody = false
true to render an “up” day (close price greater than open price) with a filled candlestick body.
this.fillDownBody = true
true to render a “down” day (close price lower than open price) with a filled candlestick body.
this.upBodyColor = null
Color of candlestick body of an “up” day. Default is series color.
this.downBodyColor = null
Color of candlestick body on a “down” day. Default is series color.
this.hlc = false
true if is a hi-low-close chart (no open price). This is determined automatically from the series data.
Width of the hi-low line and open/close ticks. Must be set in the rendererOptions for the series.
Plugin renderer to draw a pie chart. x values, if present, will be used as slice labels. y values give slice size.
To use this renderer, you need to include the pie renderer plugin, for example:
<script type="text/javascript" src="plugins/jqplot.pieRenderer.js"></script>
plot2 = $.jqplot('chart2', [s1, s2], { - seriesDefaults: { - renderer:$.jqplot.PieRenderer, - rendererOptions:{ - sliceMargin: 2, - startAngle: -90 - } - } -});
A pie plot will trigger events on the plot target according to user interaction. All events return the event object, the series index, the point (slice) index, and the point data for the appropriate slice.
Outer diameter of the pie, auto computed by default
padding between the pie and plot edges, legend, etc.
angular spacing between pie slices in degrees.
Threshhold in percentage (0-100) of pie area, below which no label will be displayed. This applies to all label types, not just to percentage labels.
this.dataLabelPositionFactor = 0.52
this.dataLabelNudge = 2
this.dataLabelCenterOn = true
True to center the data label at its position. False to set the inside facing edge of the label at its position.
Angle to start drawing pie in degrees. According to orientation of canvas coordinate system: 0 = on the positive x axis -90 = on the positive y axis. 90 = on the negaive y axis. 180 or - 180 = on the negative x axis.
Legend Renderer specific to pie plots. Set by default when user creates a pie plot.
Plugin for putting labels at the data points.
<script type="text/javascript" src="plugins/jqplot.pointLabels.js"></script>
By default, the last value in the data ponit array in the data series is used for the label. For most series renderers, extra data can be added to the data point arrays and the last value will be used as the label.
For instance, this series:
[[1,4], [3,5], [7,2]]
Would, by default, use the y values in the labels. Extra data can be added to the series like so:
[[1,4,'mid'], [3 5,'hi'], [7,2,'low']]
And now the point labels would be ‘mid’, ‘low’, and ‘hi’.
Options to the point labels and a custom labels array can be passed into the “pointLabels” option on the series option like so:
series:[{pointLabels:{ - labels:['mid', 'hi', 'low'], - location:'se', - ypadding: 12 - } -}]
A custom labels array in the options takes precendence over any labels in the series data. If you have a custom labels array in the options, but still want to use values from the series array as labels, set the “labelsFromSeries” option to true.
By default, html entities (<, >, etc.) are escaped in point labels. If you want to include actual html markup in the labels, set the “escapeHTML” option to false.
show the labels or not.
this.location = 'n'
compass location where to position the label around the point. ‘n’, ‘ne’, ‘e’, ‘se’, ‘s’, ‘sw’, ‘w’, ‘nw’
this.labelsFromSeries = false
true to use labels within data point arrays.
this.seriesLabelIndex = null
array index for location of labels within data point arrays. if null, will use the last element of the data point array.
array of arrays of labels, one array for each series.
this.stackedValue = false
true to display value as stacked in a stacked plot. no effect if labels is specified.
this.ypadding = 6
vertical padding in pixels between point and label
this.xpadding = 6
horizontal padding in pixels between point and label
this.escapeHTML = true
true to escape html entities in the labels. If you want to include markup in the labels, set to false.
this.edgeTolerance = -5
Number of pixels that the label must be away from an axis boundary in order to be drawn. Negative values will allow overlap with the grid boundaries.
this.hideZeros = false
true to not show a label for a value which is 0.
this.position = null
Position of axis. Values are: top, bottom , left, center, right. By default, x and x2 axes are bottom, y axis is center.
this.barPadding = 10
True to fill the bars.
this.offsetBars = false
False will center bars on their y value. True will push bars up by 1/2 bar width to fill between their y values. If true, there needs to be 1 more tick than there are bars.
Plugin which will automatically compute and draw trendlines for plotted data.
Wether or not to show the trend line.
CSS color spec for the trend line. By default this wil be the same color as the primary line.
this.renderer = new $.jqplot.LineRenderer()
Renderer to use to draw the trend line. The data series that is plotted may not be rendered as a line. Therefore, we use our own line renderer here to draw a trend line.
this.rendererOptions = {marker:{show:false}}
Options to pass to the line renderer. By default, markers are not shown on trend lines.
Label for the trend line to use in the legend.
this.type = 'linear'
Either ‘exponential’, ‘exp’, or ‘linear’.
true or false, wether or not to show the shadow.
this.markerRenderer = {show:false}
Renderer to use to draw markers on the line. I think this is wrong.
Width of the trend line.
Angle of the shadow on the trend line.
this.shadowOffset = 1.0
pixel offset for each stroke of the shadow.
Alpha transparency of the shadow.
number of strokes to make of the shadow.
jqPlot is a jQuery plugin to generate pure client-side javascript charts in your web pages.
The jqPlot home page is at http://www.jqplot.com/.
The project page and downloads are at http://www.bitbucket.org/cleonello/jqplot/.
Below are a few examples to demonstrate jqPlot usage. These plots are shown as static images. Many more examples of dynamically rendered plots can be seen on the test and examples pages here: ../../tests/.
jqPlot requires jQuery (1.4+ required for certain features). jQuery is included in the distribution. To use jqPlot include jquery, the jqPlot jQuery plugin, jqPlot css file and optionally the excanvas script for IE support in your web page. Note, excanvas is required only for IE versions below 9. IE 9 includes native support for the canvas element and does not require excanvas:
<!--[if lt IE 9]><script language="javascript" type="text/javascript" src="excanvas.js"></script><![endif]--> -<script language="javascript" type="text/javascript" src="jquery.min.js"></script> -<script language="javascript" type="text/javascript" src="jquery.jqplot.min.js"></script> -<link rel="stylesheet" type="text/css" href="jquery.jqplot.css" />
Add a container (target) to your web page where you want your plot to show up. Be sure to give your target a width and a height:
<div id="chartdiv" style="height:400px;width:300px; "></div>
Then, create the actual plot by calling the $.jqplot plugin with the id of your target and some data:
$.jqplot('chartdiv', [[[1, 2],[3,5.12],[5,13.1],[7,33.6],[9,85.9],[11,219.9]]]);
Which will produce a chart like:
You can customize the plot by passing options to the $.jqplot function. Options are described in jqPlot Options in the jqPlotOptions.txt file. An example of options usage:
$.jqplot('chartdiv', [[[1, 2],[3,5.12],[5,13.1],[7,33.6],[9,85.9],[11,219.9]]], -{ title:'Exponential Line', - axes:{yaxis:{min:-10, max:240}}, - series:[{color:'#5FAB78'}] -});
Which will produce a plot like:
You can use jqPlot plugins (that is, plugins to the jqPlot plugin) by including them in your html after you include the jqPlot plugin. Here is how to include the log axis plugin:
<link rel="stylesheet" type="text/css" href="jquery.jqplot.css" /> -<!--[if IE]><script language="javascript" type="text/javascript" src="excanvas.js"></script><![endif]--> -<script language="javascript" type="text/javascript" src="jquery.min.js"></script> -<script language="javascript" type="text/javascript" src="jquery.jqplot.min.js"></script> -<script language="javascript" type="text/javascript" src="jqplot.logAxisRenderer.js"></script>
Important note: For jqplot builds r529 and above (0.9.7r529 and higher), you must explicitly enable plugins via either the { show: true } plugin option to the plot or by using the $.jqplot.config.enablePlugins = true; config options set on the page before plot creation. Only plugins that can be immediately active upon loading are affected. This includes non-renderer plugins like cursor, dragable, highlighter, and trendline.
Here is a the same $.jqplot call but with a log y axis:
$.jqplot('chartdiv', [[[1, 2],[3,5.12],[5,13.1],[7,33.6],[9,85.9],[11,219.9]]], -{ title:'Exponential Line', - axes:{yaxis:{renderer: $.jqplot.LogAxisRenderer}}, - series:[{color:'#5FAB78'}] -});
Which produces a plot like:
You can further customize with options specific to the log axis plugin:
$.jqplot('chartdiv', [[[1, 2],[3,5.12],[5,13.1],[7,33.6],[9,85.9],[11,219.9]]], -{ title:'Exponential Line', - axes:{yaxis:{renderer: $.jqplot.LogAxisRenderer, tickDistribution:'power'}}, - series:[{color:'#5FAB78'}] -});
Which makes a plot like:
For a full list of options, see jqPlot Options in the jqPlotOptions.txt file.
You can add as many plugins as you wish. Order is generally not important. Some plugins, like the highlighter plugin which highlights data points near the mouse, don’t need any extra options or setup to function. Highlighter does have additional options which the user can set.
Other plugins, the barRenderer for example, provide functionality the must be specified in the chart options object. To render a series as a bar graph with the bar renderer, you would first include the plugin after jqPlot:
<script language="javascript" type="text/javascript" src="plugins/jqplot.barRenderer.min.js"></script>
Then you would create a chart like:
$.jqplot('chartdiv', [[34.53, 56.32, 25.1, 18.6]], {series:[{renderer:$.jqplot.BarRenderer}]});
Here the default LineRenderer is replaced by a BarRenderer to generate a bar graph for the first (an only) series.
Area charts support highlighting and mouse events by default. The options and handlers and callbacks are essentially the same as with bar, pie, donut and funnel charts. One notable exception for area charts is that no data point index will be provided to the callback and the entire data set for the highlighted area will be returned. This is because the area is not associated with one particular data point, but with the entire data set of the series.
For the chart below, mouseover has been disabled and click handling is enabled by setting "highlightMouseDown: true". For "fillToZero" area charts that have both negative and positive values as shown below, clicking in either the positive of negative regions will generate the same result.
jqPlot support axis labels through the "label" option of each axis. The default label renderer creates labels in div tags, which allows full css control over every label. Labels are assigned css classes like "jqplot-axis_name-label" where "axis_name" will be xaxis, yaxis, etc.
By including the "jqplot.canvasTextRenderer.min.js" and "jqplot.canvasAxisLabelRenderer.min.js" plugins, you can render label text directly onto canvas elements. This allows text to be rotated and yaxes will have their labels rotated 90 degrees by default. By default the labels will be rendered using the Hershey font metrics and not stroked as text. Most recent browsers (include IE 9) support native text rendering in canvas elements.
If a visitors is using a browser suppporting native canvas fonts, the plot belowsupported browser, they will see the labels in the plot below rendered as 12 pt Georgia (or their system serif font if Georgia is unavailable). If they are on an unsupported browser, they will see the default Hershey font.
Bands (like confidence intervals or error bands) can be added to line charts through the "bands" option of the line renderer. The band data can be automatically computed or manually assigned. If assigned manually, the simpliest approach is to set the "rendererOptions: { bandData: [] }" array on the series. Note that band data is taken into account when axes scale themselves so bands will not get clipped.
Band data can be supplied as arrays of [x,y] values. One array for the upper band line and one for the lower band line.
The number of points in the band data arrays does not have to correspond to the number of points in the data series. Also, band data will be drawn as smoothed lines if the data series is smoothed.
In this example, band data is supplied as an array of arrays of y values for the low and hi bands. X values for the bands are taken from the x values of the series. The band data is of the form: [ [y low 1, y hi 1], [y low 2, y hi 2], ... ] and there must be a corresponding array of low/hi y values for each x value in the data series.
The band data can also be supplied as an array of [low y values], [hi y values]. In this case there must also be an equal number of low y values and hi y values as there are data points in the series. X values for the low and hi bands will be taken from the series data. Additionally, the order of low/hi values does not matter as long as they are consistent. jqPlot will figure out which is the low values and which are the high values.
Band data does not have to be provided. By default, jqPlot will compute +/- 3% band intervals if the "rendererOptions: { bands: { show: true } }" option is set. The band intervals can be customized as well through the "rendererOptions: { bands: { interval: [number|string|arry] } }" option. Valid intervals are:
Examples of such interval specifications are shown below:
You can also customize the fill color of the bands and turn on/off band lines. By default, bands respond to the mouse over event, but they can be set to respond to mouse down as well.
Note, the plots on this page all extend the following pre-defined theme:
Click on a bar in the plot below to update the text box.
You Clicked: - Nothing yet. -
This plot animates the bars bottom to top and the line series left to right upon initial page load. Since the animateReplot: true option is set, the bars and line will also animate upon calls to plot1.replot( { resetAxes: true } ).
animateReplot: true
plot1.replot( { resetAxes: true } )
Below is a default bar plot. Bars will highlight on mouseover. Events are triggered when you mouseover a bar and also when you click on a bar. Here We capture the 'jqplotDataClick' event and display the clicked series index, point index and data values. When series data is assigned as a 1-dimensional array as in this example, jqPlot automatically converts it into a 2-dimensional array for plotting. So a series defined as [2, 6, 7, 10] will become [[1,2], [2,6], [3,7], [4,10]].
- -
The plot target also fires a 'jqplotDataMouseOver' when the cursor is moused over a bar even if highlighting is turned off. This event will fire continuously as the user mouses over the bar. 'jqplotDataHighlight' fires only once when the user first passes over the bar. Additionally, a 'jqplotDataUnhighlight' event is fired when the user moves out of a bar (if highlighting is enabled).
The next example has the plot's 'captureRightClick' option set to true. This causes the plot to fire a 'jqplotRightClick' event the the user clicks the right mouse button over a bar. Here, the 'highlightMouseDown' option is also set to true. This will highlight a slice on mouse down instead of on move over. Highlighting will occur for either left or right click.
A pie chart is added to test for incompatibilities.
The nex example shows the placement of point labels on negative bars. They shou be placed on the opposite position. That is, if it is placed 'north' to the positive bars, then it should be placed 'south' to the negative bars.
The Bezier curve renderer can distinguish between two different input data formats. This first example has the data passed in as 2 data points, the second one defining the Bezier curve to the end point. With this format, non-default axes renderers will require specifying the minimum and maximum on the axes.
- [[xstart, ystart], [cp1x, cp1y, cp2x, cp2y, xend, yend]]; -
This second example has the data broken out into 4 points, which will be assembled to define the Bezier Curve. With this format, any axes renderer can be used without explicitly specifying the minimum and maximum.
- [[xstart, ystart], [cp1x, cp1y], [cp2x, cp2y], [xend, yend]]; -
Here is an example using a date axis renderer with Bezier curves. The data looks like:
- [['01/01/2010', 6], ['02/01/2010', 9], ['03/01/2010', 8], ['04/01/2010', 3]] -
Below is an example block plot. This plot also uses the Enhanced Legend Renderer plugin. Clicking on an item in the legend will toggle display of the appropriate series.
Blocks can be moved by selecting the series, the point, and an optional duration parameter. If specified, duration will animate the movement. Duration is either a number in milliseconds, or the keywords 'fast' or 'slow'. Higher numbers will cause a slower animation.
This second chart is like the first except the "varyBlockColors" renderer option is set to true. This will vary the color of each block in a series separately. This allows displaying a third dimension to the data such as grouping beverage products by producer and by category such as "cola", "tea", "energy drink", etc.
Also, the legend has it's "showSwathces" option set to false, since the blocks of each series will be of varying color and won't correspond to one swatch color. This still enables the user to show and hide the series by clicking on a label in the legend.
Bubble charts represent 3 dimensional data. First, a basic bubble chart with the "bubbleGradients: true" option to specify gradient fills. Radial gradients are not supported in IE version before IE 9 and will be automatically disabled.
Data is passed in to a bubble chart as a series of [x, y, radius, <label or object>]. The optional fourth element of the data point can either be either a label string or an object having 'label' and/or 'color' properties to assign to the bubble.
By default, all bubbles are scaled according to the size of the plot area. The radius value in the data point will be adjusted to fit the bubbles in the chart. If the "autoscaleBubbles" option is set to false, the radius value in the data will be taken as a literal pixel value for the radius of the points.
Next are some basic customizations of bubble appearance with the "bubbleAlpha" and "highlightAlpha" options.
In the following example, display of a custom toolip and highlighting of a custom table legend is performed by binding to the "jqplotDataHighlight" and "jqplotDataUnhighlight" events. The custom legend table here is dynamically created with a few lines of jQuery (O.K., it could be done in one line) based on the data array of the plot.
Bubble charts represent 3 dimensional data. Data is passed in to a bubble chart as a series of [x, y, radius, <label or object>]. The optional fourth element of the data point can either be either a label string or an object having 'label' and/or 'color' properties to assign to the bubble.
The below chart show basic customization of bubble appearance with the "bubbleAlpha" and "highlightAlpha" options.
Below is a basic bubble chart showing usage of the optional label and color properties passed in with the data.
The next chart uses the "bubbleGradients: true" option to specify gradient fills on the bubbles. Radial gradients are not supported in IE* and will be automatically disabled.
*Radial gradients are not supported in IE 7 and IE 8 because they are not supported in the excanvas emulation layer used by jqPlot to render charts in IE 7 and IE 8. jqPlot renders charts using the HTML canvas element which is supported by nearly every browser including IE 9. Excanvas translates the canvas rendering to VML rendering for IE 7 and 8, but unfortunately does not properly handle radial gradients.
The following bubble chart shows the "autoscalePointsFactor" and "autoscaleMultiplier" options which can be used to control bubble scaling. The "autoscalePointsFactor" options controls bubble scaling with the number of points on the plot. A negative value will decrease bubble size and number of bubbles increases. The "autoscaleMultiplier" will makes all bubbles larger or smaller for values greater or less than 1.0.
This chart also demonstrates some of the highlighting options. Bubble highlighting is controlled with the "highlightMouseOver" and "highlightMouseDown" boolean options. Here the "highlightMouseDown: true" option is set which causes the plot to highlight on mousedown (click). This automatically sets the "highlightMouseOver" option to false.
Events are also trigger with plot interaction. Specifically, "jqplotDataHighlight", "jqplotDataUnhighlight", "jqplotDataClick" and "jqplotDataRightClick" events are triggered. Handlers are passed an event object, the series index, the point index, and the bubble data.
OHLC, HLC and Candlestick charts are all created using the $.jqplot.OHLCRenderer plugin. The plots on this page make use of the highlighter plugin which shows a customized tooltip as the mouse moves over a data point.
The previous plots use the following data set. jqPlot will parse most human readable date formats. It is always safest, however, to pass a date in as a JavaScript timestamp rather than have jqPlot parse an arbitrary date string.
The examples on this page use the folowing code:
The Highlighter plugin will highlight data points near the mouse and display an optional tooltip with the data point value. By default, the tooltip values will be formatted with the same formatter as used to display the axes tick values. The text format can be customized with an optional sprintf style format string.
The Cursor plugin changes the mouse cursor when it enters the graph area and displays an optional tooltip with the mouse position. The tooltip can be in a fixed location, or it can follow the mouse. The pointer style, set to "crosshair" by default, can also be customized. Tooltip values are formatted similar to the Highlighter plugin. By default they use the axes formatters, but can be customized with a sprintf format string.
Data renderers allow jqPlot to pull data from any external source (e.g. a function implementing an AJAX call). Simply assign the external source to the "dataRenderer" plot option. The only requirement on data renderers is that it must return a valid jqPlot data array.
Data renderers get passed options by the plot. The signiture for a data renderer is:
-function(userData, plotObject, options) { - ... - return data; -} -
Where userData is whatever data was passed into the plot, plotObject is a reference back to the plot itself, and options are any options passed into the plots "dataRendererOption" option. The following example shows a more complicated example which uses ajax pulls data from an external json data source.
Date axes support is provided through the dateAxisRenderer plugin. Date axes expand javascripts native date handling capabilities. This allow dates to be input in almost any unambiguous form, not just in milliseconds!
Note, although jqPlot will parse most any human readable date, it is safest to use javascript time stamps when possible. Also, it is best to specify a date and time and not just a date alone. This is due to inconsistent browser handling of local time vs. UTC with bare dates.
Date Axes also provide powerful formatting features. This allows custom formatter strings to be used to format axis tick labels precisely the way you want.
Date axis renderer with default settings. Ticks are given wider spacing by default since date axes typically have longer tick labels.
Date axis recognizes rotated tick labels. It will space ticks a little closer when labels are rotated.
If you want more or less ticks, specify the "numberTicks" options. Date axes will try to produce the desired number of ticks, but may adjust to get a nice interval.
'+str+'
The charts on this page depend on the following files:
Enter 2 series to fill between: