ClientsideTech.com

SmartTable

The SmartTable is the crux of the Clientside Tech platform.

The constructor:

new SmartTable( String (id), Array (columns) , Array/String (data) [,SmartTableParams (params)] [,Array (hiddencolumns)] [,Object (paginationrenderer)])

The constructor parameters are explained below:

id: the id of the TABLE element that will be used by the SmartTable to render the data. If no table exists the SmartTable will create one and append it using this id. Also, you can get a pointer to the SmartTable instance with this id using SmartTables.get(<id>)
columns: An array of strings which are the column header names
data: This parameter can either be a 2-dimensional array (each subarray must be the same length as the number of columns), or a delimited string which will be split up into a 2-dimensional array based on teh number of columns.
params (optional); an instance of a SmartTableParams object. See the How-TO guide for an explanation of this object.
hiddencolumns (optional): an array of strings which are the hidden column names. Only necessary if your data is a delimited string. If you include this parameter, you'll need a null placeholder for "params" if you aren't also including a params arg.
PagiationRenderer (optional): if this is not included, the default pagination will be used. If you include this arg, the previous optional args must be included or have null in their place.

Functions:

init(): Initializes the instance. Automatically called by the SmartTables object when you call SmartTables.init()

make(page): Will render the given page of the table. If no "page" arg is sent, will render page one.

search(searcher) The searcher argument must be an instance of ArraySearcher.

sort(colnum) Will sort the table based on the values in the column specified, and re-render at page one.

getParams(): returns the SmartTableParams object being used by the instance.

setParams(SmartTableParams): sets a new SmartTableParams object to be used by the instance.

setUpInd(String): Sets the location of the forward sort indicator

setDownInd(String): Sets the location of the reverse sort indicator

setValidator(function,Number): Sets a validator to be used when editing values in the column, which is indicated by the second argument.

setColumnType(String,Number): Column type can be "date" or "number". Any other value will have no effect. Setting "date" or "number" tells the instance to convert the values to that kind of object which makes sorting more accurate, and also the built-in search UI will account for those types.

setSortable(Number, Boolean): Sets the given column number to sortable or not sortable

setSearchable(Number, Boolean): Sets the given column number to searchable or not searchable

setPaginationRenderer(Object): Sets a new pagination renderer object to be used by the instance.

getPaginationRenderer(): returns the current pagination renderer object

setColumnHeaders(Array): resets the column headers.

getColumnHeaders(): returns the array of column header names

setData(Array/String): resets the current data set. If you pass a delimited string it will convert it to an array based on the number of columns (including hidden).

getData(): returns the 2-dimensional array of data

getRow(index): returns the given row of data based on the index value passed

addRow(Array): adds a new row of data to the existing data set

addRows(Array/String): will append the new data to the current data set.

insert(Array): insert a new record into the existing rendered HTML table and append the record to the internal data set.

insertMulti(2-d Array): insert new records into the existing rendered HTML table and append the records to the internal data set.

setValue(index,column,value): Resets the value in the data set at the index and column indicated.

setStyleRoot(String): Sets a new styleroot to be used for the css class names.

setHeaderStyle(style,column): Sets a new className for the column header indicated where "column" is a number.

setColumnStyle(style,column): Set a new className for the cells in the column indicated.

setEditStyle(style,column): Set a new className to be applied to editable cells in the column indicated

setRenderer(column,Function): Set a new renderer for the column indicated

removeRenderer(column): Remove any custom renderers for the column indicated

serializeEdits(): returns a delimited string from the rows that have had edited fields.

getEdits(): returns an array of all the rows that have been edited

serializeData(): Returns a delimited string of all the data

setEditMode(mode,column): Set the edit mode to "text", "checkbox", or "select" for the colum indicated.

setConstraints(values, column, delimiter(optional)): sets the value constraints for the column indicated.

SmartLogger

The SmartLogger makes it easy to log messages and alerts while developing complex scripts. The SmartLogger is a single object that does not need to created with a constructor. The SmartLogger outputs to a SPAN with the id of "SmartLoggerSpan". If you want to add styles to the logs, each log element is within an "LI" tag. If you don't create the "SmartLoggerSpan", the SmartLogger will automatically create it and append it to the bottomof the page. If you use the logger before the page has loaded, it will retain the log messages as a "safe" log. Once the page is loaded, the next log will trigger the output of the "safe" logs.

If you want to convert an existing script's alerts to SmartLogger logs, use this line:


    var alert = SmartLogger.log;

init(): starts the SmartLogger. You must call SmartLogger.init() if you plan to log.

log(<anything>): the log function takes anything as an argument. It will log the time that it was called.

Shortcuts:

sl= SmartLogger

DOMHelper

The DOMHelper is a single object that offers several shortcuts for dealing with DOM operations. The DOMHelper also has a shortcut reference of dh. So you can, say, append one node to another with dh.d(node1,node2). The shortcuts are generally used when you want to optimize the download size of your script. Most of the ClientsideTech utilities use the DOMHelper

create(String): A shortcut for document.createElement

get(String): A shortcut for document.getElementById

getByName(String): A shortcut for document.getElementsByName

appendChild(parent,child): A shortcut for DOMNode.appendChild()

appendChildListed(parent[,childNode1,childNode2....] [,boolean): A shortcut for appending any number nodes to a parent. If the last parameter is a boolean the is true, the parent node is returned. Otherwise it is a void return.

appendChildNested(parent[,childNode1,childNode2....] [,boolean): A shortcut for appending any number nodes to each other, starting with the first node. So, node 1 is the parent of node2, which is the parent of node3, and so on. This is especially useful when creating a simple table with a single row and cell, which tends to happen a lot. If the last parameter is a boolean the is true, the first node is returned. Otherwise it is a void return.

swap(newNode,oldNode): The swap function in IE is not W3C compliant. This little helper provides that useful functionality.

stripChildren(DOMnode): Strips all the children out of the node.

The shortcuts:
dh = DOMHelper
dh.a = DOMHelper.create
dh.b = DOMHelper.get
dh.c = DOMHelper.getByName
dh.d = DOMHelper.appendChild
dh.e = DOMHelper.appendChildListed
dh.h = DOMHelper.swap
dh.sc = DOMHelper.stripChildren

DOMCloner

The cloneNode function is faster than the document.createElement function. If your script is creating a lot of DOMNodes, you can speed it up by using the DOMCloner. The DOMCloner creates only one of any given element you want to create, then clones it for efficiency.

You can always use get for anything but getNode, getLink and getInput are there for conveniently getting nodes, links and form fields that have properties already set for you. It lets you do things with one line of code instead of four or five.

get(type): "Type" is the tagname of the node to create. Returns a node of that type.

getNode(type,id,className,innerHTML): "Type" is the tagname of the node to create. The id, className and innerHTML parameters should be self-explanatory. They are optional but you must include null values for them if you are going to pass real values for a later parameter. So, the following two examples are legal:


    var mynode = DOMCloner.getNode("SPAN");
    var mynode2 = DOMCloner.getNode("SPAN",null,"SPANCLASS");

getLink(href,innerHTML,className,id): The arguments should be self explanatory.

getInput(type,value,className,id,name): The arguments should be self explanatory.

Shortcuts dc = DOMCloner
dc.g = DOMCloner.get
dc.gn = DOMCloner.getNode
dc.gi = DOMCloner.getInput
dc.ga = DOMCloner.getLink

SelectMenuHelper

Select menu tags present a cumbersome problem for scripters. To get the selected value and other operations can require several lines of code or long-winded references such as:

    var selectedValue = document.getElementById("myMenu").options[document.
    getElementById("myMenu").options.selectedIndex].value;

The SelectMenuHelper provides lots of convenient helper methods for manipulating SELECT tags.

getSelectedValue(menuObject): Returns the selected value of the menu. "menuObject" parameters is a DOMNode reference to the SELECT element.

getSelectedValues(menuObject): Returns an array of the selected values of the menu, even if only 1. "menuObject" parameters is a DOMNode reference to the SELECT element.

getSelectedIndex(menuObject): Returns the selected index of the menu. "menuObject" parameters is a DOMNode reference to the SELECT element.

getSelectedIndexes(menuObject): Returns an array of the selected indexes of the menu, even if only 1. "menuObject" parameters is a DOMNode reference to the SELECT element.

getSelectedText(menuObject): Returns the selected text of the menu. "menuObject" parameters is a DOMNode reference to the SELECT element.

getSelectedTexts(menuObject): Returns an array of the selected texts of the menu, even if only 1. "menuObject" parameters is a DOMNode reference to the SELECT element.

move(fromMenu,toMenu): Moves the selected options from the "fromMenU" to the "toMenu". This means the options are now in the toMenu, and NOT the fromMenu.

copy(fromMenu,toMenu): Copies the selected options from the "fromMenU" to the "toMenu". This means the options are now in both menus.

size(menuObject): Returns the number of options in the menu.

add(menuObject,optiontext,optionvalue): Adds a new options to the menu using "optionValue" for the value and "optionText" for the text.

make(text,value): Creates a new Option object.

getSelectedDOMObject(menuObject): Returns a reference to the selected option element DOM node.

set(menuObject,ParameterCollection): Takes a ClientsideTech ParameterCollection instance and creates new options from all the NameValuePairs in the ParameterCollection

moveUp(menuObject): Moves the current selected option in the menu up by one.

moveDown(menuObject): Moves the current selected option in the menu down by one.

selectByIndex(menuObject,index): Sets the menu option with that index to selected.

selectByValue(menuObject,value): Sets the menu options with that value to selected.

removeAll(menuObject): Removes all the options from the menu.

sort(menuObject): Sorts all the options by text.

sortByValue(menuObject): Sorts all the options by value.

Shortcuts

sh=SelectMenuHelper
sh.a=SelectMenuHelper.getSelectedValue
sh.b=SelectMenuHelper.getSelectedValues
sh.c=SelectMenuHelper.getSelectedIndex
sh.d=SelectMenuHelper.getSelectedIndexes
sh.e=SelectMenuHelper.getSelectedText
sh.f=SelectMenuHelper.getSelectedTexts
sh.g=SelectMenuHelper.getSelectedDOMObject
sh.h=SelectMenuHelper.move
sh.i=SelectMenuHelper.copy
sh.j=SelectMenuHelper.size sh.k=SelectMenuHelper.add
sh.l=SelectMenuHelper.remove
sh.m=SelectMenuHelper.make
sh.n=SelectMenuHelper.set
sh.o=SelectMenuHelper.moveUp
sh.p=SelectMenuHelper.moveDown
sh.q=SelectMenuHelper.selectByIndex
sh.r=SelectMenuHelper.selectByValue
sh.s=SelectMenuHelper.removeAll
sh.t=SelectMenuHelper.sort
sh.u=SelectMenuHelper.sortByValue

XMLHelper

Internet Explorer and Firefox require different techniques for getting and loading an XMLDOMDocument. The XMLHelper makes it easy to use one simple technique that works in both browsers.

xmlObject(String): the String argument is the source of the XML. Returns an XMLDOMDocument based on the source string argument.

isLoaded(String): the String argument is the source of the XML. Returns true once the document that was called via getDomObject is loaded.

getSingleValue(XMLDomDocument,String): The String argument is the tagName of the element within the XMLDomDocument. Returns the FIRST node's value with that name.

getSingleNode(XMLDomDocument,String): The String argument is the tagName of the element within the XMLDomDocument. Returns the FIRST node with that name.

gtn(XMLDomDocument,String): The String argument is the tagName of the element within the XMLDomDocument. Returns the collection of nodes with that name. This is simply a shortcut for getElementsByTagName

getValue(XMLDomDocument,String): The String argument is the tagName of the element within the XMLDomDocument. The IE and firefox implementations of the XMLDOMDocument handle node values differently. This makes it simple to write scripts that get node values without having to constantly check for browser type.

getText(XMLDomDocument): Returns the text representation of the entire XMLDOMDocument's contents.

getHTML(XMLDomDocument): Returns the HTML representation of the entire XMLDOMDocument's contents.

Shortcuts:

xh = XMLHelper
xh.xo=xh.xmlObject
xh.s = xh.getSingleValue
xh.e = xh.getSingleNode
xh.v = xh.getValue

ParameterCollection

This object allows you to create and maintain a collection of NameValuePairs with a simple, easy to use API. It automatically constructs an instance based on all arguments in the URL and names it at window.PARAMS. Anytime you want to use any parameter from the URL in a script, you can get it from window.PARAMS

Example:


    var myValueFromTheURL = window.PARAMS.<parameter_name>;
    var myValueFromTheURL2 = window.PARAMS.value(<parameter_name>);

The ParameterCollection constructor takes two arguments. The values and a boolean that determines whether or not to set all name/value combos as named properties on the instance.

The ParameterCollection can set each value as a named property on itself. So if you add a parameter with a name of "id" and a value of "1234", then the ParameterCollection instance will also have an id property. ie.


     myParameterCollection.id;

The constructor's first parameter can take a variety of types.

Array: an Array of NameValuePair objects. These will be set as the name/value combos on the ParameterCollection
Array: an Array of strings values. Each string value will be used to create a NameValuePair with name and value being the same.
String : A string delimited by the normal URL parameter method. Each name/value combo is separated with "&" and each name/value combo is also split with an "=". For example: "value1=myval&value2=yourval". The constructor will split this string out and create new NameValuePair instances based on the values.
ParameterCollection: If you pass a ParameterCollection instance to the constructor it will create a new instance using all the name/value combos in the argument instance.

addValues(values): This function can take all the same types of arguments as the constructor, and will append these name/value combos in addition to existing ones.

add(String/NameValuePair): Adds a single new name/value combo to the instance. The arg can be a NameValuePair instance or a string value in which case the name and value will be the same. If a value with that name already exits, the ParameterCollection will maintain both and return them all from the getValues function.

replace(String/NameValuePair): Adds a single new name/value combo to the instance. The arg can be a NameValuePair instance or a string value in which case the name and value will be the same. This will replace any pre-existing values for that name.

clear(): removes all current name/value combos from the instance.

remove(value): removes the name/value combos that have a value equal to the argument.

get(name): returns the value of the name/value combos with a name equal to the argument. If more than one exists it will return the first one.

name(value): returns the name associated with that value if it exists. This allows the ParameterCollection to behave somewhat like a java Hashtable for those familiar with java.

getValues(name): returns an array of the values with a name equal to the argument, even if only one exists.

size(): returns the number of NameValuePairs in the collection.

getNames(): returns an array of the all the names being used in the collection.

hasValue(name): returns true if there is a value with that name.

getNameValuePairs(): returns an array of all the name/value combos.

toString(): returns a formatted string listing all the name/value combos.

beforeFirst(): sets the internal counter to the beginning.

hasNext(): returns true if there are any remaining name/value combos.

hasPrevious(): returns true if there are any previous name/value combos.

next(): return the next value.

previous(): returns the previous value.

Special Shortcuts:

PC = new ParameterCollection(values,boolean)
PC is a wrapper function that takes the same args as the ParameterCollection constructor and returns a new ParameterCollection instance.

ArraySerializer

This object makes it easy to turn a delimited string into a 2-dimensional array, and vice versa.

Constructor: new ArraySerializer(length,strings,delimiter): "length" is the length of the subarray, strings is an array of string indexed values if you wish to have those, and delimiter will override the default delimiter which is a comma.

deserialize(string): The string value should be a delimited string that will conform to the parameters you used in the constructor. If you want to deserialize into arrays with 2 indexed record and 2 string-indexed values called "one" and "two", this is an example:

    var data = "vala,valb,one1,two1,valc,vald,one2,two2...... ";
    var mySerializer = new ArraySerializer(2,new Array("one","two"));
    var deserializedArray = mySerializer.deserialize(data);

serialize(array [,string]) The second argument is optional and will replace the default delimiter which is a comma. The serialize function will serialize any 2-dimensional array. The native join(delimiter) function will not override the comma on second-level arrays, and will skip over string-indexed values. So the ArraySerializer is necessary when you need that functionality.

ArraySearcher

The ArraySearcher makes it easy to search an array of objects or a 2 dimensional array.

There are three steps involved:
First you create an instance, the you set up the search criteria using the simple API, then you pass it an array to search against.

The constructor takes two boolean arguments: matchall,and returnIndexes.

constructor: new ArraySearcher(true/false,true/false): The first argument tells the searcher what kind of search to conduct. If false, it will return records that match *any* of the criteria you set on the ArraySearcher. If true it will only return records that match ALL the criteria. The second argument tells the ArraySearcher to return an array of numbers that are the indexes of the found records. If false, it will return the actual records.

setSearch(index,value,searchType,excludeBoolean): This function is how to set a search criterion. The first argument is the index of the second level array that you want to search against. The second value is the value to match against all the elements in the array. The searchType tells the search what kind of search to do. The types of searches are:

Contains search: Will match true if the value in the subarray contains the search value. If you want to return all subarrays with a value at index[2] that contains "t", you'd set a search like so:
```
      mySearcher.setSearch(2,"t","contains");
      
```
Equals search: will return true if the value in the subarray equals the search value.
Begins with search: will return true if the value in the subarray begins with the search value.
Ends with : will return true if the value in the subarray ends with the search value.
Maximum: will return true if the value in the subarray is equal to or less than the search value.
Minimum: will return true if the value in the subarray is equal to or greater than the search value.
Less than: will return true if the value in the subarray less than the search value.
Greater than: will return true if the value in the subarray greater than the search value.

The searchType must be a value that the searcher can recognize to know which type of search to do. The following are acceptable:

Contains search: "has", "contains", "like", "%"

Equals search: "equals", "=", "==", "is", "eq"

Begins With search: "begins", "begins_with", "bw"

Ends With search: "ends", "ends_with", "ew"

Maximum search: "max", ">=", "gte", "to"

Minimum search: "min", "<=", "lte", "from"

Less Than search: "less_than", "lt", "<"

Greater Than search: "greater_than", "gt", ">"

search(Array): searches the array based on the search criteria you have set and returns the results.

Standalone functions and shortcuts

Here are some other shortcut and helper functions

getRandomNumber(min,max) returns a random whole number between the two values passed
getRandomElement(array) returns a random element from the array.

NA(): returns a new empty array
ND(): returns a new Date
NO(): returns a new Object
ST(number,string): shortcut for setTimeout
IO(val1,val2): returns val1.indexOf(val2)
SO(element,classname): sets element.className = classname
SV(element,value): sets element.value = value
SI(element,value): sets element.innerHTML = value
SD(element,value): sets element.style.display = value
PI(val): returns parseInt(val)
PF(val): returns parseFloat(val)getBool(bool) return the boolean value if bool exists, or false if it is null
getDefaultValue(val,default) return the default if value is null
exists(value) returns true if value is not null and the typeof operation is not "undefined"
isString(value): returns true if the value is a string type
isNumber(value) returns true if the value is a number type
isArray(value) returns true if the value is a Array type
isObject(value) returns true if the value is a object type
isType(value,type) returns true if the value is the same type as the "type" argument
isFunction(value) returns true if the value is a Function
isBoolean(value) returns true if the value is a Boolean type
isDate(value) returns true if the value is a Date type

some shortcuts for the above functions

IS=isString
IN=isNumber
IA=isArray
ISO=isObject
IT=isType
IF=isFunction
ID=isDate
TV=toggleValue
IB=isBoolean
GB=getBool
GDV=getDefaultValue