The Objectsheet       A visual data environment

## Objectsheet Function/Method/Variable Reference

as a self-contained html file.
 Contents: Array Calc:Format Calc:Math File Shortcut:Application Table Table:Prep Automate Calc:Logic Calc:Vars HTML Shortcut:Table Table:Display Table:Reference Calc:Aggregation Calc:Lookup Date:Time Panel String Table:Misc Table:Style
Additional methods of Arrays. Some of these methods (find, grep, collect) have more generic counterparts that can be applied to strings or generic objects (see Calc: Lookup in this reference for more information)

### Array      (top)

Additional methods of Arrays. Some of these methods (find, grep, collect) have more generic counterparts that can be applied to strings or generic objects (see Calc: Lookup in this reference for more information)
Array::sum() Determine sum of any numbers in array Determine product of any numbers in array Determine sum of product of numbers across two arraysExample: `[2,3,4].innerProduct([7,6,5])` gives 52 (ie., 2 * 7 + 3 * 6 + 4 * 5) Determine average of any numbers in array Determine maximum value of any numbers in array. If array is length zero, returns null. Determine minimum value of any numbers in array Filter array based on expr. Expr can be a string, in which case it's evaluated, or a regular expressionExample: `this.us.grep("self.index%2==0")` returns every odd numbered row in the current Table Create histogram of values in array. Bins can be single number, a range of numbers separated by a dash, or a list of numbers separated by comma. If no argument, bins are the unique values in the array (ie., categories). 3 cases for argument bin. If a single bin, returns number of occurences of bin in array. If bin is array, returns object with bin names as keys and values the number of occurences of each element in bin. In cases 2 and 3, returned histogram is packed in an object, with the object keys denoting each bin.Example: if `a = [2,3,3,4,3,4,5,5,5,6,8]` `a.histogram()` returns "2":1, "3":3, "4":2, "5":3, "6":1, "8":1}`a.histogram(5)` returns 3`a.histogram("2-4")` returns 6, `a.histogram([2,"3-4",5])` returns { "2":1, "3-4":5, "5":3} Apply expr to each element in array, return results. Only non-null results are added. If want nulls, specify 1 for includeNulls.Example: `a.collect("self.length")` where a = ["Alabama", "Alaska","Arkansas","Arizona","California"] returns the length of each element: [7, 6, 8, 7, 10] Select attributes out of an array of objects. Attribute names (attr) can be in an array, or a comma- or semicolon- separated list. This assumes the elements of Array are objects. Find expr within a complex object. .find() evaluates expr for each element in array, return first element of array where expr is true. Within expr, self refers to the current value.Example: for `a=[{color:green}, {color:red}, {color:blue}]; a.find("self.color =='blue'")` returns `{color:blue}` return index of first element that matches val. val must be a literal. Returns -1 if val is not found. Return true if array contains val (this is a simpler alternative to: `[..].indexOf(val) > -1` Remove all zeros, empty string, and undefined values from array Filter out redundant values from array Remove first element from array that matches val. val must be a literal. The original array is modified. If no match, nothing is removed. Returns resulting array. To remove all values, use Array::subtract()Example: `a.removeValue(9)` where `a` = [2,8,9, "fleas", 9] sets `a` = [2,8,"fleas",9] and returns `a` Extend array with the elements of a. Array itself is changed and also returned. Remove all values from array that match val (if passed in as literal) or elements of val (passed in as array). If no match, nothing is removed. Returns resulting array. Example: `[1,2,3,4,5].subtract([3,4])` => [1,2,5] Rotate values of array n times. Positive n rotates values right, negative n rotates left. No value rotates one to the rightExample: `[1,2,3,4,5].rotate(1)` => `[5,1,2,3,4]`, `[1,2,3,4,5].rotate(-2)` => `[3,4,5,1,2]`

### Automate      (top)

Scriptable methods for automatic creation and manipulation of Objectsheet elements
os_mgr::removeSection(sectionName) Remove a section by name from the Objectsheet application
os_mgr::createSection(name, secType, options, objs, props) Function to create a new section. name = secton name, type = "Table", "Scratch", or "Html", options is an object to set "view" parameters, objs and props (table only) pre-populate table with any given objects and properties (column definitions)
os_mgr::renameSection(oldName, newName) Rename a section. Note: within the Objectsheet application, use: _mgr.renameSection(oldName, newName)
Table::deleteObject(oIndex) Remove a single object from this Table
Table::addProperty(name, index, options) Insert a single new column to this Table. In the arguments, any number will be interpreted as the column number (column 0 is the leftmost column, negative numbers are measured from the end, numbers contrained not more than 1 from end of table, existing columns pushed to the right). A text argument will be the name of the column (enclosed numeric names in quotes) and an object argument ({...}) defines general options (where you can specify forumulas, formats, etc.
Example: `this.addProperty("propName")`: add property with given name to end of table, `this.addProperty(3)`: add autonamed property as 4th column, `^this.addProperty({name:"y", index:2, formula:"x+3",...})`: add property with named options,
Table::deleteProperty(index) remove a property from this Table
Table::rename(newName) Rename this Table. Note: this only works correctly for stand-alone tables. If using this within the Objectsheet application (e.g., if there is an objectsheet menubar at the top left), use `_mgr.renameSection(oldName, newName)`
Table::pasteObjects(newUs, startRow, startCol, overWrite) Add object(s) to this Table starting at a particular row. Single object can be added as either text string, a single object, or an array of objects. You can add an instance formula by preceeding the value with "\\=" (`{a:3,b:5,c:"\\=a+b"}`). Existing properties will be retained.
Example:
 1 `table1.pasteObjects()` Adds a single new row to the end of table1. 2 `table1.pasteObjects({a:3,b:5,c:8})` Adds a new row with columns a, b, and c having the values 3, 5, and 8, respectively. 3 `table1.pasteObjects("3,5,8")` Same as #2 4 `table1.pasteObjects([{a:3,b:5,c:8}])` Same as #2 (can add multiple rows by adding more objects to the outer array). 5 `table1.pasteObjects([[5,8], [2,-1]],-1,1)` Add 2 rows at the end (startRow = -1) starting at the second column (startCol = 1).
Table::where(expr) Filter table rows given expression. Purpose similar SQL's where statement
TableSection::getSelection() Get user-highlighted objects/rows and properties/columns from a table, place into 2-d array

### Calc: Aggregation      (top)

Array and aggregation helper functions. Some numeric functions (sum(), average(), etc.) are similar to Array methods, but these functions also operate on objects that have numeric attributes. These functions are useful to iterate over table rows.
increment(str) smartly increment a string (increment last number in string) return sum of numbers in array or object. If argument is an object, only numeric values (not numeric keys) are used. return product of numbers in array or object a. If a is an object, only numeric values (not numeric keys) are used. return average of numbers in array or object a. If a is an object, only numeric values (not numeric keys) are used. Return array of numbers between 1 and start, or between start and end. Default step = 1Example: `range(5)` returns [0,1,2,3,4,5]. `range(4,2)` returns [4,3,2]. `range(1,5,2)` returns [1,3,5]. Return array of numbers, geometrically spaced, between start and end (using step or 1). If len not specified, 6 values are returned.Example: grange(2,32,5) returns [2, 4,8,16,32] convert difference between two dates (given in internal representation) to number of days find string or RegExp s in object or array o. Returns an array of matches. Each match is in itself an object of the form, {element:e, value:v}, where e is a string representing the path to found object v is the found value.Example: if `a = {num1:2, num2:4, d:[3,2,"happy"]};``locate(a, "happy")` returns[ { element:".d[2]", value:"happy"}]`locate(a,2)` returns [{ element:".num1", value:2},{ element:".d[1]", value:2}] Shows entirety of nested object o . All results of Scratch sections are put through splay(). o can be artbitrary depth, up to SPLAY_MAX_LEVELS deep and arbitrary number of elements, up to SPLAY_MAX_ELEMENTS. Both of these are variables you can change. Shows single level of nested object o . Includes both data and method elements of o. turn 2-dimensional array s into a tab-delimited text table

### Calc: Format      (top)

Number and text formatting functions for use in Table format rows or in general
Math::fix(n,p) Show n with no more than p decimal places. Do not show trailing decimal zeros Show n with no more than p decimal places. Include trailing decimal zeros Force whole-number portion of n to have p digits, prefixing zeros as necessary. Show n as a percent, showing no more than p decimal places. Include trailing decimal zeros Show n in scientific format, showing no more than p decimal places. Do not include trailing decimal zerosExample: `sci(32000, 2)` => `3.2e5` Show n in engineering format (e.g., 3.2 e 6, ensuring the exponent is divisible by 3), showing no more than p decimal places. Do not include trailing decimal zeros. Numbers in between 0.001 and 1000 are not shown in engineering format. Show n with engineering units (e.g., 3.2k), showing no more than p decimal places. Do not include trailing decimal zeros. Max 9 decimal places. Show n in U.S. Dollar notation (e.g., \$3200), showing no more than p decimal places. p is optional, defaulting to 2. Leaves non-numbers alone. Thousands separator for numbers. Default is ",". Change to suit your locale. Currency character(s). Default is "\$". Change to suit your locale (e.g., in a Scratch section or in the misc row of a Table) Show n with comma separators(e.g., 3,200.00), showing no more than p decimal places. p is optional, defaulting to 2. Leaves non-numbers alone. Separator can be changed by changing `Math.separator`. Turn str (could be the result of prepDate()) into date (currently English). Mask is a string that can include any characters, but the following are converted from date: yyyy = four number year yy = two number year mmmm = full month name mmm = abbreviated month name mm = month number dd = day of month hh = hours nn = minutes ss = secondsNote: within mask, a prefix of zero before mm, dd, hh, nn, or ss forces zero to be shown for values less than 10

### Calc: Logic      (top)

Comparison helpers
contains(expr, arg1, arg2) returns true if number expr is contained within numeric ranges. arg1 is a comma separated string of values and ranges "a-b, c, d-e, ...". expr will be tested as being between any numeric ranges (numbers separated by "-") or equal to any singular values. Alternatively, contains() will test if expr is between two simple numbers arg1 and arg2. All range tests are inclusive of the end points.Example: `contains(23, "5,10-15, 20-25")` returns `true` `contains(26, "5,10-15, 20-25")` returns `false` `contains(25, 20, 30)` returns `true` returns true if s exists Returns true if x is text

### Calc: Lookup      (top)

Array or object search and change functions. Some of these functions (grep(), collect(), etc.) have Array method counterparts, but these functions also operate on strings and generic objects.
grep(aref, expr) extract all elements of aref that meet the expr. expr is expressed as a string. grep operates over the elements of array, an object, or the lines of a string. Within expr, self represents the current item in the arrayExample: `grep(Table1.us, "self.a > 0")` extracts all rows where a > 0 (try this in a Scratch section). Extract elements from a complex object. Source may be an array, object, or number. Within expr use self to refer to the current item in the array, i to refer to the index.Example: `collect(Table1.us, "self.a")` returns the 'a' attribute of each element (row) of Table1.us. return the keys of an associative array (or object) as an array. Return the methods added to an array or object. Built-in methods are not included. Method names are returned as an array. Return evaluated result upon the first occurence of criteria in source

### Calc: Math      (top)

Math functions
Math::log10(x) return base 10 log of x Simple trinary compare function. Returns -1 if a < b, 0 if a == b, or 1 if a > b. Returns -1 if a < 0, 0 if a == 0, or 1 if a > 0. (Same as `cmp(a,0)`)

### Calc: Vars      (top)

Convencience variables available for use
var days_long Array of complete (English) day names: [Sunday, Monday,..., Saturday] Array of short (English) day names: [Sun, Mon,...Sat] Array of complete (English) month names: [January, February,..., December] Array of short (English) month names: [Jan , Feb,..., Dec]

### Date: Time      (top)

General date and time manipulation functions
toTime(n) convert number from milliseconds to amount of time in hh:mm:ss.ss

### File      (top)

The following public methods are platform agnostic, but then call platform-specific functions. These methods currently work for Mozilla and Internet Explorer.
includeObject(file, type) Load Javascript or CSS content in file Save content to fileName. Optional silence supresses error warnings. Save content to fileName within web directory dir. This runs in coordination with an httpupload.py script on the server (url defined in `File.webSaveScript`). Post content to url. This uses HTTP post capability. Load contents of file specified in url. url can be a local file or from over the web. url can be absolute or relative. Rename oldName to newName Place information about the directory specified in path into an array of objects. path may be local or web (this method uses File.webDir or File.localDir). Return directory based on web server's index page (uses screen scraping) Place information about the directory specified in path into an array of objects. Each object in this array has file's date (last modified date, in Javascript internal format), size (in bytes), name, and extension. Directories are also captured Return names of subdirectories of the directory specified in path. Reuse any existing currentFileObject (mozilla: nsILocalFile or ie: FileSystemObject) file passed in Return true if there is a file or directory specified at path. return filename portion of path. also look for portion of path prior to "?" in URL return directory portion of path, including trailing '/' or '\'

### HTML      (top)

Functions and suggestions for working with Objectsheet HTML Sections
hselect(name, values, options) Create select box called name from array values
`<% ... %>` within html Embedded live data: evaluate and display all Javascript contained in such tags
Example: `<% dol(Table1.a().sum()) %>` returns the sum of all cells of column "a" in Table1, formatted with US dollars.
HTMLSection::focusName If focusName is set for an HTMLSection (e.g., from a scratch section) and refers to the name of a HTML input element, that element will always get the focus when the section is caculated.
HTMLSection::selectName If selectName is set for an HTMLSection (e.g., from a scratch section) and refers to the name of a HTML input element, that element content will always be selected when the section is caculated.
wiki content for HTML area Interpret easy-on-the-eyes wiki syntax
 !, !!,... Heading level 1, level 2,... '''xyz''' Bold //xyz// Italicize --- Horizontal line, 25% wide (For thick line, use '='s) ---- Horizontal line, 50% wide (For thick line, use '='s) ----- Horizontal line, 100% wide(For thick line, use '='s) *, **, or *** bulleted list: level1, level2, level3 respectively |...|(params) make table-- params (first line only) set table html params

### Panel      (top)

The Panel class is responsible for showing the outer frame (titlebar, hide/close boxes, title, right/bottom resize bars). This is used by all Sections in the Objectsheet. The Panel object for each section is stored in `Section::_panel` (the underscore prefix hides the Panel object when a section's data is shown in a Scratch section.
 When Panels use the "stacked" mode (ie., are displayed down the screen in a single column), the Panel.DEFAULT_STACK_MARGIN static variable defines the vertical spacing between successive panels Update the Name of the Panel visible in the titlebar Change closeability of Panel. If state is set to zero, the Panel's close box will be removed. If no parameter is passed, the closebox will be toggled between hidden and shown. Enable/disable resize bars based on state. Allowable values are "", "h", "v", or "hv"/"vh" Shows or hides the Panel's titlebar. state can be 1 or "" to show the Titlebar, 0 or "none" to hide it, or no empty/undefined to toggle show/hide. Show or hide panel's content. state can be either "" or 1 to show the Panel, "none" or 0 to hide it, or no parameter to toggle the Panel's state

### Shortcut: Application      (top)

General keyboard shortcuts within the Objectsheet Application
F2 Recalculate all sheets Save current file Open File Dialog Create new Scratch section Create new HTML Section

### Shortcut: Table      (top)

Keyboard shortcuts specific to Table Sections.
Ctrl-0 through Ctrl-8 Set fixed decimal for property/column to so many places. If there's no preexisting number format (e.g., pct, fix, eng, engu, sci), make number format fix(). Also right-align numbers. Note: this does not currently work with Mozilla on Mac Remove fixed decimal and right alignment from property/column Make property/column boldface Make property/column date format Make property/column engu format (ie., prefix large/small numbers: m (milli), G (giga), etc.) Make property/column dollar format Show numbers in property/column in percent format Italicize property/column Align property/column text: cycle from Left => Center => Right and back again. Create on-off button for property/column (alternative to checkbox) Cut all values in current Table to windows clipboard Copy values in current Table to windows clipboard Paste values into table with cursor at upper left corner Recalculate without moving out of cell

### String      (top)

Additional methods of the Javascript String object and general string helper
qw(s) turn string into array, seperated by whitespace turn string into 2-d array. Figure out comma versus tab seperated by # of occurences. Optional delim parameter forces delimiter. Replicate a string n times Count the number of a particular character c in string Split comma separated words into array

### Table      (top)

TableSections are individual spreadsheet-like containers for data. Note: 'Table' methods concern data, formulas, etc. TableSections methods handle display in web browser. All Table methods are available from a TableSection object.
Table::getPropNames() return an array of all property names in this Table Process table cells. This is just the (internal) calculation part; does not format, style, or display cells. Constructor. 'data' is an object of the form {us:objects, prop:props}. 'objects' can be a count or an array of values. 'props' can be prop count or an associative array of properties and their attributes. 'options' are an object that can include: 'canMove:0' make table stationary. Default=1 (moveable) 'lockTemplate:1' make templates uneditable by user. Default=0 (editable) 'stacked:1' stack sections vertically--this also forces sections to be stationary. Default = 0 (moveable) 'canHide:0' Table cannot be hidden by user. Default=1 (hideable) 'canMinimize:0' section cannot be minimized by user. Default=1 (minimizable) resizeable:'hv' section includes horizontal and vertical resize bars (leave out letters to prevent user from growing/shrinking section Update the display attribute of a column. Since display update is slow, it is not done automatically. Calculate just this Table. updateDisplay is optional. if updateDisplay is 1, then the property display attributes are updated Remove object by row # on screen (using this._shown[]). Two ways to remove objects: 1) specify as array: Table1.removeObjects([1,3,5]), and 2) Specify count and optionally to only remove the last highlighted object Return 2-dimensional array containing all values in the Table. The first row of the result is the column names Turn a table into string, including column names. Each row is a line of string; each column separated by tabs.

### Table: Display      (top)

These are functions used in a Table's display row. These functions change a column's (or the entire Table's) cells from the standard text box to something else.
text(showFormula) standard single-line text cell. showFormula= 1 means to show the formula after the result, seperated by ":=" HTML cell, read only. Similar to bare(), but bareDiv() has improved text overflow behavior for narrow columns. HTML cell, read only. Simpler than bareDiv(), but text overflow doesn't behave as well. HTML cell, click to edit. Multiline text area. taRows specifies how many rows in the text area. Drop-down select box. specify the elements of the select box via arguments or via an array.Example: `select(["high", "medium", "low"])` or `select("high", "medium", "low")` shows a 3-element select box with the indicated values Multi-item select box. specify the elements of the select box via an array; size (number of entries high) of select box defaults to the array size (but no more than 6). You can select combinations of elements using shift and control/command keys.Example: `multi(["sprinkles", "cherry", "caramel", "nuts"])` shows a 4-element tall select box with the indicated values. Collection of radio buttons. Specify the radio button values via an array.Example: `radio(["high", "medium", "low"])` or `radio("high", "medium", "low")` shows 3 radio buttons with the indicated values. The value of the cell is the selected value. Checkbox, with optional label appearing after the checkbox. The value of the cell is 1 (or onValue) if checked, zero (or offValue) if unchecked. button that toggles through multiple states. Button shows current value. Clicking button will cycle across the arguments (or array) passed to toggleButton(). This is an analog for a select boxExample: `toggleButton(["low", "medium", "high"])` produces an 3-state button that cycles in order between the values. `toggleButton("low medium high")` does the same thing button that toggles through 2 states. Alternate form of checkbox functionality. Possible values are 1 (on) and 2 (off). series of buttons that toggle through 2 states. Results show as array of values selected. Optional css text allows you to style button independent of the cell itself.

### Table: Misc      (top)

The following variables and functions are useful in a Table's misc row in the Section-level template.
Table::clearProp(pname) Clear all values of a given column within a table Fix number of properties (columns) at n Set property names to those in array a. Adjusts number of columns if necessary. show only rows in other otherTable according to expr (expr behaves similar to filter). Mirror other Table's template in current Table. Changes to the template in either table will be reflected in both. If passed expr, rows in this table will reflect filtering of other table by expr. To remove linkage between the tables, use Table.unmirror(). Detach mirroring from other Table by copying template values from it Determines the order in which objects are sorted before they are displayed. Specify in the filter cell in a table's Section template. The underlying objects are retained in their original order. If sorting on a column, the column name will show a prefix ("+" for low-to-high sort and "-" for high-to-low sort) Example: `sort="a"` sorts by variable a, lowest to highest; `sort ="-a"` sorts by a, highest to lowest`sort="cmp(o1.date, o2.date)"` sorts by the date (see the cmp() function for more information) Table property that sets the html of each row's label (leftmost column). use index to refer to the current row. Remember to keep any string literals in nested quotes. Alternatively, you can declare rowLabel as a function with the row number as argument.Example: this.rowLabel='"row"+index'

### Table: Prep      (top)

Preprocessing helpers for Table prep row or anywhere
prepEngu(textNum) Prepare a "engu"-formatted number. Incorporate multiplier suffix (m (milli), k (kilo), etc.) to turn into a proper number. In the Objectsheet, this is typically used in a Table's prep row to process such a number just typed in.Example: `prepEngu("32.5k")` => 32500 Turn comma-separated items into array Turn a generically entered textDate (e.g., 3/23/2003, 23 feb 2003, FEB 23, 2003, etc.) into a standard, sortable form (via Date.valueOf()). Also see toDate() format function. convert time of day entered as hh:mm:ss to internal representation Remove non-numeric characters from number Applies prep function once to existing values in column. Use to update values in-place.

### Table: Reference      (top)

return nearest value above current column where expr is true
Table::rc(row,col) Return cell value by cartestian coordinates row and col umn Return cell formula (or value) by cartestian coordinates row and col umn Forces a Table column's values to span from start (at top) to end (at bottom). Uses Table's formula row. As table is grown or shrunk, the endpoints are maintained.Example: `range(0,10)` in a property's function cell numbers the values in that column from 0 to 10, regardless of how many rows are in the Table Forces a Table column's values to span from start (at top) to end (at bottom). Uses Table's formula row. Values are geometrically spaced. As table is grown or shrunk, the endpoints are maintained. return all numeric values in the current row, ignoring index. If ignorecols is supplied as an array or as space-separated attribute names, those columns are not returned by this method.

### Table: Style      (top)

These functions assist in the smart styling of cells to assist in catching errors, highlighting certain conditions, etc.
constrain(expr) Highlight cells for a given property where expr evaluates to false. The CSS used to do the highlighting is in the variable `constrain.style` and can be changed. Hilights row (if in Section Template) or cell (if in Property Template) in light yellow if expr evaluates to true. if lo and hi parameters are supplied, highlights if expr is number between lo and hi. The CSS used to do the highlighting is in the variable `hilite.style` and can be changed.