Table Section Overview

Page Contents: Overview, Template (overview, Property, Section, precedence), Referring to Cells, Referring to Rules, Summary

Table Sections are finite grids of cells with a coherent data structure. A Table represents an array of Javascript objects, referred to as the us[] array. Each Javascript object occupies a row in the table. Each cell in a row represents a named property of the object. In the table below, us[1].tax corresponds to row 1, "tax" column, or the number 200. In addition, there are also other ways to refer to values in Table cells.

The structure of cells in an Objectsheet table

Tables are comprised of two main areas: the Instance area and the Template. The Template is where all the "rules" go— rules are standard expressions that apply to the cells of the table. The Instance area is where the resulting values go. Values in a table may be calculated by a Template formula or you can directly enter values or formulas into cells in the Instance area.

In the table above, columns "cost" and "tax" have formulas in the formula row; values calculated by formula are shown with gray background. The "area" column does not have a formula-- any values are manually entered and are shown with a white background. The value in row 2 of the "cost" column was entered manually, overriding the formula and turning the background white.

The Template

The Template itself is composed of two parts. The Property Template is where rules (formula, format, style, etc.) can be entered for individual columns. The Section Template is for rules that affect all columns at once. When first created, a table shows only the Instance area and the "name" and "formula" rows; the rest of the Templates are hidden.

The Section Template (Green rows above)

Expressions in the Section Template affect all columns. The "S" button (upper right corner of the section) shows or hides the Section Template. The following describes the rows of the Section Template (and where in the Tutorial you can find more detail):

• filter: Show only rows where expression is true. See Tutorial 2, #9.
• format: Format that applies to all columns (see Property template entry above)
• style: CSS literal or expression that applies to all columns (see Property template entry above)
• display: display expression that applies to all columns (see Property template entry above)
• misc: The misc row allows you to execute an expression each time before a table is calculated. This can be used to fix or track (against another table) the number of rows or columns, or to set convenience variables. See Tutorial 3, #12.
• formula: Formula that applies to all columns (see Property template entry above)

The Property Template (Blue rows above)

The Property Template holds formulas that affect each column. To show or hide the Property Template, use the "P" button (upper right corner of the section). A separate f() button controls just the formula row. The name row is always visible. The following describes the rows of the Property Template:

• action: This expression triggers actions when values are entered by hand. This can be used to trigger an update elsewhere in the Objectsheet or to force calculation for an table that is "offline". See Tutorial 2, #8.
• prep: This expression prepares values typed directly into cells, to strip unwanted characters, validate data, or do a preliminary conversion. See Tutorial 2, #6.
• format: The format row is for expressions that convert the calculated value to the one shown in the cell. Format formulas can show units, format numbers, convert units for display. See Tutorial 2, #5.
• style: The style row controls the style used to display a value (text alignment, colors, borders, font family and size, etc.). CSS text can be entered directly, or expressions can be entered (prefixed with an equals sign). Can also be used to highlight cells that meet thresholds, or hide a column completely. See Tutorial 2, #7.
• display: Allows you to change the cell from normal text entry to select box, radio button, multiline text area, etc. See Tutorial 2, #8.
• formula: This is the expression used to calculate cell values down a column. See Tutorial 1, #3 for more details and an example.

The "P" button (upper right corner of the section) shows or hides the Property Template. A separate f() button controls just the formula row. The name row is always visible.

Expression Precedence

To determine which formula applies to a particular cell, the Objectsheet uses a "bottom-up" precedence order. The lowest precedence is the Section Template, highest is when a value or formula is entered directly in a cell in the Instance Area. Alternatively,

Instance cell formula OVERRIDES Property Template formula, which OVERRIDES the Section Template formula

You can enter formulas directly into cells in the instance area, but there is no mechanism to directly enter other attributes (display, format, style, etc.). These attributes are determined only by the Template. You can effectively override attributes for specific cells by testing for the appropriate row or cell within a template expression.

Referring to Table Cell Values

Objectsheet Tables make use of Javascript data structures. Refer to different cells use the following techniques*:

1. Same Row: To refer to a cell's value from another cell in the same row, just use the cell's column name. Note that the Objectsheet evaluates columns left to right; referring to a column "to the right" that contains a formula may give improper results. There is also a way to refer to a column's numeric index.
2. Prior Row: Since referring to "the row directly above" during calculation is common, the prev object provides this. To refer to a cell in the prior row, use prev.columnname.
3. By Row: To refer to an arbitrary cell in the same table, use us[i].columnname, with i simply the labeled row number (see above). For instance, in the table above, us[1].cost returns the number 5000. As with spreadsheets, the raw (unformatted) value is returned.
4. By Named Row: If you add the prefix "*" to a row's name, the values in that column become names of each row (replacing us[rownumber]). For an example of this, see Tutorial 3.
5. By Column: Another way to refer to an arbitrary cell is by the Column Function: just use the column name as a function: columnname(row#) with the row number the argument. To return the entire column of values as an array, just use the column name without any argument: columnname(). Note that the Column function is a Table-scoped function. To use this in formula cells within a Table, prefix the function with "this"; e.g., this.columnname(row#)
6. Across Sections: To refer to a cell from another table or anywhere else in an Objectsheet, prefix us[] or the Column Function with the table's name; e.g., table2.us[1].area or table2.area(1).

* Examples of approaches 1-3 are shown in tutorial 2; examples of approach 4 and 5 are shown in tutorial 3, here and here. Approaches 3 and 4 are also illustrated below.

Since all of the above are Javascript expressions, you can use variables in place of numbers, column names, and section names to refer to cells in an Objectsheet Table.

Each row in a Table's instance area is an element in the us[] array.
For references within a table, the table's name is optional.

Additional information about Objectsheet Tables can be found in the tutorials.

(Advanced) Referring to the Rules within a Table

In addition to table's values, all formulas, styling, and other rules in an Objectsheet Table (and all other Objectsheet sections) are enclosed in the table's data structure. For most uses, your formulas shouldn't need to refer to template cells, but doing so can be useful when reusing parts of the template between tables (e.g., column "e" in tutorial example 12) or for debugging using a Scratch section).

For the Property Template, you can access the attributes of each column either by number using the "_iprop" array (._iprop[columnnumber]) or by column name using object notation (.prop.columnname).

For the Section Template, you can reference a named attribute using the attribute's name referenced to the Section javascript object (sectionname.attributename across Tables or simply attributename within the Table.

You can explore all of the above attributes in a few different ways. First, you can inspect these data structures using a scratch section (see example in tutorial). You can also inspect an Objectsheet source file using a text editor. Take a look at a sample .os file. Within an .os file you will also see a ".view" object for each section, which holds information on screen positioning, section visibility, template visibility, etc. Note: only a table's _iprop[] array (not the prop object) is stored in a .os file.

Summary

In summary, the above features of the Objectsheet Table increase usability and reduce errors:

Each of the above features are demonstrated in the accompanying Tutorial.