Persits Software, Inc. Web Site
Main Menu:  Home |  Manual |  Object Reference |  FAQ |  Download & Buy |  Clients |  Live Demos |  Contact
 Navigator:  Home |  Object Reference |  Column Object
Cell Object Grid Object
  Column Object
The Column object represents a column in a grid. An instance of this object is obtained via the methods Grid.Cols and Grid.ColRange. The Column object enables you to set various formatting aspects of a column (such as colors, fonts, sizes, etc.) as well as specify an edit control for a column such a combo box, textarea or checkbox.

Properties Methods

Array As Variant (Read/Write)

Specifies a list of options for this column that will be displayed in a combo box when the record is in the edit mode. This property may be used alone or in conjunction with VArray that specifies the corresponding list of values.

VBScript Grid(2).Array = Array("Married", "Single", "Divorced")
XML <Cols Index="2">
  <Item Value="Married"/>
  <Item Value="Single"/>
  <Item Value="Divorced"/>
Relevant Chapters 4 and all others.

CanSort As Boolean (Read/Write)
False by default. If set to True enables sorting on this column by showing sort buttons on both sides of the caption in the header.

VBScript Grid("name").CanSort = True
XML <Cols Index="name">
Relevant Chapters 4 and all others.

Caption As String (Read/Write)
Specifies the column caption shown in the header. If this property is not specified, the database field name will be used by default.

VBScript Grid("hiredate").Caption = "Hire Date"
XML <Cols Index="hiredate">
 <Caption>Hire Date</Caption>
Relevant Chapters 4 and all others.

Cell As Object (Read-only)
Returns the Cell object for this column that represents attributes of the <TD> tags within the grid body.

VBScript Grid(2).Cell.Width = "50"
XML <Cols Index="2">
 <Cell Width="50"/>
Relevant Chapters 3 and all others.

DefaultValue As Variant (Read/Write)
Specifies a default value for the column. This value will be used to initialize this column's edit control when a new record is being added. If a column is hidden or read-only, the default value will be saved to the database when a new record is added. The default value will also be used when a column is not hidden or read-only, but left blank during editing.

DefaultValue is a Variant, so it can be set to a value of any readable data type including String, Integer, Float, Date, etc. When set with XML, the possible values for the Type attribute are "boolean", "float", "int", "string" and "date".

VBScript Grid("dept_id").DefaultValue = 50
XML <Cols Index="dept_id">
 <DefaultValue Type="int">50</DefaultValue>
Relevant Chapters 4, 7

FieldName As String (Read/Write)
Overrides the default database field name for certain operations such as sorting and inserts. May be useful if your SQL SELECT statement does not explicitly reference a field name, e.g. "select id, a + b from table".

VBScript Grid(3).FieldName = "somename"
XML <Cols Index="3">
Relevant Chapters N/A

Footer As Object (Read-only)
Returns the Cell object that represents attributes of the <TD> tag of the grid's footer. The possible indices for Grid.Cols( index ).Footer are 0, 1 and 999 to denote the left-side column, navigation area, and right-side column, respectively.

VBScript Grid(0).Footer.BGColor = "#FF0000"
XML <Cols Index="0">
 <Footer BGColor="#FF0000"/>
Relevant Chapters 3 and all others.

FormHTML As String (Read-only)
Returns the HTML code for a form element. This property is populated by calling Grid.BuildForm.

This property was introduced in AspGrid 2.5 for building data-bound forms. It is still supported in AspGrid 3.0 for backwards compatibility, but it is recommended that you use Grid.Output.Rows( ).Value instead.

VBScript Response.Write Cols("name").FormHTML
Relevant Chapters 10.

Header As Object (Read-only)
Returns the Cell object that represents attributes of the <TH> tag of the column's header.

VBScript Grid(0).Header.BGColor = "#FF0000"
XML <Cols Index="0">
 <Header BGColor="#FF0000"/>
Relevant Chapters 3 and all others.

Hidden As Boolean (Read/Write)
False by default. If set to True makes this column hidden.

You should always hide the identity column of your grid, or at least make it read-only.

VBScript Grid("id").Hidden = True
XML <Cols Index="id">
Relevant Chapters 2 and all others.

Index As Long (Read-only)
Returns this column's index.

VBScript Response.Write Grid.Cols("name").Index
Relevant Chapters N/A

InputMaxLength As Integer (Read/Write)
Specifies the MAXLENGTH attribute for <INPUT TYPE=TEXT> items displayed by a column in the edit mode.

VBScript Grid("state").InputMaxLength = 2
XML <Cols Index="state">
Relevant Chapters N/A

InputSize As Integer (Read/Write)
Specifies the SIZE attribute for <INPUT TYPE=TEXT> items displayed by a column in the edit mode.

VBScript Grid("ssn").InputSize = 12
XML <Cols Index="ssn">
Relevant Chapters 3 and all others.

InputUserAttributes As String (Read/Write)
Specifies one or more additional attributes for an <INPUT TYPE=TEXT> (or any other edit control) displayed by a column in the edit mode.

VBScript Grid("code").InputUserAttributes = "VALUE=2"
XML <Cols Index="code">
 <InputUserAttributes>VALUE=2 </InputUserAttributes>
Relevant Chapters N/A

ReadOnly As Boolean (Read/Write)
False by default. If set to True makes this column read-only which means the column will not switch to the edit mode when the rest of the row does.

VBScript Grid("id").ReadOnly = True
XML <Cols Index="id">
Relevant Chapters 2 and all others.

VArray As Variant (Read/Write)
Works in conjunction with Array to specify a list of corresponding database values. The number of elements in VArray must match that in Array. VArray cannot be used alone, i.e. without Array.

In the example below, a combo box with three options will be presented to the user in the edit mode for the column "marital": Married, Single and Divorced. The corresponding values for these options are 1, 2, and 3, respectively. This means that if the option Single is selected, the value 2 will be put into the field "marital" when the record is saved.

VBScript Grid("marital").Array = Array("Married", "Single", "Divorced")
Grid("marital").VArray = Array(1, 2, 3)
XML <Cols Index="marital">
  <Item Value="Married" DBValue="1"/>
  <Item Value="Single" DBValue="2"/>
  <Item Value="Divorced" DBValue="3"/>
Relevant Chapters 4

Function ApplyFormat( Num As Double) As String
A helper function that converts a number to a string taking into account format settings specified by FormatNumeric. This method does not affect the appearance of a grid. May be useful when customizing the way a grid is displayed.

VBScript Response.Write Grid(2).ApplyFormat(3344234.3234)
Relevant Chapters 8

Sub AttachCalendar( Optional Month, Optional Year, Optional Format )
In the edit mode, displays a "calendar" icon next to a text box. When this icon is clicked, a JavaScript-based pop-up calendar will come up allowing a user to pick a date.

By default, the calendar opens up displaying the current month and year. You can specify a different month and/or year via the arguments Month (0-11 for Jan-Dec) and Year (a 4-digit value), respectively. The default date format returned by the calendar is "MM/DD/YYYY". You may specify a different format via Format, for example, "DD/MM/YY"

For a pop-up calendar to function, you must include the file calendar.js (shipped with the AspGrid component) in your ASP file's header as follows:

<script language="JavaScript" src="calendar.js"></script>

VBScript Grid.Cols("hiredate").AttachCalendar , , "DD/MM/YY"
XML <Cols Index="hiredate">
 <AttachCalendar Format="DD/MM/YY"/>
Relevant Chapters 4

Sub AttachCheckbox( DisplayChecked As String, DisplayUnchecked As String )
Turns a column into a checkbox in the edit mode. All non-zero values are displayed as checked boxes, all zero values as clear boxes. Apply this method to Boolean and numeric fields only.

DisplayChecked and DisplayUnchecked specify what should be displayed for non-zero and zero values, respectively, while in the regular display mode. You can simply specify words such as "Yes" and "No", or HTML tags such as "<IMG SRC=yesimage.gif>" and "<IMG SRC=noimage.gif>".

VBScript Grid.Cols("vested").AttachCheckbox "Yes", "No"
XML <Cols Index="vested">
 <AttachCheckBox Checked="Yes" Unchecked="No"/>
Relevant Chapters 4 and all others.

Sub AttachExpression( Expression As String )
This method is useful for turning a column into a hyperlink or image in the regular display mode. Expression is a string that may contain one or more references to field names. A field name must be surrounded by either two pairs of braces, e.g. {{dept_id}}, or two pairs of square brackets, e.g. [[name]].

A field name in double braces will be replaced by its respective value for this record. A field name in double square brackets will be replaced by its value in a URL-encoded form.

For example, if a table record contains the values id=3 and name="R & D", the statement

Grid("name").AttachExpression _
  "<A HREF=script.asp?name=[[name]]&id={{id}}>{{name}}</A>"

will produce the value

<A HREF=script.asp?name=R+%26+D&id=3>R & D</A>

Note that setting a string above via XML requires that you replace the < symbol with its HTML encoding &lt; or a syntax error would be generated by the XML parser.

VBScript Grid("name").AttachExpression "<A HREF=form.asp?id={{id}}>{{name}}</A>"
XML <Cols name="vested">
 <AttachExpression Expression="&lt;A HREF=form.asp?id={{id}}>{{name}}&lt;/A>"/>
Relevant Chapters 7, 10

Sub AttachForeignTable( SQL As String, KeyCol As Long, DispCol As Long )
Turns a column into a combo box in the edit mode. Has the same effect as with the Array and VArray properties, except that the option names and corresponding values come from a recordset rather than pre-set arrays.

SQL specifies a SELECT statement this combo box will be based on. KeyCol specifies the 1-based index of a field in that recordset where database values are to come from. DispCol specifies the index of a field where option names are to come from.

E.g. the table Employees has a field dept_id which stores a department ID for each employee. The department information is stored in a separate table, Departments with the fields id, name, and maybe a few others. We want our Employees-based grid to present a user with a list of department names to choose from for the dept_id column. To turn this column into a user-friendly list of options, the following statement should be used:

Grid("dept_id").AttachForeignTable "select id, name from departments", 1, 2

VBScript Grid("dept_id").AttachForeignTable "select id, name from departments", 1, 2
XML <Cols Index="dept_id">
  SQL="select id, name from departments"
  KeyCol="1" DispCol="2"/>
Relevant Chapters 4

Sub AttachTextarea( Optional Rows = "", Cols = "" )
Turns a column into a <TEXTAREA> in the edit mode. Rows and Cols, if specified, set the ROWS and COLS attributes, respectively.

VBScript Grid.Cols(5).AttachTextarea 20, 5
XML <Cols Index="5">
 <AttachTextarea Rows="20" Cols="5"/>
Relevant Chapters N/A

Sub FormatDate( Format As String, Optional EditFormat = "")
Specifies date formatting for a column. You must only apply this method to date fields. Format specifies the formatting string for dates in the regular display mode. EditFormat, if specified, affects dates in the edit mode. If it is omitted, a default database date format will be used in the edit mode.

A formatting string contains one or more codes that represent various components of a date/time. The formatting codes are listed below (copied from MSDN):

%aAbbreviated weekday name
%AFull weekday name
%bAbbreviated month name
%BFull month name
%cDate and time representation appropriate for locale
%dDay of month as decimal number (01 - 31)
%HHour in 24-hour format (00 - 23)
%IHour in 12-hour format (01 - 12)
%jDay of year as decimal number (001 - 366)
%mMonth as decimal number (01 - 12)
%MMinute as decimal number (00 - 59)
%pCurrent locale’s A.M./P.M. indicator for 12-hour clock
%SSecond as decimal number (00 - 59)
%UWeek of year as decimal number, with Sunday as first day of week (00 - 53)
%wWeekday as decimal number (0 - 6; Sunday is 0)
%WWeek of year as decimal number, with Monday as first day of week (00 - 53)
%xDate representation for current locale
%XTime representation for current locale
%yYear without century, as decimal number (00 - 99)
%YYear with century, as decimal number
%zTime-zone name or abbreviation; no characters if time zone is unknown
%%Percent sign

For example, the formatting string "%b %d, %Y" formats the date 05/18/70 into May 18, 1970.

VBScript Grid.Cols("hiredate").FormatDate "%b %d, %Y"
XML <Cols Index="hiredate">
 <FormatDate Format="%b %d, %Y"/>
Relevant Chapters 4

Sub FormatNumeric(Decimal As Integer, Optional ThouComma = True, Optional NegativeSign = True, Optional FloatingPoint = True, Optional Prefix = "" )
Specifies numeric formatting for a column.

Decimal specifies the number of decimal positions for a number.
ThouComma is optional and True by default. If set to False, suppresses comma separators between 000's.
NegativeSign is optional and True by default. If set to False, suppresses the "-" sign for negative numbers and uses the parenthesized (...) form instead.
FloatingPoint is optional and True by default. If set to False, uses the European format (floating commas and "dot" separators), e.g. 1.234.567,89.
Prefix is optional and empty by default. Specifies a string prefix that will be automatically inserted in front of each number in the column.

VBScript Grid("salary).FormatNumeric 2, , , , "$"
XML <Cols Index="salary">
 <FormatNumeric Decimal="2" Prefix="$"/>
Relevant Chapters 4

Grid Object Cell Object

  This site is owned and maintained by Persits Software, Inc. Copyright © 2000 - 2010. All Rights Reserved.