PERGOLA LOGO

pergola.DataGrid

System events: YES.

User events and functions: NO.

An instance of this class cannot be an orphan object and must be contained in a window. It is typically created by instantiating a Window and invoking its datagridMaker() prototype method. See Example. Learn more in the DATAGRID section of the Tutorial.

The native data format for pergola.DataGrid is JSON. Learn more in the DATAGRID#data section of the Tutorial.

Listed: class properties/methods; prototype properties and methods; instance properties. Prototype properties and methods inherited by the Class superclass are not listed.

class

None

prototype

PROPERTIES

headerHeight

Defined in pergola.presentationAttributes – number (user space units).

rowHeight

Defined in pergola.presentationAttributes – number (user space units) or the string "auto" (default).

nColumns

Defined in pergola.presentationAttributes – number. Number of columns; applies to empty grid. If binding is specified, this columns length.

nRows

Defined in pergola.presentationAttributes – number. Number of rows; applies to empty grid. If binding is specified, this rows length.

fill

Defined in pergola.presentationAttributes – string.

altFill

Defined in pergola.presentationAttributes – string.

stroke

Defined in pergola.presentationAttributes – string.

highlightFill

Defined in pergola.presentationAttributes – string.

highlightStroke

Defined in pergola.presentationAttributes – string.

gutter

Defined in pergola.presentationAttributes – boolean. If true, the datagrid has line numbers.

gutterWidth

0 – number. The value is dependent of the nRows number of rows.

readOnly

true – boolean. In this mode the menu “Save” and “Save As” are inactive.

savePath

"." – string. The folder containing the saved files. The default represents the location of writeFile.php, the script designated as default by pergola.writeFile.

permissions

"user" – string. Option "administrator"; affects Save and Save As.

language

pergola.locale – string. To override this property you must specify a string containing a BCP 47 language tag.

false – boolean or array of strings. If true, these menus are built by default: "file"; "edit"; "view"; "search". If menu is an array, it specifies which menus (from the previous list) must be built.

Note: you can also add custom menus.

METHODS

save()

Builds a JSON object based on the current state of this columns and this rows and invokes pergola.save(). Overwriting the current file is only allowed if the value of this permissions is "administrator".

saveAs()

Callback function for this getFiles(). Invokes this pergola.saveJSON(). Rejects any attempt to overwrite the current file if the value of this permissions is not "administrator".

syncMenu()

This method is invoked by the build() method, which is invoked asynchronously. Therefore the data can be queried, allowing to build and set the menu voices accordingly. It also applies for the customMenus.

Callback function for this find(). Assigns the object returned by the getData() method of the pergola.findDialog panel to this stringData. Invokes this doFind() and this gotoFound().

searchUpdate()

Invoked for updating this found array on changes affecting its structure. Invokes this doFind().

doFind()

Reinitializes this found to the empty array and populates it with object elements with label string, line number, entry string, textNode text node, start number, length number properties.

gotoFound(d)

Invokes the goToColumn() and goToLine() methods; creates a selection range.

goToLine(n)

n represents the row number. Invokes nth row select() method. Invokes this owner.doc transformation methods.

goToColumn(label)

label string represents the column's label. Invokes the column's select() method. Invokes this owner.doc transformation methods.

toggleColumn(label)

label string represents the column's label. Hides or shows the column with the specified label; sets the column's display property accordingly.

removeColumn(header)

header represents the column's DataGridHeader object. Frees its dependencies, removes the DOM objects. Note: deleting a column removes it permanently, affecting the file output on saving.

setDisplayed()

Updates the displayed array containing the visible columns.

setColumnsOffset()

Reorganizes columns and cells position after column displacement or on/off toggling; sets the columns' x properties accordingly.

gutterPositionOnScroll()

Makes the gutterGroup static.

headerPositionOnScroll()

Makes the headerGroup static.

getColumnSelectionFrameData(x)

x number is the value of the selected column's x property; returns a string representing the computed value of the columnSelectionFrame d attribute.

getRowSelectionFrameData(y)

y number is the value of the selected row's y property; returns a string representing the computed value of the rowSelectionFrame d attribute.

deselect()

Invokes this deselectColumn() and this deselectRow().

deselectColumn()

Deselects this currentColumn().

deselectRow(object)

Deselects this currentRow().

sortAscending(label, type)

label string represents the column's label and type its type ("number", "date", or alphanumeric [default]). Sorts the data in ascending order; invokes this sortApply().

sortDescending(label, type)

label string represents the column's label and type its type ("number", "date", or alphanumeric [default]). Sorts the data in descending order; invokes this sortApply().

sortApply()

Applies the rows' translations and fills.

createRows(zone)

zone is an object with start and end properties representing indices (see buffered). Invoked by this render() once if this buffered is false, or sequentially (timer). This ensures that the data is displayed upon creation of the first fifty rows. Depending on the number of cells, some browsers might reach the end of computing quicker than the rendering time for the first fifty rows.

render()

Invoked by this build.

build([object])

this inherits the properties specified in object; prototype properties specified in object are overridden. Creates elements, components and instance properties. Returns this. The method is invoked asynchronously.

instance

name

String. If not passed to the constructor, gets a generated XML name (Class).

id

String. The return value of this name.toXML(). This container ID. Used as prefix where other elements' IDs are attributed.

owner

Must be specified. Designates the owner object, which for a datagrid object can only be a Window instance.

parent

Must be specified. Designates the parent node, which for a datagrid object can only be window.doc.transformable.

binding

String or Object. In remote mode, a string representing the URL of the JSON data to load; in local mode, an object literal. If not specified, an editable blank grid is displayed with the default nColumns and nRows; in this case the readOnly property is forced to false. See the DATAGRID section of the Tutorial for details.

Structure of JSON object/object literal:

Note that if/when editing the object literal by hand you can skip unneeded quotes for property names, but a saved JSON object will have all properties in string representation.

Each column object must have the "label" and "type" properties. The data in each column must be of the same type. Learn about data types in the Columns and Data Types sections of the Tutorial.

folder

String. If binding is a URL string, the folder name string where the file is located; if binding is an object, this property is undefined. See also Save and Save As.

filename

String. If binding is a URL string, the file name string without the extension; if binding is an object, this property is undefined. See also Save and Save As.

radixChar

String. The value of pergola.radixChar[this.language]. Used for converting locale number strings back to numbers, this property is passed to the String unformatNumber() prototype extension method.

columns

Array of objects. As defined by the columns property of the loaded JSON object (or object literal in local mode). Its elements and/or their order may change on user actions and/or on dynamic updates.

After construction each object in this columns has the following properties (besides those set in the JSON data):

  • index : Number
  • x : Number (user space units)
  • width : Number (user space units)
  • display : String – "block"/"none"
  • header : pergola.DataGridHeader instance

rows

Array of objects. As defined by the rows property of the loaded JSON object (native format), or empty array for blank datagrid. Its elements and/or their order may change on user actions and/or on dynamic updates.

After construction each object in this columns has the following properties (besides those set in the JSON data):

  • y : Number (user space units)
  • height : Number (user space units)
  • group : <g> element
  • line : pergola.DataGridLine instance
  • cells : Object

The cells object has a number of object properties equal to the number of fields in each row; the property names are the columns' label values.

In readOnly mode the objects in cells have these properties: container <g> element; rect <rect> element; element <text> element; value string.

In read/write mode the objects in cells are pergola.Input instances.

Note: all formatting is applied to the value property of the cell object–and the text node of the cell's element (<text> element). The original values in the rows are not changed. On cell editing, the corresponding value in rows is updated after conversion to the appropriate type.

transY

Number. Used for sequential y positioning of the rows.

buffered

Boolean or Array – false if this rows length is <= 50; otherwise array of objects with start and end number properties representing chunks of 50 rows.

currentColumn

Reference to the currently selected column object. This cross-reference is set in the DataGridHeader's select() method on column selection, and gets the value of the header's (DataGridHeader instance) column property, which is a reference to its respective element of this columns array.

currentRow

Reference to the currently selected row object. This cross-reference is set in the DataGridLine's select() prototype method on row selection, and gets the value of the row's (DataGridLine instance) row property, which is a reference to its respective element of this rows array.

ordered

Array representing the currently displayed columns in their order (left to right).

displayed

Array representing the columns with the display property set to "block".

exclude

If specified, Array of strings representing names of columns with sensitive data to exclude in readOnly mode, or empty array if the property is not specified.

container

<g> element.

gutterGroup

<g> element.

headerGroup

<g> element.

dummy

<rect> element. Static top-left dummy box.

customMenus

If specified (using regular Menu syntax) the custom menus are added after the default menus.

height

Number representing this container's bounding box height.

width

Number representing this container's bounding box width.

columnSelectionFrame

<path> element. Column highlighter frame. Its width and positions are updated to the selected column.

rowSelectionFrame

<path> element. Row highlighter frame. Its width, height, and positions are updated to the selected row.

stringData

Object. Return value of the getData() method of pergola.findDialog.

found

Array. Defined on first use of this search() if any occurrences are found.