Grid Object

Overview

Grid is AspGrid's top-level object that serves as an "object factory" for all other objects. Create an instance of the Grid object as follows:

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

You may also create an instance of Grid using the <OBJECT> tag as follows:

<OBJECT RUNAT="Server" ID="Grid" PROGID="Persits.Grid">
</OBJECT>

Member List

Properties


CanAppend As Boolean (Read/Write)
True by default. If set to False, causes AspGrid to hide the "Add New" button which prevents new records from being added.

CanDelete As Boolean (Read/Write)
True by default. If set to False, causes AspGrid to hide "Delete" buttons which prevents existing records from being deleted.

CanEdit As Boolean (Read/Write)
True by default. If set to False, causes AspGrid to hide "Edit" buttons which prevents existing records from being modified.

Connection As String (Read/Write)

By default, AspGrid creates an instance of ADO Connection internally. This property can be used to specify an external ADO connection object instead. You must open the connection before passing it to AspGrid.

You MUST NOT pass an external ADO Connection object to AspGrid if the component is registered under MTS (Component Services) since ADO Connection cannot be marshaled across apartments.

This property can also be used to retrieve the internal ADO Connection object in case it needs to be re-used.


DeleteButtonOnClick As String (Read/Write)
Specifies a verbal message to be displayed by a confirmation dialog box when the user clicks on a "Delete" button. If this property is not specified, no confirmation dialog will be displayed upon deletion.

Expires As Date (Read-only)
Returns the component's expiration date. If a valid registration key is installed, this property returns 9/9/9999. If a registration key is invalid or corrupt, it returns 0 (displayed as 12:00:00).

ExtraFormItems As String (Read/Write)
Use this property to specify one or more hidden form items. These items will be added to every form AspGrid generates. This may be useful to make a variable passed from another page persistent.

FileName As String (Read/Write)
Obsolete. AspGrid 3.0 sets this property automatically to the name of the current ASP script. Supported for backwards compatibility only.

FormName As String (Read/Write)
Obsolete. Has no effect whatsoever. AspGrid 3.0 generates form names automatically. Supported for backwards compatibility only.

FormOnSubmit As String (Read/Write)
Specifies the OnSubmit attribute for the "Save" <FORM> tags that AspGrid generates. The OnSubmit attribute usually contains a call to a client-side JavaScript validation routine that returns True if validation succeeds or False otherwise. This enables you to perform client-side data validation before a record is submitted.

ImagePath As String (Read/Write)
Specifies the location of the control button files such as save.gif etc. relative to the current script. If you place the button images in the same directory as the current script, you do not need to set this property.

MaxRows As Long (Read/Write)
Limits the number of records shown at a time. If the actual number of records in a recordset is greater that that specified by MaxRows, AspGrid automatically displays navigation buttons in the footer section of the grid.

MethodGet As Boolean (Read/Write)
True by default which makes AspGrid use the HTTP "GET" method in all its forms. Setting this property to False makes AspGrid switch to the "POST" method.

NumberOnPage As Long (Read/Write)
1 by default. Use this property to assign a unique integer ID to a grid if multiple instances of the Grid object are hosted on the same ASP page. You do not need to set this property if only one grid resides on a page.

Output As Object (Read-only)
When Display(False) or BuildForm is called, this property returns the Output object which encapsulates a collection of individual grid elements. You can manually display these elements, either in the default or a customized form.

ReadOnly As Boolean (Read/Write)
Setting this property to True has the same effect as setting the properties CanEdit, CanDelete and CanAppend to False. Setting ReadOnly to False has no effect.

Recordset As Object (Read/Write)
By default, AspGrid creates an instance of the ADO Recordset object internally. You can use this property to specify an external Recordset object. You must open the recordset before passing it to AspGrid. You can also use this property to access AspGrid's internal recordset object. This may be useful to gain programmatic access to the grid values.

RecordsSkipped As Long (Read-only)
Returns the current number of skipped records. This property is only meaningful after Display or BuildForm is called. Can be useful for displaying row numbers in a grid.

RoleExt As String (Read-only)
Specifies an extension to the COM+ roles CanDelete, CanEdit and CanAppend that AspGrid will look for when the component is registered under MTS/Component Services, and COM+ role-based security is enabled. By default, this property is empty and AspGrid uses the roles CanDelete, CanEdit and CanAppend. If, for example, this property is set to "2", AspGrid will be looking for CanDelete2, CanEdit2, and CanAppend2 instead. See Chapter 12 for more info.

SaveButtonOnClick As String (Read/Write)
Specifies the OnClick attribute for the Save button tags that AspGrid generates. Obsolete. For data validation, use FormOnSubmit.

ShowHeader As Boolean (Read/Write)
True by default. If set to False, causes AspGrid to hide the grid header with column captions and sort buttons.

SQL As String (Read/Write)
Specifies an SQL SELECT statement that this grid will be based on. For a grid to be updateable, your table must contain an identity (AutoNumber) field, and it must be referenced first in the SELECT statement.

You may also specify the name of a stored procedure via this property. This stored procedure must be programmed to return a valid recordset.

You do not have to specify a value for the SQL property if you are passing an external ADO Recordset object via the Recordset property.


SQLAfterDelete As String (Read/Write)
Specifies an SQL statement that will be executed immediately after a delete command is executed. Your SQL statement may contain the wildcard ??? that will be automatically replaced by the ID of a record being deleted. You may use this property to delete orphan records or trigger a stored procedure every time a record is deleted.

SQLAfterInsert As String (Read/Write)
Specifies an SQL statement that will be executed immediately after a new record is added. You may use this property to perform certain database operations or trigger a stored procedure every time a new record is added.

SQLAfterUpdate As String (Read/Write)
Specifies an SQL statement that will be executed immediately after a record is changed. Your SQL statement may contain the wildcard ??? that will be automatically replaced by the ID of a record being updated. You may use this property to log some information or trigger a stored procedure every time a record is modified.

SQLBeforeDelete As String (Read/Write)
Same as SQLAfterDelete, but executed right before a record is deleted.

SQLBeforeInsert As String (Read/Write)
Same as SQLAfterInsert, but executed right before a new record is added.

SQLBeforeInsert As String (Read/Write)
Same as SQLAfterUpdate, but executed right before a record is modified.

Table As Object (Read-only)
Returns the Table object that encapsulates the attributes of a grid's <TABLE> tag.

UseImageButtons As Boolean (Read/Write)
True by default. If set to False, causes AspGrid to switch from image buttons to regular gray SUBMIT buttons.

Version As String (Read-only)
Returns the component's version in the format "3.1.0.1".
This property is added in service release 3.1.0.1.

Methods


Sub BuildForm(Optional OneRowAtATime = True )

Opens a recordset and builds a grid. Does not send any information to the browser, populates the Output object instead. Causes all records to appear in the edit mode. Also useful for building data-bound forms.

If the OneRowAtATime argument is omitted or set to True, BuildForm generates the Save and Delete buttons for each row. If this argument is set to False, a single Update button is generated instead, so a user can update and delete multiple rows at once. See the second half of Chapter 9 for details about this mode of operation.


Function ColRange(FromIndex As Integer, ToIndex As Integer) As Object
Returns a "compound" Column object that represents a range of columns. Setting any property on this Column object is equivalent to setting this property individually on every Column object in the range. FromIndex and ToIndex are 1-based column indices. Columns are numbered according to their order in the SELECT statement.

Function Cols(Index As Variant) As Object
Returns a "compound" Column object that represents a range of columns. Setting any property on this Column object is equivalent to setting this property individually on every Column object in the range. FromIndex and ToIndex are 1-based column indices. Columns are numbered according to their order in the SELECT statement.

Sub Connect( DSN As String, Username As String, Password As String, Optional Options = -1 )
Returns a "compound" Column object that represents a range of columns. Setting any property on this Column object is equivalent to setting this property individually on every Column object in the range. FromIndex and ToIndex are 1-based column indices. Columns are numbered according to their order in the SELECT statement.

Sub Disconnect()
Returns a "compound" Column object that represents a range of columns. Setting any property on this Column object is equivalent to setting this property individually on every Column object in the range. FromIndex and ToIndex are 1-based column indices. Columns are numbered according to their order in the SELECT statement.

Sub Display( Optional Show = True )
The main workhorse method of AspGrid. It opens a recordset, handles commands from the user and builds a grid. If Show is omitted or set to True, Display sends HTML code for the grid directly to the browser by calling Response.Write internally. If Show is set to False, no information is sent to the browser, and the Output object is populated instead.

Function Find( Criteria As String ) As Integer
Attempts to find a record in the recordset that meets the specified criteria. If a call to Find is successful, the recordset cursor is moved to the found record. This method is usually called right before Display so that the grid is displayed starting from a record that meets the criteria. Returns the absolute position of the found record in the recordset, or -1 if no records meeting the criteria were found. Use Find to implement record search functionality.

Function Find( Criteria As String ) As Integer
Attempts to find a record in the recordset that meets the specified criteria. If a call to Find is successful, the recordset cursor is moved to the found record. This method is usually called right before Display so that the grid is displayed starting from a record that meets the criteria. Returns the absolute position of the found record in the recordset, or -1 if no records meeting the criteria were found. Use Find to implement record search functionality.

Sub IgnoreCommands() As Integer
Instructs AspGrid to ignore all commands such as "edit" or "delete" from the user. This method is useful when server-side data validation is performed.

Sub LoadParameters(URL As String ) As Integer
Loads parameters from an XML file pointed to by URL. The XML file must follow the rules set forth in the Document Type Definition file AspGrid.dtd included with the component.

Sub ShowLeftSideButtons(Optional RightButtonsIntact = True) As Integer
By default, AspGrid displays control buttons on the right side only. This method makes AspGrid display control buttons on both sides, or left-side only. If RightButtonsIntact is set to True or omitted, the control buttons will appear on both sides. If it is set to False, the buttons will appear on the left side only.
Object Diagram Column Object