AspGrid.com -- 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

Array

CanSort

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.

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.

Caption As Boolean (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.

Cell As Object (Read-only)

Returns the Cell object for this column that represents attributes of the <TD> tags within the grid body.

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".

FieldName As String (Read-only)

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".

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.

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.

Header As Object (Read-only)

Returns the Cell object that represents attributes of the <TH> tag of the column's header.

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.

Index As Long (Read-only)

Returns this column's index.

InputMaxLength As Integer (Read/Write)

Specifies the MAXLENGTH attribute for <INPUT TYPE=TEXT> items displayed by a column in the edit mode.

InputSize As Integer (Read/Write)

Specifies the SIZE attribute for <INPUT TYPE=TEXT> items displayed by a column in the edit mode.

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.

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.

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.

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.

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>

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>".

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 < or a syntax error would be generated by the XML parser.

Sub AttachForeignTable(Num As Double)

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

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.

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

Code
Description

%a
Abbreviated weekday name

%A
Full weekday name

%b
Abbreviated month name

%B
Full month name

%c
Date and time representation appropriate for locale

%d
Day of month as decimal number (01 - 31)

%H
Hour in 24-hour format (00 - 23)

%I
Hour in 12-hour format (01 - 12)

%j
Day of year as decimal number (001 - 366)

%m
Month as decimal number (01 - 12)

%M
Minute as decimal number (00 - 59)

%p
Current locale’s A.M./P.M. indicator for 12-hour clock

%S
Second as decimal number (00 - 59)

%U
Week of year as decimal number, with Sunday as first day of week (00 - 53)

%w
Weekday as decimal number (0 - 6; Sunday is 0)

%W
Week of year as decimal number, with Monday as first day of week (00 - 53)

%x
Date representation for current locale

%X
Time representation for current locale

%y
Year without century, as decimal number (00 - 99)

%Y
Year with century, as decimal number

%z
Time-zone name or abbreviation; no characters if time zone is unknown

%%
Percent sign

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.

Column Object

Overview

Member List

Properties

Methods