From 3ddd89b52e81c60e4b0e7c92ae9f6b1a2de291b2 Mon Sep 17 00:00:00 2001 From: Allan Jardine Date: Sun, 27 Nov 2011 17:50:06 +0000 Subject: [PATCH] Add JSDoc comments for the DataTables settings object --- media/js/jquery.dataTables.js | 1132 +++++++++++++++++------------ media/src/.DS_Store | Bin 6148 -> 6148 bytes media/src/DataTables.js | 1 + media/src/model/model.search.js | 33 + media/src/model/model.settings.js | 1099 ++++++++++++++++------------ 5 files changed, 1305 insertions(+), 960 deletions(-) create mode 100644 media/src/model/model.search.js diff --git a/media/js/jquery.dataTables.js b/media/js/jquery.dataTables.js index ad067615..91e1089b 100644 --- a/media/js/jquery.dataTables.js +++ b/media/js/jquery.dataTables.js @@ -8523,599 +8523,729 @@ */ var _aoSettings = []; - /* - * Function: classSettings - * Purpose: Settings container function for all 'class' properties which are required - * by dataTables - * Returns: - - * Inputs: - + + /** + * DataTables settings object - this holds all the information needed for a + * given table, including configuration, data and current application of the + * table options. DataTables does not have a single instance for each DataTable + * with the settings attached to that instance, but rather instances of the + * DataTable "class" are created on-the-fly as needed (typically by a + * $().dataTable() call) and the settings object is then applied to that + * instance. + * + * Note that this object is related to {@link DataTable.models.oInit} but this + * one is the internal data store for DataTables's cache of columns. It should + * NOT be manipulated outside of DataTables. Any configuration should be done + * through the initialisation options. + * @namespace + * @todo Really should attach the settings object to individual instances so we + * don't need to create new instances on each $().dataTable() call (if the + * table already exists). It would also save passing oSettings around and + * into every single function. However, this is a very significant + * architecture change for DataTables and will almost certainly break + * backwards compatibility with older installations. This is something that + * will be done in 2.0. */ DataTable.models.oSettings = { - - /* - * Variable: oFeatures - * Purpose: Indicate the enablement of key dataTable features - * Scope: jQuery.dataTable.classSettings + /** + * Primary features of DataTables and their enablement state. + * @namespace */ - oFeatures: { - "bPaginate": true, - "bLengthChange": true, - "bFilter": true, - "bSort": true, - "bInfo": true, + "oFeatures": { + + /** + * Flag to say if DataTables should automatically try to calculate the + * optimum table and columns widths (true) or not (false). + * @type boolean + * @default true + */ "bAutoWidth": true, + + /** + * Delay the creation of TR and TD elements until they are actually + * needed by a driven page draw. This can give a significant speed + * increase for Ajax source and Javascript source data, but makes no + * difference at all fro DOM and server-side processing tables. + * @type boolean + * @default false + */ + "bDeferRender": false, + + /** + * Enable filtering on the table or not. Note that if this is disabled + * then there is no filtering at all on the table, including fnFilter. + * To just remove the filtering input use sDom and remove the 'f' option + * @type boolean + * @default true + */ + "bFilter": true, + + /** + * Table information element (the 'Showing x of y records' div) enable + * flag + * @type boolean + * @default true + */ + "bInfo": true, + + /** + * Present a user control allowing the end user to change the page size + * when pagination is enabled. + * @type boolean + * @default true + */ + "bLengthChange": true, + + /** + * Pagination enabled or not. Note that if this is disabled then length + * changing must also be disabled. + * @type boolean + * @default true + */ + "bPaginate": true, + + /** + * Processing indicator enable flag whenever DataTables is enacting a + * user request - typically an Ajax request for server-side processing. + * @type boolean + * @default false + */ "bProcessing": false, - "bSortClasses": true, - "bStateSave": false, + + /** + * Server-side processing enabled flag - when enabled DataTables will + * get all data from the server for every draw - there is no filtering, + * sorting or paging done on the client-side. + * @type boolean + * @default false + */ "bServerSide": false, - "bDeferRender": false + + /** + * Sorting enablement flag. + * @type boolean + * @default true + */ + "bSort": true, + + /** + * Apply a class to the columns which are being sorted to provide a + * visual highlight or not. This can slow things down when enabled since + * there is a lot of DOM interaction. + * @type boolean + * @default true + */ + "bSortClasses": true, + + /** + * State saving enablement flag. + * @type boolean + * @default false + */ + "bStateSave": false }, - /* - * Variable: oScroll - * Purpose: Container for scrolling options - * Scope: jQuery.dataTable.classSettings + + /** + * Scrolling settings for a table. + * @namespace */ - oScroll: { - "sX": "", - "sXInner": "", - "sY": "", + "oScroll": { + /** + * Indicate if DataTables should be allowed to set the padding / margin + * etc for the scrolling header elements or not. Typically you will want + * this. + * @type boolean + * @default true + */ + "bAutoCss": true, + + /** + * When the table is shorter in height than sScrollY, collapse the + * table container down to the height of the table (when true) + * @type boolean + * @default false + */ "bCollapse": false, + + /** + * Infinite scrolling enablement flag. Now deprecated in favour of + * using the Scroller plug-in. + * @type boolean + * @default false + * @deprecated + */ "bInfinite": false, - "iLoadGap": 100, + + /** + * Width of the scrollbar for the web-browser's platform. Calculated + * during table initialisation. + * @type int + * @default 0 + */ "iBarWidth": 0, - "bAutoCss": true + + /** + * Space (in pixels) between the bottom of the scrolling container and + * the bottom of the scrolling viewport before the next page is loaded + * when using infinite scrolling. + * @type int + * @default 100 + * @deprecated + */ + "iLoadGap": 100, + + /** + * Viewport width for horizontal scrolling. Horizontal scrolling is + * disabled if an empty string. + * @type string + * @default Empty string + */ + "sX": "", + + /** + * Width to expand the table to when using x-scrolling. Typically you + * should not need to use this. + * @type string + * @default Empty string + * @deprecated + */ + "sXInner": "", + + /** + * Viewport height for vertical scrolling. Vertical scrolling is disabled + * if an empty string. + * @type string + * @default Empty string + */ + "sY": "" }, - /* - * Variable: aanFeatures - * Purpose: Array referencing the nodes which are used for the features - * Scope: jQuery.dataTable.classSettings - * Notes: The parameters of this object match what is allowed by sDom - i.e. - * 'l' - Length changing - * 'f' - Filtering input - * 't' - The table! - * 'i' - Information - * 'p' - Pagination - * 'r' - pRocessing + /** + * Language information for the table. + * @namespace + * @extends DataTable.models.oInit.oLanguage */ - aanFeatures: [], - - /* - * Variable: oLanguage - * Purpose: Store the language strings used by dataTables - * Scope: jQuery.dataTable.classSettings - * Notes: The words in the format _VAR_ are variables which are dynamically replaced - * by javascript - */ - oLanguage: { - "sProcessing": "Processing...", - "sLengthMenu": "Show _MENU_ entries", - "sZeroRecords": "No matching records found", - "sEmptyTable": "No data available in table", - "sLoadingRecords": "Loading...", - "sInfo": "Showing _START_ to _END_ of _TOTAL_ entries", - "sInfoEmpty": "Showing 0 to 0 of 0 entries", - "sInfoFiltered": "(filtered from _MAX_ total entries)", - "sInfoPostFix": "", - "sInfoThousands": ",", - "sSearch": "Search:", - "sUrl": "", - "oPaginate": { - "sFirst": "First", - "sPrevious": "Previous", - "sNext": "Next", - "sLast": "Last" - }, + "oLanguage": { + /** + * Information callback function. See + * {@link DataTable.models.oInit.fnInfoCallback} + * @type function + * @default + */ "fnInfoCallback": null }, - /* - * Variable: aoData - * Purpose: Store data information - * Scope: jQuery.dataTable.classSettings - * Notes: This is an array of objects with the following parameters: - * array: _aData - internal data - used for sorting / filtering etc - * node: nTr - display node - * array node: _anHidden - hidden TD nodes - * string: _sRowStripe + /** + * Array referencing the nodes which are used for the features. The + * parameters of this object match what is allowed by sDom - i.e. + * + * @type array + * @default [] */ - aoData: [], + "aanFeatures": [], - /* - * Variable: aiDisplay - * Purpose: Array of indexes which are in the current display (after filtering etc) - * Scope: jQuery.dataTable.classSettings + /** + * Store data information - see {@link DataTable.models.oRow} for detailed + * information. + * @type array + * @default [] */ - aiDisplay: [], + "aoData": [], - /* - * Variable: aiDisplayMaster - * Purpose: Array of indexes for display - no filtering - * Scope: jQuery.dataTable.classSettings + /** + * Array of indexes which are in the current display (after filtering etc) + * @type array + * @default [] */ - aiDisplayMaster: [], - - /* - * Variable: aoColumns - * Purpose: Store information about each column that is in use - * Scope: jQuery.dataTable.classSettings - */ - aoColumns: [], - - /* - * Variable: aoHeader - * Purpose: Store information about the table's header - * Scope: jQuery.dataTable.classSettings - */ - aoHeader: [], - - /* - * Variable: aoFooter - * Purpose: Store information about the table's footer - * Scope: jQuery.dataTable.classSettings - */ - aoFooter: [], + "aiDisplay": [], - /* - * Variable: asDataSearch - * Purpose: Search data array for regular expression searching - * Scope: jQuery.dataTable.classSettings + /** + * Array of indexes for display - no filtering + * @type array + * @default [] */ - asDataSearch: [], + "aiDisplayMaster": [], - /* - * Variable: oPreviousSearch - * Purpose: Store the previous search incase we want to force a re-search - * or compare the old search to a new one - * Scope: jQuery.dataTable.classSettings + /** + * Store information about each column that is in use + * @type array + * @default [] */ - oPreviousSearch: { - "sSearch": "", - "bRegex": false, - "bSmart": true - }, + "aoColumns": [], - /* - * Variable: aoPreSearchCols - * Purpose: Store the previous search for each column - * Scope: jQuery.dataTable.classSettings + /** + * Store information about the table's header + * @type array + * @default [] */ - aoPreSearchCols: [], + "aoHeader": [], - /* - * Variable: aaSorting - * Purpose: Sorting information - * Scope: jQuery.dataTable.classSettings - * Notes: Index 0 - column number - * Index 1 - current sorting direction - * Index 2 - index of asSorting for this column + /** + * Store information about the table's footer + * @type array + * @default [] */ - aaSorting: [ [0, 'asc', 0] ], + "aoFooter": [], - /* - * Variable: aaSortingFixed - * Purpose: Sorting information that is always applied - * Scope: jQuery.dataTable.classSettings + /** + * Search data array for regular expression searching + * @type array + * @default [] */ - aaSortingFixed: null, + "asDataSearch": [], - /* - * Variable: asStripeClasses - * Purpose: Classes to use for the striping of a table - * Scope: jQuery.dataTable.classSettings + /** + * Store the applied global search information in case we want to force a + * research or compare the old search to a new one + * @namespace + * @extends DataTable.models.oSearch */ - asStripeClasses: [], + "oPreviousSearch": {}, - /* - * Variable: asDestroyStripes - * Purpose: If restoring a table - we should restore its striping classes as well - * Scope: jQuery.dataTable.classSettings + /** + * Store the applied search for each column - see + * {@link DataTable.models.oSearch} for the format that is used for the + * filtering information for each column. + * @type array + * @default [] */ - asDestroyStripes: [], + "aoPreSearchCols": [], - /* - * Variable: sDestroyWidth - * Purpose: If restoring a table - we should restore its width - * Scope: jQuery.dataTable.classSettings + /** + * Sorting that is applied to the table. Note that the inner arrays are + * used in the following manner: + * + * @type array + * @default [[0, 'asc', 0]] + * @todo These inner arrays should really be objects */ - sDestroyWidth: 0, + "aaSorting": [[0, 'asc', 0]], - /* - * Variable: fnRowCallback - * Purpose: Call this function every time a row is inserted (draw) - * Scope: jQuery.dataTable.classSettings + /** + * Sorting that is always applied to the table (i.e. prefixed in front of + * aaSorting). + * @type array|null + * @default null */ - fnRowCallback: null, + "aaSortingFixed": null, - /* - * Variable: fnHeaderCallback - * Purpose: Callback function for the header on each draw - * Scope: jQuery.dataTable.classSettings + /** + * Classes to use for the striping of a table + * @type array + * @default [] */ - fnHeaderCallback: null, + "asStripeClasses": [], - /* - * Variable: fnFooterCallback - * Purpose: Callback function for the footer on each draw - * Scope: jQuery.dataTable.classSettings + /** + * If restoring a table - we should restore its striping classes as well + * @type array + * @default [] */ - fnFooterCallback: null, + "asDestroyStripes": [], - /* - * Variable: aoDrawCallback - * Purpose: Array of callback functions for draw callback functions - * Scope: jQuery.dataTable.classSettings - * Notes: Each array element is an object with the following parameters: - * function:fn - function to call - * string:sName - name callback (feature). useful for arranging array + /** + * If restoring a table - we should restore its width + * @type int + * @default 0 */ - aoDrawCallback: [], + "sDestroyWidth": 0, - /* - * Variable: fnPreDrawCallback - * Purpose: Callback function for just before the table is redrawn. A return of false - * will be used to cancel the draw. - * Scope: jQuery.dataTable.classSettings + /** + * Call this function every time a row is inserted (draw) + * @type function + * @default null + * @todo Make into an array so plug-ins can hook in */ - fnPreDrawCallback: null, + "fnRowCallback": null, - /* - * Variable: fnInitComplete - * Purpose: Callback function for when the table has been initialised - * Scope: jQuery.dataTable.classSettings + /** + * Callback function for the header on each draw + * @type function + * @default null + * @todo Make into an array so plug-ins can hook in */ - fnInitComplete: null, + "fnHeaderCallback": null, - /* - * Variable: sTableId - * Purpose: Cache the table ID for quick access - * Scope: jQuery.dataTable.classSettings + /** + * Callback function for the footer on each draw + * @type function + * @default null + * @todo Make into an array so plug-ins can hook in */ - sTableId: "", + "fnFooterCallback": null, - /* - * Variable: nTable - * Purpose: Cache the table node for quick access - * Scope: jQuery.dataTable.classSettings + /** + * Array of callback functions for draw callback functions + * @type array + * @default [] */ - nTable: null, + "aoDrawCallback": [], - /* - * Variable: nTHead - * Purpose: Permanent ref to the thead element - * Scope: jQuery.dataTable.classSettings + /** + * Callback function for just before the table is redrawn. A return of + * false will be used to cancel the draw. + * @type function + * @default null + * @todo Make into an array so plug-ins can hook in */ - nTHead: null, + "fnPreDrawCallback": null, - /* - * Variable: nTFoot - * Purpose: Permanent ref to the tfoot element - if it exists - * Scope: jQuery.dataTable.classSettings + /** + * Callback function for when the table has been initialised + * @type function + * @default null + * @todo Make into an array so plug-ins can hook in */ - nTFoot: null, + "fnInitComplete": null, - /* - * Variable: nTBody - * Purpose: Permanent ref to the tbody element - * Scope: jQuery.dataTable.classSettings + /** + * Cache the table ID for quick access + * @type string + * @default Empty string */ - nTBody: null, + "sTableId": "", - /* - * Variable: nTableWrapper - * Purpose: Cache the wrapper node (contains all DataTables controlled elements) - * Scope: jQuery.dataTable.classSettings + /** + * The TABLE node for the main table + * @type node + * @default null */ - nTableWrapper: null, + "nTable": null, - /* - * Variable: bDeferLoading - * Purpose: Indicate if when using server-side processing the loading of data - * should be deferred until the second draw - * Scope: jQuery.dataTable.classSettings + /** + * Permanent ref to the thead element + * @type node + * @default null */ - bDeferLoading: false, + "nTHead": null, - /* - * Variable: bInitialised - * Purpose: Indicate if all required information has been read in - * Scope: jQuery.dataTable.classSettings + /** + * Permanent ref to the tfoot element - if it exists + * @type node + * @default null */ - bInitialised: false, + "nTFoot": null, - /* - * Variable: aoOpenRows - * Purpose: Information about open rows - * Scope: jQuery.dataTable.classSettings - * Notes: Has the parameters 'nTr' and 'nParent' + /** + * Permanent ref to the tbody element + * @type node + * @default null */ - aoOpenRows: [], + "nTBody": null, - /* - * Variable: sDom - * Purpose: Dictate the positioning that the created elements will take - * Scope: jQuery.dataTable.classSettings - * Notes: - * The following options are allowed: - * 'l' - Length changing - * 'f' - Filtering input - * 't' - The table! - * 'i' - Information - * 'p' - Pagination - * 'r' - pRocessing - * The following constants are allowed: - * 'H' - jQueryUI theme "header" classes - * 'F' - jQueryUI theme "footer" classes - * The following syntax is expected: - * '<' and '>' - div elements - * '<"class" and '>' - div with a class - * Examples: - * '<"wrapper"flipt>', 'ip>' + /** + * Cache the wrapper node (contains all DataTables controlled elements) + * @type node + * @default null */ - sDom: 'lfrtip', + "nTableWrapper": null, - /* - * Variable: sPaginationType - * Purpose: Note which type of sorting should be used - * Scope: jQuery.dataTable.classSettings + /** + * Indicate if when using server-side processing the loading of data + * should be deferred until the second draw + * @type boolean + * @default false */ - sPaginationType: "two_button", + "bDeferLoading": false, - /* - * Variable: iCookieDuration - * Purpose: The cookie duration (for bStateSave) in seconds - default 2 hours - * Scope: jQuery.dataTable.classSettings + /** + * Indicate if all required information has been read in + * @type boolean + * @default false */ - iCookieDuration: 60 * 60 * 2, + "bInitialised": false, - /* - * Variable: sCookiePrefix - * Purpose: The cookie name prefix - * Scope: jQuery.dataTable.classSettings + /** + * Information about open rows. Each object in the array has the parameters + * 'nTr' and 'nParent' + * @type array + * @default [] */ - sCookiePrefix: "SpryMedia_DataTables_", + "aoOpenRows": [], - /* - * Variable: fnCookieCallback - * Purpose: Callback function for cookie creation - * Scope: jQuery.dataTable.classSettings + /** + * Dictate the positioning of DataTables' control elements - see + * {@link DataTable.model.oInit.sDom}. + * @type string + * @default null */ - fnCookieCallback: null, + "sDom": null, - /* - * Variable: aoStateSave - * Purpose: Array of callback functions for state saving - * Scope: jQuery.dataTable.classSettings - * Notes: Each array element is an object with the following parameters: - * function:fn - function to call. Takes two parameters, oSettings and the JSON string to - * save that has been thus far created. Returns a JSON string to be inserted into a - * json object (i.e. '"param": [ 0, 1, 2]') - * string:sName - name of callback + /** + * Which type of pagination should be used + * @type string + * @default two_button */ - aoStateSave: [], + "sPaginationType": "two_button", - /* - * Variable: aoStateLoad - * Purpose: Array of callback functions for state loading - * Scope: jQuery.dataTable.classSettings - * Notes: Each array element is an object with the following parameters: - * function:fn - function to call. Takes two parameters, oSettings and the object stored. - * May return false to cancel state loading. - * string:sName - name of callback + /** + * The cookie duration (for bStateSave) in seconds + * @type int + * @default 0 */ - aoStateLoad: [], + "iCookieDuration": 0, - /* - * Variable: oLoadedState - * Purpose: State that was loaded from the cookie. Useful for back reference - * Scope: jQuery.dataTable.classSettings + /** + * The cookie name prefix + * @type string + * @default Empty string */ - oLoadedState: null, + "sCookiePrefix": "", - /* - * Variable: sAjaxSource - * Purpose: Source url for AJAX data for the table - * Scope: jQuery.dataTable.classSettings + /** + * Callback function for cookie creation + * @type function + * @default null */ - sAjaxSource: null, + "fnCookieCallback": null, - /* - * Variable: sAjaxDataProp - * Purpose: Property from a given object from which to read the table data from. This can - * be an empty string (when not server-side processing), in which case it is - * assumed an an array is given directly. - * Scope: jQuery.dataTable.classSettings + /** + * Array of callback functions for state saving. Each array element is an + * object with the following parameters: + * + * @type array + * @default [] */ - sAjaxDataProp: 'aaData', + "aoStateSave": [], - /* - * Variable: bAjaxDataGet - * Purpose: Note if draw should be blocked while getting data - * Scope: jQuery.dataTable.classSettings + /** + * Array of callback functions for state loading. Each array element is an + * object with the following parameters: + * + * @type array + * @default [] */ - bAjaxDataGet: true, + "aoStateLoad": [], - /* - * Variable: jqXHR - * Purpose: The last jQuery XHR object that was used for server-side data gathering. - * This can be used for working with the XHR information in one of the callbacks - * Scope: jQuery.dataTable.classSettings + /** + * State that was loaded from the cookie. Useful for back reference + * @type object + * @default null */ - jqXHR: null, + "oLoadedState": null, - /* - * Variable: fnServerData - * Purpose: Function to get the server-side data - can be overruled by the developer - * Scope: jQuery.dataTable.classSettings + /** + * Source url for AJAX data for the table + * @type string + * @default null */ - fnServerData: function ( url, data, callback, settings ) { - settings.jqXHR = $.ajax( { - "url": url, - "data": data, - "success": function (json) { - $(settings.oInstance).trigger('xhr', settings); - callback( json ); - }, - "dataType": "json", - "cache": false, - "type": settings.sServerMethod, - "error": function (xhr, error, thrown) { - if ( error == "parsererror" ) { - alert( "DataTables warning: JSON data from server could not be parsed. "+ - "This is caused by a JSON formatting error." ); - } - } - } ); - }, + "sAjaxSource": null, - /* - * Variable: aoServerParams - * Purpose: Functions which are called prior to sending an Ajax request so extra parameters - * can easily be sent to the server - * Scope: jQuery.dataTable.classSettings - * Notes: Each array element is an object with the following parameters: - * function:fn - function to call - * string:sName - name callback - useful for knowing where it came from (plugin etc) + /** + * Property from a given object from which to read the table data from. This + * can be an empty string (when not server-side processing), in which case + * it is assumed an an array is given directly. + * @type string + * @default aaData */ - aoServerParams: [], + "sAjaxDataProp": 'aaData', - /* - * Variable: sServerType - * Purpose: Send the XHR HTTP method - GET or POST (could be PUT or DELETE if required) - * Scope: jQuery.dataTable.classSettings + /** + * Note if draw should be blocked while getting data + * @type boolean + * @default true */ - sServerMethod: "GET", + "bAjaxDataGet": true, - /* - * Variable: fnFormatNumber - * Purpose: Format numbers for display - * Scope: jQuery.dataTable.classSettings + /** + * The last jQuery XHR object that was used for server-side data gathering. + * This can be used for working with the XHR information in one of the + * callbacks + * @type object + * @default null */ - fnFormatNumber: function ( iIn ) - { - if ( iIn < 1000 ) - { - /* A small optimisation for what is likely to be the vast majority of use cases */ - return iIn; - } - else - { - var s=(iIn+""), a=s.split(""), out="", iLen=s.length; - - for ( var i=0 ; iEmpty string + */ + "sSearch": "", + + /** + * Flag to indicate if the search term should be interpreted as a + * regular expression (true) or not (false) and therefore and special + * regex characters escaped. + * @type boolean + * @default false + */ + "bRegex": false, + + /** + * Flag to indicate if DataTables is to use its smart filtering or not. + * @type boolean + * @default true + */ + "bSmart": true + }; + DataTable.ext = {}; diff --git a/media/src/.DS_Store b/media/src/.DS_Store index f12219104830d1577bc0a29559adb394065f5d63..613c4b7b53c1fc98c92310d403fed12212f540f9 100644 GIT binary patch delta 14 VcmZoMXffEZjFGW(^K!;mF#ssv1sDJT delta 14 VcmZoMXffEZjFGW@^K!;mF#ssj1r`7R diff --git a/media/src/DataTables.js b/media/src/DataTables.js index cf5fed7a..2df090a9 100644 --- a/media/src/DataTables.js +++ b/media/src/DataTables.js @@ -93,6 +93,7 @@ require('model.settings.js'); require('model.row.js'); require('model.column.js'); + require('model.search.js'); DataTable.ext = {}; diff --git a/media/src/model/model.search.js b/media/src/model/model.search.js new file mode 100644 index 00000000..a5104bb7 --- /dev/null +++ b/media/src/model/model.search.js @@ -0,0 +1,33 @@ + + + +/** + * Template object for the way in which DataTables holds information about + * search information for the global filter and individual column filters. + * @namespace + */ +DataTable.models.oSearch = { + /** + * Applied search term + * @type string + * @default Empty string + */ + "sSearch": "", + + /** + * Flag to indicate if the search term should be interpreted as a + * regular expression (true) or not (false) and therefore and special + * regex characters escaped. + * @type boolean + * @default false + */ + "bRegex": false, + + /** + * Flag to indicate if DataTables is to use its smart filtering or not. + * @type boolean + * @default true + */ + "bSmart": true +}; + diff --git a/media/src/model/model.settings.js b/media/src/model/model.settings.js index 9c4d7b58..52692430 100644 --- a/media/src/model/model.settings.js +++ b/media/src/model/model.settings.js @@ -6,599 +6,729 @@ */ var _aoSettings = []; -/* - * Function: classSettings - * Purpose: Settings container function for all 'class' properties which are required - * by dataTables - * Returns: - - * Inputs: - + +/** + * DataTables settings object - this holds all the information needed for a + * given table, including configuration, data and current application of the + * table options. DataTables does not have a single instance for each DataTable + * with the settings attached to that instance, but rather instances of the + * DataTable "class" are created on-the-fly as needed (typically by a + * $().dataTable() call) and the settings object is then applied to that + * instance. + * + * Note that this object is related to {@link DataTable.models.oInit} but this + * one is the internal data store for DataTables's cache of columns. It should + * NOT be manipulated outside of DataTables. Any configuration should be done + * through the initialisation options. + * @namespace + * @todo Really should attach the settings object to individual instances so we + * don't need to create new instances on each $().dataTable() call (if the + * table already exists). It would also save passing oSettings around and + * into every single function. However, this is a very significant + * architecture change for DataTables and will almost certainly break + * backwards compatibility with older installations. This is something that + * will be done in 2.0. */ DataTable.models.oSettings = { - - /* - * Variable: oFeatures - * Purpose: Indicate the enablement of key dataTable features - * Scope: jQuery.dataTable.classSettings + /** + * Primary features of DataTables and their enablement state. + * @namespace */ - oFeatures: { - "bPaginate": true, - "bLengthChange": true, - "bFilter": true, - "bSort": true, - "bInfo": true, + "oFeatures": { + + /** + * Flag to say if DataTables should automatically try to calculate the + * optimum table and columns widths (true) or not (false). + * @type boolean + * @default true + */ "bAutoWidth": true, + + /** + * Delay the creation of TR and TD elements until they are actually + * needed by a driven page draw. This can give a significant speed + * increase for Ajax source and Javascript source data, but makes no + * difference at all fro DOM and server-side processing tables. + * @type boolean + * @default false + */ + "bDeferRender": false, + + /** + * Enable filtering on the table or not. Note that if this is disabled + * then there is no filtering at all on the table, including fnFilter. + * To just remove the filtering input use sDom and remove the 'f' option + * @type boolean + * @default true + */ + "bFilter": true, + + /** + * Table information element (the 'Showing x of y records' div) enable + * flag + * @type boolean + * @default true + */ + "bInfo": true, + + /** + * Present a user control allowing the end user to change the page size + * when pagination is enabled. + * @type boolean + * @default true + */ + "bLengthChange": true, + + /** + * Pagination enabled or not. Note that if this is disabled then length + * changing must also be disabled. + * @type boolean + * @default true + */ + "bPaginate": true, + + /** + * Processing indicator enable flag whenever DataTables is enacting a + * user request - typically an Ajax request for server-side processing. + * @type boolean + * @default false + */ "bProcessing": false, - "bSortClasses": true, - "bStateSave": false, + + /** + * Server-side processing enabled flag - when enabled DataTables will + * get all data from the server for every draw - there is no filtering, + * sorting or paging done on the client-side. + * @type boolean + * @default false + */ "bServerSide": false, - "bDeferRender": false + + /** + * Sorting enablement flag. + * @type boolean + * @default true + */ + "bSort": true, + + /** + * Apply a class to the columns which are being sorted to provide a + * visual highlight or not. This can slow things down when enabled since + * there is a lot of DOM interaction. + * @type boolean + * @default true + */ + "bSortClasses": true, + + /** + * State saving enablement flag. + * @type boolean + * @default false + */ + "bStateSave": false }, - /* - * Variable: oScroll - * Purpose: Container for scrolling options - * Scope: jQuery.dataTable.classSettings + + /** + * Scrolling settings for a table. + * @namespace */ - oScroll: { - "sX": "", - "sXInner": "", - "sY": "", + "oScroll": { + /** + * Indicate if DataTables should be allowed to set the padding / margin + * etc for the scrolling header elements or not. Typically you will want + * this. + * @type boolean + * @default true + */ + "bAutoCss": true, + + /** + * When the table is shorter in height than sScrollY, collapse the + * table container down to the height of the table (when true) + * @type boolean + * @default false + */ "bCollapse": false, + + /** + * Infinite scrolling enablement flag. Now deprecated in favour of + * using the Scroller plug-in. + * @type boolean + * @default false + * @deprecated + */ "bInfinite": false, - "iLoadGap": 100, + + /** + * Width of the scrollbar for the web-browser's platform. Calculated + * during table initialisation. + * @type int + * @default 0 + */ "iBarWidth": 0, - "bAutoCss": true + + /** + * Space (in pixels) between the bottom of the scrolling container and + * the bottom of the scrolling viewport before the next page is loaded + * when using infinite scrolling. + * @type int + * @default 100 + * @deprecated + */ + "iLoadGap": 100, + + /** + * Viewport width for horizontal scrolling. Horizontal scrolling is + * disabled if an empty string. + * @type string + * @default Empty string + */ + "sX": "", + + /** + * Width to expand the table to when using x-scrolling. Typically you + * should not need to use this. + * @type string + * @default Empty string + * @deprecated + */ + "sXInner": "", + + /** + * Viewport height for vertical scrolling. Vertical scrolling is disabled + * if an empty string. + * @type string + * @default Empty string + */ + "sY": "" }, - /* - * Variable: aanFeatures - * Purpose: Array referencing the nodes which are used for the features - * Scope: jQuery.dataTable.classSettings - * Notes: The parameters of this object match what is allowed by sDom - i.e. - * 'l' - Length changing - * 'f' - Filtering input - * 't' - The table! - * 'i' - Information - * 'p' - Pagination - * 'r' - pRocessing + /** + * Language information for the table. + * @namespace + * @extends DataTable.models.oInit.oLanguage */ - aanFeatures: [], - - /* - * Variable: oLanguage - * Purpose: Store the language strings used by dataTables - * Scope: jQuery.dataTable.classSettings - * Notes: The words in the format _VAR_ are variables which are dynamically replaced - * by javascript - */ - oLanguage: { - "sProcessing": "Processing...", - "sLengthMenu": "Show _MENU_ entries", - "sZeroRecords": "No matching records found", - "sEmptyTable": "No data available in table", - "sLoadingRecords": "Loading...", - "sInfo": "Showing _START_ to _END_ of _TOTAL_ entries", - "sInfoEmpty": "Showing 0 to 0 of 0 entries", - "sInfoFiltered": "(filtered from _MAX_ total entries)", - "sInfoPostFix": "", - "sInfoThousands": ",", - "sSearch": "Search:", - "sUrl": "", - "oPaginate": { - "sFirst": "First", - "sPrevious": "Previous", - "sNext": "Next", - "sLast": "Last" - }, + "oLanguage": { + /** + * Information callback function. See + * {@link DataTable.models.oInit.fnInfoCallback} + * @type function + * @default + */ "fnInfoCallback": null }, - /* - * Variable: aoData - * Purpose: Store data information - * Scope: jQuery.dataTable.classSettings - * Notes: This is an array of objects with the following parameters: - * array: _aData - internal data - used for sorting / filtering etc - * node: nTr - display node - * array node: _anHidden - hidden TD nodes - * string: _sRowStripe + /** + * Array referencing the nodes which are used for the features. The + * parameters of this object match what is allowed by sDom - i.e. + *
    + *
  • 'l' - Length changing
    • + *
  • 'f' - Filtering input
    • + *
  • 't' - The table!
    • + *
  • 'i' - Information
    • + *
  • 'p' - Pagination
    • + *
  • 'r' - pRocessing
    • + *
+ * @type array + * @default [] */ - aoData: [], + "aanFeatures": [], - /* - * Variable: aiDisplay - * Purpose: Array of indexes which are in the current display (after filtering etc) - * Scope: jQuery.dataTable.classSettings + /** + * Store data information - see {@link DataTable.models.oRow} for detailed + * information. + * @type array + * @default [] */ - aiDisplay: [], + "aoData": [], - /* - * Variable: aiDisplayMaster - * Purpose: Array of indexes for display - no filtering - * Scope: jQuery.dataTable.classSettings + /** + * Array of indexes which are in the current display (after filtering etc) + * @type array + * @default [] */ - aiDisplayMaster: [], - - /* - * Variable: aoColumns - * Purpose: Store information about each column that is in use - * Scope: jQuery.dataTable.classSettings - */ - aoColumns: [], - - /* - * Variable: aoHeader - * Purpose: Store information about the table's header - * Scope: jQuery.dataTable.classSettings - */ - aoHeader: [], - - /* - * Variable: aoFooter - * Purpose: Store information about the table's footer - * Scope: jQuery.dataTable.classSettings - */ - aoFooter: [], + "aiDisplay": [], - /* - * Variable: asDataSearch - * Purpose: Search data array for regular expression searching - * Scope: jQuery.dataTable.classSettings + /** + * Array of indexes for display - no filtering + * @type array + * @default [] */ - asDataSearch: [], + "aiDisplayMaster": [], - /* - * Variable: oPreviousSearch - * Purpose: Store the previous search incase we want to force a re-search - * or compare the old search to a new one - * Scope: jQuery.dataTable.classSettings + /** + * Store information about each column that is in use + * @type array + * @default [] */ - oPreviousSearch: { - "sSearch": "", - "bRegex": false, - "bSmart": true - }, + "aoColumns": [], - /* - * Variable: aoPreSearchCols - * Purpose: Store the previous search for each column - * Scope: jQuery.dataTable.classSettings + /** + * Store information about the table's header + * @type array + * @default [] */ - aoPreSearchCols: [], + "aoHeader": [], - /* - * Variable: aaSorting - * Purpose: Sorting information - * Scope: jQuery.dataTable.classSettings - * Notes: Index 0 - column number - * Index 1 - current sorting direction - * Index 2 - index of asSorting for this column + /** + * Store information about the table's footer + * @type array + * @default [] */ - aaSorting: [ [0, 'asc', 0] ], + "aoFooter": [], - /* - * Variable: aaSortingFixed - * Purpose: Sorting information that is always applied - * Scope: jQuery.dataTable.classSettings + /** + * Search data array for regular expression searching + * @type array + * @default [] */ - aaSortingFixed: null, + "asDataSearch": [], - /* - * Variable: asStripeClasses - * Purpose: Classes to use for the striping of a table - * Scope: jQuery.dataTable.classSettings + /** + * Store the applied global search information in case we want to force a + * research or compare the old search to a new one + * @namespace + * @extends DataTable.models.oSearch */ - asStripeClasses: [], + "oPreviousSearch": {}, - /* - * Variable: asDestroyStripes - * Purpose: If restoring a table - we should restore its striping classes as well - * Scope: jQuery.dataTable.classSettings + /** + * Store the applied search for each column - see + * {@link DataTable.models.oSearch} for the format that is used for the + * filtering information for each column. + * @type array + * @default [] */ - asDestroyStripes: [], + "aoPreSearchCols": [], - /* - * Variable: sDestroyWidth - * Purpose: If restoring a table - we should restore its width - * Scope: jQuery.dataTable.classSettings + /** + * Sorting that is applied to the table. Note that the inner arrays are + * used in the following manner: + *
    + *
  • Index 0 - column number
    • + *
  • Index 1 - current sorting direction
    • + *
  • Index 2 - index of asSorting for this column
    • + *
+ * @type array + * @default [[0, 'asc', 0]] + * @todo These inner arrays should really be objects */ - sDestroyWidth: 0, + "aaSorting": [[0, 'asc', 0]], - /* - * Variable: fnRowCallback - * Purpose: Call this function every time a row is inserted (draw) - * Scope: jQuery.dataTable.classSettings + /** + * Sorting that is always applied to the table (i.e. prefixed in front of + * aaSorting). + * @type array|null + * @default null */ - fnRowCallback: null, + "aaSortingFixed": null, - /* - * Variable: fnHeaderCallback - * Purpose: Callback function for the header on each draw - * Scope: jQuery.dataTable.classSettings + /** + * Classes to use for the striping of a table + * @type array + * @default [] */ - fnHeaderCallback: null, + "asStripeClasses": [], - /* - * Variable: fnFooterCallback - * Purpose: Callback function for the footer on each draw - * Scope: jQuery.dataTable.classSettings + /** + * If restoring a table - we should restore its striping classes as well + * @type array + * @default [] */ - fnFooterCallback: null, + "asDestroyStripes": [], - /* - * Variable: aoDrawCallback - * Purpose: Array of callback functions for draw callback functions - * Scope: jQuery.dataTable.classSettings - * Notes: Each array element is an object with the following parameters: - * function:fn - function to call - * string:sName - name callback (feature). useful for arranging array + /** + * If restoring a table - we should restore its width + * @type int + * @default 0 */ - aoDrawCallback: [], + "sDestroyWidth": 0, - /* - * Variable: fnPreDrawCallback - * Purpose: Callback function for just before the table is redrawn. A return of false - * will be used to cancel the draw. - * Scope: jQuery.dataTable.classSettings + /** + * Call this function every time a row is inserted (draw) + * @type function + * @default null + * @todo Make into an array so plug-ins can hook in */ - fnPreDrawCallback: null, + "fnRowCallback": null, - /* - * Variable: fnInitComplete - * Purpose: Callback function for when the table has been initialised - * Scope: jQuery.dataTable.classSettings + /** + * Callback function for the header on each draw + * @type function + * @default null + * @todo Make into an array so plug-ins can hook in */ - fnInitComplete: null, + "fnHeaderCallback": null, - /* - * Variable: sTableId - * Purpose: Cache the table ID for quick access - * Scope: jQuery.dataTable.classSettings + /** + * Callback function for the footer on each draw + * @type function + * @default null + * @todo Make into an array so plug-ins can hook in */ - sTableId: "", + "fnFooterCallback": null, - /* - * Variable: nTable - * Purpose: Cache the table node for quick access - * Scope: jQuery.dataTable.classSettings + /** + * Array of callback functions for draw callback functions + * @type array + * @default [] */ - nTable: null, + "aoDrawCallback": [], - /* - * Variable: nTHead - * Purpose: Permanent ref to the thead element - * Scope: jQuery.dataTable.classSettings + /** + * Callback function for just before the table is redrawn. A return of + * false will be used to cancel the draw. + * @type function + * @default null + * @todo Make into an array so plug-ins can hook in */ - nTHead: null, + "fnPreDrawCallback": null, - /* - * Variable: nTFoot - * Purpose: Permanent ref to the tfoot element - if it exists - * Scope: jQuery.dataTable.classSettings + /** + * Callback function for when the table has been initialised + * @type function + * @default null + * @todo Make into an array so plug-ins can hook in */ - nTFoot: null, + "fnInitComplete": null, - /* - * Variable: nTBody - * Purpose: Permanent ref to the tbody element - * Scope: jQuery.dataTable.classSettings + /** + * Cache the table ID for quick access + * @type string + * @default Empty string */ - nTBody: null, + "sTableId": "", - /* - * Variable: nTableWrapper - * Purpose: Cache the wrapper node (contains all DataTables controlled elements) - * Scope: jQuery.dataTable.classSettings + /** + * The TABLE node for the main table + * @type node + * @default null */ - nTableWrapper: null, + "nTable": null, - /* - * Variable: bDeferLoading - * Purpose: Indicate if when using server-side processing the loading of data - * should be deferred until the second draw - * Scope: jQuery.dataTable.classSettings + /** + * Permanent ref to the thead element + * @type node + * @default null */ - bDeferLoading: false, + "nTHead": null, - /* - * Variable: bInitialised - * Purpose: Indicate if all required information has been read in - * Scope: jQuery.dataTable.classSettings + /** + * Permanent ref to the tfoot element - if it exists + * @type node + * @default null */ - bInitialised: false, + "nTFoot": null, - /* - * Variable: aoOpenRows - * Purpose: Information about open rows - * Scope: jQuery.dataTable.classSettings - * Notes: Has the parameters 'nTr' and 'nParent' + /** + * Permanent ref to the tbody element + * @type node + * @default null */ - aoOpenRows: [], + "nTBody": null, - /* - * Variable: sDom - * Purpose: Dictate the positioning that the created elements will take - * Scope: jQuery.dataTable.classSettings - * Notes: - * The following options are allowed: - * 'l' - Length changing - * 'f' - Filtering input - * 't' - The table! - * 'i' - Information - * 'p' - Pagination - * 'r' - pRocessing - * The following constants are allowed: - * 'H' - jQueryUI theme "header" classes - * 'F' - jQueryUI theme "footer" classes - * The following syntax is expected: - * '<' and '>' - div elements - * '<"class" and '>' - div with a class - * Examples: - * '<"wrapper"flipt>', 'ip>' + /** + * Cache the wrapper node (contains all DataTables controlled elements) + * @type node + * @default null */ - sDom: 'lfrtip', + "nTableWrapper": null, - /* - * Variable: sPaginationType - * Purpose: Note which type of sorting should be used - * Scope: jQuery.dataTable.classSettings + /** + * Indicate if when using server-side processing the loading of data + * should be deferred until the second draw + * @type boolean + * @default false */ - sPaginationType: "two_button", + "bDeferLoading": false, - /* - * Variable: iCookieDuration - * Purpose: The cookie duration (for bStateSave) in seconds - default 2 hours - * Scope: jQuery.dataTable.classSettings + /** + * Indicate if all required information has been read in + * @type boolean + * @default false */ - iCookieDuration: 60 * 60 * 2, + "bInitialised": false, - /* - * Variable: sCookiePrefix - * Purpose: The cookie name prefix - * Scope: jQuery.dataTable.classSettings + /** + * Information about open rows. Each object in the array has the parameters + * 'nTr' and 'nParent' + * @type array + * @default [] */ - sCookiePrefix: "SpryMedia_DataTables_", + "aoOpenRows": [], - /* - * Variable: fnCookieCallback - * Purpose: Callback function for cookie creation - * Scope: jQuery.dataTable.classSettings + /** + * Dictate the positioning of DataTables' control elements - see + * {@link DataTable.model.oInit.sDom}. + * @type string + * @default null */ - fnCookieCallback: null, + "sDom": null, - /* - * Variable: aoStateSave - * Purpose: Array of callback functions for state saving - * Scope: jQuery.dataTable.classSettings - * Notes: Each array element is an object with the following parameters: - * function:fn - function to call. Takes two parameters, oSettings and the JSON string to - * save that has been thus far created. Returns a JSON string to be inserted into a - * json object (i.e. '"param": [ 0, 1, 2]') - * string:sName - name of callback + /** + * Which type of pagination should be used + * @type string + * @default two_button */ - aoStateSave: [], + "sPaginationType": "two_button", - /* - * Variable: aoStateLoad - * Purpose: Array of callback functions for state loading - * Scope: jQuery.dataTable.classSettings - * Notes: Each array element is an object with the following parameters: - * function:fn - function to call. Takes two parameters, oSettings and the object stored. - * May return false to cancel state loading. - * string:sName - name of callback + /** + * The cookie duration (for bStateSave) in seconds + * @type int + * @default 0 */ - aoStateLoad: [], + "iCookieDuration": 0, - /* - * Variable: oLoadedState - * Purpose: State that was loaded from the cookie. Useful for back reference - * Scope: jQuery.dataTable.classSettings + /** + * The cookie name prefix + * @type string + * @default Empty string */ - oLoadedState: null, + "sCookiePrefix": "", - /* - * Variable: sAjaxSource - * Purpose: Source url for AJAX data for the table - * Scope: jQuery.dataTable.classSettings + /** + * Callback function for cookie creation + * @type function + * @default null */ - sAjaxSource: null, + "fnCookieCallback": null, - /* - * Variable: sAjaxDataProp - * Purpose: Property from a given object from which to read the table data from. This can - * be an empty string (when not server-side processing), in which case it is - * assumed an an array is given directly. - * Scope: jQuery.dataTable.classSettings + /** + * Array of callback functions for state saving. Each array element is an + * object with the following parameters: + *
    + *
  • function:fn - function to call. Takes two parameters, oSettings + * and the JSON string to save that has been thus far created. Returns + * a JSON string to be inserted into a json object + * (i.e. '"param": [ 0, 1, 2]')
    • + *
  • string:sName - name of callback
    • + *
+ * @type array + * @default [] */ - sAjaxDataProp: 'aaData', + "aoStateSave": [], - /* - * Variable: bAjaxDataGet - * Purpose: Note if draw should be blocked while getting data - * Scope: jQuery.dataTable.classSettings + /** + * Array of callback functions for state loading. Each array element is an + * object with the following parameters: + *
    + *
  • function:fn - function to call. Takes two parameters, oSettings + * and the object stored. May return false to cancel state loading
    • + *
  • string:sName - name of callback
    • + *
+ * @type array + * @default [] */ - bAjaxDataGet: true, + "aoStateLoad": [], - /* - * Variable: jqXHR - * Purpose: The last jQuery XHR object that was used for server-side data gathering. - * This can be used for working with the XHR information in one of the callbacks - * Scope: jQuery.dataTable.classSettings + /** + * State that was loaded from the cookie. Useful for back reference + * @type object + * @default null */ - jqXHR: null, + "oLoadedState": null, - /* - * Variable: fnServerData - * Purpose: Function to get the server-side data - can be overruled by the developer - * Scope: jQuery.dataTable.classSettings + /** + * Source url for AJAX data for the table + * @type string + * @default null */ - fnServerData: function ( url, data, callback, settings ) { - settings.jqXHR = $.ajax( { - "url": url, - "data": data, - "success": function (json) { - $(settings.oInstance).trigger('xhr', settings); - callback( json ); - }, - "dataType": "json", - "cache": false, - "type": settings.sServerMethod, - "error": function (xhr, error, thrown) { - if ( error == "parsererror" ) { - alert( "DataTables warning: JSON data from server could not be parsed. "+ - "This is caused by a JSON formatting error." ); - } - } - } ); - }, + "sAjaxSource": null, - /* - * Variable: aoServerParams - * Purpose: Functions which are called prior to sending an Ajax request so extra parameters - * can easily be sent to the server - * Scope: jQuery.dataTable.classSettings - * Notes: Each array element is an object with the following parameters: - * function:fn - function to call - * string:sName - name callback - useful for knowing where it came from (plugin etc) + /** + * Property from a given object from which to read the table data from. This + * can be an empty string (when not server-side processing), in which case + * it is assumed an an array is given directly. + * @type string + * @default aaData */ - aoServerParams: [], + "sAjaxDataProp": 'aaData', - /* - * Variable: sServerType - * Purpose: Send the XHR HTTP method - GET or POST (could be PUT or DELETE if required) - * Scope: jQuery.dataTable.classSettings + /** + * Note if draw should be blocked while getting data + * @type boolean + * @default true */ - sServerMethod: "GET", + "bAjaxDataGet": true, - /* - * Variable: fnFormatNumber - * Purpose: Format numbers for display - * Scope: jQuery.dataTable.classSettings + /** + * The last jQuery XHR object that was used for server-side data gathering. + * This can be used for working with the XHR information in one of the + * callbacks + * @type object + * @default null */ - fnFormatNumber: function ( iIn ) - { - if ( iIn < 1000 ) - { - /* A small optimisation for what is likely to be the vast majority of use cases */ - return iIn; - } - else - { - var s=(iIn+""), a=s.split(""), out="", iLen=s.length; - - for ( var i=0 ; i