Objectsheet Reference

© 2001 Rich Knopman

This page serves as detailed documentation for Objectsheet proof-of-concept application.

General

• An Objectsheet is an organizing medium for data, with application similar to the spreadsheet. A single Objectsheet is essentially a single table of finite size with its own display space and its own behavior (via formulas and functions). Multiple Objectsheets in a single file calculate as a whole, but can be moved, reformatted, and redefined independent of each other.
• JavaScript is the processing engine for all aspects of the Objectsheet, although effective use of Objectsheets do not require knowledge of JavaScript.
• This version of the Objectsheet software was written entirely in JavaScript so it opens up in a safe browser window. The download is less than 100KB and runs only under Internet Explorer 5.

  you can see a here, but first, please check out the tutorial!

User Interface Overview

• An Objectsheet is made up of five sections:
  1. Sheet section (in orange background) -- holds sheet level information and actions
  2. Template section (cells with yellow background) -- holds common characteristics of the objects in the sheet
  3. Instance section (cells with white background) -- holds actual values of the objects in the sheet
  4. Summary value section (yellow area just below instance section)-- holds results of summary properties.
  5. Status bar (grey area at bottom) -- holds status and error messages and other indicators

• A newly created Objectsheet consists of a small set of cells, but can be expanded to be as large as you like. To add cells to a sheet, click on the expandor (the plus sign in the middle-top) and drag down (to add objects) and/or to the right (to add properties). The number of objects and properties to be added appear in the status bar. (In this version, of the Objectsheet, you cannot delete cells)
• Enter numbers, text, or formulas into cells, either in the (white) instance section or the (yellow) formula row. Formulas in cells are denoted by the first character being an equals sign (like the traditional spreadsheet). When you change a cell's value and then click out of or tab out of it, the sheet propagates that change throughout that sheet as well as all sheets in that file.
• There are two menus: SHEET and VIEW. to use, click on those titles and select an action from the dropdown list. Note: to quit a menu without selecting an item, you must click on the SHEET or VIEW label again.

Introduction

External vs internal object representation

• Each row in the instance section represents a single, exposed, object. These UI-facing objects are the basic semantic elements of the Objectsheet; they can each represent rooms in a house, students in a class, etc.
• Each object in the instance section is represented internally as a Javascript object. There are many other internal Javascript objects to repesent properties, other-object references, the Objectsheet's own name, etc. They are not exposed graphically, but you can access and change them. For instance, the entire sheet is a Javascript object, containing all the information within. It is called 'this'. The sheet's name (the bold name in the upper left of the sheet) can be retrieved in a formula as 'this.name'.

Objectsheet Calculation

• Objectsheet calculation works by evaluating things in the following order:
  1. The scratch area (if user explicitly executed a scratch calculation)
  2. The modified cell (if not a scratch calculation)
  3. All content in the script area
  4. All summary properties
  5. Each object in the instance section (either via the formula template row or "override" formulas in the cell itself)
  6. For each object, each property is evaluated in order, left to right.
  7. Summary properties again (to evaluate any formulas that refer to just-calculated objects)
  8. html text
  9. Reflect template (automatic) vs in-cell (override) calculation as style in each object cell
  10. Apply formatting to each object cell via formulas in the format template row
  11. Apply styling to each object cell via formulas in the style template row
  12. Render each object cell as either standard textbox or via formula in the display template row

  Note that object calculations are done down the rows, and properties are calculated left to right, so if a formula references a cell below or directly to the right (ie. a cell that hasn't yet been calculated), the value used will be current value (which may change when that cell is eventually calculated).

Object vs Sheet Scope

There are two contexts under which formulas are calculated. They access data in slightly different ways.

The primary context is Object scope, which applies to all instance-section and Template cells. Calculation of objects and other cell attributes (steps 8-11 above) applies each formula to each row (object) in sequence, top to bottom. A great majority of the formulas in an Objectsheet are generally Object scope.

In these cells, the default object is "the object in the current row". When a formula references another property of the same object, all that is needed is a property reference (this is the way object method scope works in all object oriented languages). When a formula references another object (on a different row), an explicit object reference is required. This is discussed later.

The other context is Sheet Scope, which applies to the scratch area, summary properties, and script area. They are only evaluated in the context of the whole sheet. The only exception is that additional object methods and properties can be defined in the script area, but indeed can only be accessed by the objects themselves.

The default object in this case is the sheet itself (this). These sheet level areas still have access to the objects in the instance section (via the object[] array), but do not have access to some row-specific attributes, like me and prev.

Sheet Level Properties

 

General Properties of the Sheet Object, this

• Note: To see the internal object structure of an entire sheet, evaluate the expression this (or splay2(this) for large sheets) in the scratch row.
• name: the name of this sheet (upper left corner text box, modifiable).
• script: Javascript code that is executed before the sheet is calculated. You can define functions in the script area and use them in template or instance formulas. VIEW > script shows or hides the script box.

  Optional functions NOT YET BUILT for the script area:

  • function finally() is executed after sheet is calculated.
  • function eachObject() is executed before each object (row) is calculated
  • function eachCell() is executed before each cell (object.property) is calculated.
• html: html source to be rendered in the sheet (above the template). VIEW > html shows or hides the html source.
• mom: the parent sheet (under development-- not exposed in the current application).
• calc(): causes the sheet tocalculate. Do not use yet, as it can cause the objectsheet to enter an infinite loop. Once safety features are in place, it will be possible to use calc() to do controlled, iterative, calculations.
• _len: gives the number of objects in the current sheet. _len is an alias for object.length (this is the same as _len in Object Scope)

Object and Property References from Sheet Object (this)

• property with a name of 'name': if a property of the sheet is given the name 'name', it becomes magical; the value of the 'name' property in each row becomes the name for the object in that row. here is an example:

  

• object[]: indexed array of objects in the sheet.
• prop: holds references to each named property and its associated attributes (see the property object below).
• iprop[]: indexed array of properties in the sheet (see the property internal object below)
• props("expression", condition) function: processes expression through all objects, returning results as an array. more...

Child/Parent relationships

• sib(sheet_name) function: returns a references to the named sheet spawned from the current sheet (sheet are spawned using either the SHEET > New or the SHEET > Load menu command).
• indexChild[] array: array of children sheets spawned from the current sheet.
• root() function: reference to the root sheet in the current heirarchy, "_top".

Object References

me: The default (current) reference to an individual object The me object is implied in Template and override cell formulas (i.e. the formulas 'a*2 + b' and 'me.a * 2 + me.b' are equivalent).

prev: This always refers to "the row above the current one". It returns undefined if the index variable (the row number) = 0.

self: This refers to the value in the current cell. Most often used as the target value in template expressions, especially for format and conditional style cells.

us[] array: The array of objects on current sheet, indexed by the numbers in the left side of the sheet. note: this has the same general function as the object[] array (with sheet scope), but us[] has object scope. us[] can be used inside a standard property or cell override formula (actually, within such cells, us[] is equivalent to this.object[]).

_len: gives the number of objects in the current sheet. _len is an alias for us.length (this is the same as _len in Sheet Scope)

index: This variable always contains the index (ie. row number) of the object being calculated.

Properties and their Attributes

Objectsheets can have one or more properties. Properties form the columns of the Objectsheet. Each property, in turn, has several attributes that control how that property is calculated and displayed. Cells for these attributes can be shown or hidden via the VIEW menu, or can be referenced in formula by "prop.propertyname.attribute" (e.g. prop.a formula shows the current formula for a). Likewise, a property attribute can be set by formula with "prop.propertyname.attribute = value" (e.g. prop.a.cellWidth = 12, which sets the width of the a column to 12 characters).

Each property has the following attributes:

Attribute	Description	Notes
name	The name the property is referred by objects on the sheet.	The default name of the first property (column) in the sheet is 'a'. when you change a property name in the name cell, all occurances of that name in formulas are also changed automatically.
formula	If a formula cell is filled in, that property is automatically calculated for each object and that column is shaded grey to indicate automatic calculation.	If a property has no formula, the column is shaded white. An individual cell will also be shaded white if there is a formula, but you override it with a literal value or formula in a specific cell.
width	The width in characters of the column that makes up the property.
format	The formula that determines how the property is displayed. Some helper functions: fix(self,n) Limits the number of decimal places to no more than n. sci(self,n) Scientific notation, limiting the number of decimal places to n eng(self,n) Engineering notation exponent divisible by 3 engu(self,n) Suffix notation: (P = 1015, T, G, M, k=103, m=10-3, u, n, f, p, a =10-18) dol(self,n) Dollar notation	The format attribute represents a generic transformation of calculated value to displayed value; the value in the current cell is self. Other examples include self+"in." , which suffixes "in." to all values, self>10?"":self, which only displays values greater than 10, and self<0?"("+(-self)+")":self, which displays negative numbers in parentheses. In all these cases, the cell still retains its raw (untransformed) value when referenced from other formulas; this transformation is for display only. Also note that complex functions like self<0?"("+(-self)+")":self may be turned into a function in the script area (choose script from the VIEW menu), or alternatively, placed into a separate '.js' file and imported via statement in the script area via the execScript(scriptName) command.
style	Retrieves or sets the style (CSS notation) for each cell in a column. The full CSS capabilities of the browser can be used here. To give all cells of a property a particular style, just type the desired css text in the respective style cell. Some examples of css tags are: font-family: (helvetica, times, ...) font-style: italic (et al) font-weight: bold font-variant: small-caps text-decoration: underline text-align: (left | center | right | justify) text-transform: (capitalize | uppercase | lowercase) color: (color name | #rrggbb) --this is text color background-color: (color name | #rrggbb)	See Tom's CSS Quick Reference for a more thorough treatment For conditional syling (selectively styling some elements based on a particular condition), use a formula, prefixed with an equals sign. Some examples include =self<0?"color:red":"", which displays negative numbers in red; =index%2?"background-color:yellow":"", which alternates backgound color for successive cells down a column. A special formula called constrain() provides a generic form of type- or range- checking. This function accepts a conditional expression (the constraint) as its only argument. If the condition is not met in a particular cell, a red border is drawn around it. Again, self refers to "the current value". Some examples: =constrain(self>0) Asserts the current value to be a positive number (i.e. highlights any occurences of zero, negative numbers, or non-numbers, like text); =constrain(!isNan(self)) Alerts if the cell is not a number =constrain(self.toString().match(/\d{3}-\d{3}-\d{4}/)) Alerts if the value is not a 10-digit US phone number (XXX-XXX-XXXX).

Cell Types

A cell is a visible container for an individual piece of data. The cell in a traditional spreadsheet is defined by its cartesian location on the within the spreadsheet. In the Objectsheet the term 'cell' is indeed the fundametal container, but is defined by its association with the row and column who's intersection it forms. a cell is accessed as an intersection of object-dot-property, not by its coordinates on the grid of cells.

Type	Indicated By	Description
Literal	white background	Expect manual entry of values. Any cell not defined by a formula in the formula row is automatically a literal cell.
Calculated	grey background	These cells have formulas defined in the "formula" row of the template and therefore are automatically calculated.
Override	white background	A calculated cell (see above) can be overridden with a value (either literal or formula) simply by placing text, a number, or formula in the desired cell. In this case, the cell background reverts to white to denote manual entry, and the formula remains in the cell as a suffix to the value, separated by ':='.
Summary	yellow background	Any template formula that starts with ':' (instead of '=') becomes a summary formula and the property a summary property. Summary formulas are evaluated before (to allow definition of constants) and again afer all the instance rows (to allow summarization of the last calculation). Summary properties have no instance cells; results appear in a special cell immediately below the instance section.

 

Objectsheet Function Reference

These are all simple Javascript functions. You can see the code behind them by typing the bare function name (no parentheses) into the scratch area and evaluating it.

Object Iterators/Array processing Mostly useful in summary property formulas.
props("expr", condition)	Evaluate "expr" through all objects, returning results as array. An optional condition includes only those values for which condition is true. The returned array can be supplied to functions below. Note that props() has Sheet scope; to use in an instance or template cell, use this.props().
sum(array)	Returns sum of values in array
avg(array)	Returns numeric average of values in array
amax(array)	Returns numeric maximum value of array
amin(array)	Return numeric minimum value of array
prod(array)	Returns multiplicative product of values in array

Example: To sum the values of property "a", use sum(props("a"))

To come: object sort function

General Math
log10(value)	Return log base 10 of value (Javascript default is base e)
log2(value)	Return log base 2 of value

 

Formula Cell All these functions are Object Scope.
range(a, b)	generate values over inclusive range [a, b], arithmetically interpolated
erange(a, b)	generate values over exclusive range [a, b), arithmetically interpolated
grange(a, b)	generate values over inclusive range [a, b], geometically interpolated

 

Format Cell
fix(value, places)	Limits number of decimal places in value to no more than places.
sci(value, places)	Scientific notation, limiting the number of decimal places to no more than places.
eng(value, places)	Engineering notation (exponent divisible by three), limiting the number of decimal places to no more than places.
engu(value, places)	Suffix notation: (P = 1015, T, G, M, k=103, m=10-3, u, n, f, p, a =10-18)
dol(value, places)	Fixes value, inserts commas, prefixes '$'. places defaults to 2.

 

Style Cell
constrain(expr)	alerts (outlines cell in red) if expr not met. Examples are: constrain(typeof self=='number')-- alerts if value cannot be interpreted as a number constrain(self >= 0)-- alerts if value < 0 constrain(self.toString().match(\d{3}-\d{3}-\d{3}/) -- alerts if value is not of matching form (on this case, U.S. phone number, portions separated by dash
inRange(num, limit1, limit2)	returns 1 (true) if num is numerically between limit1 and limit2, inclusive (doesn't matter whether limit1 is greater or less than limit2). returns 0 (false) otherwise.

 

Display Cell Renders cell in form other than default single-line textbox.
textarea(rows, cols)	Shows cell value in multiline textbox
select(elements)	dropdown select box- elements is an array. can be a reference to another array or can be an array literal (e.g. [2, 4 8]). the cell value is the visible value of the select box.
radio(elements)	Like select(), except items are displayed as radio buttons
checkbox(label)	checkbox element-- returns 1 (true)/0 (false)-- if label specified, displays to right of checkbox
toggle(elements)	Not yet working: Toggle button-- elements is an array. Sequences among array values when clicked. Current cell value appears to left of button, next element in array appears as button label.

 

Miscellaneous Mostly useful for exploring the internal Javascript objects via the scratch area
splay(object)	unfolds object into tabbed tree
alert2(text)	similar to JavaScript alert() but displays as scrollable window
increment(text)	smart increment- returns text with last found number incremented. If text contains no number, returns text_1.

Some Standard Javascript Functions and Constants

Math
Arithmetic Operators	+ , - , * , / , % , ++ , -- , ','
Comparison Operators	< , <= , > , >= , == , ===
Bitwise Operators	& , | , ~ , ^ , << , >>
Logical Operators	&& , || , ! , (? : )
Transcendental Functions	acos() , asin() , atan() , atan2() , cos() , sin() , tan() , exp() , log()
Miscellaneous Functions	floor() , ciel() , round() , abs(), pow() , sqrt() , max() , min() , random()
Constants	E , LN2 , LN10 , LOG2E , LOG10E , PI , SQRT1_2 , SQRT2

 

Processing Methods and Functions
Array	.concat() , .join() , .reverse() , .sort() , .length()
Text	.charAt() , .charCodeAt() , .fromCharCode() , .indexOf() , .lastIndexOf() , .match() , .replace() , .slice() , .split() , .substr() , .substring() , .toLowerCase(), .toUpperCase() , .valueOf()
Miscellaneous	escape() , unescape() , eval()
Date Object	Setting the formula of a property or cell to 'new Date()' will generate a javascript Date object. new Date() without any value calculates the current date, or with arguments, will calculate the date with respsect to those arguments (see a Javascript reference).
Comments	//... and /*...*/ can be entered in any cell

Reserved Words

Both the Objectsheet and the underlying Javascript language have a number of reserved words that you cannot use as identifiers. Reserved words have a specific meaning to the Javascript language, as they are part of the language syntax. Using a reserved word causes a compilation error when loading your script.

Objectsheet Reserved Words

The following words are used internal to the Objectsheet. While they are only active in particular context, and thus only cause problems in that context, their use is still discouraged.

Javascript Reserved Words

Javascript Future Reserved Words

Javascript also has a list of future reserved words. These words are not currently part of the Javascript language, but are reserved for future use. 

When choosing identifiers it is also important to avoid any words that are already the names of intrinsic JScript objects or functions, such as String or parseInt.

Rich Knopman © 2001.

Updated 25 Aug 01