Customize

Wiki: Home | FAQ | Customize | Snippets | Search | Language | Changes | Change summary

Custom Widget Build

• A dist folder is dynamically created and updated with .min.js and .min.css versions of all the files.
• The jquery.tablesorter.js file is copied as-is from the source directory.
• A custom jquery.tablesorter.widgets.js file is created using npm & grunt; this file also includes a compressed version.
• This custom file places all included widgets within a UMD (Universal Module Definition) wrapper, for RequireJS, AMD & CommonJS compatibility.
• If you need a source (uncompressed/developement) version of the file, look in the js/, css/ or addons/ folders.

Installing Node.js & Grunt

• Install Node.js - it includes npm (node package manager).
• Open a command window in the tablesorter root directory.
• Enter npm install to load all the necessary dependencies into the node_modules folder; this includes grunt.
• Enter npm install -g grunt-cli to install the grunt command-line-interface globablly.
• Now you are ready to run grunt!

Standard Build

• A standard build includes the following widgets:

  • storage - local storage of specific widget settings with a cookie fallback.
  • uitheme - Enhancements to add Bootstrap & jQuery UI themes to tablesorter.
  • columns - Column highlighting of sorted columns.
  • filter - Filter rows
  • stickyHeaders - make the header stick to the top of the page while scrolling.
  • resizable - make columns resizable.
  • saveSort - Use the storage widget to save the last sort.

• To create a jquery.tablesorter.widgets.js (and compressed file) with the standard widgets, enter:

  grunt
  

Custom Build

• To get a custom build, you'll need to create a json file in the root directory, with a list of the widgets to include.
• Name the file anything you want but do not include any spaces.
• An example.json file has been included in the root directory for reference, but don't modify it because it will get updated with the repository.

json File

The contents of the json file may look like this (example.json contents are shown):

{
  "widgets" : "filter stickyHeaders uitheme",
  "parsers" : "ignore-articles network",
  "includeDependencies" : false,
  "destFileName" : "jquery.tablesorter.custom-widgets.js"
}

options

• widgets option:
  • The widgets option will be a list of widget names taken from the file name between the "widget-" and the ".js" (widget-{name}.js), e.g. use "filter-formatter-jui" for the jQuery UI specific filter formatter file named "widget-filter-formatter-jui.js".
  • For ease of entry, this value is a string of space separated widget names, extra spaces will be ignored.
  • If no widgets names are included in the custom options, the build will abort (changed v2.21.4) continue with the default widgets.
• parsers option (added v2.21.4):
  • The parsers option will be a list of parser names taken from the file name between the "parser-" and the ".js" (parser-{name}.js), e.g. use "input-select" for the parser set up to obtain the values from inputs, textarea, checkboxes or select (text or value) elements named "parser-input-select.js".
  • For ease of entry, this value is a string of space separated parser names, extra spaces will be ignored.
  • If no parsers are included in this option, the custom build will continue without any parsers.
• includeDependencies option:
  • This option adds any widget dependencies to the custom widget file during the build when set to true.
  • For example, several widgets need the storage widget to save data, so if you include the "saveSort" widget, the "storage" widget will automatically be included when this option is true.
  • Another example is if you include the "filter-formatter-jui" widget, it will automatically include the "filter" widget.
  • Setting this option to false will flag the build to not include dependencies within the jquery.tablesorter.widgets.js file; just be aware that the included widgets might still need that dependency.
  • Not setting or including this option will make it default to true.
• destFileName option:
  • Set to add a destination file name for the custom widgets.
  • If no file name is provided, the file name will default to "jquery.tablesorter.custom-widgets.js".
  • This file will be created in the dist/js folder, along with a .min version; and a copy will be made in the js/ folder.
• To use the custom options:

  • Run grunt custom:{file-name} to create the custom file.

  • This example shows how to use the included example.json set up.

    grunt custom:example.json
    

What happens during a build:

• jquery.tablesorter.js is copied to the dist/js folder.
• All less files are copied to the dist/css/less folder.
• All images, including the pager icons, is copied into the dist/css/images folder.
• A combined widget file is created:
  • For a standard build, a jquery.tablesorter.widgets.js file is created in the dist/js folder.
  • Custom builds will create a jquery.tablesorter.custom-widgets.js file (or customized name from the settings) of the selected widgets in the dist/js folder.
  • This file is then copied back to the js folder.
• A combined tablesorter file is created:
  • For a standard build, a jquery.tablesorter.combined.js file is created in the dist/js folder.
  • A custom build will also create the same named file, but include all selected widgets & parsers all wrapped to work as a UMD module.
  • This file is then copied back to the js folder.
• A .min.js file is created for the core, widget and combined files in the dist/js folder, then all parsers & widgets are compressed separately in the dist/js/parsers and dist/js/widgets folder, respectively.
• A .min.css file is created for all themes, dragtable, filter-formatter & pager styles.
• The version number of the core and minified core is updated to match the package.json value.
• The black-ice theme within the distribution folder is renamed to theme.blackice.min.css (no dash). See issue #785.

Testing a Build

• The following command will perform jshint & qunit tests on the files

  grunt test
  

File changes made for the build update (v2.20.0):

• The following changes to files have been made (this might break a few jsFiddle demos):
  • jquery.metadata.js has been moved into the js/extras folder.
  • jquery.tablesorter.widgets-filter-formatter.js
    • moved to the js/widgets folder
    • Broken into two files, and renamed to widget-filter-formatter-html5.js and widget-filter-formatter-jui.js.
  • jquery.tablesorter.widgets-filter-formatter-select2.js
    • Moved into the js/widgets folder.
    • Renamed to widget-filter-formatter-select2.js
  • jquery.tablesorter.widgets.js
    • Has been broken up into separate widget files: widget-column.js, widget-filter.js, widget-resizable.js, widget-saveSort.js, widget-stickyHeaders.js, widget-storage.js and widget-uitheme.js.
    • A standard build creates a file of the above widgets combined in the dist/js folder.
    • A copy of this newly created combined widget file is then copied back to the js/ folder to allow external demos (jsFiddle) to still work.

Build Change Log

• v2.21.3: Added destFileName option within the build json file. This allows naming the custom widget build file.
• v2.21.4: Added parsers option to build json file; Build now includes a combined file containing the core plugin and all selected widgets & parsers.