AspGrid 2.5

Implementation Guidelines

Copyright (c) Persits Software, Inc. 1998

Other resources:   Please read the Disclaimer before installing and using AspGrid.
 
  1. Register the component on your system by executing the command

    regsvr32 c:\<Your AspGrid Dir>\aspgrid.dll

    in the MS DOS prompt or from Start/Run dialog.
    Create an instance of the AspGrid object as follows:

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

    or

    <OBJECT RUNAT=SERVER PROGID="Persits.AspGrid.1" ID=Grid>
    </OBJECT>
     
    If you have several grids on a page, you must create an AspGrid object for each grid.

  2. Connect to an ODBC data source as follows:

    Grid.Connect "YourDSN", "UserID", "Pwd"

    The data source must be a system DSN.

  3. Specify the file name of this ASP page via the FileName property as follows:

    Grid.FileName = "ThisPage.asp"

    This must be done to ensure the proper values of ACTION attributes of <FORM> tags.

  4. If you have more that one grid on a page, assign a unique integer index to each grid object via the NumberOnPage property as follows:

    Grid1.NumberOnPage = 1
    Grid2.NumberOnPage = 2

  5. Specify a SELECT statement for the grid via the SQL property, as follows:

    Grid.SQL = "select id, name, age from person"

    IMPORTANT: For the grid to be updateable, the database table on which the SELECT statement is built must contain an IDENTITY column, and this column must be first in the SELECT list. Also, an updateable grid may not be based on a join.

    It is always a good idea to hide the identity column from the user, or at least make it read-only, e.g.

    Grid.Cols(1).Hidden = True

    or

    Grid.Cols(1).ReadOnly = True

  6. Set properties of individual columns in a grid via the Cols(i) method. This method returns the i-th Column object. E.g.

    Grid.Cols(2).Caption = "Last Name"

    To set properties of several adjacent columns you may use the ColRange(i, j) method. This method returns a Column object that represents a "collective" column, i.e. the line

    Grid.ColRange(1, 3).Header.Width = "100"

    is equivalent to

    Grid.Cols(1).Header.Width = "100"
    Grid.Cols(2).Header.Width = "100"
    Grid.Cols(3).Header.Width = "100"

    IMPORTANT: The indices of columns are 1-based and correspond to the sequential order of fields in the SELECT statement regardless of whether any of the columns are made hidden.

  7. If your underlying table contains a foreign key field, you must include it in the SELECT statement. You may then hide the corresponding column and specify the default value for it. E.g.

    Grid.SQL = "select id, order_id, item, quantity from order_items"
    Grid.ColRange(1, 2).Hidden = True
    Grid.Cols(2).DefaultValue = 15

    In this example all records inserted into the table order_items will have the foreign key field order_id set to 15.

  8. You can to assign a pick list to any of your columns via the Array property. The following statement will force the user to pick values for field 5 from a three-item drop-down list box:

    Grid.Cols(5).Array = Array("Yes", "No", "Maybe")

    If you want these options to be saved in the database as numbers rather than words, you must specify an array of corresponding numeric values via the VArray properties as follows:

    Grid.Cols(5).Array = Array("Yes", "No", "Maybe")
    Grid.Cols(5).VArray = Array(1, 2, 3)

  9. If you need the list box items in the previous example to be dynamic, you may choose to attach a foreign table to your column via the AttachForeignTable method as follows:

    Grid.Cols(5).AttachForeignTable "select response_id, response_text from responses", 1, 2

    In this example, the items in the drop-down list box will be pulled from field 2 of table responses, the corresponding numeric values from field 1 of that table.

  10. If you need to store logical values of the type True/False or Yes/No in your table, you may choose to use an HTML checkbox to display these values in the edit mode as follows:

    Grid.Cols(5).AttachCheckBox "Yes", "No"

    Or

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

    The corresponding database field must be an integer such as long, int, short, tinyint, or bit.

    The two String arguments of AttachCheckBox method specify the strings that will be displayed in the column in the non-edit mode when the corresponding database field is nonzero and zero, respectively. The arguments can be simple string values, such as "Yes",
    "No" (as in the first example), or HTML tags for displaying images of checked and unchecked icons (as in the second example).

  11. You can control the appearance of the output HTML table generated by AspGrid by setting various HTML tag attributes via the corresponding properties as follows:

    <TABLE>:
    Grid.Table.Border (type: String, e.g. "1")
    Grid.Table.Align (type: String, e.g. "LEFT", "RIGHT", "CENTER")
    Grid.Table.Width (type: String, e.g. "100", "50%")
    Grid.Table.Caption (type: String)
    Grid.Table.CellSpacing (type: String, e.g. "5")
    Grid.Table.CellPadding (type: String, e.g. "1")
    Grid.Table.Class (type: String)
     
    <TD>:
    Grid.Cols(i).Cell.NoWrap (type: Boolean)
    Grid.Cols(i).Cell.Align (type: String, e.g. "LEFT", "RIGHT", "CENTER")
    Grid.Cols(i).Cell.Valign (type: "TOP", "BOTTOM")
    Grid.Cols(i).Cell.Width (type: String, e.g. "10" or "100%")
    Grid.Cols(i).Cell.Height (type: String)
    Grid.Cols(i).Cell.BGCOLOR (type: String, e.g. "#FF0000")
    Grid.Cols(i).Cell.Class (type: String)  

    <TH>:
    Grid.Cols(i).Caption
    Grid.Cols(i).Header.NoWrap
    Grid.Cols(i).Header.Align
    Grid.Cols(i).Header.Valign
    Grid.Cols(i).Header.Width
    Grid.Cols(i).Header.Height
    Grid.Cols(i).Header.BGCOLOR
    Grid.Cols(i).Header.Class  

     
    <FONT>:
    Grid.Cols(i).Cell.Font.Face (type: String, e.g. "Tahoma, Arial")
    Grid.Cols(i).Cell.Font.Size (type: String, e.g. "4")
    Grid.Cols(i).Cell.Font.Color (type: String, e.g. "#A0FF00")
    Grid.Cols(i).Cell.Font.Bold (type: Boolean)
    Grid.Cols(i).Cell.Font.Class (type: String)

    Grid.Cols(i).Header.Font.Face
    Grid.Cols(i).Header.Font.Size
    Grid.Cols(i).Header.Font.Color
    Grid.Cols(i).Header.Font.Bold
    Grid.Cols(i).Header.Font.Class

     
    <INPUT TYPE=TEXT SIZE=??? MAXLENGTH=??? --other attributes-->:
    Grid.Cols(i).Cell.InputSize (type: Integer)
    Grid.Cols(i).Cell.InputMaxLength (type: Integer)
    Grid.Cols(i).Cell.InputUserAttributes (type: String)  
  12. To format numeric values, you may use the FormatNumeric method as follows:

    Gird.Cols(i).FormatNumeric 2, FALSE

    The following example formats a numeric column to have 2 decimal places and no comma separators. The first parameter, Decimals, specifies the number of decimal places in the number. The seconds parameter, UseCommas, is optional and is True by default.

  13. By default, AspGrid uses images for control buttons. The image file names are addnew.gif, cancel.gif, delete.gif, edit.gif, save.gif, up.gif and down.gif. You may supply your own images by replacing the images shipped with the component. You may also force AspGrid to use standard HTML SUBMIT buttons instead of images as follows:

    Grid.UseImageButtons = False 

    By default, the button images must be located in the same directory as the grid's ASP file. You may specify a different location for the images via the ImagePath propery as follows: 

    Grid.ImagePath = "\images\buttons\"

  14. You can limit the amount of records displayed at one time via the MaxRows property as follows:

    Grid.MaxRows = 10

    The navigation buttons will be displayed automatically on the bottom of the grid when needed.

  15. AspGrid can be "tricked" into displaying data as hyperlinks or images by constructing "smart" SQL statements, e.g.

    Grid.SQL = "select id, '<A HREF=' + name + '.asp>' + name + '</A>', price from items"
  16. You may enable sorting on any or all grid columns by setting the corresponding column's CanSort property to True:

    Grid.Cols(3).CanSort = True.

    However, if you do so you can no longer use the ORDER BY clause in your Grid.SQL statement since it may conflict with the ORDER BY clause generated by AspGrid.