SortedTable documentation v0.8f

Summary

Adds sorting capabilities to a table (manual with move and automatic with sort).

Created by

The SortedTable constructor:

new SortedTable( [ elementId ] )

Parameters

elementId

Optional. The id of the <table> element that needs to be sorted. If no id is defined the constructor will find all tables with classname sorted. The returned object is based on the first such table.

Additional options are passed to the object via classnames on the table element

sorted

Makes a table sortable if it's not passed as the elementId to the constructor.

regroup

Forces a regroup of the tbody elements in init.

Description

The SortedTable object allows sorting of a table.

All the operations of the object are based on manipulating with DOM elements. This allows any other manipulations that will effect the table automatically.

Constructing with no parameters

If you pass no parameters to the constructor will search the DOM for any tables with classname sorted.

All such tables will be extended to SortedTable. You can find the tables via:

SortedTable.getSortedTable(element)

Properties

Static

tables

Array of created SortedTable object.

gecko

Boolean that defines if the browser is Gecko to allow some performance tweaks.

removeBeforeSort

Boolean that defines if rows should be removed from the DOM before being sorted.

Dynamic

table

HTMLTableElement that the SortedTable object is 'extending'.

head

The first <thead> of the table.

body

The first <tbody> of the table. Only the first <tbody> element is sortable. If you have more such elements check regroup().

foot

The first <tfoot> of the table.

elements

A nodeList of HTMLTableRowElements that reside in the body. Since this is not an Array but a nodeList instead it always includes the right elements.

allowMultiple

Boolean. If true multiple selects are allowed.

allowDeselect

Boolean. If true deselection by clicking on a previously selected row is not allowed.

selectedElements

Array of selected HTMLTableRowElements.

cols

Array of HTMLTableCellElements. This is needed for sorting but needs to be updated after every change of the elements.

Methods

Static methods

move ( direction, element )

Moves an element in a certain direction. It first finds the corresponding SortedTable with getSortedTable.

If the direction is positive the row 'gains' a place and is therefore positioned higher in a table.

Returns nothing.

moveSelected ( direction, element )

Moves the selected elements of a table that contains the given element in a certain direction.

If the direction is positive the row 'gains' a place and is therefore positioned higher in a table.

Returns nothing.

findParent ( element, tag )

Finds an element with the given tag that is in the parent chain of the given element.

Returns DOM element.

getEventElement ( event )

Finds the element that was the source of a specified event.

If event is not specified or is null it tries to get it from window.event.

Returns DOM element.

getSortedTable ( element )

Finds a SortedTable objects that is parent to the specified element.

It uses findParent method and tables property.

Returns SortedTable.

Initialization methods

init ( element )

Sets most of the properties of the SortedTable. Passed element (HTMLTableElement) is the source table element.

Called from the constructor. Calls parseCols at the end.

Returns nothing.

findTable ()

Finds all tables that with class sorted that are not yet extended to SortedTable.

Called from the constructor if more than one SortedTable object needs to be constructed.

Returns HTMLTableElement.

parseCols ()

Parses all rows to create the cols array.

Called from init

Returns nothing.

prep ()

Registers the table in tables array and prepares the header and body.

Called from the constructor, calls register, prepBody and prepHeader.

Returns nothing.

register ()

Adds the SortedTable object to tables array.

Returns nothing.

regroup ()

Finds all <tbody> and moves all the rows to the first one referenced with the body property. This feature is useful if you're working with XML Data Islands. On init this function is triggered by class "regroup" on the table element.

Returns nothing.

prepHeader ()

If the header doesn't have class nosort adds event handlers. If a presort is defined with class sortedplus or sortedminus the table is sorted.

Called from prep.

Returns nothing.

prepBody ()

Removes whitespace between HTMLTableRowElements and adds event handlers.

Called from prep.

Returns nothing.

Helper methods

trim ( string )

Trims the given string. It actually just removes spaces from the beginning and the end of the string.

Returns String.

hasClass ( element, className )

Finds if the given element has the given className.

The integer it returns is a 1-based index of the givern className in the className string.

Returns Integer.

changeClass ( element, oldclass, newclass )

Changes the oldclass of the given element to the newclass.

If oldclass is empty it will just add the newclass to the className of the element. If the newclass is empty it will just remove the oldclass from the className of the element.

Returns nothing.

elementIndex ( element )

Find the index of the given element.

The number it returns is a 0-based index of the element in the elements list. If the element is not found returns -1.

Returns Number.

findParent ( element, tag )

Dynamic alias of the findParent.

Event handler methods

callBodyHover ()

Callback function for hover on the body of the table.

If the row element has class hover it is removed, if it doesn't it's added.

Executes onbodyhover before other actions, if defined.

Returns false.

callBodyClick ()

Callback function for click on the body of the table.

Selects a row or a range of rows (depends on allowMultiple property). If the corresponding rows are selected it deselects them.

Normal selection modifiers shift and control are supported.

Executes onbodyclick before other actions, if defined.

Returns false.

callBodyDblClick ()

Callback function for doubleclick on the body of the table.

Executes onbodydblclick before other actions, if defined.

Returns false.

callHeadHover ()

Callback function for hover on the header of the table.

Executes onheadhover before other actions, if defined.

Returns false.

callHeadClick ()

Callback function for click on the header of the table.

Sorts the selected column. If the column is already sorted it reverses the sort.

Executes onheadclick before other actions, if defined.

Returns false.

callHeadDblClick ()

Callback function for doubleclick on the header of the table.

Executes onheaddblclick before other actions, if defined.

Returns false.

Select related methods

selected ( element )

Returns true if the given element (HTMLTableRowElement) is selected.

Returns Boolean.

select ( element )

Selects the given element (HTMLTableRowElement).

Executes onselect after other actions, if defined.

Returns nothing.

deselect ( element )

Deselects the given element (HTMLTableRowElement).

Returns nothing.

selectRange ( element )

Selects a range from the last selection to the given element.

Any selected elements that are in the range are deselected.

If no previous elements are selected only the given element is selected and false is returned. If a range is selected the returned boolean is true.

Returns Boolean.

cleanselect ()

Deselects all elements that are selected.

Returns nothing.

Sorting related methods

compareSmart ( value1, value2 )

Compares the two values and returns 1 if value1 is bigger and -1 if it's smaller. If they're the same it returns 0.

The comparison is made on the basis of words. The number parts are compared as numbers, strings as strings.

Returns Number.

compare ( value1, value2 )

Compares the two values and returns 1 if value1 is bigger and -1 if it's smaller. If they're the same it returns 0.

The passed values are DOM elements. The value to compare is the title attribute if it exists and the innerHTML if it doesn't. The comparison is based on the axis attribute of the elements.

Returns Number.

findSort ()

Finds the column that is currently sorted in any direction.

Returns HTMLTableCellElement.

sort ( element [, reverse] )

Sorts the table on the column of which element is the header cell. If reverse is passed the elements are not sorted but only reversed. If removeBeforeSort is true elements are removed and then appended again.

Executes onsort after sorting, if defined.

Returns nothing.

resort ( element )

Calls sort and sets the appropriate classes to the given header element. If the order only needs to be reversed it passes true as the second attribute to sort.

Returns nothing.

cleansort ( [element] )

Cleans the sorting. Called whenever a row is moved. If element is passed the column with the given element is not 'cleaned'.

Returns nothing.

Move related methods

compareindex ( value1, value2 )

Compares the two values and returns 1 if value1 is bigger and -1 if it's smaller. If they're the same it returns 0.

Returns Number.

move ( direction [, element] )

Moves the given element in the given direction. If the element is not given selected rows are moved. If the direction is positive the row 'gains' a place and is therefore positioned higher in a table.

Executes onmove after moving, if defined.

Returns nothing.

moverow ( direction, element )

Moves the given element (HTMLTableRowElement) in the given direction. If the direction is positive the row 'gains' a place and is therefore positioned higher in a table.

Returns nothing.

canMove ( direction, element )

Checks whether the given element can move in the given direction and returns true if it does.

Returns Boolean.

Events

Mouse events

onbodyhover

Triggered before anything else on hover on the table body.

onbodyclick

Triggered before anything else on click on the table body.

onbodydblclick

Triggered before anything else on doubleclick on the table body.

onheadhover

Triggered before anything else on hover on the table header.

onheadclick

Triggered before anything else on click on the table header.

onheaddblclick

Triggered before anything else on doubleclick on the table header.

SortedTable events

onselect ( element )

Triggered after each row is selected. The newly selected row is passed as element. When selectRange is applied onselect fires for every selected row.

ondeselect ( element )

Triggered after each row is deselected. The newly deselected row is passed as element. When selectRange is applied onselect fires for every selected row.

onsort ( element )

Triggered after the table is sorted. The element passed is the header of the column that has been sorted.

onmove ( direction [, element] )

Triggered after a move has been done. The passed elements are the direction of the move and the element that has been moved. As with move element is optional. If empty check selectedElements for moved rows.