AspGrid.com - Object Reference: Grid Object

Main Menu:	Home \| Manual \| Object Reference \| FAQ \| Download & Buy \| Clients \| Live Demos \| Contact
Navigator:	Home \| Object Reference \| Grid Object

Grid Object

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>

Properties Methods

CanAppend
CanDelete
CanEdit
Connection
DeleteButtonOnClick
Expires
ExtraFormItems
FileName
FormName
FormOnSubmit
ImagePath
MaxRows
MethodGet
NumberOnPage
Output
ReadOnly
Recordset
RecordsSkipped
RoleExt
SaveButtonOnClick
ShowHeader
SQL
SQLAfterDelete
SQLAfterInsert
SQLAfterUpdate
SQLBeforeDelete
SQLBeforeInsert
SQLBeforeUpdate
Table
UseImageButtons
Version
BuildForm
ColRange
Cols
Connect
Disconnect
Display
Find
IgnoreCommands
LoadParameters
ShowLeftSideButtons

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.
Usage:

VBScript Grid.CanAppend = False
XML <Grid CanAppend="False">...</Grid>

Relevant Chapters 7

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.
Usage:

VBScript Grid.CanDelete = False
XML <Grid CanDelete="False">...</Grid>

Relevant Chapters 7

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.
Usage:

VBScript Grid.CanEdit = False
XML <Grid CanEdit="False">...</Grid>

Relevant Chapters N/A

Connection As Object (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.
Usage:

VBScript Set Conn = Server.CreateObject("ADODB.Connection")
Conn.Open strConnect
Grid.Connection = Conn
XML N/A

Relevant Chapters 2, 8

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.
Usage:

VBScript Grid.DeleteButtonOnClick = "Are you sure?"
XML <Grid>...
<DeleteButtonOnClick>Are you sure?</DeleteButtonOnClick>

Relevant Chapters 6

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).
Usage:

VBScript Response.Write Grid.Expires
XML N/A

Relevant Chapters N/A

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.
Usage:

VBScript Grid.ExtraFormItems="<INPUT TYPE=HIDDEN NAME=id VALUE=<%=id%>>"
XML N/A

Relevant Chapters 7, 10

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.
Usage:

VBScript Grid.Name = "this_script.asp"
XML <Grid>...
<FileName>this_script.asp</FileName>

Relevant Chapters N/A

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.
Usage:

VBScript Grid.FormOnSubmit = "return Validate();"
XML <Grid>...
<FormOnSubmit>return Validate();</FormOnSubmit>

Relevant Chapters 6

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.
Usage:

VBScript Grid.ImagePath = "images/"
XML <Grid>...
<ImagePath>images/</ImagePath>

Relevant Chapters 2 and all others.

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.
Usage:

VBScript Grid.MaxRows = 10
XML <Grid MaxRows="10">...</Grid>

Relevant Chapters 3, 8, 11

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.
Usage:

VBScript Grid.MethodGet = False
XML <Grid MethodGet="False">...</Grid>

Relevant Chapters 3

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.
Usage:

VBScript Grid.NumberOnPage = 2
XML <Grid NumberOnPage="2">...</Grid>

Relevant Chapters 4

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.
Usage:

VBScript Grid.Display(False)
Response.Write Grid.Output.TableTag
XML N/A

Relevant Chapters 8, 9, 10

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.
Usage:

VBScript Grid.ReadOnly = True
XML <Grid ReadOnly="True">...</Grid>

Relevant Chapters 10

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.
Usage:

VBScript Set RecSet = Server.CreateObject("ADODB.Recordset")
RecSet.CursorLocation = 3 ' adUseClient
RecSet.Open "departments", Conn, 2, 3
Grid.Recordset = RecSet
XML N/A

Relevant Chapters 2

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.
Usage:

VBScript Count = Grid.RecordsSkipped + 1
XML N/A

Relevant Chapters 8

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.
Usage:

VBScript Grid.RoleExt = "2"
XML N/A

Relevant Chapters 12

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

VBScript Grid.SaveButtonOnClick = "return someproc();"
XML <SaveButtonOnClick>return someproc();</SaveButtonOnClick>

Relevant Chapters N/A

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.
Usage:

VBScript Grid.ShowHeader = False
XML <Grid ShowHeader="False">...</Grid>

Relevant Chapters 7

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.
Usage:

VBScript Grid.SQL = "select id, name, phone from departments"
XML <Grid>...
<SQL>select id, name, phone from departments</SQL>

Relevant Chapters 2 and all others.

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.
Usage:

VBScript Grid.SQLAfterDelete = "delete from empl where dept_id=???"
XML <Grid>...
<SQLAfterDelete>delete from empl where dept_id=???</SQLAfterDelete>

Relevant Chapters N/A

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.
Usage:

VBScript Grid.SQLAfterInsert = "sp_writelog"
XML <Grid>...
<SQLAfterInsert>sp_writelog </SQLAfterInsert>

Relevant Chapters N/A

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.
Usage:

VBScript Grid.SQLAfterUpdate = "sp_writetolog(???)"
XML <Grid>...
<SQLAfterUpdate>sp_writetolog(???)</SQLAfterUpdate>

Relevant Chapters N/A

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.
SQLBeforeUpdate 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.
Usage:

VBScript Grid.Table.CellSpacing = 0
Grid.Table.Caption = "Employees"
XML <Grid>...
<Table CellSpacing="0">
  <Caption Value="Employees"/>
</Table>

Relevant Chapters 2 and all others.

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

VBScript Grid.UseImageButtons = False
XML <Grid UseImageButtons="False">...</Grid>

Relevant Chapters 10

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.
Usage:

VBScript Response.Write Grid.Version
XML N/A

Relevant Chapters N/A

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.
Usage:

VBScript Grid.BuildForm
XML N/A

Relevant Chapters 9, 10

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.
Usage:

VBScript Grid.ColRange(2, 5).Cell.BGColor = "#FF0000"
XML <Grid>...
<ColRange From="2" To="5">
  <Cell BGColor="#FF0000"/>
</ColRange>

Relevant Chapters 3 and all others.

Function Cols( Index As Variant ) As Object
Returns a Column object specified by Index which can either be a numeric 1-based index or database field name. Index can also be 0 or 999 to denote the left-side and right-side control button columns, respectively. Before you can reference a column by field name, you must specify the connection parameters and SQL statement. Cols is the default method of the Grid object, and therefore the word .Cols may be omitted.
Usage:

VBScript Grid.Cols(1).Hidden = True

or
Grid("id").Hidden = True
XML <Grid>...
<Cols Index="1">
  <Hidden>True</Hidden>
</Cols>

or
<Cols Index="id">
  <Hidden>True</Hidden>
</Cols>

Relevant Chapters 3 and all others.

Sub Connect( DSN As String, Username As String, Password As String, Optional Options = -1 )
Connects AspGrid to a datasource. DSN can either be a system DSN or a DSNless connection string. Username and Password specify user credentials in case your database requires authentication. Otherwise these arguments can be left blank. Notice that you can also pass user credentials via a DSNless connection string, so these two arguments are somewhat redundant.
The optional Options argument specifies ADO Connection options. Currently, only two options are defined: adConnectUnspecified (-1, default) and adAsyncConnect (16).
Usage:

VBScript Grid.Connect "mydsn", "uid", "xxxx"
XML <Grid>...
<Connect DSN="mydsn" Username="uid" Password="xxxx"/>

Relevant Chapters 2 and all others.

Sub Disconnect( )
Disconnects from the datasource. If this method is not called explicitly, AspGrid will call it internally right before the Grid object is destroyed.
Usage:

VBScript Grid.Disconnect
XML N/A

Relevant Chapters 2 and all others.

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.
Usage:

VBScript Grid.Display
XML N/A

Relevant Chapters 2 and all others.

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.
Usage:

VBScript Grid.Find "name like 'jo%'"
XML N/A

Relevant Chapters 11

Sub IgnoreCommands( )
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.
Usage:

VBScript Grid.IgnoreCommands
XML N/A

Relevant Chapters 6

Sub LoadParameters( URL As String )
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.
Usage:

VBScript Grid.LoadParameters "myparams.xml"
XML N/A

Relevant Chapters 5

Sub ShowLeftSideButtons( Optional RightButtonsIntact = True )
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.
Usage:

VBScript Grid.ShowLeftSideButtons False
XML <Grid>...
<ShowLeftSideButtons RightButtonsIntact="False"/>

Relevant Chapters 3 and all others.


	Search AspGrid.com