AspGrid 2.5

Object Reference

Copyright (c) Persits Software, Inc. 1998

Other resources:

AspGrid Object Model diagram

AspGrid Implementation Guidelines

AspGrid User Manual

Please read the Disclaimer before installing and using AspGrid.

Grid Object

This is the main object that can be created as follows:

Set Grid = Server.CreateObject("Persits.AspGrid.1")

</OBJECT>

Grid Properties

SQL Type: String
Required: Yes
Comments: Specifies the main SQL SELECT statement the grid is based on. For the grid to be updateable, the SELECT statement may not contain a join. Also, an updateable grid must be based on a table that contains an identity column, and this column must be the first one in the SELECT statement's field list. FileName Type: String
Required: Yes
Comments: Specifies the file name of this ASP page. Setting this property is necessary to correctly generate the ACTION attribute of <FORM> tags. FormName Type: String
Required: No
Comments: Specifies the NAME attribute of the <FORM> tags. This property is optional.
NumberOnPage Type: Integer
Required: Yes if there are multiple grid objects on a page.
Default Value: 1
Comments: Specifies a unique integer identifier of a grid object. This property is necessary to avoid conflicting HTML form field names when multiple grid objects are placed on the same page. Usage: Grid1.NumberOnPage = 1
Grid2.NumberOnPage = 2 CanAppend
CanEdit
CanDelete Type: Boolean
Required: No
Default Value: True
Comments: Specify whether the grid should display the Add New, Edit and Delete buttons, respectively. ShowHeader Type: Boolean
Required: No
Default Value: True
Comments: Specifies whether the grid should show a header with column names. UseImageButtons Type: Boolean
Required: No
Default Value: True
Comments: Specifies whether the grid should use images for the edit, delete, add new, page up, page down, cancel, and ok buttons. If set to False, it makes the grid use regular HTML submit buttons. MaxRows Type: Integer
Required: No
Default Value: 0 (which means unlimited)
Comments: Specifies the maximum amount of rows displayed by the grid at a time. If the amount of records in the current record set exceeds MaxRows, the navigation buttons will be shown automatically. ImagePath Type: String
Required: No
Comments: Specifies the path to the button images. By default, the buttons images are located in the same directory as the ASP file. Usage: Grid.ImagePath = "/images/buttons/" ExtraFormItems Type: String
Requres: No
Comments: Specifies additional form items that will be included in every form generated by AspGrid. This may be necessary if, for example, a parameter variable is passed from another frame and this variable needs to be made persistent in this frame. Usage: Grid.ExtraFormItems = "<INPUT TYPE=HIDDEN NAME=ID VALUE=" & Request("ID") & ">"

SQLBeforeInsert
SQLAfterInsert
SQLBeforeUpdate
SQLAfterUpdate
SQLBeforeDelete
SQLAfterDelete

Type: String
Requres: No
Comments: Specify SQL statements that will be executed at the appropriate time.

Expires Type: Date (read-only)
Required: No
Comments: Returns the component's expiration date. If the return value is 9/9/9999 it means that the component never expires. If the expiration value in the registry is missing or corrupt, the return value is 0 (displayed as "12:00:00 AM ").

Grid Methods

Connect(DSN as String, UserID as String, Password as String)
Return Type: Integer
Parameters: DSN - a system ODBC data source name.
UserID, Password - authentication parameters for the data source. Comments: Establishes a connection with an ODBC data source. Throws an exception in case of an error. Disconnect Return value: Integer
Comments: Disconnects from the data source. Display Return Type: Integer
Comments: Displays the grid. Throws exceptions in case of an error. BuildForm Return Type: Integer
Comments: Should be used instead of Display if AspGrid is used in the form mode. This method does not display anything. Instead it builds HTML input tags for each field in the SQL statement and places these tags in their respective Column objects. The tags are then accessible via the Cols(i).FormHTML property. See Lesson 6 of the manual for more info. Table Return Type: Object
Parameters: None
Comments: Returns the Table object.
Cols(Index as Integer) Return Type: Object
Parameters: Index: a 1-based index of the column. Comments: Returns the specified Column object. ColRange(FromIndex as Integer, ToIndex as Integer) Return Type: Object
Parameters: FromIndex, ToIndex specify the column range. Comments: Returns a special Column object that represents a group of adjacent Column objects. Usage: Grid.ColRange(2, 3).Cell.Nowrap = True
(equivalent to
Grid.Cols(2).Cell.Nowrap = True
Grid.Cols(3).Cell.Nowrap = True) ShowLeftSideButtons(Optional ShowBoth) Return Type: None
Parameters: ShowBoth, if True or omitted, instructs AspGrid to display control buttons both on the left and right sides of the grid. Otherwise, only the buttons on the left side will be diplayed. Comments: This method instructs AspGrid to display control buttons on the left side of the grid. If the optional parameter is set to False, the buttons will not be displayed on the right side.

Table Object

The Table object encapsulates the HTML <TABLE> attributes of the grid.

Table Properties

Border Type: String
Comments: Specifies the BORDER attribute of the <TABLE> tag. If this property is not set, this attribute will be omitted.
Align Type: String
Comments: Specifies the ALIGN attribute of the <TABLE> tag. If this property is not set, this attribute will be omitted.
Width Type: String.
Comments: Specifies the WIDTH attribute of the <TABLE> tag. If this property is not set, this attribute will be omitted.
Caption Type: String
Comments: Specifies the CAPTION attribute of the <TABLE> tag. If this property is not set, this attribute will be omitted.
Class Type: String
Comments: Specifies the CLASS attribute of the <TABLE> tag. If this property is not set, this attribute will be omitted.
CellSpacing Type: Integer
Default Value: 0
Comments: Specifies the CELLSPACING attribute of the <TABLE> tag.
CellPadding Type: Integer
Default Value: 1
Comments: Specifies the CELLPADDING attribute of the <TABLE> tag.

Column Object

The Column object represents a single grid column.

Column Properties

Header Type: Object
Comments: Returns this column's Header object. This property is read-only.
Cell Type: Object
Comments: Returns this column's Cell object. This property is read-only.
Index Type: Integer
Comments: Specifies the 1-based index of this column.
Caption Type: String
Comments: Specifies the caption of the column that will be displayed in the column header. If this property is not set, the ODBC record set field name will be displayed. Hidden Type: Boolean
Default Value: False
Comments: Specifies whether this column is hidden.
ReadOnly Type: Boolean
Default Value: False
Comments: Specifies whether this column is read-only. CanSort Type: Boolean
Default Value: False
Comments: Specifies whether this column can be sorted on. If set to True, an "arrow up" and "arrow down" buttons will be added to the headed of this column. NOTE: if you set any of the CanSort properties to True, you may no longer use an "ORDER BY" clause in your Grid.SQL.
DefaultValue Type: Variant
Comments: Specifies the value that will be stored in the database for hidden, read-only and blank columns whenever a record is added or edited. Array Type: Variant Array
Comments: Specifies the array of values (options) that will be displayed in a drop-down list box whenever a record is added or edited. VArray Type: Variant Array
Comments: Works together with Array. Specifies the array of corresponding values that will be saved in the database whenever the user picks a value specified by the Array property. This property cannot be set unless the Array property is also set. Usually, both Array and VArray properties are used to display a list of text values to the user but store them in the database as numeric values. Usage: Grid.Cols(2).Array = Array("Yes", "No", "Maybe")
Grid.Cols(2).VArray = Array(1, 2, 3) FormHTML Type: String
Comments: This property only contains a valid value if Grid.BuildForm method has been called. Contains an HTML input tag when AspGrid is used in the form mode. See Lesson 6 of the manual for more info. FieldName Type: String
Comments: If this property is set, AspGrid will use this value to build all the INSERT and UPDATE statements as well as ORDER BY clauses instead of the field name used in Grid.SQL. This may be necessary if your SQL statement contains an expression such as Grid.SQL = "select f1 + f2 ..." and the field name cannot be obtained.

Column Methods

FormatNumeric( Decimals as Integer, Optional ShowCommas) Parameters: Decimals - the number of decimal places in the number.
ShowCommas - show commas separators (True by default). Comments: Formats a numeric column.
AttachForeignTable(SQL as String, KeyColumn as Integer, DisplayColumn as Integer) Parameters: SQL - the SQL statement that obtains the list of values from a foreign table.
KeyColumn - the 1-based index of the field in that SQL statement that will be saved in the database.
DisplayColumn - the 1-based index of the field in that SQL statement that will be shown to the user. Comments: Attaches a foreign table to a column in the grid. If KeyColumn and DisplayColumn are the same, the same values will be shown to the user and saved in the database. Usage: Grid.Cols(3).AttachForeignTable "select id, name from items", 1, 2 (item names will be shown to the user, and the item id will be saved in the table). Grid.Cols(4).AttachForeignTable "select country_name from country", 1, 1 (country names will be shown to the user and saved in the table). AttachCheckBox(DisplayChecked as String, DisplayUnchecked as String) Parameters: DisplayChecked - the string that will be displayed in the column in the non-edit mode when the corresponding database field's low byte value is non-zero. DisplayUnchecked - the string that will be displayed in the column in the non-edit mode when the corresponding database field's low byte value is zero. Comments: Use this method if you want to display a field in your database as a checkbox. Calling this method forces the grid to display this column as a checked or unchecked checkbox in the edit mode, and as DisplayChecked or DisplayUnchecked in the non-edit mode if the corresponding database field is nonzero or zero, respectively. The arguments can be simple string values, such as "Yes", "No", or HTML tags for displaying images of checked and unchecked icons. Usage: Grid.Cols(6).AttachCheckBox "Yes", "No"

Grid.Cols(6).AttachCheckBox "<IMG SRC=""check.gif"">", "<IMG SRC=""nocheck.gif"">"

AttachTextArea(Optional Rows, Optional Cols)

Parameters: Rows, Cols - the ROWS and COLS attributes of the <TEXTAREA> tag, respectively. If any of the parameters is not specified, the corresponding attribute will be omitted. Comments: Use this method if you want to display a field in your database as a text area. This is particularly useful when the grid is used in the form mode. Usage: Grid.Cols(6).AttachTextArea 5, 30

Cell Object

The Cell object encapsulates the attributes of HTML <TH> and <TD> tags inside the grid.

Cell Properties

Font Type: Object
Comments: Returns the Font object associated with this cell or header. This property is read-only.
Nowrap Type: Boolean
Comments: Specifies whether this cell has a NOWRAP attribute.
Align Type: String
Comments: Specifies the ALIGN attribute of the <TD> or <TH> tag. If this property is not set, this attribute will be omitted.
VAlign Type: String
Comments: Specifies the VALIGN attribute of the <TD> or <TH> tag. If this property is not set, this attribute will be omitted.
Width Type: String
Comments: Specifies the WIDTH attribute of the <TD> or <TH> tag. If this property is not set, this attribute will be omitted.
Height Type: String
Comments: Specifies the HEIGHT attribute of the <TD> or <TH> tag. If this property is not set, this attribute will be omitted.
BGColor Type: String
Comments: Specifies the BGCOLOR attribute of the <TD> or <TH> tag. If this property is not set, this attribute will be omitted.
Class Type: String
Comments: Specifies the CLASS attribute of the <TD> or <TH> tag. If this property is not set, this attribute will be omitted.
InputSize Type: Integer
Comments: Specifies the SIZE attribute of the <INPUT TYPE=TEXT> tag when a row is in the edit mode. If this property is not set, this attribute will be omitted. InputMaxLength Type: Integer
Comments: Specifies the MAXLENGTH attribute of the <INPUT TYPE=TEXT> tag when a row is in the edit mode. If this property is not set, this attribute will be omitted. InputUserAttributes Type: String
Comments: Specifies any number of arbitrary attribute/value pairs for the <INPUT TYPE=TEXT> tag when a row is in the edit mode. The string specified will appear in the <INPUT> tag as is with no additional formatting. Usage: Grid.Cols(3).Cell.InputUserAttributes = "OnChange=""func_change()"" OnFocus=""func_focus()"""

Font Object

The Font object encapsulates the attributes of the <FONT> tag associated with a cell or header.

Font Properties

Face Type: String
Comments: Specifies the FACE attribute of the <FONT> tag. If this property is not set, this attribute will be omitted. Size Type: Integer
Comments: Specifies the SIZE attribute of the <FONT> tag. If this property is not set, this attribute will be omitted. Color Type: String
Comments: Specifies the COLOR attribute of the <FONT> tag. If this property is not set, this attribute will be omitted. Class Type: String
Comments: Specifies the CLASS attribute of the <FONT> tag. If this property is not set, this attribute will be omitted. Bold Type: Boolean
Comments: Specifies whether the cell or header will be surrounded by <B> </B> tags.