webapp/resources/datatables-1.9.4/media/src/model/model.ext.js

   1
   2
   3 /**
   4  * DataTables extension options and plug-ins. This namespace acts as a collection "area"
   5  * for plug-ins that can be used to extend the default DataTables behaviour - indeed many
   6  * of the build in methods use this method to provide their own capabilities (sorting methods
   7  * for example).
   8  *
   9  * Note that this namespace is aliased to jQuery.fn.dataTableExt so it can be readily accessed
  10  * and modified by plug-ins.
  11  *  @namespace
  12  */
  13 DataTable.models.ext = {
  14         /**
  15          * Plug-in filtering functions - this method of filtering is complimentary to the default
  16          * type based filtering, and a lot more comprehensive as it allows you complete control
  17          * over the filtering logic. Each element in this array is a function (parameters
  18          * described below) that is called for every row in the table, and your logic decides if
  19          * it should be included in the filtered data set or not.
  20          *   <ul>
  21          *     <li>
  22          *       Function input parameters:
  23          *       <ul>
  24          *         <li>{object} DataTables settings object: see {@link DataTable.models.oSettings}.</li>
  25          *         <li>{array|object} Data for the row to be processed (same as the original format
  26          *           that was passed in as the data source, or an array from a DOM data source</li>
  27          *         <li>{int} Row index in aoData ({@link DataTable.models.oSettings.aoData}), which can
  28          *           be useful to retrieve the TR element if you need DOM interaction.</li>
  29          *       </ul>
  30          *     </li>
  31          *     <li>
  32          *       Function return:
  33          *       <ul>
  34          *         <li>{boolean} Include the row in the filtered result set (true) or not (false)</li>
  35          *       </ul>
  36          *     </il>
  37          *   </ul>
  38          *  @type array
  39          *  @default []
  40          *
  41          *  @example
  42          *    // The following example shows custom filtering being applied to the fourth column (i.e.
  43          *    // the aData[3] index) based on two input values from the end-user, matching the data in
  44          *    // a certain range.
  45          *    $.fn.dataTableExt.afnFiltering.push(
  46          *      function( oSettings, aData, iDataIndex ) {
  47          *        var iMin = document.getElementById('min').value * 1;
  48          *        var iMax = document.getElementById('max').value * 1;
  49          *        var iVersion = aData[3] == "-" ? 0 : aData[3]*1;
  50          *        if ( iMin == "" && iMax == "" ) {
  51          *          return true;
  52          *        }
  53          *        else if ( iMin == "" && iVersion < iMax ) {
  54          *          return true;
  55          *        }
  56          *        else if ( iMin < iVersion && "" == iMax ) {
  57          *          return true;
  58          *        }
  59          *        else if ( iMin < iVersion && iVersion < iMax ) {
  60          *          return true;
  61          *        }
  62          *        return false;
  63          *      }
  64          *    );
  65          */
  66         "afnFiltering": [],
  67
  68
  69         /**
  70          * Plug-in sorting functions - this method of sorting is complimentary to the default type
  71          * based sorting that DataTables does automatically, allowing much greater control over the
  72          * the data that is being used to sort a column. This is useful if you want to do sorting
  73          * based on live data (for example the contents of an 'input' element) rather than just the
  74          * static string that DataTables knows of. The way these plug-ins work is that you create
  75          * an array of the values you wish to be sorted for the column in question and then return
  76          * that array. Which pre-sorting function is run here depends on the sSortDataType parameter
  77          * that is used for the column (if any). This is the corollary of <i>ofnSearch</i> for sort
  78          * data.
  79          *   <ul>
  80      *     <li>
  81      *       Function input parameters:
  82      *       <ul>
  83          *         <li>{object} DataTables settings object: see {@link DataTable.models.oSettings}.</li>
  84      *         <li>{int} Target column index</li>
  85      *       </ul>
  86      *     </li>
  87          *     <li>
  88          *       Function return:
  89          *       <ul>
  90          *         <li>{array} Data for the column to be sorted upon</li>
  91          *       </ul>
  92          *     </il>
  93          *   </ul>
  94          *
  95          * Note that as of v1.9, it is typically preferable to use <i>mData</i> to prepare data for
  96          * the different uses that DataTables can put the data to. Specifically <i>mData</i> when
  97          * used as a function will give you a 'type' (sorting, filtering etc) that you can use to
  98          * prepare the data as required for the different types. As such, this method is deprecated.
  99          *  @type array
 100          *  @default []
 101          *  @deprecated
 102          *
 103          *  @example
 104          *    // Updating the cached sorting information with user entered values in HTML input elements
 105          *    jQuery.fn.dataTableExt.afnSortData['dom-text'] = function ( oSettings, iColumn )
 106          *    {
 107          *      var aData = [];
 108          *      $( 'td:eq('+iColumn+') input', oSettings.oApi._fnGetTrNodes(oSettings) ).each( function () {
 109          *        aData.push( this.value );
 110          *      } );
 111          *      return aData;
 112          *    }
 113          */
 114         "afnSortData": [],
 115
 116
 117         /**
 118          * Feature plug-ins - This is an array of objects which describe the feature plug-ins that are
 119          * available to DataTables. These feature plug-ins are accessible through the sDom initialisation
 120          * option. As such, each feature plug-in must describe a function that is used to initialise
 121          * itself (fnInit), a character so the feature can be enabled by sDom (cFeature) and the name
 122          * of the feature (sFeature). Thus the objects attached to this method must provide:
 123          *   <ul>
 124          *     <li>{function} fnInit Initialisation of the plug-in
 125          *       <ul>
 126      *         <li>
 127      *           Function input parameters:
 128      *           <ul>
 129          *             <li>{object} DataTables settings object: see {@link DataTable.models.oSettings}.</li>
 130      *           </ul>
 131      *         </li>
 132          *         <li>
 133          *           Function return:
 134          *           <ul>
 135          *             <li>{node|null} The element which contains your feature. Note that the return
 136          *                may also be void if your plug-in does not require to inject any DOM elements
 137          *                into DataTables control (sDom) - for example this might be useful when
 138          *                developing a plug-in which allows table control via keyboard entry.</li>
 139          *           </ul>
 140          *         </il>
 141          *       </ul>
 142          *     </li>
 143          *     <li>{character} cFeature Character that will be matched in sDom - case sensitive</li>
 144          *     <li>{string} sFeature Feature name</li>
 145          *   </ul>
 146          *  @type array
 147          *  @default []
 148          *
 149          *  @example
 150          *    // How TableTools initialises itself.
 151          *    $.fn.dataTableExt.aoFeatures.push( {
 152          *      "fnInit": function( oSettings ) {
 153          *        return new TableTools( { "oDTSettings": oSettings } );
 154          *      },
 155          *      "cFeature": "T",
 156          *      "sFeature": "TableTools"
 157          *    } );
 158          */
 159         "aoFeatures": [],
 160
 161
 162         /**
 163          * Type detection plug-in functions - DataTables utilises types to define how sorting and
 164          * filtering behave, and types can be either  be defined by the developer (sType for the
 165          * column) or they can be automatically detected by the methods in this array. The functions
 166          * defined in the array are quite simple, taking a single parameter (the data to analyse)
 167          * and returning the type if it is a known type, or null otherwise.
 168          *   <ul>
 169      *     <li>
 170      *       Function input parameters:
 171      *       <ul>
 172          *         <li>{*} Data from the column cell to be analysed</li>
 173      *       </ul>
 174      *     </li>
 175          *     <li>
 176          *       Function return:
 177          *       <ul>
 178          *         <li>{string|null} Data type detected, or null if unknown (and thus pass it
 179          *           on to the other type detection functions.</li>
 180          *       </ul>
 181          *     </il>
 182          *   </ul>
 183          *  @type array
 184          *  @default []
 185          *
 186          *  @example
 187          *    // Currency type detection plug-in:
 188          *    jQuery.fn.dataTableExt.aTypes.push(
 189          *      function ( sData ) {
 190          *        var sValidChars = "0123456789.-";
 191          *        var Char;
 192          *
 193          *        // Check the numeric part
 194          *        for ( i=1 ; i<sData.length ; i++ ) {
 195          *          Char = sData.charAt(i);
 196          *          if (sValidChars.indexOf(Char) == -1) {
 197          *            return null;
 198          *          }
 199          *        }
 200          *
 201          *        // Check prefixed by currency
 202          *        if ( sData.charAt(0) == '$' || sData.charAt(0) == '&pound;' ) {
 203          *          return 'currency';
 204          *        }
 205          *        return null;
 206          *      }
 207          *    );
 208          */
 209         "aTypes": [],
 210
 211
 212         /**
 213          * Provide a common method for plug-ins to check the version of DataTables being used,
 214          * in order to ensure compatibility.
 215          *  @type function
 216          *  @param {string} sVersion Version string to check for, in the format "X.Y.Z". Note
 217          *    that the formats "X" and "X.Y" are also acceptable.
 218          *  @returns {boolean} true if this version of DataTables is greater or equal to the
 219          *    required version, or false if this version of DataTales is not suitable
 220          *
 221          *  @example
 222          *    $(document).ready(function() {
 223          *      var oTable = $('#example').dataTable();
 224          *      alert( oTable.fnVersionCheck( '1.9.0' ) );
 225          *    } );
 226          */
 227         "fnVersionCheck": DataTable.fnVersionCheck,
 228
 229
 230         /**
 231          * Index for what 'this' index API functions should use
 232          *  @type int
 233          *  @default 0
 234          */
 235         "iApiIndex": 0,
 236
 237
 238         /**
 239          * Pre-processing of filtering data plug-ins - When you assign the sType for a column
 240          * (or have it automatically detected for you by DataTables or a type detection plug-in),
 241          * you will typically be using this for custom sorting, but it can also be used to provide
 242          * custom filtering by allowing you to pre-processing the data and returning the data in
 243          * the format that should be filtered upon. This is done by adding functions this object
 244          * with a parameter name which matches the sType for that target column. This is the
 245          * corollary of <i>afnSortData</i> for filtering data.
 246          *   <ul>
 247      *     <li>
 248      *       Function input parameters:
 249      *       <ul>
 250          *         <li>{*} Data from the column cell to be prepared for filtering</li>
 251      *       </ul>
 252      *     </li>
 253          *     <li>
 254          *       Function return:
 255          *       <ul>
 256          *         <li>{string|null} Formatted string that will be used for the filtering.</li>
 257          *       </ul>
 258          *     </il>
 259          *   </ul>
 260          *
 261          * Note that as of v1.9, it is typically preferable to use <i>mData</i> to prepare data for
 262          * the different uses that DataTables can put the data to. Specifically <i>mData</i> when
 263          * used as a function will give you a 'type' (sorting, filtering etc) that you can use to
 264          * prepare the data as required for the different types. As such, this method is deprecated.
 265          *  @type object
 266          *  @default {}
 267          *  @deprecated
 268          *
 269          *  @example
 270          *    $.fn.dataTableExt.ofnSearch['title-numeric'] = function ( sData ) {
 271          *      return sData.replace(/\n/g," ").replace( /<.*?>/g, "" );
 272          *    }
 273          */
 274         "ofnSearch": {},
 275
 276
 277         /**
 278          * Container for all private functions in DataTables so they can be exposed externally
 279          *  @type object
 280          *  @default {}
 281          */
 282         "oApi": {},
 283
 284
 285         /**
 286          * Storage for the various classes that DataTables uses
 287          *  @type object
 288          *  @default {}
 289          */
 290         "oStdClasses": {},
 291
 292
 293         /**
 294          * Storage for the various classes that DataTables uses - jQuery UI suitable
 295          *  @type object
 296          *  @default {}
 297          */
 298         "oJUIClasses": {},
 299
 300
 301         /**
 302          * Pagination plug-in methods - The style and controls of the pagination can significantly
 303          * impact on how the end user interacts with the data in your table, and DataTables allows
 304          * the addition of pagination controls by extending this object, which can then be enabled
 305          * through the <i>sPaginationType</i> initialisation parameter. Each pagination type that
 306          * is added is an object (the property name of which is what <i>sPaginationType</i> refers
 307          * to) that has two properties, both methods that are used by DataTables to update the
 308          * control's state.
 309          *   <ul>
 310          *     <li>
 311          *       fnInit -  Initialisation of the paging controls. Called only during initialisation
 312          *         of the table. It is expected that this function will add the required DOM elements
 313          *         to the page for the paging controls to work. The element pointer
 314          *         'oSettings.aanFeatures.p' array is provided by DataTables to contain the paging
 315          *         controls (note that this is a 2D array to allow for multiple instances of each
 316          *         DataTables DOM element). It is suggested that you add the controls to this element
 317          *         as children
 318          *       <ul>
 319      *         <li>
 320      *           Function input parameters:
 321      *           <ul>
 322          *             <li>{object} DataTables settings object: see {@link DataTable.models.oSettings}.</li>
 323          *             <li>{node} Container into which the pagination controls must be inserted</li>
 324          *             <li>{function} Draw callback function - whenever the controls cause a page
 325          *               change, this method must be called to redraw the table.</li>
 326      *           </ul>
 327      *         </li>
 328          *         <li>
 329          *           Function return:
 330          *           <ul>
 331          *             <li>No return required</li>
 332          *           </ul>
 333          *         </il>
 334          *       </ul>
 335          *     </il>
 336          *     <li>
 337          *       fnInit -  This function is called whenever the paging status of the table changes and is
 338          *         typically used to update classes and/or text of the paging controls to reflex the new
 339          *         status.
 340          *       <ul>
 341      *         <li>
 342      *           Function input parameters:
 343      *           <ul>
 344          *             <li>{object} DataTables settings object: see {@link DataTable.models.oSettings}.</li>
 345          *             <li>{function} Draw callback function - in case you need to redraw the table again
 346          *               or attach new event listeners</li>
 347      *           </ul>
 348      *         </li>
 349          *         <li>
 350          *           Function return:
 351          *           <ul>
 352          *             <li>No return required</li>
 353          *           </ul>
 354          *         </il>
 355          *       </ul>
 356          *     </il>
 357          *   </ul>
 358          *  @type object
 359          *  @default {}
 360          *
 361          *  @example
 362          *    $.fn.dataTableExt.oPagination.four_button = {
 363          *      "fnInit": function ( oSettings, nPaging, fnCallbackDraw ) {
 364          *        nFirst = document.createElement( 'span' );
 365          *        nPrevious = document.createElement( 'span' );
 366          *        nNext = document.createElement( 'span' );
 367          *        nLast = document.createElement( 'span' );
 368          *
 369          *        nFirst.appendChild( document.createTextNode( oSettings.oLanguage.oPaginate.sFirst ) );
 370          *        nPrevious.appendChild( document.createTextNode( oSettings.oLanguage.oPaginate.sPrevious ) );
 371          *        nNext.appendChild( document.createTextNode( oSettings.oLanguage.oPaginate.sNext ) );
 372          *        nLast.appendChild( document.createTextNode( oSettings.oLanguage.oPaginate.sLast ) );
 373          *
 374          *        nFirst.className = "paginate_button first";
 375          *        nPrevious.className = "paginate_button previous";
 376          *        nNext.className="paginate_button next";
 377          *        nLast.className = "paginate_button last";
 378          *
 379          *        nPaging.appendChild( nFirst );
 380          *        nPaging.appendChild( nPrevious );
 381          *        nPaging.appendChild( nNext );
 382          *        nPaging.appendChild( nLast );
 383          *
 384          *        $(nFirst).click( function () {
 385          *          oSettings.oApi._fnPageChange( oSettings, "first" );
 386          *          fnCallbackDraw( oSettings );
 387          *        } );
 388          *
 389          *        $(nPrevious).click( function() {
 390          *          oSettings.oApi._fnPageChange( oSettings, "previous" );
 391          *          fnCallbackDraw( oSettings );
 392          *        } );
 393          *
 394          *        $(nNext).click( function() {
 395          *          oSettings.oApi._fnPageChange( oSettings, "next" );
 396          *          fnCallbackDraw( oSettings );
 397          *        } );
 398          *
 399          *        $(nLast).click( function() {
 400          *          oSettings.oApi._fnPageChange( oSettings, "last" );
 401          *          fnCallbackDraw( oSettings );
 402          *        } );
 403          *
 404          *        $(nFirst).bind( 'selectstart', function () { return false; } );
 405          *        $(nPrevious).bind( 'selectstart', function () { return false; } );
 406          *        $(nNext).bind( 'selectstart', function () { return false; } );
 407          *        $(nLast).bind( 'selectstart', function () { return false; } );
 408          *      },
 409          *
 410          *      "fnUpdate": function ( oSettings, fnCallbackDraw ) {
 411          *        if ( !oSettings.aanFeatures.p ) {
 412          *          return;
 413          *        }
 414          *
 415          *        // Loop over each instance of the pager
 416          *        var an = oSettings.aanFeatures.p;
 417          *        for ( var i=0, iLen=an.length ; i<iLen ; i++ ) {
 418          *          var buttons = an[i].getElementsByTagName('span');
 419          *          if ( oSettings._iDisplayStart === 0 ) {
 420          *            buttons[0].className = "paginate_disabled_previous";
 421          *            buttons[1].className = "paginate_disabled_previous";
 422          *          }
 423          *          else {
 424          *            buttons[0].className = "paginate_enabled_previous";
 425          *            buttons[1].className = "paginate_enabled_previous";
 426          *          }
 427          *
 428          *          if ( oSettings.fnDisplayEnd() == oSettings.fnRecordsDisplay() ) {
 429          *            buttons[2].className = "paginate_disabled_next";
 430          *            buttons[3].className = "paginate_disabled_next";
 431          *          }
 432          *          else {
 433          *            buttons[2].className = "paginate_enabled_next";
 434          *            buttons[3].className = "paginate_enabled_next";
 435          *          }
 436          *        }
 437          *      }
 438          *    };
 439          */
 440         "oPagination": {},
 441
 442
 443         /**
 444          * Sorting plug-in methods - Sorting in DataTables is based on the detected type of the
 445          * data column (you can add your own type detection functions, or override automatic
 446          * detection using sType). With this specific type given to the column, DataTables will
 447          * apply the required sort from the functions in the object. Each sort type must provide
 448          * two mandatory methods, one each for ascending and descending sorting, and can optionally
 449          * provide a pre-formatting method that will help speed up sorting by allowing DataTables
 450          * to pre-format the sort data only once (rather than every time the actual sort functions
 451          * are run). The two sorting functions are typical Javascript sort methods:
 452          *   <ul>
 453      *     <li>
 454      *       Function input parameters:
 455      *       <ul>
 456          *         <li>{*} Data to compare to the second parameter</li>
 457          *         <li>{*} Data to compare to the first parameter</li>
 458      *       </ul>
 459      *     </li>
 460          *     <li>
 461          *       Function return:
 462          *       <ul>
 463          *         <li>{int} Sorting match: <0 if first parameter should be sorted lower than
 464          *           the second parameter, ===0 if the two parameters are equal and >0 if
 465          *           the first parameter should be sorted height than the second parameter.</li>
 466          *       </ul>
 467          *     </il>
 468          *   </ul>
 469          *  @type object
 470          *  @default {}
 471          *
 472          *  @example
 473          *    // Case-sensitive string sorting, with no pre-formatting method
 474          *    $.extend( $.fn.dataTableExt.oSort, {
 475          *      "string-case-asc": function(x,y) {
 476          *        return ((x < y) ? -1 : ((x > y) ? 1 : 0));
 477          *      },
 478          *      "string-case-desc": function(x,y) {
 479          *        return ((x < y) ? 1 : ((x > y) ? -1 : 0));
 480          *      }
 481          *    } );
 482          *
 483          *  @example
 484          *    // Case-insensitive string sorting, with pre-formatting
 485          *    $.extend( $.fn.dataTableExt.oSort, {
 486          *      "string-pre": function(x) {
 487          *        return x.toLowerCase();
 488          *      },
 489          *      "string-asc": function(x,y) {
 490          *        return ((x < y) ? -1 : ((x > y) ? 1 : 0));
 491          *      },
 492          *      "string-desc": function(x,y) {
 493          *        return ((x < y) ? 1 : ((x > y) ? -1 : 0));
 494          *      }
 495          *    } );
 496          */
 497         "oSort": {},
 498
 499
 500         /**
 501          * Version string for plug-ins to check compatibility. Allowed format is
 502          * a.b.c.d.e where: a:int, b:int, c:int, d:string(dev|beta), e:int. d and
 503          * e are optional
 504          *  @type string
 505          *  @default Version number
 506          */
 507         "sVersion": DataTable.version,
 508
 509
 510         /**
 511          * How should DataTables report an error. Can take the value 'alert' or 'throw'
 512          *  @type string
 513          *  @default alert
 514          */
 515         "sErrMode": "alert",
 516
 517
 518         /**
 519          * Store information for DataTables to access globally about other instances
 520          *  @namespace
 521          *  @private
 522          */
 523         "_oExternConfig": {
 524                 /* int:iNextUnique - next unique number for an instance */
 525                 "iNextUnique": 0
 526         }
 527 };
 528