<li>Build a table starting with an assortment of data types ( array, text (CSV, HTML) or object (json) ).</li>
<li>This widget isn't really a widget because it is run and does it's processing before tablesorter has initialized; but the options for it are contained within the tablesorter <code>widgetOptions</code>.</li>
<li>Using the core build options:
<ul>
<li>The <code>build_type</code> tells the widget which type of data processing to use on the data.</li>
<li>The <code>build_source</code> points the widget to the data source.</li>
<li>Once the data is obtained from the <code>build_source</code>, you can do whatever processing that needs to be done on it using the <code>build_processing</code> option.
<ul>
<li>For example, if the table data is within a larger JSON, you can just return that portion of the JSON to the widget: <code>build_processing : function(data, wo) { return data.all_info_tables.table_of_contents; }</code></li>
<li>Anoter example is to use the processing option to split a string into an array (see the "Array (from string w/processing)" section below)</li>
</ul>
</li>
</ul>
</li>
<li>An extra option named <code>build_numbers</code> has been included:
<ul>
<li>This option only applies to array and csv source table builds.</li>
<li>Set the <code>build_numbers.addColumn</code> option to <code>true</code> (or a string with the column name <code>"#"</code>) to add a row number column on the far left of the table.</li>
<li>Set the <code>build_numbers.sortable</code> option to <code>true</code> to make the added number column sortable. This option only applies if the <code>addColumn</code> option is <code>true</code>.</li>
<p>Internally, all triggered events use jQuery's <ahref="http://api.jquery.com/triggerHandler/">triggerHandler</a> method to get around the issue of events triggered on a nested table bubbling up to the parent table; e.g. we don't want a "sortEnd" event to trigger on a parent table when a nested table has completed sorting.</p>
<strong>A binding added to the wrapper will not execute, and you can not target a table element that has not yet been created.</strong>
<p>To add an event listener to a table created by the build widget, you will need to use the <code>initialized</code> callback:</p>
HTML (before)
<preclass="prettyprint lang-html"><!-- empty wrapper before the table has been built -->
Contains the data stored as an array, object, jQuery object or <ahref="http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings">ajax settings</a> used to obtain ajax data (include any desired ajax options).
<divclass="collapsible"><br>
Options include: an array, object, jQuery Object (<code>$('.csv')</code>) or ajax settings( <code>{ url: 'mysite.com/data.json', dataType: 'json' }</code> ).
Add a function that returns a useable build_type. (e.g. string to array)
<divclass="collapsible"><br>
The function receives two parameters: <code>data</code> which contains the obtained data and <code>wo</code> which is the widget options (<code>table.config.widgetOptions</code>).<br>
<li>The array is set up such that it is an array of arrays. The outer array contains each row array, and within each row array is the cell text.</li>
<li>Using an array is limiting, so addtional options have been added:
<ul>
<li>(<code>build_headers</code>&<code>build_footers</code>) have been added allowing customizing the headers and/or footers.</li>
<li>The <code>rows</code> option sets the number of headers rows to include from the data source. <strong>Zero is not an option</strong> since tablesorter requires a thead in place before it will initialize.</li>
<li>The <code>text</code> array within these options will override any text obtained from the data source.</li>
<li>The <code>widths</code> array, only in the <code>build_headers</code> option, sets column widths by building <code><col></code> elements within a <code><colgroup</code>.</li>
<li>Adding class names to the tbody rows or cells isn't easily accomplished, but you can bind to the build complete event (<code>'tablesorter-build-complete'</code>) and add them yourself.</li>
<li>We start out with a string and split it into a useable array of arrays.</li>
<li>The settings are similair to the Array (javascript variable) code above with the exception of using the <code>build_processing</code> function to create the array.
<ul>
<li>The string is set up to separate each row by a semi-colon, then each cell by a comma.</li>
<li>The first split is needed to create an array of rows <code>.split(';')</code></li>
<li>The second split can be accomplished using <code>.split(',')</code> on each row of the array, but instead we use the build table widget function <code>$.tablesorter.buildTable.splitCSV(cells, ',');</code> to ensure that the split doesn't occur if the separator is within double quotes (note the footer text).</li>
<li>Then just return this newly built array back to the build table widget (see the full code below).</li>
<h3><ahref="#">Setup - CSV (txt within DOM element)</a></h3>
<div>
<h3>Notes</h3>
<ul>
<li>A jQuery object targeting the CSV text can be passed to the <code>build_source</code> option.</li>
<li>The widget detects that a jQuery object was passed to it, and grabs the HTML (not text) of the element.
<ul>
<li>Make sure not include HTML tags, or at least use the <code>build_processing</code> function to reformat the data.</li>
<li>The row of csv data is trimmed of extra tabs and spaces (only from the beginning & end of each row).</li>
<li>Building a table from CSV or array use the same script, so the same addtional options are available:
<ul>
<li>(<code>build_headers</code>&<code>build_footers</code>) have been added allowing customizing the headers and/or footers.</li>
<li>The <code>rows</code> option sets the number of headers rows to include from the data source. <strong>Zero is not an option</strong> since tablesorter requires a thead in place before it will initialize.</li>
<li>The <code>text</code> array within these options will override any text obtained from the data source.</li>
<li>The <code>widths</code> array, only in the <code>build_headers</code> option, sets column widths by building <code><col></code> elements within a <code><colgroup</code>.</li>
<li>Adding class names to the tbody rows or cells isn't easily accomplished, but you can bind to the build complete event (<code>'tablesorter-build-complete'</code>) and add them yourself.</li>
</ul>
</li>
<li>CSV data has two additional options used during data processing:
<ul>
<li><code>build_csvStartLine</code> (default is <code>0</code>) tells the csv build script which line in the csv data to start using to build the table. This is added in case comments or other data is above the table data.</li>
<li><code>build_csvSeparator</code> (default is <code>","</code>)
<ul>
<li>This sets the separator used within the csv data to separate each cell.</li>
<li>The <ahref="https://code.google.com/p/jquerycsvtotable/">original jquerycsvtotable plugin</a> shows an <ahref="http://honestbleeps.com/csvtotable/demo.html#TSVSource">example to process tab separated values (TSV)</a> by setting this option to <code>"\t"</code>.</li>
<li>Rows are determined by placing the data on a new line.</li>
</ul>
</li>
</ul>
</li>
<li>In this demo, the <code>build_numbers</code> sub-options <code>addColumn</code> and <code>sortable</code> are set to add a numeric column on the left side.
<ul>
<li>The <code>addColumn</code> option contains the name of the numeric column to be added to the header. Otherwise, set this option to <code>false</code> to not build this numeric column.</li>
<li>The <code>sortable</code> option makes that numeric column sortable.</li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>HTML</h3>
<preclass="prettyprint lang-html"><!--
Note: if the csv data contains commas ("10,000 days") wrap it in quotes
build_csvStartLine : 0, // line within the csv to start adding to table
build_csvSeparator : "," // csv separator
}
});
});</pre>
<h3>Result</h3>
<divid="csv2Table"class="container"></div>
</div>
<h3><ahref="#">Setup - CSV (txt file via ajax)</a></h3>
<div>
<h3>Notes</h3>
<ul>
<li>If the csv data is obtained via ajax instead of from a DOM element, only the <code>build_source</code> option needs to change, everything else stays the same.
<ul>
<li>Set the <code>build_source</code> to contain any <ahref="http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings">ajax settings</a> required to load the data.</li>
<li>In this case the csv file is contained within a text file (<code>build.txt</code>), so a <code>url</code> option is set to point to the file and the <code>dataType</code> option (set to <code>html</code>) is set so that ajax knows the type of file to access.</li>
<li>The remaining default settings were left out of the example below.</li>
</ul>
</li>
<li>Please note that browsers like Chrome will not allow you to access locally hosted (desktop) files. Test it with Firefox instead.</li>
These are definitions to words as used within this documentation.
<ul>
<li>A <strong>key-value pair</strong> (or <strong>attribute</strong>): Within an object, the way to assign a value is by using a key-value pair (<code>"name" : "Fred"</code>; which is like saying <code>name = "Fred"</code> or <code>x = 1</code> outside of an object).</li>
<li>A <strong>block</strong> is essentially the "value" portion of a key-value pair; specifically when referring to the value of the header, footer, row and cell blocks.</li>
<li>An <strong>array</strong> is a list or group of values (i.e. <code>['x','y','z']</code>).</li>
<li>An <strong>array of arrays</strong> is an array that contains more arrays (i.e. <code>[ ['a','b','c'], ['d','e','f' ] ]</code>). This applies to the header, row and footer blocks.</li>
<li>Any build table widget object:
<ul>
<li>These objects are a grouping of key-value pairs used to define a tbody, row or cell.</li>
<li>These objects contains all of the attributes which are to be added to a table element while building the table.</li>
<li>The keys used in these attributes will look familiar - <code>class</code> (see row 7 below), <code>colspan</code> (see row 4 below), <code>data-</code>attributes (see row 7 cell 3 below), etc.</li>
<li>Depending on where an object is located (tbody, row or cell), it will have a special key word or words which are significant (see the Objects section below).</li>
</ul>
</li>
</ul>
</div>
<h3><ahref="#">Blocks:</a></h3>
<div>
(row #), or (row # cell #) in these descriptions refer to the demo object code below
<ul>
<li><code>header</code> block:
<ul>
<li>This block will contain an array of rows. The rows can be defined as another array of cell text (row 1-3,5-6), or row objects (row 0, 4 & 7).</li>
<li>The <code>header</code> object key name can be modified by changing the widget <code>build_objectHeaderKey</code> option.</li>
</ul>
</li>
<li><code>footers</code> block:
<ul>
<li>This block can contain all of the same data as the header block.</li>
<li>This block has one additional setting, it can also contain a very specific string: <code>"clone"</code>. When this setting is used, the footer will be created by making a clone of the header.</li>
<li>The <code>footers</code> object key name can be modified by changing the widget <code>build_objectFooterKey</code> option.</li>
</ul>
</li>
<li><code>rows</code> block:
<ul>
<li>This block will contain an array of rows. The rows can be defined as another array of cell text, or as a row object (same as the header & footer blocks).</li>
<li>In addition, this block can contain a tbody object (tbody 2 & tbody 3; see the tbody object section below for more details).</li>
<li>The <code>rows</code> object key name can be modified by changing the widget <code>build_objectRowKey</code> option.</li>
</ul>
</li>
<li><code>cells</code> block:
<ul>
<li>This block will contain an array of cells. The cells can be defined as cell text (string), or cell objects.</li>
<li>The <code>cells</code> object key name can be modified by changing the widget <code>build_objectCellKey</code> option.</li>
</ul>
</li>
</ul>
</div>
<h3><ahref="#">Object Content</a></h3>
<div>
<ul>
<li>tbody object
<ul>
<li>The tbody object contains all of the attributes that are to be applied to a particular table tbody (<code>tbody</code>).</li>
<li>The tbody object <strong>requires</strong> a <code>newTbody</code> key set to <code>true</code>. It is the ONLY way the build widget can differeniate a row object from a "new" tbody object.</li>
<li>If the <code>newTbody</code> attribute is <code>true</code>, the build widget will place all remaining rows into a new tbody; or all rows, until it encounters another valid tbody object, into a new tbody.</li>
<li>If the <code>newTbody</code> attribute is <code>false</code>, the build widget will assume the object is for a row and add it as a row.</li>
<li>See "TBODY 2" and "TBODY 3" tbody objects in the code example below.</li>
</ul>
</li>
<li>row object
<ul>
<li>The row object contains all of the attributes that are to be applied to a particular table row (<code>tr</code>).</li>
<li>The row object requires a <code>cells</code> attribute.</li>
<li>The cells attribute will contain all table cell data for the cells within that table row.</li>
<li>This attribute can be changed by modifying the build table widget's <code>build_objectCellKey</code> (default is <code>"cells"</code>).</li>
<li>See row 4 and row 7 in the demo code below.</li>
</ul>
</li>
<li>row array
<ul>
<li>A row array can contain either the text for a table cell (row 0 cell 2 & 4), or a cell object (row 0 cell 1,3,5,6) contains.</li>
<li>It can also contain all cell text (row 1-3,5-6) or all cell objects (almost row 7) for cells within that row.</li>
<li>This method does not allow adding any row (<code>tr</code>) attributes, (i.e. class or data-attributes).</li>
</ul>
</li>
<li>cell object
<ul>
<li>The cell object contains all of the attributes that are to be applied to a particular table cell (<code>th</code> (thead or tfoot) or <code>td</code> (tbody).</li>
<li>This object requires either a <code>text</code> (row 0 & row 7) or <code>html</code> (row 4) attribute to add content into the cell.</li>
<li>Within the first header row only, if a <code>width</code> attribute is defined, it will be applied to a <code><col></code> element and placed within a <code><colgroup></code> before the header.</li>
<li>See row 0 (header), row 4 and row 7 (rows) in the demo code below.</li>
</ul>
</li>
<li>cell text
<ul>
<li>Within a row array or object, only the cell text can be included (row 0 cell 2,4; row 1-3,5-6; row 7 cell 5).</li>
<li>Within the header only, whenever cell content is added as a string, the widget will check the <code>widgetOptions.build_headers.classes</code>&<code>wo.build_headers.widths</code> (first row only) and apply any values it finds for that column to those cells.</li>
<h3><ahref="#">Setup - Object (json file via ajax)</a></h3>
<div>
<h3>Notes</h3>
<ul>
<li>The important difference between this demo and the javascript variable demo above is that this one retrieves a JSON file:
<ul>
<li>Set the <code>build_source</code> option to contain any <ahref="">ajax settings</a> to load the json.</li>
<li>To load the json file, set the <code>url</code> option to point to the json file and the <code>dataType</code> set to <code>"json"</code>.</li>
<li>The remaining default settings were left out of the example below.</li>
</ul>
</li>
<li>Please see the "Object (javascript variable)" section above for more details on how to set up the JSON for this demo.</li>
<li>Note that JSON formatting is very specific - only double quotes (<code>"</code>) can be used to wrap attributes, all keys must be wrapped in quotes, no comments, etc.</li>
<li>Always verify that the JSON is valid (use <ahref="http://jsonlint.com/">JSONLint</a>) and realize that browsers like Chrome will not allow you to access locally hosted (desktop) JSON files. Test it with Firefox instead.</li>
