Cover Here

Transcription

Cover Here

CLARION/ASP
CLARION/ASP
User’s
User’s Guide
2
CLARION/ASP User’s Guide
COPYRIGHT 1994-2003 SoftVelocity Incorporated. All rights reserved.
This publication is protected by copyright and all rights are reserved by SoftVelocity Incorporated. It
may not, in whole or part, be copied, photocopied, reproduced, translated, or reduced to any
electronic medium or machine-readable form without prior consent, in writing, from SoftVelocity
Incorporated.
This publication supports Clarion. It is possible that it may contain technical or
typographical errors. SoftVelocity Incorporated provides this publication “as is,” without
warranty of any kind, either expressed or implied.
Revision 1.3
SoftVelocity Incorporated
2769 East Atlantic Blvd.
Pompano Beach, Florida 33062
(954) 785-4555
www.softvelocity.com
Trademark Acknowledgements:
SoftVelocity is a trademark of SoftVelocity Incorporated.
Clarion is a trademark of SoftVelocity Incorporated.
Microsoft, Windows, and Visual Basic are registered trademarks of Microsoft Corporation.
All other products and company names are trademarks of their respective owners.
Printed in the United States of America (0204)
3
Contents:
Ch. 1: Introduction
9
Overview....................................................................................................................... 9
Road Map ................................................................................................................... 10
Preparation ................................................................................................................. 11
Creating/Modifying the Application ............................................................................. 13
Adding Clarion/ASP ............................................................................................. 14
Procedure Customizations................................................................................... 15
Generating and Incorporating .............................................................................. 15
Ch. 2: IIS, ASP, ADO, HTML
17
IIS Setup ..................................................................................................................... 17
Note: IIS Security Patches For Windows XP ....................................................... 20
IIS/ASP Check ..................................................................................................... 21
Virtual Directories................................................................................................. 22
Default Virtual Images Directory .......................................................................... 23
ASP and Database Access ........................................................................................ 24
ASP/ADO Applications......................................................................................... 24
Database Access ................................................................................................. 25
Clarion Programmers and ASP/ADO................................................................... 26
HTML (Hypertext Markup Language) ......................................................................... 27
VBScript Language..................................................................................................... 29
Ch. 3: ASP Template Concepts
31
How ASP Fits In with Clarion...................................................................................... 31
What’s Special About Our ASP Code .................................................................. 31
Interaction with Dictionary.................................................................................... 33
Navigational Links in Clarion/ASP .............................................................................. 33
Window and Control Formatting ................................................................................. 34
Security Levels ........................................................................................................... 35
Language.................................................................................................................... 36
Database Access........................................................................................................ 36
DBMS Requirements ........................................................................................... 36
Ch. 4: Getting Started Exercises
37
Ch. 5: How-To’s
39
Preparation How-To’s................................................................................................. 39
ADO and ODBC/DSN Setup................................................................................ 39
DSN Setup ........................................................................................................... 39
IIS Permissions by Directory................................................................................ 43
Directory Securities .............................................................................................. 45
Application How-To’s.................................................................................................. 46
Application of Global Template ............................................................................ 46
4
Application of Browse Template .......................................................................... 47
Application of Form Template .............................................................................. 48
Browse/Form/Browse or Query/Browse/Form ..................................................... 49
Link a Browse and Form ...................................................................................... 51
In the Browse Procedure...................................................................................... 51
In the Form Procedure ......................................................................................... 51
Graphic Link From a Browse to a Form ............................................................... 52
Form Without a Browse........................................................................................ 53
Examples ............................................................................................................. 54
A Query Page....................................................................................................... 54
Browse to Browse ................................................................................................ 55
Using a Graphic to Signal the Link....................................................................... 56
Linking from a Column Value............................................................................... 56
The Child Side...................................................................................................... 57
Select Browses .................................................................................................... 57
Table Loaded Selects on Forms .......................................................................... 58
How to Prime a Field on an Update Form............................................................ 59
Help and Popup Windows.................................................................................... 61
Dynamic Runtime Templates............................................................................... 61
Example 1: Different Color Scheme Based On a Cookie .................................... 62
Example 2: Different Template Based On Access Level ..................................... 63
Testing How-To’s........................................................................................................ 65
Testing on Your Local Machine ........................................................................... 65
Internet Services Options..................................................................................... 65
The /Images Virtual Directory .............................................................................. 69
GLOBAL.ASA....................................................................................................... 70
Loading the Test/Debug Page ............................................................................. 72
Application Timeouts............................................................................................ 73
ftp Setup ............................................................................................................... 74
Integration/Deployment How-To’s .............................................................................. 75
HTML Template ................................................................................................... 75
Style Sheets ......................................................................................................... 78
Collected Data from Forms on Your Site ............................................................. 79
Passing Data to Other Parts of Your Web ........................................................... 79
Ch. 6: Integrating with Your Site
81
Links ........................................................................................................................... 81
Persistence of Data.............................................................................................. 82
Page Naming Conventions .................................................................................. 82
Linking Conventions............................................................................................. 83
Site Standard Page Format ................................................................................. 84
Ch. 7: ASP Template Reference
85
ASP Global Template Options.................................................................................... 85
Global Options/Global Tab................................................................................... 85
Target Language.................................................................................................. 86
5
Show Help Button ................................................................................................ 86
Tooltips................................................................................................................. 87
Global Options/Cascading Style Sheets .............................................................. 87
HTML Design Time Templates ............................................................................ 87
List Defaults ......................................................................................................... 88
Data Records per HTML List ............................................................................... 88
Pad Table with Blank Rows ................................................................................. 88
Automatically Create Detail Link .......................................................................... 88
Place Database Navigation Bar on List Pages .................................................... 89
Show Add Button on DB Navigation Bar.............................................................. 89
Show Query By Form Button on Database Navigation Bar ................................. 89
Navigation Button Tool Tips................................................................................. 90
No Records Found Message ............................................................................... 90
Clear Filter Prompt ............................................................................................... 90
Form Defaults Button ........................................................................................... 91
Enable Javascript Calendar Popup...................................................................... 91
Enable DB Navigation on View Forms................................................................. 91
Required Field Indicator ....................................................................................... 92
Selected Field background .................................................................................. 92
Search Mode Select Control Text ........................................................................ 92
CRLF to HTML ..................................................................................................... 92
Form Button Text Tab .......................................................................................... 93
Form Button Titles Tab......................................................................................... 93
Form Message Text Tab ...................................................................................... 93
Form Validation Text Tab..................................................................................... 95
Include Defaults Button ........................................................................................ 95
Global Options/Generation Tab ........................................................................... 95
Enable Debug Mode ............................................................................................ 96
Suppress File Generation .................................................................................... 96
Popup Help Window Size..................................................................................... 97
Popup Select Window Size.................................................................................. 97
Global Options/Database Tab.............................................................................. 97
Connection Properties Dialog .............................................................................. 98
Connection Timeout ............................................................................................. 98
Command Timeout............................................................................................... 98
Read/List Operations ........................................................................................... 99
Form Operations .................................................................................................. 99
Call Connection Builder...................................................................................... 101
Using Access Database ..................................................................................... 104
SQL Delimiters ................................................................................................... 105
Global Options/Security Tab .............................................................................. 105
Provide User Based Security ............................................................................. 106
User Table.......................................................................................................... 106
Unique ID Column.............................................................................................. 106
Login Name Column .......................................................................................... 106
Login Password Column .................................................................................... 106
User Security Level Column .............................................................................. 106
6
User E-Mail Column ........................................................................................... 106
Second User Name Column .............................................................................. 106
User Company Name Column ........................................................................... 106
User Defined Values .......................................................................................... 107
Login Screen Text .............................................................................................. 107
Login Persistence/Cookies ................................................................................ 108
Global Options/Administration Tab .................................................................... 109
Site Title ............................................................................................................. 109
Email ADO Errors—Administrator Email............................................................ 109
Message to Display on ADO Error..................................................................... 109
Enhanced ADO Error Reporting ........................................................................ 110
Images ............................................................................................................... 111
Image Relative Path........................................................................................... 111
Image Sizes ....................................................................................................... 112
Image Type Tabs ............................................................................................... 112
User Data ........................................................................................................... 112
Includes.............................................................................................................. 113
The ASP Browse Extension Template ..................................................................... 114
Browse Options/Globals Tab ............................................................................. 114
Conditional Row Formatting............................................................................... 116
Browse Options/Global Tab/Database Tab ....................................................... 117
Browse Options/Global Tab/Security Sub Tab .................................................. 118
My Records ........................................................................................................ 118
Security Level Required to Access Page........................................................... 119
Browse Options/Page Tab ................................................................................. 120
Page Title ........................................................................................................... 120
Help URL............................................................................................................ 120
QBF Procedure .................................................................................................. 120
Add Procedure ................................................................................................... 121
Select Mode Procedure...................................................................................... 121
Browse Options/HTML Table Tab...................................................................... 121
Populated From.................................................................................................. 121
HTML Table Title................................................................................................ 122
List Box Primary Table ....................................................................................... 122
Unique Key......................................................................................................... 122
Populate an Entry Locator ................................................................................. 123
Locator Column.................................................................................................. 123
Browse Options/Default SQL Tab...................................................................... 124
Regenerate SQL ................................................................................................ 124
Default SQL Select............................................................................................. 125
Default SQL Where ............................................................................................ 125
Default SQL Order by......................................................................................... 125
Browse Options/Data Columns Tab................................................................... 125
Data Columns/General Tab ............................................................................... 128
Data Columns Properties/Actions Tab............................................................... 129
Data Columns/Properties/Column Sorting Tab.................................................. 131
Data Columns/Properties/Appearance Tab ....................................................... 133
7
Browse Options/Custom Columns Tab.............................................................. 134
Custom Columns Properties/Appearance Tab .................................................. 135
The ASP Form Extension Template ......................................................................... 139
Form Options/Global Overrides ......................................................................... 139
My Records ........................................................................................................ 140
Form Options/GlobalsTab/Security Sub Tab ..................................................... 141
Form Options/Global Tab/Database Tab ........................................................... 142
Security Levels................................................................................................... 143
Titles (Insert/Edit/Delete/View/Search) .............................................................. 143
Messages........................................................................................................... 143
Navigation .......................................................................................................... 143
Includes.............................................................................................................. 143
Form Options/ActionsTab .................................................................................. 144
Allow (Insert/Edit/Delete/View)........................................................................... 144
Page to Return To.............................................................................................. 145
Builder Page Information ................................................................................... 147
Generate QBF.................................................................................................... 147
Parent Browse.................................................................................................... 147
Form Options/Help ............................................................................................. 148
Help URL (Insert/Edit/Delete/View/Search) ....................................................... 148
Form Options/Data Access Tab......................................................................... 148
Table Sub Tab.................................................................................................... 149
SQL to Delete Row Sub Tab.............................................................................. 149
SQL for Selection Sub Tab ................................................................................ 149
Form Options/Controls Tab................................................................................ 150
Appearance Sub Tab ......................................................................................... 151
Validation Tab Sub Tab...................................................................................... 153
Select Options Sub Tab ..................................................................................... 155
Form Options/Custom Controls Tab .................................................................. 156
Ch. 8: ASP Embeds
161
Global Template Declarations .................................................................................. 162
Accessing the Embed Points.................................................................................... 163
Global Embed Points................................................................................................ 163
Browse Embed Points .............................................................................................. 164
Connection Object.............................................................................................. 164
Recordset Object ............................................................................................... 164
Merge Call.......................................................................................................... 165
Form Embed Points .................................................................................................. 165
Connection Object.............................................................................................. 165
Recordset Object ............................................................................................... 165
Merge Call.......................................................................................................... 166
Status Merge Call (Delete Only) ........................................................................ 166
Examples .................................................................................................................. 167
Form Embed ...................................................................................................... 167
Step One: Define the User Variable................................................................... 167
Step Two: Add the Code .................................................................................... 167
8
Additional Form Embed...................................................................................... 169
Browse Embed................................................................................................... 171
Step One: Define the User Variable................................................................... 171
Step Two: Add the Code .................................................................................... 171
Step Three: One More Line of Code.................................................................. 172
Ch. 9: HTML Includes
175
Understanding the Process ...................................................................................... 175
What to Use it For..................................................................................................... 177
Final Notes................................................................................................................ 178
Ch. 10:
ASP Source Code Procedure
179
Application ................................................................................................................ 179
Usage ....................................................................................................................... 181
Ch. 11: Style Sheet Editor
185
Style Sheet Tab ........................................................................................................ 187
Body Tag Tab ........................................................................................................... 189
Background Class Tab ............................................................................................. 192
Data Tab ............................................................................................................ 192
Borders Button - Data Tab ................................................................................. 193
Margins Button - Data Tab................................................................................. 194
Padding Button - Data Tab ................................................................................ 194
Header Button - Data Tab .................................................................................. 195
Column Label Button - Data Tab ....................................................................... 196
Data Rows Button - Data Tab ............................................................................ 196
Footer Button: Data Tab..................................................................................... 198
Input Label: Data Tab......................................................................................... 199
Input: Data Tab .................................................................................................. 200
Style Sheets.............................................................................................................. 202
Index:
203
CLARION/ASP Introduction
Ch. 1:
9
Introduction
This chapter summarizes Clarion/ASP programming and deployment.
Clarion/ASP auto generates ASP (Active Server Pages) pages each of which serves to
publish a standard business procedure such as query a table or view, browse (display
and allow navigation through the results of a query or a table), or updates (add new
record, change record, or delete record).
The target platform is Internet Information Server, specifically public or high volume sites
using IIS and an ADO data-store. Clarion/ASP allows for a high degree of customization
of the interface, allowing for excellent integration into existing sites. All business and
application logic is strictly divided from the interface; in fact a web developer may safely
edit the HTML and Cascading Style Sheets which provide the “setting” for the database
“components” without fear of “breaking” the ASP code.
Overview
The following is meant to convey a conceptual summary of the Clarion/ASP code
generation process, for the developer familiar with creating desktop applications:
•
The modular application pages that Clarion/ASP generates fit together with links.
You therefore apply Clarion/ASP to the individual procedures for which you want
to provide web access. Clarion/ASP reads your data dictionary and builds a
default procedure (as an extension to your existing procedure). Then you
customize the Clarion/ASP procedure settings using the template interface,
rather than the formatters or Clarion embeds. This makes it important that you
use the Validity Checks tabs in the dictionary for all related fields. This helps the
template create a pseudo application flow for stateless http (stateless means that
each page is isolated, and can’t see variables contained on the previous or next
pages). You’ll also build a connection string (using a wizard) that tells ADO how
and where to access the database server. In essence, these items function as
the database/driver/tables settings for the application.
•
You’ll create a style sheet that controls the appearance for everything, using the
template interface and an HTML template which will act as a “setting” into which
Clarion/ASP will place the controls it generates. This is roughly equivalent to
setting global window and control appearance properties for your application (all
of which can be overridden at the procedure level).
•
You can add many further behavior or appearance customizations through the
template interface. In addition to the various database behaviors in your
application, these may include links to other non-Clarion/ASP generated pages at
the site, incorporation of various images stored at the site, etc. These function as
the directives (and to some extent in the case of custom links, embedded code)
10
that tell the Clarion Application Generator what customizations for functionality
and appearance to place in the generated code.
•
You’ll generate the pages. In this case, generating source code is all that is
necessary; no compiler needs to be called because ASP is a scripting language.
You (and your web administrator) are then free to further customize the
generated pages (for appearance, application behavior, etc.).
•
Windows NT Workstation, Windows 2000 Professional, and Windows XP
Professional all provide a copy of Internet Information Server so that the
developer may test and debug the application on the machine that they develop
on.
•
Then you integrate the pages into your existing web, and copy them to an IIS
server, which is equivalent to deploying the application.
Note that you apply the Clarion/ASP templates first as a global extension template, and
then on a procedure by procedure basis. When you apply the browse extension template
to a browse, it will automatically create a link to the appropriate update form, but you
must manually apply the form extension to its update procedure.
In other words, if your application has fifty procedures, for which you wish to enable ASP
for five browse and five form procedures, you’ll first apply the global template, then apply
the ASP browse template five times, i.e., once for each of the five browses, and five
times for the forms.
Road Map
Detailing the actual steps summarized in the “conceptual” overview above, this section
provides a simple overview of the development and execution of an application, from
“scratch.”
•
The developer starts with a Clarion database dictionary describing the structures
in an SQL DBMS (hereafter, DBMS will refer to any client server relational
Database Management System such as MS SQL Server, Oracle, IBM DB2, etc).
•
The developer pre-formats the dictionary to include all relations, business rules,
additional indices where a sort order request is expected, plain english
descriptions for tables and fields, and control pre-formatting.
•
The developer optionally adjusts the field order within each table as well as sets
the “do not populate” options as appropriate, in preparation for running the
application wizard. Clarion/ASP reads the list boxes (for browses) and windows
(for forms) generated by the application wizard in order to determine which fields
it should populate in its tables (for browses) and forms, in the order that the fields
appear in those structures.
11
•
The developer runs the application wizard (or creates an empty .app file and
manually populates browse and form procedures).
•
The developer applies the Clarion/ASP global extension template, specifying, at
that time, the DSN, the HTML design time template, and the style sheet options,
i.e., the global connectivity, look and feel options.
•
The developer decides which procedures require ASP page equivalents.
•
The developer applies the browse and form procedures respectively to the
browses and forms in the application.
•
The developer customizes the various fields within each procedure where
necessary, using the design time interface.
•
The developer links additional procedures as needed using the design time
interface. (As an example, a navigational list view (browse) of a “products” table
might link not only to the update form for the product, but also to a browse of all
products by the supplier of the original product, and/or a browse of all products in
the same category as the selected product).
•
The developer tests the various procedures locally using the Clarion/ASP
generated menu page and a local copy of Internet Information Server.
•
The developer fine tunes each procedure as necessary, whether for application
logic, or look and feel.
•
The developer generates the pages and tests them locally.
•
The developer and web administrator together may optionally “fine tune” the
generated pages.
•
The developer and web administrator together provide links as needed, to/from
the rest of the site to the ASP pages, and upload the ASP pages for deployment.
Preparation
As with normal Clarion programming, start with a data dictionary. In general,
Clarion/ASP, if applied to an existing application procedure, ignores the control formatting
customizations in the procedure, and instead reads the customizations in the dictionary. It
refers to the window in the procedure to determine what fields to populate, and in what
order.
The starting point should be a data dictionary referencing an SQL database. Note that
Clarion/ASP also provides an option for working against Microsoft Access, should you
wish to do so for testing purposes. You may not use Clarion/ASP with ISAM databases
(even ISAM databases via ODBC; we note that though Access is technically an ISAM
database, access is only via SQL).
12
•
Every table you require should exist in the dictionary; each should have the Full
Pathname box in its File Properties dialog filled in properly.
•
If you wish to set a particular field order, you may do so in the dictionary.
•
Every relationship should be properly defined.
•
Every table should have a key defined with a primary attribute (in the Clarion
dictionary; the DBMS will no doubt have a primary key).
•
Every view, should you intend to use it in the ASP pages, should have at least
one “key” defined, i.e., a field(s) selected that can later be specified as an SQL
“Order by” clause. We encourage you to work with the database administrator to
create VIEWs. A helpful hint: remember that there will be no such thing as
“reports.” (Every HTML page full of data is already a formatted document). If an
existing application contains some useful reports that access multiple tables, you
may wish to examine the underlying Clarion VIEW structure and create or ask
the DBA to create a similar SQL view. This makes it easy to create a browse
displaying the same data. Such a report can easily be made read only, and you
can set the number of rows to display to as many rows as you wish.
•
Unless you don’t require security at all, you should add, if no such functionality
exists within the current database, a users table which will hold user names,
passwords, security access level and email addresses. See Global
Options/Security Tab for details.
•
If you’re deploying an SQL/ASP version of an existing Clarion desktop
application which utilizes an ISAM database, we also encourage you to work with
your DBA to create triggers to replace some of the business logic in the desktop
application. Remember that since Clarion/ASP outputs only ASP code, Clarion
code in template embed points is completely ignored.
•
Within the dictionary, fill in the “description” fields for tables, keys and columns.
These will function as default “tool tips” in your Clarion/ASP application. Note that
Clarion/ASP picks up all its formatting options from the dictionary; not from any
attributes added to a control in the window formatter. The only thing that
Clarion/ASP will pick up from the window formatter will be the fields list: those
fields present as entry controls in the update forms, and the columns within a
listbox within a browse procedure. (Note: in this case, “entry” refers to any control
which accepts user entry, not just entry “boxes.”)
•
Check the “Do Not Populate” option for all tables, keys and fields you will not
wish to populate under any circumstances. Check that the template has
populated the proper SQL date/time field in cases and not fields for which the
dictionary import wizard has automatically created a GROUP over that date/time
field. Clarion/ASP uses the SQL date/time field, not the Group or its components.
•
Fill in the description and prompt text for all fields you expect to populate.
13
•
Set the Justification option on fields as necessary.
•
Fill in the Validity Checks tab in the Fields Properties dialogs wherever possible,
using the “Must be in File” option on primary/foreign key relations. When you
place a file drop list control template, or combo drop control template in a Clarion
window, Clarion/ASP can then populate a list filled from the related table.
Additionally, for non-linking fields, fill in ranges, true/false, Must be in List
wherever possible, so that Clarion/ASP can generate Javascript client side
validations. In general, the more client side validity checking your ASP
application can do, the less need for communication of error messages between
the DBMS and the end user.
•
Set up window control types (such as radio buttons, as opposed to entry boxes)
and control properties for fields wherever possible. Bear in mind that some
attributes will be ignored (e.g., font, transparency, mouse cursor) because they
are not supported in HTML.
All the above actions emphasize storing application design in the dictionary as much as
possible, which is an excellent every day strategy for any Clarion developer who creates
multiple applications which access the same database whether using Clarion/ASP or not.
Many Clarion developers already do so as a matter of course.
Creating/Modifying the Application
While in fact you can simply add the ASP extension to an existing application and then
take the procedures you wish and “ASP-ize” them, we suggest starting a new application.
It’s a simple organizational issue: In the existing application you will no doubt have
procedures you don’t wish to put on the web; and you may have source and report
procedures which you can’t put on the web. (Note that you may apply Clarion/ASP to
applications utilizing either the Clarion or ABC template chains).
This is merely a recommendation. Many developers will prefer to keep everything
(desktop and ASP) in one code repository. The reality is that the desktop and ASP
applications will share no code; only a dictionary.
For other developers, it may be most straightforward to create a new application, and not
populate any files, in effect creating a blank application tree. You may then add “ToDo”
procedures and use the browse procedure and form procedure wizards.
When you’re ready to create the ASP pages, all you need do is choose Project >
Generate all from the development menu, as opposed to pressing the “Make” button.
You may also take the following actions, which will facilitate viewing and navigation
across tables for the end user:
14
•
Add Field Lookup Buttons, File Drop Lists, and File Drop Combos to windows to
facilitate navigational flow. The HTML pages produced won’t have tabs leading to
child or select browses; these actions will allow the end user to either drop a list
or press a button to navigate to related data.
•
“De-normalize” the data in the browses. If a browse contains “Product_ID,” and
“Person_ID” from the Orders table, use the list box formatter to link in the
Products and SalesPerson tables, and add in the “Product_Name” and
“Last_Name” from the related tables. Clarion/ASP will automatically add the JOIN
syntax and display data from the three tables. You may then instruct ASP not to
display any unwanted fields, such as ID numbers.
Adding Clarion/ASP
You’ll apply Clarion/ASP as a global extension template. This manual contains detailed
instructions on the template interface options for the global extension. You must add the
global extension before you add any procedure extensions. The global extension merely
sets the defaults. After setting the global extension, you then add the ASP browse and
form procedure templates to the procedures for which you wish to generate ASP pages.
You cannot apply the procedure extension templates until you’ve added the global
extension, and you will not generate any ASP procedure pages unless you’ve then added
the ASP procedure templates to a procedure(s).
When you add the global extension, you must define a connection string. Your ASP
application does not use Clarion drivers. It uses either OLE DB or ODBC. A connection
string is merely a list of parameters that MS Internet Information Server requires to
access the database. The Connection will provide a wizard like interface for you to build
your connection string.
You may define the style sheet and the HTML template when you apply the global
extension, or do it afterwards. The style sheet is much like a style list you may be familiar
with from word processors. For Clarion/ASP, for each “part” of a browse or form, you’ll
use a separate style, which holds the coloring, font, sizing and font attributes choices.
Using style sheets allows the web site to completely change the “look” of the site by
editing only a single file.
The HTML design time template provides a “setting” for the browses and forms; in effect,
you may place HTML elements such as a logo or text above and/or below the browses
and forms, set page background colors, etc. If your site already has a “template” for web
pages, you may easily take this, add a single text symbol, and thereafter all your
generated pages will appear inside your template.
At the global level, you’ll also set security options. Clarion/ASP makes implementing a
flexible security policy (for example, you may allow some users to edit certain data,
others to view it and still others not to view it at all) very straightforward.
15
Procedure Customizations
You’ll apply the procedure extension template only to those procedures for which you
wish to generate ASP pages.
In many cases, you’ll elect to edit the list of fields contained within the browse. The
reason for this is both that your data displays in a table, which is not scrollable, and
because the more data in the table, the more network communications and memory
usage are required by browser, server, and DBMS. In general, we recommend limiting
the number of columns to four or five.
You’ll also have an option to either allow for a “button” at the left or right of a browse row
to link to an update form, or define link fields, so that when the end user clicks a data item
in a row it opens the update. You can also include “custom” columns which may contain
an image linking to another procedure or even to a page elsewhere in your site.
You may wish to specify security levels for the forms. This allows you to define access as
edit/view/none dependent on the user.
If you defined the “Must be in table” options in the data dictionary, links to parent tables
can provide a “select” button which provides for a popup window of allowable values from
the other table. If you wish, you may instead populate a file drop control template in the
form window, which instead populates a file loaded dropdown list box for the end user to
choose from.
There are many additional options documented within the command reference section of
this manual.
Generating and Incorporating
When you’ve generated your pages, you’ll test them using the web server on your
development machine. Then, when incorporating them into your site, you may also wish
to consult with the web administrator so that your style sheet will complement the site’s
current styles, and probably also that the site can provide a frame and links to the
procedure pages.
It’s important to realize that each browse, update form, view form, or Query-by-Form can
be called from any other page in the site. In fact, in cooperation with the web
administrator, you can “pre-fill” data fields within a Clarion/ASP form by posting the data
from forms that may already exist at the site. Or you may wish to collect data on a
Clarion/ASP form and post that to an existing form.
You’ll find that Clarion/ASP pages work well with existing pages in the site, and that this
manual documents how such cooperation works.
16
CLARION/ASP IIS, ASP, ADO, HTML
Ch. 2:
17
IIS, ASP, ADO, HTML
The purpose of this section is to briefly provide an overview of ASP – Active Server
Pages – technology to Clarion and other database developers who may only have
passing familiarity with it. ASP has so far been the province of web designers who have
learned something of development tools because they had to. Clarion/ASP comes from
the opposite direction... it’s for developers who want to create ASP. Developers bring with
them very unique advantages that web designers could not be expected to bring, in areas
of programming efficiency and data management.
At its simplest, ASP is a form of server side scripting. ASP, executed from a dynalink
library, runs as a service subordinate to the web server. It receives a request from the
web server (usually but not exclusively Microsoft Internet Information Server) for a page
whose file extension is .ASP. The ASP library examines the page, runs its embedded
scripts, and “writes” an HTML page which reflects the resolution of whatever script(s)
were run. It passes the HTML to the web server, which passes it to the web browser. The
web browser receives only the HTML, and never sees the scripts which produced it.
The scripting language is usually VBScript, but any other scripting tool recognized by the
server, such as JScript or Perl can be utilized.
The script has access to all the resources that the system account on the web server has
(“system” is the default, but can be changed).
IIS Setup
This section is designed to help the developer set up IIS and a Clarion/ASP application
on a Windows NT/2000/XP Professional workstation. It’s assumed that for site
deployment your web administrator will provide the expertise to set up the application,
and that all the developer need do is to turn over the files and agree with the web
administrator on the name of the ADO connection.
You can easily run IIS locally to test your Clarion/ASP application, using the localhost
(127.0.0.1) IP address.
IIS differs slightly from Windows version to version in its install wizard and procedures. In
general, the developer should first check the Administrative Tools shortcut group to see if
the Internet Information Services icon is present. If it is, then IIS is already installed. If
not:
•
Windows NT and Windows 2000: if IIS is not installed, insert your Windows
installation CD, and search for a directory called i386\inetsrv. The installation
program is called INETSTP.EXE.
•
Windows XP Professional: insert your Windows installation CD, wait for the
autorun installation program, and choose Install Optional Windows Components.
Internet Information Server appears in the subsequent list.
18
Once everything is installed, open your browser, type http://127.0.0.1 in the address bar,
and you should see a default home page. If not, open Control Panel, find the Services
applet (one level down under Administrative Tools in Windows 2000 and Windows XP),
and start the World Wide Web Publishing Service service. If you are running a fresh
installation of Windows XP and have recently applied security patches, you may not see
a default home page; the default page depends on ASP, and the security patches may
turn off necessary permissions. Windows XP users should read the section immediately
following before continuing.
19
If you’ve installed IIS for the first time, or if you simply haven’t used it before, we strongly
suggest that you take a little more time to install the latest Windows Service packs, and
then afterwards, the latest IIS Security patches. We suggest reading the IIS Security
page at
http://www.microsoft.com/technet/treeview/default.asp?url=/TechNet/security/prodtech/iis
sec.asp for further information.
Note also that you may display the IIS help via the URL http://localhost/iishelp.
20
You can, of course, generate pages without having IIS on your development machine,
and copy them to a server. You can even set a network share on the server and develop
in a directory on the server so that you don’t even have to copy the .ASP pages there. In
the latter case, we strongly suggest that the server be located only on your intranet, and
not accessible from the Internet.
Note: IIS Security Patches For Windows XP
As of March 2002, new IIS security patches, if applied to a new installation of Windows
XP may turn off some read/write and execute permissions on the web root. This prevents
any ASP pages from running. The “symptom” that this is the problem will be that when
you type “http://localhost” in your browser address box, an error page will indicate an
error in an asp page called “localstart.asp.”
Additionally, simply changing the permissions for the root only will not enable ASP... you
must extend the permissions to all existing subdirectories.
Do the following only if you have a fresh XP IIS installation, i.e., you’ve never added any
real or virtual subdirectories to the web root, and haven’t changed the location of the web
root. We have not seen any security patches which change the permissions of an IIS
installation which previously had a functioning web server.
21
The initial home directory properties will look like this:
Note the unchecked box for “Read” in the untitled group box, and the selection of “none”
in the Execute Permissions check box. You must check the “Read” check box, and set
the Execute Permissions choice to “Scripts Only.”
Then, after checking OK or Apply, a dialog box appears asking to apply the permissions
to the child directories. The text in this box is somewhat confusing. You must select all
and press OK.
Following this, reload the default home page in your browser. If it does not load
immediately, restart the IIS service by using the stop/play buttons in the Internet Services
Manager. If the default home page still does not appear, review the steps in this section.
IIS/ASP Check
This step should only be necessary for Windows NT users who did not install the NT
Option Pack.
Verify that your ASP and ADO dyna link libraries are in place. To do so, locate the inetsrv
directory with the IIS binaries (probably %windows%\system32\inetsrv), and verify that
ASP.DLL is present. If not, you must install it. We cannot say how much longer the option
pack will be available, but at the time this manual went to press, it was downloadable at
22
http://www.microsoft.com/ntserver/nts/downloads/recommended/NT4OptPk/default.asp.
(Though the URL indicates NT Server, you’ll find an option for choosing workstation at
that location). If the option pack is no longer available at the time you read this, it may be
necessary to upgrade your operating system.
Virtual Directories
With IIS working on your workstation, you must keep in mind that the local web site’s
directory structure is in no way obligated to match your directory structure. Its root
directory will be viewed as “/” by the browser (remember that as a web service, the
directory delimiter is a forward slash, rather than a backslash). The fully qualified file
name of the directory on your hard drive may be C:\Inetpub\wwwroot (the default).
When you create a directory below the root, such as C:\Inetpub\wwwroot\mydirectory,
your web browser will see the directory as http://localhost/mydirectory.
A virtual directory allows you to declare that a directory located anywhere on your hard
drive can fit into your web directory structure. This is generally far easier to manage.
Assume that you’re working on a project called myproject. Your Clarion project directory
is C:\My Documents\Clarion\myproject. You wish the browser to see the application
directory as residing in http://localhost/myproject.
23
Rather than copying over all the ASP files to another directory each time you regenerate
them, it would be far easier if you told Internet Information Server to use your working
directory’s ASP subdirectory as a virtual directory. Thus, rather than creating a
subdirectory and copying your files to C:\Inetpub\wwwroot\myproject, you’ll declare that
the ASP directory that Clarion/ASP will create under your project directory is a virtual
directory. The name of that directory (in this case) would be C:\My
Documents\Clarion\myproject\asp).
When you’re ready to create a virtual directory for your project, you’ll find step by step
instructions in the section of this manual called “Testing on Your Local Machine.”
Note: some very useful settings to know about IIS, especially when you expect to test
applications, are the timeout settings for application variables. You’ll find access to these
on the “Home Directory” tab (or “Directory” if you wish to manage a single directory at a
time) of the directory settings. Locate the “Configuration” button in the lower part of the
tab. This leads to the Application Configuration dialog. The settings are:
•
Session Timeout: this times out the session variables, including user ID’s for
logins. For testing, set it low.
•
Enable Buffering: turn this off if you expect to be generating frequently while
tuning the application.
•
ASP Script Timeout: turn this very low (e.g., 15 seconds) when you’re testing
ADO via custom queries; Clarion/ASP won’t be able to output debug information
upon an ADO connection error. Therefore, it’s best to keep the timeouts short.
•
Additionally, on the Home Directory tab (which precedes the three settings
above), we recommend that you set Application Protection to “Low” using the
dropdown choice list.
Default Virtual Images Directory
Many web sites have a virtual directory in which they store frequently used images,
usually called /images. You probably do not have such a directory on your development
machine. As you set IIS up on your development machine you should create this virtual
directory and point it to Clarion\images\asp, so that the Clarion/ASP button images can
be found by your application (of course, you can override this location if you prefer to
keep the images elsewhere). For further information, please see the section entitled
“Testing On Your Local Machine/Internet Services Options.”
24
ASP and Database Access
For database access, ADO (Active Data Objects, or sometimes ActiveX Data Objects) is
the normal means of access. In essence, this means that the script creates an OLE DB
object that takes requests from the script, queries or takes action on the database, and
provides a resultset (query result) object to ASP. ASP then examines this object and
generates a web page with some result.
Through methods such as, for example, connection pooling (logging into the database
just once, and bringing back all queries for all subsequent users through the one
connection), ASP manages resources efficiently, making the solution quite scalable.
Originally, ASP’s purpose was limited to making web pages more interactive; obtaining
user information from an HTML form, and then tailoring subsequent pages to cater to the
interests of the end user. This was quite scalable, and small but customized pages could
be served up very quickly.
A feature that helped to transform ASP into a business applications platform was the
addition of ADO, which provides flexible, secure access to SQL databases.
ASP/ADO Applications
Think of your ASP application, therefore, as a browser based interface to a powerful back
end application. The ASP platform has its strengths and weaknesses:
Stengths:
•
Your applications’ interfaces gain the advantage of being accessible from
anywhere without requiring installation.
•
They can be very scalable.
•
The applications are secure, because the end user only sees the user interface,
and the interface shows only the data you decide to show.
•
The applications are manageable at a single point (the web server), and
upgrades require no action on the part of the end user.
•
The applications themselves can look very pretty and be very functional.
Weaknesses:
•
The applications look and feel different than desktop applications; issues such as
window and thread management, and a restricted selection of window controls
may be frustrating to some developers.
•
25
The scripting languages, and the programming structure for them may not be as
fully featured as other languages.
Note that Clarion/ASP’s ADO access requires that if you do not use a virtual directory,
you must either copy the GLOBAL.ASA file generated by Clarion/ASP to your server’s
application directory, or (more likely) cut and paste the text in that file into the
GLOBAL.ASA file in your web’s root directory, whichever your web administrator prefers.
The GLOBAL.ASA file contains several variable declarations used by Clarion/ASP. For
more information on these variables, see the Global.ASA section in the Testing HowTo’s.
Database Access
In regards to relational databases, ADO – Active Data Objects – is an ActiveX interface to
ODBC access. ADO also provides interfaces to non relational tables such as Excel
spreadsheets, in which case ODBC is not used.
Using the templates, it’s not necessary for the Clarion developer to know the ADO
methods; like the ASP objects described above, they are important if you wish to
understand the generated ASP code.
ADO works within ASP with the declaration of a connection object. The open method of
the connection object takes the connection string as a parameter, and opens the
database.
The execute method of the connection object takes an SQL statement as a parameter,
and returns a result set: an array of database values. As an example, “Select FirstName,
LastName from MyTable” returns the values of all the first and last names from all the
rows of MyTable.
Using the resultset methods, such as next and previous, the developer can navigate
through the database. The Clarion developer need not be concerned with ADO code. The
template builds the necessary parameters.
The template interface also generates the SQL code. These statements are exposed in
the procedure properties dialogs; those Clarion developers with an excellent knowledge
of SQL should feel free to modify the code should they feel they can make it more
efficient.
Clarion/ASP is designed for use with Client/Server SQL databases exclusively. In very
low volume sites, the Microsoft Jet Engine (Microsoft Access .mdb files) can be
substituted; SoftVelocity has built in compatibility with its non standard syntax.
26
Clarion Programmers and ASP/ADO
This section provides a very brief introduction to how experienced Clarion programmers
will work with Clarion/ASP. Here are the main points:
•
The biggest change is that you don’t program database access in Clarion. For
lack of a better analogy, Clarion programmers must sit back and “let the
templates drive.”
•
You will continue to work with templates, the dictionary, and the application
generator.
•
The “look” of the application will be controlled through style sheets.
•
You may choose to apply the global ASP template to an existing application or a
new one.
•
Once the global template is applied, you select the browse or form procedures
for which you wish ASP pages, and apply the ASP browse and form templates to
them.
•
The options set by the window formatter to format the appearance and behavior
of controls will not affect their ASP equivalents; however, any control you wish to
appear on the ASP page must have an equivalent in the browse listbox (for
browses) or in the WINDOW (for forms) structures. In other words, you can place
a field with the window formatter, but everything else will be controlled in the ASP
Browse or ASP Form extension dialog.
•
These dialogs provide for a great deal of customization, both in appearance and
functionality.
•
To generate the ASP pages, you’ll choose the Generate All command, and then
transfer the pages to your server.
•
Your .APP file will still generate a Clarion/Windows desktop application,
separately, safely ignoring your ASP options and scripts.
•
As always, the Application Generator will safely regenerate new code when you
make changes without losing old customizations.
27
HTML (Hypertext Markup Language)
In order for us to introduce the VBScript language, we must quickly review the elements
of HTML.
Each HTML page is a combination of static text, formatting tags, and links which instruct
the browser how to display the text. The links provide access to another page, when the
end user clicks one, or it may instruct the browser to get another file, such as an image
file, and display inside the page.
The formatting tags consist of codes enclosed in angle brackets, and generally come in
pairs. The first of the pair is the code within the angle brackets, such as <b> for bold. The
second of the pair includes a forward slash to indicate it’s the ending format code, such
as </b>.
They surround the word or paragraph the format applies to; for example, to bold the word
Clarion in the following sentence fragment, the HTML code would be: amongst database
development tools, <b>Clarion</b> stands out.
Other key tags include <TITLE>, which delivers the page title which appears in the
caption bar, and <p> which provides the beginning and end markers for a paragraph.
Certain built in styles, such as headers of different styles, bullets, and numbered lists are
available.
You can encode further styles in a separate file called a cascading style sheet. This can
store a preference for a certain font, size, color, etc. When you create a standard style
sheet and use its styles for all the text in the pages at your site, you can easily update the
look of the site by editing the style sheet, thereby changing the fonts throughout all your
documents.
To arrange the layout of text and pictures, the most common method is to declare a table.
It’s easiest to think of a table as a flexible grid, whose cells you can merge, or insert to
easily. In general, whenever you see a web page with newspaper style columns,
indented text, or any sort of fancy layout of graphic elements, it’s using a table.
Clarion/ASP does not require you to know a single thing about HTML. You can apply the
various style sheets supplied to use the colors and font schemes you think look best;
If you wish to customize further, you can edit the style sheets; or the HTML code within
the ASP pages you generate; or you can have a designer or web master edit the
appearance of the pages you produce.
28
Here is a “bare minimum” HTML page, consisting of a title, headline, a small amount of
body text, and a text link to a page called “other page:”
<html>
<head>
<title>This Appears in the Browser Caption Area</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1>This is the Page Headline</h1>
<p>This is some body text. Every good boy deserves favor. All work and no
play
makes Jack a dull boy. The quick brown fox jumped over the lazy
dog.</p>
<p>The following text, where it says <a
href="http://www.mydomain.com/pages/another_page.htm">Click
Here</a> provides a text link to another page.</p>
<p>And finally, the SoftVelocity logo will appear centered below:</p>
<p align="center"><img src="/images/SoftVelocityLogo240w.GIF" width="240"
height="127"></p>
</body>
</html>
And here is that page as it appears in an HTML editor’s preview:
29
VBScript Language
The scripting language itself is derived from Microsoft Basic. Perhaps more important for
ASP than the basic language elements and statements are the built in classes and
objects for page and component access.
Chief among these are the Request and Response objects, which refer to the incoming
http request, and the outgoing http response respectively: the URL, parameters and
posted data (fill in form data) that your ASP page receives, and the HTML page it posts in
response.
For example, if a form on the referring page contains a text box named FillThisIn, to
retrieve the value that the end user typed in, the developer uses the method called
Request.Form(“FillThisIn”).
To write a string out to the client’s browser containing the contents of a variable, the
developer may use the method Response.Write (myvariable).
Script statements are enclosed in tags: <% before the statement, and %> at the end of
the statement. Notice that the end marker does not contains a forward slash, as HTML
markers do.
To write out a variable within an HTML string, an equal sign is added within the script
statement tag. For example, to begin and end a paragraph with text, and insert the
contents of a variable within it, you might use the following: <p>Counter value equals
<%=MyCounter%> right now.</p>
Another object, the application object, provides a global storage area applicable to the
application, so that all sessions can refer to a single variable, for example.
The session object refers to the interaction between the server application and a single
user at one “sitting.” This is an important concept to master. HTTP is a stateless protocol.
That means the browser sends a request for a document, the server sends it, and that’s
the end of the transaction. As far as the server is concerned, the next request from the
browser is a completely new request, and it does not recognize having fulfilled a request
from the browser previously. The session object is a workaround for this protocol, using
cookies and unique ID’s. This provides a storage space for the equivalent of global
variables.
The data types in VBScript are limited to one type, called a variant. To mimic the use of
data types, the developer uses conversion functions whenever retrieving a variable. The
conversion functions, of which there are nine, start with the letter “C” plus the type to
convert to. To convert a variable for use as an integer, for example, the necessary
function is CINT(myvariable).
Clarion programmers only need to use VBScript should they wish to customize the
behaviors in the generated web pages.
30
CLARION/ASP ASP Template Concepts
Ch. 3:
31
ASP Template Concepts
Longtime Clarion developers used to working in the Clarion language may be startled to
think of the Clarion application generator generating applications in another language.
Clarion has generated database applications on DOS, Windows and IP platforms for
nearly two decades.
How ASP Fits In with Clarion
Clarion’s emphasis throughout its long history has been to provide “canned” application
behaviors which developers tie together through series of prompts and wizards:
•
The developer creates a database dictionary describing the data, which also
holds various application options.
•
The development environment further presents a design-time interface which
provides for further application customization, as well as source code level
customizations.
•
The application generator takes all the customizations and outputs source code
files.
•
The project system then compiles and links the resulting program.
Clarion has been the “language of choice” for the applications it’s created, though
developers have had the option of incorporating C, C++, and Modula-2 source code
modules. Clarion/ASP represents the first time the Clarion environment has been used to
generate source code modules with no Clarion code.
Clarion/ASP provides a new option to deploy Clarion applications to browser-based users
from public or high volume sites, utilizing the same elements: database dictionary,
design-time interface, and application generator. Clarion/ASP creates Clarion type
applications for browser clients/ASP servers.
What’s Special About Our ASP Code
The ASP/ADO code generated by the application generator is highly compact and
efficient, yet features robust error checking.
•
“Processor Pages,” which complement each of the .asp pages that Clarion/ASP
generate for your procedures contain the database access code. The processors
consist of small, tight loops which smoothly handle difficult access issues such as
column names with embedded spaces, null values, which are particularly
troublesome in ASP, and type conversions.
•
Compact Javascript functions provide for rapid client side validation.
32
•
Customization support within the template interface which essentially allows the
developer to place HTML/VBScript code alongside the Clarion/ASP code without
harming the generated code, and without risk of overwriting the customizations at
generation time.
•
Rich support for images, whether displayed from a database row or external file.
•
A flexible security model which provides up to 100 different security levels per
procedure, along with options to allow viewing, adding, editing or deleting data
according to the level of the user.
•
“My Records” filtering, an integral part of the security model, allows “ownership”
of rows by an individual user or group of users. The developer may then specify
that only that user or group may access that data.
•
Automatic calls to login screens and user validation from within all pages using
security, so that the proper security is in place even if the ASP page is called
from a page not generated by Clarion/ASP.
•
Extremely flexible interaction with URL parameters, making it possible to identify
record(s) for use when called from other pages at the site not generated by
Clarion/ASP. (i.e., link to an update form for a specific record from any other
HTML page. (Except the templates for the browse pages. These require that the
order of the components be preserved; these templates contain comments so
that the web designer understands what is and is not “editable.” The columns
may be rearranged).
•
Flexible interaction with the specific form fields within the update form allowing,
for example, a page from elsewhere in the site to link to a form and pre-fill one or
more fields.
•
Extremely flexible layouts via HTML run-time templates which can help you
change any layout beyond the many options already available through the
template interface. Clarion/ASP completely separates the application logic from
the interface, making it a simple matter to turn the interface over to a web
designer without worry that the customization will break the app. The web
designer may modify anything and everything, so long as he or she cuts and
pastes the symbols (for example @TableNameFieldName@) for each element to
its new location.
•
An enormous amount of flexibility via use of style sheets that work along with the
ASP pages allowing you to define exactly the look you wish, and which allow you
to “blend” the pages into an existing web using the same look and feel, and then
automatically change the “look” whenever the site is updated.
33
Interaction with Dictionary
There are two guidelines to keep in mind when working with Clarion/ASP:
•
The template looks to the dictionary for your application flow and pre-formatting,
not to your .app file.
•
HTML controls are different than Windows application controls. There is
significantly less capability for customizing appearance, behavior, and
positioning.
The first guideline makes it crucial that you store as much information about the business
rules and control pre-formatting in the dictionary as possible. The second, that you rely as
much as possible on the global level options (via the dictionary and the Global ASP
extension dialog) to set control behavior rather than on the window formatter. The only
information that Clarion/ASP will pick up from your WINDOW structures is the list of
available controls.
Navigational Links in Clarion/ASP
Because HTML is stateless, the application you produce must also be. Every page can
stand alone; unlike Windows applications, you cannot assume that “window 2” will only
appear if the end user first did something with “window 1.” That can only be managed in
the broader context of your overall web site flow.
Be sure to define the “Must be in Table” option within the dictionary for all fields which
have a file relation. This will allow for hyperlinks to the appropriate related tables.
Additionally, if you wish to implement the “browse/form/browse” paradigm that Clarion
desktop applications implement by default, you’ll simply accept the default links to the
update form from the browse. To the end user, it will appear as a graphic that when
clicked leads to an update form.
ASP opens up additional navigational possibilities from within the browse. The normal
navigational direction in Clarion flow is from parent to child to child (edit a record, view
child browses, double click the child, edit the child, view its child browses, etc).
Clarion/ASP allows for navigation in the opposite direction. In much the same way that
you can declare a field to be a procedure link to a child update form, you can declare
another field to be a procedure link to a parent update form. This is allowed through
procedure links. You can conceivably create a table with four or five columns and ten or
twenty rows and enable every single piece of data in the resulting “cells” to link to a form
or browse in a parent or child table that is filtered by the value in the cell it was linked
from.
34
It’s therefore quite simple to go from browse to browse. For Clarion developers who in the
past have stuck closely the templates, Clarion/ASP may seem to offer an overwhelming
variety of new choices. In the case of browse-to-browse navigation, however, developers
will find that this is the HTML implementation of child browses on a form; separating the
child browse from the form allows for more efficient memory and network
communications.
It’s important to remember that each procedure or page must be able to stand in
isolation, or even, which procedures must be accessible from “outside,” i.e., a completely
different part of the site having nothing to do with the application. For this reason, the
developer must decide which procedure must link to others. Implementing the links
require a few mouse clicks.
Likewise, the requirement that each procedure be able to stand in isolation makes the
concept of a “menu” problematical. Clarion developers accustomed to the application
frame as a gatekeeper to access to each of the procedures may consider the simple list
of procedures that Clarion/ASP generates as a “menu” to be unappealing and
unimaginative compared to the functionality of the other pages that Clarion/ASP
generates. The “menu,” however, isn’t meant to be deployed, but instead is a simple
convenience for the developer to use when testing. It’s up to the developer in conjunction
with the web site administrator to provide for the proper ‘gateway” into the individual
procedure pages that Clarion/ASP generates.
Window and Control Formatting
A key concept to understand when creating ASP applications is that HTML controls are
different than Windows application controls. There is significantly less capability for
customization and far less control over positioning. This leads us to a “good news and
bad news” situation.
The good news is, despite these limitations, in Clarion/ASP we’ve accomplished an
extraordinary amount of mimicry of control formatting and layout using HTML 4.0 and
stored it all in style sheets for maximum flexibility. The bad news is that because there’s
no way to equate every single one of the properties in the dictionary control formatting
options with HTML we can’t guarantee that everything will be perfect. For example, we
can’t provide for transparency, immediacy, selected coloring, or control-specific cursors,
to name a few. We can’t recreate controls such as regions.
Developers will find that your control formatting will be less visual, and more dependent
on selecting properties from lists. Layouts are either horizontal, as in a browse, or vertical
as in a form, one control to a line. You may specify the types of control, and a number of
options for appearance and behavior, but it’s not the same as designing a dialog box.
Good use of style sheets, however, can make for a very attractive page.
35
After the page is generated, however, you can load the runtime HTML template that
Clarion/ASP produces in an HTML editor. That template contains symbols
(@TableNameColumnName@) that indicate where the data will “go.” You can completely
redesign the placement of everything on your forms by editing the runtime template.
Security Levels
Clarion/ASP provides for a straightforward yet highly flexible security scheme based on a
pyramid of user/group access rights with up to 100 user levels.
When you enable security on a global level, each generated procedure will include a
login routine. Access by the end user to any procedure page with security enabled will
invoke a login screen. Once the user enters a successful login on one page, they may
access any page their security level allows rights to, providing that any period of inactivity
does not extend beyond a configurable timeout. If it does, they must log in again.
You may designate a table within the database to store a user ID (we suggest that an
email address is highly useful for general public web applications), password, and access
level (an integer between 0 and 99). Optionally, the table may store the user name (either
first and last names separately, or first and last combined), and an email address if not
used for the user ID.
The login messages/instructions are configurable.
After specifying that security is to be enabled, and designating the table which holds the
user information, the developer may then set custom access levels by procedure (the
default for all, once security is enabled, is 1). Within each procedure, the developer may
separately specify separate access levels for viewing, editing, adding, and deleting data.
Thus, should the developer specify that ordinary users are level 30, supervisors level 50,
managers level 70 and senior managers level 90, a developer may specify that a
particular form might be viewed all, a new record added by supervisors and higher, an
existing record edited by managers and higher, and deleted only by senior managers.
With 100 possible values and four possible access levels per update form, the security
system allows for many possible access scenarios.
Additionally, implementing the global security table in conjunction with the “My Records”
filtering, which allows you to designate a column as that particular row’s “owner” allows
you not only to provide for limiting access to the record only to an individual, but also to
provide for security “groups.” By designating, for example, a department ID as the owner,
you may effectively limit viewing and editing of data to only the members of that group.
All traffic between the browser and the server is unencrypted and therefore open to
packet sniffers, unless secure http (https) is used. Deployment of https is beyond the
scope of this manual and is a matter for the web administrator.
36
Language
Clarion/ASP’s default messages (e.g., “Next record” as a tool tip for the “Next” navigation
button) are completely customizable. We’ve provided “sets” of messages in three
languages: English, Spanish, and French. Choose the language set in the global options,
and if necessary, customize the messages further at either the global or procedure level.
If you wish to customize the default prompts, edit the .TRN files in the Clarion template
directory. Each of the files is named ASP_LG??.TRN, where ?? is a two letter
abbreviation for a language. “EN” = English, “FR” = French, “NL” = Dutch, “DE” =
German, and “SP” = Spanish. The file format is template symbol=text. Note that no %
sign precedes the template symbol, that no space should exist on either side of the =
sign, and the text string is unquoted.
Database Access
DBMS Requirements
Clarion/ASP is designed to work with ADO, which is designed for SQL. The ASP code it
produces has been tailored to be fast and scalable, and is well suited for high volume
sites.
The database behind the application is of the utmost importance. Use a dedicated
relational DBMS for all but the smallest sites and for testing. Clarion/ASP provides for
optional code generation compatibility with the Microsoft Jet Engine (MS Access) for
testing and for very low volume sites. ODBC database drivers must be thread safe to
work well with ASP. Be sure that the drivers for the DBMS are up to date.
Theoretically, one could use Clarion/ASP to generate an ASP front end for OLE DB
access to a Microsoft Excel data range. We suggest that as a developer you should be
realistic about the platform you deploy your database on.
CLARION/ASP Getting Started Exercises
Ch. 4:
37
Getting Started Exercises
Our Annotated Examples book provides very detailed instructions for creating the sample
applications.
We suggest that you use these as a starting point for working with Clarion/ASP. Most
specifically, the “Tasks” example provides a quick and easy demonstration of significant
functionality yet takes only a short time to complete.
38
CLARION/ASP How-To’s
Ch. 5:
39
How-To’s
The subsequent topics provide step-by-step directions for implementing Clarion/ASP for
your business applications. The “How-To’s” cover preparation, application, testing, and
Site Deployment/Integration.
Preparation How-To’s
ADO and ODBC/DSN Setup
ADO (Microsoft Active Data Objects) provides for data access to relational and/or non
relational data via ODBC or OLE DB ASP provides library functions that make use of
ADO, and Clarion/ASP uses these functions extensively.
In general, ADO access to relational databases is accomplished by ADO calling the
ODBC drivers, and non-relational access (for example, to an Excel spreadsheet) is
accessed via OLE. In either case, data access is usually fast, and resource-efficient.
The Clarion/ASP developers’ interaction with ADO is usually limited to building a
connection string via the global template prompts. When creating your application, you
will call the Connection Builder (described below) to identify your data and the OLE
provider. You may also choose the OLE Provider for ODBC, in which case you must set
up an ODBC DSN. You must set up the DSN before any other steps.
DSN Setup
DSN stands for Data Source Name, which will be familiar to anyone who has worked with
ODBC. A DSN simply provides a list of resources that describe where the database is
and how to connect to it: the server, the driver, the tables, the user ID, password, etc.
Note that user ID and password, are invisible to the browser (i.e., when the user issues
the “View Source” command in the browser, the page that the user sees does not contain
the user ID and password).
If using ODBC, or the OLE Provider for ODBC, when testing on one machine, and
deploying on another, you must install the ODBC driver and set up the DSN on both
machines. To set up the DSN, you should use the Control Panel Data Sources applet for
ODBC. Choose either a system DSN or a file DSN, so that the DSN will be available to
the system account.
Note: Remember that since OLE DB almost always utilizes the ODBC layer (even when
not using the OLE DB Provider for ODBC), you may take advantage of ODBC tracing
whenever database access issues must be debugged. To enable tracing, open the
ODBC administrator, select the “Tracing” tab, and press the “Start Tracing Now” button.
Remember to note the precise location of the trace file. After you test the application,
open the trace file and read from the bottom to the top to determine any possible data
access errors. Remember also to turn tracing off when done. The use of ODBC tracing
40
can be particularly important should any ADO errors be severe enough as to cause a
timeout. In this situation, no information is returned to the web server, and the only error
information available to the end user is that the application timed out.
Because the prompts for the Data Sources applet can vary by driver selected and
Windows version, we’ve provided only an example of a DSN for Microsoft SQL Server
(as set up under Windows XP Pro), and notes on the settings we’ve chosen:
41
42
The connection string when using a DSN can consist of some or all of the following fields:
•
When typing in a server name, should you be using a TCP/IP only connection, be
sure that the server name is located in the HOSTS file or accessible via DNS.
•
If the driver supports a Client Configuration dialog, be sure to verify the network
protocol and port. In the case of MS SQL Server, our illustration shows a TCP/IP
only connection. Here we use the default IP port number.
•
The user name in the illustration is one set up for our example; it is not a built in
account.
•
It’s good practice to specify the default database.
43
IIS Permissions by Directory
It’s possible that when you apply various IIS security patches that the default IIS
permissions may not permit ASP applications the permissions they need. When working
in the IIS applet, you must be sure that the security permissions set for your application
directory are:
•
Read Permission (Directory or Virtual Directories properties sheet)
•
Execute Scripts (Directory or Virtual Directories properties sheet)
44
•
Anonymous Access (Directory Security properties sheet/press Edit
button/Authentication Methods dialog).
45
Directory Securities
You will probably not have to worry about the directory security, unless you’ve changed
the default settings for your machine. Your project directory will have an asp subdirectory.
The SYSTEM account, which IIS uses, needs access to the asp directory to read the
ASP pages.
46
Application How-To’s
Application of Global Template
This section provides and overview and describes the essential/required steps involved in
applying the Clarion/ASP global template. A more complete description is available in the
Reference section of this document.
To apply the Global Template:
1.
Open an existing application, or create one with the application wizard.
2.
Press the Global button in the Application Tree dialog.
3.
Press the Extensions button in the Global Properties dialog.
4.
Press the Insert button in the Extension and Control Templates dialog.
5.
Select “ASP Global Template” in the Select Extension dialog.
The global extension prompts consist of eight tabs. These are all explained in the
reference section of this document. Though all the tabs have important options, there is
only one tab which must be filled in when first applying the extension template:
•
Database Tab/Build Connection String Button: this displays the Database
Properties dialog. Press the Call Connection Builder button to identify the
database, and the method of access to it. Without this information, the web
server cannot provide the ADO libraries with the information necessary to access
the data.
In addition, the Security tab may be considered by many to be essential. Please see the
Global Options/Security Tab section for further information on security.
47
Application of Browse Template
This section provides and overview and describes the essential steps involved in
applying the Clarion/ASP browse template. A more complete description is available in
the Reference section of this document.
To apply the ASP Browse template to a browse procedure:
1.
Open the Procedure Properties dialog for the browse you wish.
2.
Press the Extensions button in the Procedure Properties dialog.
3.
4.
Select the ASP Browse template from the Select Extension dialog.
When applying the browse extension template, verify the unique key on the HTML Table
tab contains the correct key information. Please see the Browse Options section for
further information on the ASP Browse template.
48
Application of Form Template
This section provides and overview and describes the essential steps involved in
applying the Clarion/ASP form template. A more complete description is available in the
Reference section of this document.
To apply the ASP Form template to a form procedure:
1.
Open the Procedure Properties dialog for the form you wish.
2.
Press the Extensions button in the Procedure Properties dialog.
3.
4.
Select the ASP Form template from the Select Extension dialog.
You must verify that the Form Primary File and the Unique Key on the Data Access tab
are filled in properly before you may save the form properties.
49
Browse/Form/Browse or Query/Browse/Form
If you’ve used the default Clarion template set to create an existing application for which
you wish to generate ASP pages, your application is probably in browse/form/browse
format. By this we mean that the top level procedures browse a list of records, and the
end user locates a record they wish to edit. The end user pulls up a form, and if it’s
necessary to navigate further, either to select a value in a related table, or to browse a
related table, another browse appears.
In general, web based applications start with a query form, for privacy reasons and/or to
reduce the amount of data to be passed to the client (downloading a 1000 item product
list vs. typing in a product name).
SoftVelocity has designed Clarion/ASP so that it works equally well starting out with a
browse, query form, or for that matter, a form. In the latter case, you must either start with
a blank insert form, or pass a unique ID to the page if it’s an update. You set the unique
ID field in the Procedure Properties dialog, and identify it in the URL as “ID1.” Thus, for
an order form, whose unique identifier is the order number such as 12345, to directly
open a form containing the order, the linking URL should contain a parameter in the form
http://YourPageURL?ID1=12345. Clarion/ASP does not pass the name of the field,
because that could compromise security. Note that in case of a multiple component
primary key, the parameter format, for a two component key, for example, is in the format
?ID1=12345&ID2=67890
The Browse-Form-Browse paradigm has been further enhanced in the latest version of
the Clarion/ASP templates to include the "range limit" option on a Form procedure. This
feature permits you to identify a value (not necessarily the primary key) which will be
"persisted" at several levels and used for; returning to a list that is a subset, applying the
range to a search condition automatically, view form navigation of a subset, and priming
of newly inserted rows with the range value. To utilize this feature simply enable the
option "Enable Range limit option" on the Clarion/ASP->Form->Data Access->Table tab.
And then select the appropriate data column.
In general, you do not need to adjust your application at all. Browses and update forms
will be generated with the parameters (or lack of parameters) that you specify. It’s merely
a matter of linking to the ASP page with the correct URL.
The following are examples of the ways in which you can link to the ASP pages from
either the top level contents page, from a frame, from any other pages (not produced by
Clarion/ASP) at your site. You may combine as many of these access methods as you
like.
For the purposes of this example, the table is called “Products,” the procedure is called
BrowseProducts (the table name figures into the page naming convention, e.g, the ASP
file with the browse will be called /myapp/BrowseProductsList.asp) a column containing
50
unique values (strings) is called “Product_Name”, and a column containing duplicate
values is called “Category.” Assume also that the category values are integers.
Finally, assume that all URLs are encoded /myapp/filename.asp.
•
Normal Browse (no filter other than that defined in the template procedure):
this is the default, so no actions are necessary within the template interface. The
link is simply /myapp/BrowseProductsList.asp. Note: Microsoft Internet
Information Server is case insensitive.)
•
Browse (with a range select on one field): in the ASP extension template for
this procedure, locate the Product Name column on the Table Data Columns tab.
Press the Properties button. On the Column Header tab, check the box labeled
“allow calling this procedure with the value passed as a parameter.” You may
then filter by value, simply providing a parameter called ID1, as in
/myapp/BrowseProductsList.asp?ID1=Potatoes. Note that Clarion/ASP
automatically distinguishes between numeric or string parameters in the URL
parameter.
Assume that you wish to see all the product names in category 1. The URL would be
/myapp/BrowseProductsList.asp?ID1=1.
Note that the general http format for passing multiple parameters within a URL is
?parameter1=value&parameter2=value&parameter3=value.
It’s important to note that you may only assign one field per browse table to filter the
browse by ID1 parameter. If you also wish to filter by a single, different field, copy the
procedure, rename the copy, and set the template option for the different field. If you wish
to filter by multiple fields you may filter via a multiple component unique key, if one exists,
or if not, a ?WHR parameter.
To use a ?WHR parameter, the usage is
http://mydomain/myapp/BrowseProductsList.asp?WHR=dbo.products.price > 10. Bear in
mind that this exposes your column names to the end user, who can see it in the address
box of the browser.
•
Query by Form: no parameter is necessary from the calling page. The URL
would be /myapp/UpdateProductsSearch.asp
•
Blank Update Form: no parameter is necessary from the calling page. The URL
would be /myapp/UpdateProductsAdd.asp.
•
Update Form for a Specific Record: simply use the unique ID1 value as a
parameter called “ID1.” Thus, to call an update form for the product named “Ford
Model T Black,” form the URL with /myapp/UpdateProductsEdit.asp?ID1=“Ford
Model T Black.”
51
Link a Browse and Form
Linking to a form from a browse is done automatically when you apply the browse
template (though you must also apply the form template to the form. But if you wish to do
it manually, it requires specifying which column should be the hyperlink.
Remember that unlike a desktop application, the HTML application cannot receive a
double click, or a right click and then a menu option. Therefore, there must be a single
click way to select a record and link to an update form. For each row, you will designate
one column as that link. You can select more than one, but that could be confusing to the
user.
You simply have to decide whether to use the text value for a specific field for that link
(for example, click on a last name to update a personnel record), or to accept the default
graphic link, so that the end user locates a row they desire to edit, they click on the pencil
either at the left or right of that row.
In the Browse Procedure
Providing for a text link requires the following steps.
1.
On the parent browse, be sure the ASP browse extension template has been
applied. Verify that the primary column and the unique key fields have been
selected.
2.
On the Data Columns tab, select the column you wish to make the link and press
the Properties button.
3.
On the Actions Tab in the Data Columns dialog choose Procedure Link in the
Create Column as a Link dropdown list.
4.
Choose the Update procedure in the Procedure to Link dropdown list.
5.
Choose Edit from the Type of Procedure dropdown list.
6.
Save changes and regenerate.
When the end user clicks on a value in the column you selected, an update form will
appear.
In the Form Procedure
To complete the action from the form side, you merely have to verify that the parent
browse was correctly identified, so that when the update action is complete it will return to
the browse.
52
1.
On the update procedure, be sure the ASP form extension template has been
applied. Verify that the primary table and the unique key fields have been
selected.
2.
On the Actions tab, verify that the parent browse procedure from the Parent
Browse dropdown list is correct.
3.
On the Data Access tab, verify that the Primary Table and Unique Key are
correctly identified.
4.
Graphic Link From a Browse to a Form
The following is the default generated by the template; if for some reason you wish to do
it manually, be sure to have a small transparent .GIF file available. A transparent
background provides for flexibility in case you elect to change the table background color.
1.
On the parent browse, be sure the ASP browse extension template has been
applied. Verify that the primary column and the unique ID fields have been
selected.
2.
On the browse procedure’s ASP extension template, open to the Custom
Controls tab. Insert a column, calling it, for example “Edit Record.”
3.
Choose the alignment and location for the picture column. This is a matter of
taste. The placement will be either to the left or the right of the data columns.
4.
Choose Procedure Link in the Create This Column as a Link group box.
5.
Choose Edit from the Type of Procedure dropdown list.
6.
Choose the Update procedure in the Procedure to Link dropdown list.
7.
Press the Image button to select an image to display.
8.
Most likely, to signal a link you’ll choose an external .GIF file. Choose Disk File
from the Populate From dropdown list. (Note that in most cases you will wish to
copy the image either to the project\asp\images directory, or to the /images
directory of your web server).
9.
Use the file selector to choose the image file.
10.
53
Form Without a Browse
The steps to display the form vary according to whether you wish to link to a blank update
form, an update form for a specific record, or a deletion. To link to an update form, it’s
necessary only to supply a unique parameter for the record you want, unless you wish to
add a new record, in which case no parameter is necessary. There is no difference in
calling an update or a delete (the record will be presented to confirm deletion), other than
the name of the form to link to.
54
Examples
•
Update Form for a Specific Record: simply choose the unique identifier and
use a value as a calling parameter named ID. To call an update form, the URL
should be /myapp/myprocedureEdit.asp?ID1=”a unique ID.” Don’t include the
period! The unique ID is the value corresponding to the column which was
identified in the extensions dialog as the unique column. Note: a read-only or
view form is also available which allows the end user to view the data without
allowing for editing. The calling URL is identical except that the page name ends
in “View” instead of “Edit,” as in /myapp/myprocedureView.asp?ID1=”a unique
ID.”
•
Delete Form for a Specific Record: exactly the same as update, except that the
page name will be different. Simply use the field name and value as a calling
parameter. To call an update form, the URL should be
/myapp/myprocedureDel.asp?ID1=”a unique ID.” Don’t include the period!
•
Blank Update Form: no parameter is necessary from the calling page. The URL
would be/myapp/myprocedureAdd.asp.
A Query Page
Clarion developers often use the Browse/Form/Browse paradigm as a convenient way to
allow the end user to type a few keys to locate the record they wish to edit. Providing a
query page for this functionality is often a more useful strategy for Internet applications, in
that it’s not necessary to download a page or table full of records in order to locate a
specific record for editing. By displaying the form, the end user can type in an ID number
or a few letters, view a list of records that match the query, and then choose one for
editing.
The Query by Form will use the same form layout as the update form, except for any
fields you elect not to populate (by checking the Do Not Populate on QBF box on the
form extension). The end user can type in a value or values, and any matching records
will be returned in a browse, through which they can proceed to a view or update form.
Note that in general, the less fields on the query form, the easier it is for the end user to
use the query form. Additionally, this also prevents users from querying unindexed
columns, which otherwise might slow the DBMS.
Note: an unchecked check box instructs the query to test the field for a FALSE value.
Leaving a check box unchecked is not equivalent no choice.
55
To link to the query from an outside page, link to /myapp/myprocedureSearch.asp. No
parameter is necessary.
Browse to Browse
A Browse to Browse navigational link helps you provide a simulation of the parent/child
browse functionality which Clarion so easily supports in desktop applications.
Instead of providing two lists (or selects) in a single window, the child records of which
update to reflect the values dependent on the key record selected in the parent table, in
this case the end user only sees the child browse when they click or link in from a
selected row in the parent table. By segregating the browses into two separate windows,
Clarion/ASP reduces the amount of communications necessary between the server and
the browser.
The end user therefore clicks on a record in the parent table for which they wish to see
the child detail. A new table appears with the child records. A navigational back button in
the child table returns to the original parent browse.
On the parent browse, be sure the ASP browse extension template has been applied.
Verify that the primary column and the unique ID fields have been selected. On the child
browse, be sure that the Data Columns options for the linking field includes the “Range
Limit on this column” option, which is a check box option.
Much like navigating from a browse to an update form, you must decide whether to link
from a graphic, static text, or from a text value within a row of data. A browse to browse
from customers to orders, for example, might simply say “Show Orders,” whether the link
be text, or a button you’ve created as a .GIF displaying that particular text.
56
Using a Graphic to Signal the Link
For a picture link, be sure to have a small .GIF file available. A transparent background
provides for flexibility in case you elect to change the table background color. Then:
1.
On the parent browse procedure’s ASP extension template, select the Custom
Columns tab. Insert a column, calling it, for example “Orders.”
2.
Choose the alignment and placement for the picture column. This is a matter of
taste. The placement will be either to the left or the right of the data.
3.
Choose Procedure Link in the Create This Column as a Link group box.
4.
Choose List from the Type of Procedure dropdown list.
5.
Choose the Browse procedure for the Orders table in the Procedure to Link
dropdown list and set the procedure to type “list.”
6.
Type in the name of the graphic in the Display Image box. Be sure to place the
image in the images directory.
You still need to select an option on the child browse procedure. See “The Child Side,”
below.
Linking from a Column Value
You may also provide a link to a second browse from the values displayed in one of
columns of the table rows.
To make this type of link:
1.
On the parent browse procedure’s ASP extension template, open to the Data
Columns tab. Select the column from which you wish to link and press
Properties.
2.
On the Actions tab, select Procedure Link in the Create this Column as Link
group box. Set the Type of Procedure to List, by choosing from the dropdown list.
3.
Select the name of the child browse procedure to link to from the Procedure to
Link dropdown list and set the procedure to type “list.”
You still need to select an option on the child browse procedure. See “The Child Side,”
below. Note also that you can provide a link on one column, yet pass data from another
column, even from another table to the target procedure page. For example, you may
wish to pass an employee ID number, yet the end user sees and clicks on only the
employee’s name (which indeed may come from another table in a normalized
database).
57
You could also specify that the link provide the value clicked on as a parameter to the
target browse, so that it may then range select on the value. For example, in a browse
upon a product table, a column called Category could link to a browse on the Categories
table, range selected to display all the other products in that particular category.
The Child Side
Finally, you must provide for the target (or child) browse to be ready to receive a filter.
Open the ASP extension template on the child browse procedure, and:
1.
Select the Data Columns tab.
2.
Select the data column for the filter field, and press properties.
3.
Choose the General tab in the Data Columns dialog.
4.
Check the “Range Limit on This Column.”
When all done, you must regenerate the ASP code.
Select Browses
Wherever you populate a field in a form for which you’ve placed the “Must be in Table”
option on the child table in the Clarion dictionary a button leading to a select browse will
be populated. A popup list appears when the end user presses the button, and when the
end user chooses a value, the popup will disappear and the value will be returned to the
entry box.
58
Note that you may provide for a custom graphic for the lookup button should you wish.
To enable the Select Browse procedure, you must manually choose the proper select
browse for all the “Must be in Table” columns which appear in the update form; the
procedures dropdown list will default to the first browse in the application tree. If you
forget to make a choice, it is likely that the lookup button will display an entirely different
browse in the popup, one which moreover contains no “clickable” fields from which to
choose a value.
You must also apply the browse extension template to the Select Browse procedure in
order for Clarion/ASP to generate an ASP page for the select browse. When applying,
you will then specify which value(s) to return to the calling form, and which display field
the end user will click on to indicate a choice.
Table Loaded Selects on Forms
When an RI rule specifies that a value in a given field must reside in a related table,
Clarion/ASP can automatically generate a dropdown list of those values for your update
forms. In the illustration below, from the Northwind sample database, an update form for
the products table fills dropdown lists from the suppliers and categories tables; the
dropdown is open on the categories list:
59
Experienced Clarion developers will immediately recognize this functionality from the File
Drop Control Template. You may also specify one column for display, and another to
provide the value to be written to the database. This is useful to display, for example,
“XYZ Corporation” in the list that the end user sees, while writing “12345,” the company
ID number for “XYZ” to the normalized database.
The developer need only specify in the dictionary the “Must be in Table” option on the
child table, and then must populate either a FileDrop or FileDropCombo control template
in the window.
In some cases it may be necessary to check the SQL statement generated for the select
control, which is what a listbox is called in the HTML specification.
How to Prime a Field on an Update Form
Should you wish to prime a field for an add form, use the "additional parameter" box in
the Controls dialog. Note that this is very slightly tricky should you wish to use a function
to pass a value.
The add form expects URL parameters in the form of ?controlname=value. The controls
are all named in the format txtTableNameFieldName. The txt simply stands for text, as in
a text control.
Assume that you wish to call an add form for the Categories table, and prime the
CategoryID field with the value "13." Simply enter txtCategoriesCategoryID=13 in the
additional parameter box when declaring the procedure link.
You can also specify a dynamic value. This is the only way to prime a field for an add
form. You must concatenate a string with the control name plus a VBScript function to get
the value from the record set, and then a trailing unbalanced double quote, to make up
for the first string that you "closed" with a double quote earlier.
60
Assume that you're in an order record, and you wish to pre-fill a new order details record
with the OrderID. Set the appropriate target procedure (probably UpdateOrder_Details),
set it to pass static text, leave the static text box blank, and enter the following in the
additional parameters box:
&txtOrder_DetailsOrderID=" & MID(TRIM(oRSOrders("OrderID")),1,50) & "
In the above example, txtOrder_DetailsOrderID is the control name. The MID/TRIM
functions screen any NULL values, and the oRSOrders is the name of the record set
(oRS, plus the table name). Then the trailing double quote is appended.
61
Help and Popup Windows
Help authoring may be done via generated help file shells which include a “place your
text here” area in which you may include your help text. You may use Notepad or an
HTML editor. Be sure to turn off HTML help generation in the Clarion/ASP template after
customizing! You may also use an HTML authoring tool, or Microsoft Word. In general,
however, creating help files is not within the scope of this manual.
Within each of the procedures which you’ve Clarion/ASP enabled, on the Page tab, you’ll
find a Help URL box. Normally, the simplest way to provide help is to create a separate
HTML document containing the help text for each procedure. Simply place the name of
the help file in the Help URL box. Should you place the help file in a separate directory,
use the relative path with slash delimiters. If your help is in a subdirectory below your asp
directory called help, the help URL’s should be in the format “help/helpfilename.htm.”
Note that for a small ASP application, you may wish to store all the help in one HTML file.
You may then use anchors (e.g., http://www.mydomain.tld/myhelppage.htm#myanchor)
to load the help page and jump to the section containing the appropriate help topic. Your
HTML editor should allow you to insert anchor tags.
Dynamic Runtime Templates
Clarion/ASP, by virtue of its use of runtime HTML templates, offers you the ability to
present a radically different layout at runtime depending on the value of a runtime
variable, just by changing the underlying runtime template. You can use this ability to
change the color scheme, the positioning of the data, whether to show all the data or
some of the data, whether to make some data “editable” and other read only... and so on.
You can base which template to use on any variable/value you wish. You may, for
example, base the choice on a security access level variable (as in displaying all fields of
a table for a supervisor, and only some fields to an ordinary user, or to display edit boxes
for a supervisor and read only text to an end user). In these cases, you simply make a
copy of the default template, and delete edit fields, and optionally place @symbols@ for
the data you prefer to display as text.
Or you may get a user preference stored in a cookie, for example. To change only the
colors you may simply make a copy of a template, change the one line referencing the
style sheet to reference a different style sheet, and then “call” the second template
instead of the first.
The alternate runtime HTML template files should be stored in the asp\html directory,
alongside the generated runtime HTML templates. It’s your responsibility to create the
alternate HTML files for the alternate runtime templates. The application generator will
have no knowledge of these alternates; if you start with a generated runtime template,
change the fields and regenerate, you’ll need to edit any previously made copies of that
should you wish to propagate the changes.
62
You’ll “indicate” which template to call either by passing an alternate file name for the
template as a URL parameter, or by placing vbscript embed code in a procedure which
tests for a condition and assigns the desired template file name to a specific variable.
The URL parameter is called ?HTMLT. The template variable is called HTML_Template,
and is actually a variable declared in appdata.asp whose scope is limited to each
separate .asp page.
The following provides for examples of this functionality.
Example 1: Different Color Scheme Based On a Cookie
Assume two style sheets: styles1.css and styles2.css. Styles1 provides for standard
colors and Styles2 provides for pastel colors and a different font. Styles1 is set as the
style sheet in the global template option. This then, would be the default.
Assume that the site cookie has already been created by some other page, and that a
value exists called MyColorChoice. Assume that value is always 1 for Styles1 or 2 for
Styles2. You’ll want to read that value as soon as the end user accesses the application,
and store it in a session variable. Step one is to set a user defined variable in the global
extension. That will take care of declaring the session variable. For the purpose of this
example, we’ll name the variable ud_MyColorChoice.
Next you’ll need to get the value from the cookie. The logical point at which to get this is
in login.asp, because that is called by every single page; this way the application sets the
color choice before the end user sees any pages. the place within the login code to place
this is easy to locate. Search for the text “we have a record and all is good” comment.
The next several lines store the various session variables used to keep track of the user.
You must insert whatever code you wish to insert BEFORE the line containing: else
‘password is incorrect.
The ASP statement for retrieving the cookie is Request.Cookies. Inserting the following
line of code will get the value and store it in the session variable:
Session("ud_MyColorChoice") = Request.Cookies(“MyColorChoice”)
Now, once the end user is logged on, you’ll always have the color choice value stored in
the session variable.
Now the logic to set the alternate template must be inserted into every procedure.
Remember that each procedure has its own runtime HTML template file, and that they all
have different names.
For this example, we’ll use a procedure called UpdateCustomers. The default template
for the edit form would be called UpdateCustomersEdit.htm. We’ll say that a value of 1 in
the cookie/session variable means that the end user wants to use this template. The
value of 2 should call a separate template, which had previously been copied from the
first, and then modified. We’ll call the second template UpdateCustomersEdit2.htm.
63
To modify the edit procedure to call that template, you’ll need to place the following lines
in the Clarion/ASP > Edit Mode > Builder Page > Before Merge Call embed point in the
UpdateCustomers procedure:
IF Session(“ud_MyColorChoice”) = “2” Then
HTML_Template = “html/UpdateCustomersEdit2.htm”
End If
The “trick” here is that the very next line, generated by the template, is:
CALL MergeTemplate(HTML_Template)
Therefore, the page will appear with the second template if the cookie stored a value of 2,
and with the first (default) template, if 1.
Example 2: Different Template Based On Access Level
Note: this example is more easily followed if you’ve already read example 1.
The login code already reads the access level from the security table upon login. It
automatically stores this in a session variable called “UserLevel.”
For this example, we’ll assume that the same form we used as an illustration above
(UpdateCustomersEdit) has three different three different HTML runtime templates; one
for end users, one for “workers” and one for supervisors. Workers will have an access
level set between 50 and 75, and the runtime template will be named
“UpdateCustomersEdit_worker.htm.” Supervisors will have an acess level set at 76 or
higher, and the runtime template will be named “UpdateCustomersEdit_supervisor.htm.”
Assume that end users simply use the default template, and always have an access level
set below 50.
You may “imagine” that the end user template provides two enabled edit controls and
eight disabled fields, the worker template eight enabled edit controls and two text fields,
and the supervisor template, ten enabled fields. In this case the easiest way to set up the
templates would be to rename the default template to the supervisor template, make a
copy, change two fields and save it to the worker template, then change the other six
fields, and save it to the original default template file name. The actual HTML change
involved would be to add the DISABLED attribute (no quotes) at the end of the <input>
tag (just before the closing bracket). Note that DISABLED is not universally supported by
all browsers, but is supported by current versions of Internet Explorer and Mozilla.
The only “trick” in this example is converting the string value stored in the session
variable for the access level to an integer, so you can use mathematical operators to test
the value. For that, you simply use the CINT (convert to integer) function. There would
only be one embed to deal with, since the “UserLevel” session variable was already set in
login.asp.
64
To modify the edit procedure to call that template, you’ll need to place the following lines
in the Clarion/ASP > Edit Mode > Builder Page > Before Merge Call embed point in the
UpdateCustomers procedure:
IF CINT(Session(“UserLevel”)) > 49 And CINT(Session(“UserLevel”)) < 76
Then
HTML_Template = “html/UpdateCustomersEdit_worker.htm”
ELSEIF IF CINT(Session(“UserLevel”)) > 75 Then
HTML_Template = “html/UpdateCustomersEdit_supervisor.htm”
End If
65
Testing How-To’s
Testing on Your Local Machine
If you have not already done so, you should install and test that Internet Information
Server is running correctly on your local machine. You’ll find instructions that will help you
with this task in the section of this manual called “IIS Setup.”
Following IIS setup, the next step is to create a virtual directory for the project/asp
directory. When you generated a Clarion/ASP application, it automatically creates an asp
subdirectory beneath your Clarion project directory. By creating a virtual directory, you
save yourself the trouble of creating a directory under the local web root and copying
your files there.
Internet Services Options
To allow the web server to “serve” your application, you’ll take the following actions:
You must set three items pertaining to permissions using either the Internet Services
Manager or the Microsoft Management Console, depending on which version of Windows
you’re running.
1.
Open up whichever of the above tools is applicable to your operating system.
(Windows NT: Start > Programs > Administrative Tools > Internet Services
Manager; Windows 2000/XP: Start > Settings > Control Panel > Administrative
Tools > Internet Information Services).
2.
In the left hand pane, locate an icon called “default web site” and expand it (the
node order should be something like: Internet Information Services > your
computer name > Web Sites > Default Web Site).
Your application directory is probably not already listed, assuming that you haven’t
changed the default root directory. If you’re already an IIS expert, and it doesn’t affect
any other web development work, feel free to change your web root to whatever directory
you normally place your Clarion projects under. In the majority of cases, however, that
won’t be the case, so follow these additional steps:
2a.
Right-click the default web site and choose New > Virtual Directory.
2b.
The wizard requires only two prompts: a name for the virtual directory (which will
be off the site root), and the physical location of the directory (which you may
choose from a directory chooser dialog).
66
2c.
Navigate to your project directory. Assuming that you’ve already generated your
project once with the ASP templates enabled, you’ll find an asp directory
immediately under your project directory. Select the ASP directory. (If you have
not yet generated, you can create a new directory called ASP under the project
directory, and then choose it).
Resuming the tasks to set the permissions:
3.
Locate your application directory underneath the web site root, right click it and
choose Properties.
4.
Set the Execute Permissions to Scripts Only.
67
5.
Flip to the Directory Security tab and press the “Anonymous Access and
Authentication Control” button.
6.
Turn Anonymous Access on if not already on (top checkbox), and Windows
Authentication off if not already off.
6a.
If you’re running on Windows XP with recent security patches, you must now
take one additional step. Click on the Default Web Site directory in the left hand
pane. Locate a file called localstart.asp in the right hand pane and right click on
it. Choose properties. Select the Directory Security tab and press the
“Anonymous Access and Authentication Control” button. Turn Anonymous
Access back off for this one file.
68
7.
Close the two open dialog boxes, click on the web site root icon, and press the
stop, and then the start buttons on the tool bar, thus stopping and restarting the
web server to apply your changes.
Internet Information Server should now be configured correctly. Open your browser and
type http://localhost in the address box. You should see a default web page.
Important: Windows XP users should see the window illustrated below. If not, check the
security permissions described in the IIS Setup section.
69
The /Images Virtual Directory
Many sites store images to be used throughout the site in a single directory off the root,
usually called /images. This saves disk space because the image files need not be
repeated throughout. The Clarion/ASP button images are a good candidate for storing in
a central location because they are repeated from application to application.
The install program copies the images to a default directory called
\CLARION6\images\asp (assuming your root is Clarion6, your name may vary). This
section instructs you to create a virtual directory called images, pointing to that directory.
If you already have a /images virtual directory on your “localhost” site, you may simply
copy the images to it and skip over the following instructions:
1.
Open up whichever of the IIS administrative tools is applicable to your operating
system. (Windows NT: Start > Programs > Administrative Tools > Internet
Services Manager; Windows 2000/XP: Start > Settings > Control Panel >
Administrative Tools > Internet Information Services).
2.
In the left hand pane, locate an icon called “default web site” and expand it (the
node order should be something like: Internet Information Services > your
computer name > Web Sites > Default Web Site).
3.
Right-click the default web site and choose New > Virtual Directory.
70
4.
Press the Next button, and when prompted, name for the virtual directory
“images.”
5.
Press the Next button, and when prompted, navigate to your the
\CLARION6\images\asp directory by pressing the Browse button. (or to whatever
the relative path should be if you installed Clarion to a directory other than
\CLARION6.
When ready to deploy, don’t forget to copy the images from the \CLARION6\images\asp
directory to your server’s virtual /images directory.
Note: the Clarion/ASP install provides for a default set of blue buttons (enabled), all 20
pixels by 20 pixels. Disabled state is grayscale images (of the same buttons). Below the
images directory, you'll find alternate button sets in green and brown. Since the blue
buttons are repeated in a subdirectory, should you wish to experiment, you can simply
copy over one set of buttons with another.
GLOBAL.ASA
You may be required to create a new Global.ASA file in the web root directory, or cut and
paste lines from the one that Clarion/ASP generate for you in your application\asp
directory into your existing one.
This will depend on whether your application’s application\asp directory is a virtual
directory, or if it is physically located below the web root directory. If it is a virtual
directory, skip this section entirely. If it physically resides below the web root, then you
must follow these instructions.
The GLOBAL.ASA file stores application settings (data variables) for ASP. Items in the
file are read one time only: whenever someone starts the very first instance of an ASP
application. (Note: if you shut down and restart the web server, it has to be read again).
The GLOBAL.ASA file can hold function code, code to execute at specific events and
data declarations. Clarion/ASP uses GLOBAL.ASA only to store data declarations.
The GLOBAL.ASA is stored in the root web directory if the IIS Server is hosting only one
site. This will almost certainly be the case for your development machine. IIS, however,
can support multiple “webs” on the same machine (using multiple IP addresses/NIC
cards), in which case the GLOBAL.ASA should be located in the application root
directory.
71
In either case, you must paste six lines (not counting the comment) into your web’s
GLOBAL.ASA file to support your application. Clarion/ASP creates the file and stores the
following GLOBAL.ASA data in your project\asp directory:
''--Project Data Connection
Application("YourAppName") = "DSN=YourDSNName; USER
ID1=YourUserName; PASSWORD=YourPassword; SERVER=YourServer;
DATABASE=YourDatabase; ADDRESS="
Application("YourAppName_ConnectionTimeOut") = 15
Application("YourAppName_CommandTimeOut") = 30
Application("YourAppName_CursorLocation") = 3
The name of each variable is the string in the Application() method. As you can see,
Clarion/ASP stores the ConnectionString, connection timeout, command timeout, cursor
location, runtime user ID and password. Each is prefixed by the name of your application,
to minimize the chance of name clashes with other ASP applications. The first line,
starting with the two single quotes, is a comment.
Note that recent versions of Internet Services manager allow you to right click on the
Global.ASA file, then specify that you wish to open it in Notepad. Otherwise, locate your
root web folder (if you’re not sure of the location, right click the default web root in the
Internet Services Manager, choose properties, and find the true name of the root
directory). Open the GLOBAL.ASA file in notepad, and paste the lines from the file in
your project/asp directory into it, then save the file.
Be sure that the GLOBAL.ASA information is also correctly transferred to the server
when transferring your .ASP and other resource files. If when testing an application for
the first time (if you haven’t tested the test page), your browser simply times out without
providing a login, the first item to check is that the GLOBAL.ASA exists and is in the
correct place.
Note that should the application time out the very first time that you test it, the first thing
to consider is whether you forgot to paste the application’s data into the proper
GLOBAL.ASA file. This is quite common. Unfortunately, there’s no way in which
Clarion/ASP can provide a routine to display an error message: in this situation, the
Clarion/ASP application never starts.
72
Loading the Test/Debug Page
To test begin testing Clarion/ASP, open the URL
http://localhost/yourvirtualdirectorypath/index.htm. Index.htm is the default “start page”
that Clarion/ASP creates for your ASP procedure pages. The default start page is a very
simple list of page names and links, which you’ll no doubt replace when you’re ready for
deployment. (Note: this assumes you’ve already generated the ASP pages after applying
the ASP template to your project. If not, you’ll receive a “page not found” message).
If it did not open a page, then the web server is not working, or you have additional file
security implemented. (Note: there may be some developers who have disallowed the
“everyone” group from the directories in which they work. If it is a file security problem on
the workstation, open the Security tab for the directory in Explorer. You must have read
and write permissions either for the “everyone” group, or the Internet user account, called
IUSR_yourmachinename).
Before clicking any of the procedure links on this page, please run the test/debug page.
This will be the very first link at the top of the index page. This page opens the ADO
connection used by your application, iterates through the tables, displays the ADO
provider and its cursor support, and tests that ASP can correctly access the file system
so that it can output pages via the runtime HTML templates. Any time you create a new
application and testing on a local machine, you should test this page first.
When you deploy to the server, you should not copy this page there. Never leave this
page on a public server; it displays the DBMS server name, address, user ID and
password. If you absolutely must copy it, delete it immediately when you’ve finisted
testing.
When testing locally for the first time, load the page, choose Edit > Find from your
browser menu, and verify that each step detailed in the document succeeded. If any step
failed, the document tells you the most probably causes. In general
•
Any problems documented in the first section indicate a problem with Global.asa.
•
Any problems documented in the last section indicate a security settings issue.
•
Any problems documented in the middle indicate a database connection
problem.
73
Application Timeouts
This section is optional, and is placed here because it is managed through the Internet
Services Manager.
While developing, it’s useful to set application timeouts to a low value. In case of ADO
errors, the web server waits for a communication from the OLE DB provider for as long
as the timeout period. A useful value for script error timeouts is fifteen seconds when
testing with a localhost server.
Additionally, should you be testing procedure with security enabled, it’s also useful to set
the session timeout to a low value. With a large value, for example, twenty minutes, a
developer may frequently test, change, and test again within that period. When the
developer tests the application the second time, the login routine will find the user ID from
the previous session still exists, and not request a login.
To set the script and session timeouts, right click the Default Web Site icon in the Internet
Services Manager and choose Properties. Locate the “Configuration” button on the
“Home Directory” tab, press it, and configure the timeouts on the “Options” tab of the
“Application Configuration” dialog.
As a final note regarding testing on your local machine, we must note that IIS provides
limited ability to override its cache settings. The “Options” tab noted above provides a
checkbox for buffering. In general, should you suspect that the changes you make to the
application are not properly being served to the browser client, you may opt to restart IIS;
74
though often, closing Internet Explorer and reopening solves caching problems. Another
alternative, which works every time, but requires you to manually edit the address line of
the URL is to temporarily rename the file you’re testing!
ftp Setup
This section is optional, and is placed here because it is managed through the Internet
Services Manager.
You will most likely wish to have an ftp server on the web server to upload your files.
Setting up the production web server is beyond the scope of this document.
We do suggest, in light of the capabilities of site managers such as DreamWeaver to
manage files via ftp that you create a virtual ftp directory for your application directory,
and allow your account (as developer) access to it. It’s quite easy to use a tool like
DreamWeaver to do any additional editing of the .ASP files, adding your local
development directory as a virtual directory to the local site image, allowing you to create
files and upload them to the server smoothly.
75
Integration/Deployment How-To’s
HTML Template
Though it may seem that everything is being called a template, Clarion templates and
HTML templates are different things. This focuses only on the HTML templates. There
are two types. One is a design time template, which is used only at the code generation
step. The other is a run time template, which is used every time an end user requests a
page.
•
Design Time HTML Templates: all the ASP code that Clarion/ASP generates
for data access is a combination of HTML and ASP pages and headers, all
processed by the ASP DLL, and placed in-between the top of a page and the
bottom of a page These “tops,” “bottoms,” and “sides” are your HTML design
time template. You or your web designer will without a doubt wish to create your
own HTML design time template. Because the Clarion/ASP data elements are of
a reasonable size, they should fit well into a site with or without frames.
Clarion/ASP merges the data access elements into the pages it creates at the
time you generate the pages. Therefore, you should plan on copying your HTML
template to your development machine.
This HTML file must reside in a directory called HTML, directly below your application
project directory. You must create the directory and copy the file there. (Note: this is not
to be confused with the project directory\ASP\HTML directory, which is an output
directory).
Use any standard HTML editor to create your template page. At some point within the
page, be it top, middle or bottom, at the place you wish Clarion/ASP to insert the code it
generates (i.e., the place where you want your browses, forms, etc., to appear), place the
text @Clarion/ASP@. (Don’t type the period at the end of the sentence).
76
You must type in the name of your template in the Global Options dialog for the ASP
extension, in the field called HTML Template.
You may use the tops and bottoms to provide a place for company logos, site navigation,
privacy or other important statements, ad banners, or anything else, including links to
various Clarion/ASP generated procedures.
Many sites use HTML includes to create standardized page sections. You may include
these in the HTML template, so that the Clarion/ASP pages will be as easily maintained
as the rest of the site, and will be standardized in look and feel.
•
Run Time HTML Templates: after you’ve chosen your template, when you first
generate your application it produces additional HTML files for your other
procedures. These are also editable. In essence, these runtime templates are the
setting for the individual data fields and prompts. Each data field, prompt, or
element such as the navigation buttons has a symbol which appears in the
runtime template.
When the end user requests a page, the asp code resolves the request for the data, gets
the data, opens the runtime HTML template, replaces each symbol with the appropriate
prompt or data, and that page is then delivered to the end user.
In the browse procedures, for example, you will find tokens in the format
@TablenameFieldname@ occupying the table. Each token stands for the data which will
replace the token. Should you wish to modify the layout, you may modify the html page.
You may not add or remove tokens.
77
This therefore means that you may further customize the layouts at this level as well.
Bear in mind that these HTM files are regenerated. Turn off HTML generation at the
procedure level should you wish to make changes and keep them, or set the file to read
only.
78
Style Sheets
HTML style sheets, known as cascading style sheets (because one style may cascade its
characteristics into another, and so forth), play a large role in many sites, and a large role
in the Clarion/ASP pages.
The style sheets declare classes, which consist solely of formatting instructions. You can
then apply the style to a tag (be it a paragraph, cell in a table, a table, etc.), and that
element will then be formatted according to the instructions in the style sheet. This allows
any site to greatly change its look simply by substituting a new style sheet for an old one.
Clarion/ASP allows you to define styles for elements such as table column headers,
update form control labels (prompts), data rows, etc. When you create the style sheet,
you may wish to set their options so that they mimic the color, font, and formatting
choices of your site. Should your site subsequently modify its style sheet, simply update
your Clarion/ASP style sheet to match.
79
You’ll find more information on Clarion/ASP’s use of style sheets in the chapter devoted
to the style sheet editor. Note also that web designers may edit the style sheets using
appropriate utilities or a text editor.
Collected Data from Forms on Your Site
It may be that other parts of your site already have forms which gather important data
such as names, customer ID’s, product ID’s etc. If, for example, you already have a first
name, last name and email address, and you wish to allow the end user to create a new
customer record without having to re-type that information, you’ll want to display a blank
update form with those three fields pre-filled in.
To do so, your web administrator will need to post the data as URL parameters to the
form fields on your Clarion/ASP update form. In order to do that, the web administrator
will need to know how the form fields on the Clarion/ASP update form are named (their
ID’s).
If in doubt, it’s a simple matter to look at the html code. The formula for each form field
name is txt + Table Name + Field Name. If the table is called Customers, then the form
control names for the fields FirstName, LastName and CustomerNumber would be
txtCustomersFirstName, txtCustomersLastName, and txtCustomersCustomerNumber,
respectively, for a form using edit boxes. Then the other form simply provides a url such
as http://domain/updateform.htm?txtMyTableUserName=abcd &txtMyTableUserID=1234.
This manual assumes that if your existing web already uses HTML forms the web
administrator is familiar with working with forms, naming the fields and forming the link
properly.
Passing Data to Other Parts of Your Web
In cooperation with your web administrator, you may optionally edit the generated
Clarion/ASP files. Each .asp file includes a form declaration. The form tag includes a
“target” which is the next page the end user “goes to” after pressing the Submit button.
This page also receives the POST data, i.e., what the end user filled out in the form on
the previous page.
it’s a simple matter to change the form tag so that the action “targets” an existing or new
page in your site. Thus, a line taken from one of the pages generated by Clarion/ASP
below:
FormDeclaration = "<form name='form1' id='form1' method='POST'
action='BrowseviewContactsList.Asp'>"
In this case the “action” points to the next page that should appear after submitting the
form. Simply change the file name in the action tab to a different page in order to post the
form data to that page and display it to the end user.
80
In the above example, changing the action page is as simple as:
FormDeclaration = "<form name='form1' id='form1' method='POST'
action='/mysite/otherpage.asp'>"
(Note that the ASP page will be regenerated the next time you generate the project!
When you must edit the .ASP page, set the file property to Read Only using Explorer).
The “otherpage.asp” may then process the posted data, though the developer must
inform the web administrator of the names of the form fields. The formula for each form
field name is the “txt” + TableName + Field Name. If the table name is called Customers,
then the field names for the fields FirstName, LastName and CustomerNumber would be
txtCustomersFirstName, txtCustomersLastName, and txtCustomersCustomerNumber,
respectively. By referring to the Clarion/ASP produced HTML equivalent of the ASP page
(in the html directory below the ASP page), the web developer may easily view all the
form field names.
CLARION/ASP Integrating with Your Site
Ch. 6:
81
Integrating with Your Site
It’s anticipated that most developers will use Clarion/ASP to produce a small number of
data access enabled web pages to fit into existing sites. For these developers, the
following steps will be necessary:
•
Manage the look and feel so that the Clarion/ASP pages fit perfectly into the site,
and may be easily maintained so that overall site updates will not leave them
behind.
•
Correctly integrate links to and from various site pages and other applications
(insofar as these are consistent with the rest of the site).
•
Test that at an operating system level, the files (ftp uploads, access to the
database, directory names, securities and permissions) are correct.
•
Verify that the server resources are adequate for the application.
•
Verify that security is adequate.
Links
Links are the conduits through which one page leads to another on the Internet. There is
no program flow like a desktop application.
An important concept for database developers to grasp about ASP is that, like web
pages, the browser and web server do not maintain a continuous connection (it’s
stateless). Further, the web server and the database do not maintain a continuous
connection per each user.
For this reason, the links on the index.htm page generated by Clarion/ASP can be used
from anywhere within the site, or from anywhere within the Clarion/ASP pages. The only
limitation is a logical one: if you wish to display a form containing only one record, or
display a filtered browse, you must supply a way to identify the record(s) within the link.
You can do this as a simple HTML parameter. The parameter will always be called “ID1”
(plus “ID2” if a multi component key). The field it refers to will be the unique ID field which
you defined for the procedure extension.
Note that though the index.htm page generated by Clarion/ASP is not meant to be a table
of contents for end users (it’s intentionally kept very plain), it does provide a handy
reference to the page names you may wish to link to from other parts of the web. Its
primary purpose is to provide the developer with a quick and dirty means of testing the
Clarion/ASP generated pages.
82
Persistence of Data
It’s important to understand that each time a Clarion/ASP page makes a request to the
database for data, ASP creates a new connection object, gets the data, and closes the
connection object. Note: it does not necessarily open a new ODBC connection to the
database per each user, depending on the ODBC driver. Using a single logon to the
database is known as connection pooling.
The only persistent data lingering from page to page are the application data and session
variables, which solely reside on the web server. This is limited to a unique ID maintained
by IIS for each user’s session, plus the session variables that Clarion/ASP declares.
When, for example, a user opens a browse, ASP creates a connection object, queries the
database, receives a result set, sends some number of rows to the end user, and closes
the connection object. Additionally, IIS may hold the result set until the next request or a
time out.
Therefore, if you’re a developer thinking about program flow, and worried that you’re
leaving an open application behind if you jump from a browse to a completely different
browse: there’s no need to worry. In fact, even if the user jumps from a browse to a
completely different part of the site and never goes back to the application, all that
happens is that the session will eventually time out. Leaving an application open does not
waste a large amount of resources: at worst, it requires a few session variables and
perhaps a cached result set on the web server. Note also that you have control of the
timeout value.
Here are the main points to understand so that you can link into any part of the
Clarion/ASP pages from inside or outside the pages:
Page Naming Conventions
•
Browse: clarionbrowseprocedurenameList.asp
•
Update Form: clarionupdateprocedurenameEdit.asp
•
Blank Update Form: clarionupdateprocedurenameAdd.asp
•
Read Only Update (View) form: clarionupdateprocedurenameView.asp
•
Delete Confirmation Form: clarionupdateprocedurenameDel.asp
•
Query Form: clarionupdateprocedurenameSearch.asp
•
Processor Pages: (contain the asp code for database access) same names as
above, ending in X.asp.
CLARION/ASP Integrating with Your Site
•
83
HTM Pages: (contain the elements in which the asp pages place their data; you
may change some layout characteristics by editing these pages, but not all)
same names as above, ending in .htm.
Linking Conventions
Reminder: to pass a parameter via URL append ?ID1=value to the URL, where the value
is the value of the unique ID column.
In the examples below, we’re assuming links relative to the root of your site. Note that
“link text” is the text that the end user sees and clicks on to arrive at the page.
•
Browse, no filter: URL only, such as:
<A href="/path/clarionbrowseprocedurenameList.asp">link text</A>
•
Browse, filtered: URL plus unique field value as parameter, such as:
<A href="/path/clarionbrowseprocedurenameList.asp?ID1=1093">link text</A>
•
Query form: URL only, such as:
<A href="/path/clarionupdateprocedurenameSearch.asp">link text</A>
•
Update form, new blank record: URL only, such as:
<A href="/path/clarionupdateprocedurenameAdd.asp">link text</A>
•
Update form, update a specific record: URL plus unique field value as parameter,
such as:
<A href="/path/clarionupdateprocedurenameAdd.asp?ID1=1093">link text</A>
•
Update form, delete a specific record: URL plus unique field value as parameter,
such as:
<A href="/path/clarionupdateprocedurenameDel.asp?ID1=1093">link text</A>
•
Update form, view a specific record: URL plus unique field value as parameter,
such as:
<A href="/path/clarionupdateprocedurenameView.asp?ID1=1093">link text</A>
84
Site Standard Page Format
If you already use a standard HTML template (in the sense of a template used by layout
tools such as Dreamweaver, in which application specific tags specify to the layout editor
what parts of the page are to be “editable,” you will have no problem adapting these
templates.
In general, such templates provide the “top,” “bottom,” and “sides” of the page, and the
layout tool then allows you to (essentially) “fill in the blanks” with the text and images
specific to that page.
In Clarion/ASP, we call this a design time template. All that you need do is open the
template, insert the symbol @Clarion/ASP@ in the spot where the template normally
places the “fill in” text, and save an HTML file to the project\HTML directory. Then in the
Global Extensions, declare the page as your design time template.
At generation time, all Clarion/ASP generated elements will appear in the place in which
you put the symbol.
With apologies to the very popular site whose page was “borrowed” for the example
below, this represents what happens when you take an existing page and place the
@Clarion/ASP@ symbol inside it. Note that the colors in the style sheet were designed to
mimic those in another table found at the site:
CLARION/ASP ASP Template Reference
85
Ch. 7: ASP Template Reference
ASP Global Template Options
The template options in the global extension dialog allow you to define the look and feel
of all the pages generated for your procedures and to define the location, access method,
and security of the database.
Fill in the template prompts on each of the tabs in the global template dialog.
Global Options/Global Tab
The global tab allows you to set the look and feel for the generated pages, using HTML
templates and style sheets. It provides access to dialogs that allow you to customize all
the prompts and messages (except for the help text pages, which you must write
separately, of course). It also allows you to specify debug mode.
Because all the messages are set in the template, it makes it simple for you to customize
your applications for specific languages.
You may override your global options at the procedure level. Note that when you check
the option to override in a procedure, should you change a global option afterwards, the
global change will not affect any of the options in the changed procedure.
86
Target Language
All default Clarion/ASP help and prompt messages (not including the prompts in your
dictionary and application files, of course) are provided in English, Spanish and French.
Typically, these messages are basic instructions, such as “Add a record.” You may
override all these messages at the procedure level.
To choose a set of prompts, select “English,” “French,” or Spanish from this dropdown
list.
If you wish to customize the default prompts, edit the .TRN files in the Clarion template
directory. Each of the files is named ASP_LG??.TRN, where ?? is a two letter
abbreviation for a language. “EN” = English, “FR” = French, “NL” = Dutch, “DE” =
German, and “SP” = Spanish. The format is template symbol=text. Note that no % sign
precedes the template symbol, that no space should exist on either side of the = sign,
and the text string is unquoted.
Show Help Button
Providing a help link specifies that individual pages should display a hypertext link to a
help page. You must, of course, indicate the help page address in the individual pages’
template options should you elect not to use the auto-generated names.
87
Tooltips
Clarion/ASP generates ALT text for its button images, which are displayed as tool tips in
Internet Explorer (ALT text only displays in other browser if the image is missing). You
may enter the following tooltips:
•
Help Link: default text is “Help.”
•
Back Button: default text is “Back.”
Global Options/Cascading Style Sheets
These buttons allow you to create the cascading style sheets for use in the web pages
created for your procedures. You can specify separate style sheets for each type of page:
global, list, form, and help. Note that the global choice applies to any pages such as the
index, message pages, etc., not in the category of the other four.
An HTML style sheet is not unlike a word processor style sheet: it contains style names,
each of which contain information about the font face, size, weight and color. By storing
this information in a single file, and then indicating the style for a given paragraph inside
all the documents at the site, the administrator gains the ability to change a style sheet
and change the look of all the text within the site.
Clarion/ASP makes use of the CSS 1.0 (Cascading Style Sheet, as defined by the W3C)
specification except for one feature: should you elect to specify a local Windows color
setting (e.g., desktop background) for an item, that is a CSS 2.0 feature, and requires 5.x
browsers and higher.
Please see the following chapter, “Style Sheet Editor” for instructions on customizing your
style sheet.
HTML Design Time Templates
All the data controls generated by Clarion/ASP will appear within a page you specify. This
is convenient, for example, for placing a navigation bar at top, and other elements below.
The Clarion/ASP elements are not limited to the top or bottom. This HTML file must
reside in a directory called HTML, directly below your application project directory.
You should think of Clarion/ASP as responsible for generating only the data elements
and/or data access related messages, and your HTML design time template to provide a
setting in which these elements appear.
Use any standard HTML editor to create your template page(s). At some point within the
page, be it top, middle or bottom, at the place you wish Clarion/ASP to insert the code it
generates (i.e., the place where you want your browses, forms, etc., to appear), place the
text @Clarion/ASP@. (Don’t type the period at the end of the sentence).
88
You may use different templates for different types of procedures: list (browse), form
(update), global (all others). Press the button and enter the file name for your template(s).
You may specify separate templates for browse lists, select browse lists, forms, and all
others (help, index page, any choices not filled in). Note that you may override the default
template at the procedure level.
List Defaults
The list defaults set the global options for the amount of rows to show in the list boxes,
whether to place a navigation bar in the list, navigation bar options, and tool tips related
to list boxes. Press the button to display the dialog, and enter your preferences in the
dialog.
Data Records per HTML List
The value you specify for Data Records per HTML List sets the maximum number of
rows which you wish to appear within the HTML tables which will represent your browse
boxes. The default is 16.
Pad Table with Blank Rows
Clarion/ASP’s default behavior is to provide a standard number of rows per browse page.
If the last page does not contain the maximum number of records (for example, for a
browse procedure on a table with 93 records, presenting ten records per page, the last
page would have three records), then the page presents the extra rows, but fills the rows
with spaces. The result is that the page elements below the browse don’t appear to “jump
up” the page, because the “length” of the browse table is still the same. Should you wish
to disable this behavior, check this box.
Automatically Create Detail Link
This option automatically adds a graphic at the end of each row of each browse box
providing for a link to an update form for that row. When checked, you may specify that
the update be either view only (View) or edit. You may also specify a custom image for
the “button.”
89
Place Database Navigation Bar on List Pages
ASP creates navigation icons similar to the Clarion application toolbars, allowing the end
user to easily view the next page of the browse. You may specify custom images for the
navigation buttons on the Images tab.
Note that the normal mode of operation (see Cursor Location, below) is for the web
server to cache the result set from the database. Therefore, when pressing the
“PageDown” or “PageUp” buttons, no further communication between the web server and
database is necessary; the only communication is with the web server and the web
browser. This provides for a very fast means of browsing the database as perceived by
the end user.
Show Add Button on DB Navigation Bar
Use this checkbox to enable or disable adding records from the browse, and specify the
tool tip text.
Show Query By Form Button on Database Navigation Bar
This provides a fast, efficient means of locating a record in a large database. The end
user merely has to fill in the data to search for in a page arranged in the same layout as
an update form. Note: you’ll specify the query form within each browse properties dialog.
In addition to checking the box, enter the tool tip text for the button.
90
Navigation Button Tool Tips
Clarion/ASP generates ALT text for its button images, which are displayed as tool tips in
Internet Explorer (ALT text only displays in other browser if the image is missing). You
may enter the following tool tips for the navigation buttons:
•
First Page
•
Prior Page
•
Next Page
•
Last Page
•
Add Button
•
Query by Form Button
Note that the browses are page loaded; each page will display as many records as you
set in the Data Records per HTML List box, above.
No Records Found Message
This allows you to specify the message text the end user sees if the user chooses a
browse for which no rows are returned by the database, or queries it but no data
matching the query exists.
Clear Filter Prompt
Should you choose to populate a locator control in your table, this provides the link text
for the end user to clear the filter. The locator acts as a query limiter, tied to a specific
field. When the end user types in a value, it adds a LIKE% clause to the current where
clause. Thus, if the browse is already limited to products in category 13, the locator is on
product name, and the end user type “T” into the locator box, the results returned will be
only those products in category 13 starting with “T.” If the end user wishes to return to the
previous list/query, the end user must click on this link. The default text is “All Data.”
This message also appears following a query submitted via a search form.
91
Form Defaults Button
The form defaults set the text for the tool tips and message text related to forms, plus
allows you to specify whether to allow popup calendar entry for date fields.
Enable Javascript Calendar Popup
This will automatically place an ellipsis button next to all your date fields. When pressed,
the button will display a popup calendar, with which the end user can select a specific
date. The default is checked. Uncheck the box to disable the calendar and choose a
default date format from the dropdown list.
Enable DB Navigation on View Forms
When displaying a view only update form, Clarion/ASP automatically provides “back” and
“forward” buttons to navigate through the table in the key order specified by the parent
browse. When viewing a single record update form, therefore, the user may press a
button to view the next or previous record. This checkbox allows you to disable the
feature.
92
Additionally, you may specify the tool tip for the next and previous buttons by typing it in.
The default text is “Previous Record,” and “Next Record,” respectively. You may also
define a custom message to display when the end user presses the next or previous
button after reaching the last or first rows, respectively.
Required Field Indicator
To indicate a required field, you may optionally include you may optionally place an
asterisk (commonly used) or other character after either the field prompt or the control.
By default, Clarion/ASP provides for an asterisk following the prompt label.
To customize, check or uncheck the “display indicator” checkbox, type in the character in
the “indicator value” box, and choose the “indicator location” using the dropdown list.
Selected Field background
To change the background of any field that currently has focus, check the “Change
Background” box.
Search Mode Select Control Text
If you’ve populated your update form with a list box, that list box appears on the search
form (unless you specify otherwise). When adding a record in which a “Must Be In List”
validity option was checked, the list properly defaults to the first item in the list. But when
displaying a a list within a search form, in order to allow the user to specify no value
(instead of a single value), this text displays a “None” option, i.e., no choice was made for
the query for this field.
This text box sets the text for the list box selection signifying “any value.” The default text
is “None.”
CRLF to HTML
This checkbox allows you to specify that any carriage return/line feed characters found in
a text field in the database should be translated to HTML <br> tags. This therefore allows
you to preserve the line formatting of such fields on your HTML screens. Note this does
not affect how the data is stored in the database, and is only one way, from the database
to the screen.
93
Form Button Text Tab
These allow you to specify text for the form buttons; both for the button text, and for the
tool tip text (using ALT). Enter your preferred text for the Submit, Reset, Delete, and Edit
buttons and their respective tool tips.
Form Button Titles Tab
These allow you to specify text for the page titles (which appear in the caption bar of the
browser). You may specify separate titles for each update mode, i.e., insert, edit, delete,
view and search.
Form Message Text Tab
These boxes allow you to enter custom text that will appear to the end user in a message
page should the condition described in the list below apply:
94
•
Status Text: a label before the text that describes the current process to the end
user (i.e., te word “Status” in “Status: Updating a record”.
•
Record Not Found: a ID field for the form did not match a row in the database.
•
Return to List: a navigational aid.
•
Return to List from Search: a navigational aid.
•
Insert Failed: ADO was unable to add a new record.
•
Insert Succeeded: a new record was added.
•
Update Failed: ADO was unable to edit and save a value in an existing record.
•
Update Succeeded: ADO was able to edit and save a previously existing record..
•
Delete Failed: ADO was unable to delete a record as requested.
•
Delete Succeeded: ADO was able to delete a record as requested.
•
Delete Confirmation: asks the end user if they’re sure they wish to go ahead with
a deletion.
95
Form Validation Text Tab
This tab allows you to specify a short message that will appear in the status bar for any
fields on an update form for which client side validation is set up. You may specify the
text for required, numeric, or in-list validation. The default strings are “Required Field,”
“Numeric Field,” or “Must be in List,” respectively. Should you wish to override the
defaults, we suggest that your replacement message be as short as possible.
Include Defaults Button
This button displays a dialog that allows you to specify a virtual file path for your includes.
There are two methods to include resources, using the “file” and “virtual” keywords. “file”
is the default, but if your ISP requires the “virtual” keyword, you can toggle the setting
here.
Global Options/Generation Tab
The options on the Generation tab allow you to optionally specify and control the
additional non-ASP pages be generated when the Generate All command is executed,
and whether the resulting ASP pages should enable debug mode.
96
Enable Debug Mode
Debug mode specifies that the pages generated should be for debug purposes. Be sure
to choose this option only during development, and to turn it off before deployment due to
the possibility of a security risk because of extra information in the HTML source sent to
the browser.
Note: the debug mode instructs ASP to output a page showing as much of what it’s
instructed to produce as possible, plus important information such as the SQL statement
used to produce the data. Note, however, that if an ASP or ADO error is severe enough
so that no page is generated at all, the debug information will simply not appear. As an
example, if the ADO settings point to a DSN on the server which doesn’t exist, ASP will
simply time out, and no page at all will appear. On the other hand, should you expect a
browse with many, many records, and none appear, the SQL statement produced by the
debug option can be useful.
In debug mode, Clarion/ASP passes all IIS and/or ADO errors through to the page. In
non-debug mode, Clarion/ASP attempts to provide a “friendly” explanation.
In general, the Test/Debug page described in the Testing on Your Local Machine section
is a far more efficient means of testing the critical parts of your ASP application.
Suppress File Generation
The three components besides ASP that are produced by Clarion/ASP are the style
sheet, HTML pages and Help skeleton pages. You may enable or suppress these pages
using these controls.
•
Style Sheet (CSS): suppressing cascading style sheet generation is useful when
using a style sheet created in a previous application, which you manually copied
to your project’s project\asp\styles directory. Note that because the style sheet
options are template symbols stored in the .app file, if you copied a sheet
produced by another project, you will not have access to the settings from that
sheet through the Clarion/ASP style sheet editor. More importantly, you will wish
to turn off style sheet generation so as not to overwrite that style sheet with a
blank one.
•
HTML Pages: each of the .ASP pages that Clarion/ASP produces corresponds
to a procedure. The .ASP pages each require a corresponding .htm page that
provides a “setting” for the controls and data that the .ASP page places there.
The ASP page merges the logic from the .ASP code with the HTML layout placed
in the corresponding .htm page, merges the two of those into the HTML template
(usually providing just a top and bottom part of the page), and finally links the
style sheet to format all the text and input objects througout. You may edit the
.htm pages to custom format or change the layout of control elements. After
editing, suppress HTML Pages generation so that the next time you generate the
project you do not overwrite your customizations.
•
97
Help Pages: Clarion/ASP automatically generates skeleton pages for your help
text. These pages contain formatting according to your style sheet options, and
javascript functions to automatically size the popup windows which appear when
the end user presses the help button. To add your text to the help pages, simply
open a page in Notepad or Wordpad and type your text in the line that says
“Customize your help text here.” For large blocks of text with complicated
formatting and/or illustrations, we recommend loading the skeleton help files into
an HTML editor.
Once you’ve created the help files, suppress help page generation so that the next time
you generate the project you do not overwrite your customizations.
Popup Help Window Size
Clarion/ASP generates help document templates for each procedure and places a help
button in your procedure pages. When the end user presses the help button, the help
window sizes to the values you set in the template interface. Set the Height and Width in
pixels by typing values in these boxes.
Popup Select Window Size
In a select browse procedure, an end user can fill in an entry with a value from a related
table by clicking on a button, viewing the related table (which displays whatever fields the
developer includes, not just the one with the specific value). To fill in a customer ID field,
for example, the end user may (1) click a button, (2) locate a customer by name in a
popup window which then appears, (3) click on the customer name. When the window
closes the customer’s ID appears in the entry box.
The developer may set the Height and Width in pixels of the window which pops up by
typing the values in these boxes.
Global Options/Database Tab
The database tab helps you define the connection settings for the ADO connection from
the web server to the database server. This makes it the equivalent of your global driver
settings.
98
ASP depends on your application providing a connection string in the Global.ASA file for
your application. The connection string simply tells ASP what ODBC driver or OLE DB
provider it must use to access the database, plus any necessary options for that
database.
If using ODBC, it’s highly recommended that you set up an ODBC data source name on
your development machine that matches the data source name you set up on the web
server.
You will use the connection builder to build the connection string. The connection builder
simply runs the data link libraries supplied with either the operating system or your
database client software, depending on your operating system.
Your ASP application will not function if you omit the connection string, runtime user ID,
or password. Without them, the server will not be able to access the DBMS. There is no
means to display a dialog to retrieve the values from the end user at runtime.
To specify these settings, you’ll press the Connection Properties button on the Database
tab of the ASP global options. This will display the Build Connection String dialog, which
provides prompts for the runtime user name, password, and other connection
parameters, plus a button to call the Connection Builder dialogs.
Connection Properties Dialog
This dialog contains the following options:
Connection Timeout
Enter a value (in seconds) for the connection between IIS and the database. This
governs the timeout property for an ADO connection object.
Command Timeout
Enter a value (in seconds) for the connection between IIS and the database. This
governs the timeout for a command (such as a query) response between the web server
and the DBMS.
Note: when testing, we recommend you keep the connection and command timeout
values low. This allows you, in case of error, to more quickly start another application
session to test again.
99
Read/List Operations
The four dropdown lists in this group box allow you to manually set the connection string
parameters for ADO operations for browse procedures. You may manually override each
at the procedure level.
The default list choices should work well with most databases. We recommend that you
change the settings only after consulting the documentation for your particular database,
should you wish to change them.
The settings are:
•
Lock Type : provides for the isolation level. The default setting is read only.
•
Cursor Type: The default provides for a static cursor. In some cases, a
“ForwardReadOnly” cursor may provide optimized access.
•
Cursor Locations: in general, a client side cursor will provide for better use of
resources. In this case, the “client” is the machine running IIS/ADO, not the
browser client.
•
adCommand Type: the default “adCommandUnknown” instructs the ADO
provider to use its defaults.
Form Operations
The four buttons in this group box allow you to manually set the connection string
parameters for ADO operations for each mode (update, edit, delete) of the form
operations. You may manually override each at the procedure level.
100
The default list choices should work well with most databases. We recommend that you
change the settings only after consulting the documentation for your particular database,
should you wish to change them.
The settings are:
•
Lock Type: provides for the isolation level. The settings are optimistic for the
write operations, and read only for the view mode.
•
Cursor Type: The settings are static for the write operations, and read only for
the view mode.
•
browser client.
•
provider to use its defaults; for add operations, adCommandTable provides for
adding a row to the table.
101
Call Connection Builder
The Connection Builder button calls the Data Link Properties dialog. The specifics of this
dialog vary according to which OLE DB provider you choose. You may choose items and
fill in four tabs within this dialog. The illustrations below may not match those on your
system. Note also that the publisher of the particular library you’re using probably
supplied a help file that can be accessed via the help button in the Data Link Properties
dialog.
•
Provider Tab: this presents a list of OLE DB providers on your machine. When
developing on a workstation, you must be sure that the server you deploy to has
the same provider you choose here. You may choose an OLE DB provider
specifically provided for your database (as in the illustration below, “Microsoft
OLE DB Provider for SQL Server”), or the OLE DB provider for ODBC, which
allows you to choose any ODBC DSN previously set up on your system. In
general, if your database provides an ODBC driver, but not an OLE DB provider
library, you should be wary. It may be that the ODBC driver does not support the
features which will be required of ADO access.
102
•
Connection Tab: this allows you to input the server name, user information, and
default database. You must save the password, otherwise your application will
not work because it will have no access to the database. Note also that the tab
should include a “Test Connection” button. You should always test to make sure
that the information you’ve entered is valid.
•
103
Advanced Tab: this provides database specific access options, which may
include network/access permissions and timeouts. Note in the illustration below
(from MS SQL Server), all user controls are disabled except for the connection
timeout. In general, we recommend that you not modify the defaults on the
Advanced tab unless you are certain that your customizations will be correct.
104
•
All Tab: this provides a property sheet showing all basic and advanced settings.
In the case of MS SQL Server, below, it also provides additional properties not
on the other tabs. In general, we recommend that you not modify the defaults
unless you are certain that your customizations will be correct.
Note that after calling the Connection Builder, the connection string appears at the
bottom of the Connection Properties dialog. The following is a sample of an MS SQL
connection for the Northwind sample database using MS SQL Server’s OLE DB provider:
Provider=SQLOLEDB.1;Password=xxxxxxx;Persist Security Info=True;User
ID1=UserID;Initial Catalog=northwind;Data Source=servername
The following describes the remaining settings on the Database tab of the ASP Global
Options:
Using Access Database
Checking this box allows you to specify that the data source is MS Access, which does
not use standard SQL syntax. Access should be perfectly acceptable for testing and for
deployment for very low traffic sites. We strongly recommend a client server SQL
database for deployment for normal or busy sites.
105
When specifying MS Access, runtime user names and passwords are not required unless
you have password protected the database. Note that to password protect a database in
Access 2000 and higher, you must have installed the (optional) user level security wizard
when installing MS Office.
SQL Delimiters
Clarion/ASP automatically uses a single quote character to delimit text and date values
when communicating with the DBMS. Should your DBMS require a double quote
character instead, for text, dates, or both, you may use the drop down choice to set the
delimiter.
Global Options/Security Tab
The security model built into Clarion/ASP is user based, and assumes a database table
consisting of user names and security levels. Upon login, Clarion/ASP checks the user
name and password against this table. It is flexible enough to allow up to two columns to
store the user name. Another column stores the access level. This may be a digit up to
100. By assigning users from the same department the same access level number, you
may mimic to some extent the use of security groups.
Within the browses and forms on your site, upon a request by the user, the ASP code will
compare the users access level ID to the options you’ve specified in the template. Thus,
if you’ve specified that an access level of 75 is necessary in order to change the value in
a form, anyone with an access level below that will simply see the form as read-only.
The fields on the Security tab are as follows. Note that the ellipsis buttons next to each
field allow you to select a column/field from the dictionary as appropriate:
106
Provide User Based Security
Check this box to enable security. When checked, the fields below will be enabled.
User Table
Select the name of the table within your database containing the security information. All
fields should be character fields, except the user password column, and should contain at
least the following structure: one of FullName/FirstName + LastName/Email Address, set
as a primary key. A password column, and a security level column.
Unique ID Column
Select the name of the primary key column, or another unique key.
Login Name Column
The name of the column containing this information.
Login Password Column
Select the name of the column containing the password.
User Security Level Column
Select the name of the column containing an integer between 0 and 99 containing this
value.
On the Optional tab:
User E-Mail Column
Select the name of the column containing this information. E-Mail is only a suggested
column. This may be used to store a user name.
Second User Name Column
This allows for FILE structures containing separate columns for first and last names.
User Company Name Column
Optionally store the company name in a session variable for use in embeds or to set My
Records filtering. Choose a column from your security table.
107
User Defined Values
Optionally store up to three values in session variables for use in embeds or to set My
Records filtering. Choose the column(s) from your security table.
Note that the ASP code generated containing these items remains on the IIS server at all
times, and is not visible to the browser. Be sure, of course, to set the database server up
with proper security, so that no one is able to browse this table.
Login Screen Text
This button opens a dialog box which allows you to enter the text for your user login
pages, plus the messages to display should the login be unsuccessful.
Fill in the following text:
•
Login Prompt Text: (self explanatory)
•
Instructions: text to explain the login procedure
•
Bad User ID: text to notify the user that the login failed
•
Bad Password: text to notify the user that the login failed
•
Insufficient Access: text to notify the user his security level is lower than that
required for the page they requested
108
•
Enter Retry: text to instruct the user how to retry the login
On the Button and Field prompts tab:
•
Submit and Reset button labels: (self explanatory)
•
User ID, Password and Save Information prompts: the labels for the text boxes in
which the end user enters the information.
Login Persistence/Cookies
Cookies are ASCII files stored on the local drive of the end user, allowing you to save
variables locally, for retrieval the next time the end user logs visits your site. Clarion/ASP
allows you to store the user ID/password in a cookie, so that the end user, whenever
logging into your application from the same machine in which they stored a cookie
previously, can automatically login without having to type the user ID and password.
You may store the user ID only, or both the user ID and password. Check the “Allow
saving user identifier as cookie” box for to store the user ID, and optionally, the “allow
saving password as cookie” for the password.
You may also set the text for a message which prompts the end user to decide whether
to store the information or not. The default text is “Save Information.”
Note, of course, that should the end user’s browser security settings prevent the ability of
your site to store cookies that the cookie will not be created. The default expiration time
for the cookie is December 31st of the current year; this is (more or less) a standard. No
option is provided in the design time interface to change the expiration time; if this
necessary for your site, you may edit the login.asp page (search for the string “mydate”).
Additionally, please note that the user name and password are stored as plain text within
the cookie file.
109
Global Options/Administration Tab
The Administration tab provides global options for the pages you create.
Site Title
Fill in a string that you wish to appear in the top frame of the Clarion/ASP generated
index page.
Email ADO Errors—Administrator Email
Allows you to optionally specify that errors and logs are forwarded to the email address
you specify. Be sure to configure an email client on the IIS server. Note that this also
requires the CDONTS library and the MS SMTP service on the web server. The former is
installed along with the latter.
Message to Display on ADO Error
You may specify a custom error message to display to the end user should the
application receives an ADO error. The default error message states “A Database error
has occurred and the administrator has been notified. Thank you.” The ADO error details
will then be appended below that.
110
Note that this error displays only if the ASP library reports back an ADO error. If the
database operation simply times out, which can often be the case, then ASP may not
receive back an error message. Then the application will appear to freeze until the
timeout is reached, and then an entirely different error message appears over which you
have no control.
Enhanced ADO Error Reporting
You may choose to provide additional to the end user in case of error should you feel it is
useful. To do so, check the box on this tab. The information reported is as follows:
•
Server Name
•
Server Port
•
Web Server Software
•
IP Address
•
User
•
Host Address
•
ASP Script File Name
•
Script URL
•
Query String Parameters
•
Referring Page
•
Local IP Address
•
Fully Qualified ASP Script File Name
111
Images
The Images tab allows you to define the location of the various button images that will
appear in your pages.
The labels for the template prompts for these images are self-explanatory. Note that
several buttons provide for two images: one enabled, one disabled.
Image Relative Path
By default, the images are expected to be stored one level below the site root directory,
in a directory called /images. The web server must be able to find this directory, else your
“buttons” and other images will not display. See the section called “Internet Service
Options/Creating the /Images Virtual Directory” for instructions on creating your /images
directory on your “localhost” web server. Be sure to copy the Clarion/ASP images to the
/images directory should you not be using /CLARION6/images/asp as your default. When
deploying to your production server, be sure to copy them to its /images directory.
If you don’t wish to use “/images” as the image location, change the default. To change
the default, simply type a new directory name into the box. Be sure to copy the files to
whatever directory you indicate.
112
Image Sizes
It’s assumed that all your navigation and help icon images will be the same size. You
may enter the width and height in pixels here. If they are different sizes, enter zero and
zero. It is to your advantage to enter the pixel widths, else the browser client may redraw
the table after completing the entire download. Note: the back and help buttons are not
affected by this parameter. You may also specify a border size in pixels for the images.
Image Type Tabs
Because there are many images, these are divided into:
•
Navigation
•
Help
•
Sort Indicators
•
Database Navigation
•
Calendar
Should you wish to substitute your own .gif or .jpg images, feel free to locate the button
image you wish, and change the file name by either typing a new file name, or pressing
the ellipsis button to browse for an alternate file. Don’t forget to copy your custom images
to the images directory on the web server.
User Data
This tab allows you to define user variables for use in embedded code. Please refer to
the chapter on Embeds for information on embed points and VBScript.
Once you define a variable, you are responsible for adding the symbol name (in the
format @symbolname@) to any HTML runtime template which you wish to display the
variable. Or you may optionally name a custom control with the same name as the
variable, and Clarion/ASP will generate the symbol into the runtime template.
When you define a variable name, AppGen will automatically declare the variable at run
time, in the appdata.asp page. It is the developer’s responsibility to put the symbol to use.
To add a variable, press Insert, and type the name of the variable into the User Data
dialog. We suggest prefacing any user defined variables with a distinct preface, such as
“ud_,” in order to distinguish them within the generated code.
To edit a variable name, select the variable in the list and press the Properties button. To
delete a variable, select it and press delete.
113
Includes
Includes allow you to specify external files which will be merged into the document at the
time the end user requests it. Because this is a somewhat advanced topic, we’ve
provided a separate chapter to explain the process and its usage. Please refer to Chapter
9 in this manual for additional information.
114
The ASP Browse Extension Template
Because the ASP templates do not assume that you wish to create pages for all the
procedures in your application, you must manually apply the proper procedure template
to those procedures for which you wish to generate ASP pages.
To add the Clarion ASP Browse extension template to a browse, open the Procedure
Properties dialog for the browse, and press the Extensions button. In the Select
Extension dialog, press Insert, locate the ASP Browse template and press Select.
The ASP Browse Extension template provides the following options, on the following
tabs:
Browse Options/Globals Tab
You may override the global options for an individual browse procedure by checking the
Override box in the browse procedure. Additionally, you may specify a green bar effect or
conditional row formatting on this tab. By default, the templates provide “green bar”
formatting for browse tables.
Important: once you check the override box for any procedure, no further changes you
make to a global option will affect the procedure. This is in order to prevent the system
from overwriting any of your custom settings. If, therefore, you change a global option,
and mean to change the setting for every procedure, you must remember to execute the
same change on every overridden procedure.
115
Among the settings you can override are the following:
•
Style Sheet
•
HTML and Help file generation
•
HTML Template
•
Showing a Help Link
•
All Database Connection options
•
Number of Rows to Show in the Browse Table
•
Include an Add Button in the Navigation Bar
•
Include a Query by Form Button in the Navigation Bar
•
Include an Automatic Detail Link in Each Row of the Browse.
•
Security
•
Navigation button “tool tips”
•
Status Messages
•
Includes
Please see the Global Options section for specific explanations of the above options,
except Includes, for which you may refer to chapter 9.
•
Row Style: to specify conditional row formatting, press the Row Style button (see
“Conditional Row Formatting,” below). When set, the row is set to one style if it
meets the condition, and another if it does not. Note: you must already have
defined at least two data row styles using the Style Sheet editor to specify
conditional row formatting.
•
Security: the “Enable security for this procedure” checkbox option allows you to
turn security off for this procedure. Note that the checkbox is only available if
you’ve turned security on at the global level. Additionally, by overriding the global
security option you may add ‘My Records” functionality, as explained below.
116
Conditional Row Formatting
Conditional row formatting allows you to specify either that alternating rows will be
formatted with two row style options you previously specified in the Style Sheet’s option
for data rows, or, that rows meeting a condition you specify in this dialog will be formatted
with one row style option, and rows not meeting the condition will be formatted with
another row style option. See the chapter on the Style Sheet Editor.
Before you can set conditional row formatting options, you must check the override global
settings checkbox for the procedure, and then select the style sheet for the procedure. If
you only wish to provide conditional formatting, but keep the other global style sheet
settings, choose the same style sheet selected in the global options.
Press the Row Style button and then fill in the following options to provide the desired
behavior:
•
Default Row Style: select one of the Data Row Style Options you previously
defined in the Style Sheet as the default row formatting. Default refers to the
formatting for the odd rows should you choose a green bar option, or the rows
that don’t meet the condition if you choose conditional. The options appear in a
drop down list.
•
Use Additional Row Style: select either No, Green bar, or Conditional. ‘No”
indicates that you wish to use the row style selected above for all rows, without
condition. “Greenbar” specifies that you wish to alternately format rows using two
styles (and neither has to be green). Conditional selects one or the other row
style dependent upon a field value, chosen below.
•
Additional Row Style: select the “other” row style. This will format either the
even rows (greenbar style) or the rows that meet the condition.
•
Column to Test: when specifying a conditional option, select one of the fields in
the browse to test, by choosing from the drop down list.
•
Operator: choose an operator for the test from less than or equal to, equal to,
not equal to, or greater than or equal to.
•
Value: enter the value for the comparison.
117
Browse Options/Global Tab/Database Tab
This sub tab allows you to override the ADO parameters, which you set on the Database
tab of the global ASP extension. The default list choices should work well with most
databases. We recommend that you change the settings only after consulting the
documentation for your particular database, should you wish to change them.
The settings are:
•
Lock Type : provides for the isolation level. The default setting is read only.
•
Cursor Type: The default provides for a static cursor. In some cases, a
“ForwardReadOnly” cursor may provide optimized access.
•
browser client.
•
provider to use its defaults.
118
Browse Options/Global Tab/Security Sub Tab
This tab contains options for security level access to the entire procedure, and for “My
Records” access to individual data records:
My Records
The Clarion/ASP “My Records” support allows you to specify ownership of records by
user. Each user then views and edits only those records for which they have ownership.
The general process is as follows:
•
At login the end user uniquely identifies themselves. This is stored in a session
variable (usually, UserEmail is used, because many sites have adopted the email
address as a common identifier; it’s unique to each person and easy to
remember).
•
When the user adds a record to a “My Records” update procedure, one of the
table columns receives the session variable (email); this is done without showing
the field on the form.
•
In a browse procedure, a filter is placed on all records limiting the rows viewed to
those with the email (or other session variable) in that particular column.
•
Similarly, delete, search and view form procedures limit their scope to the users’
records.
To enable all this functionality, first turn security on globally. You must enable “My
Records” support on a procedure-by-procedure basis (both browses and forms). Then, to
enable “My Records” on a browse, check the Override box on the Browse Options
Globals tab, and then fill in the Security sub tab, as described in the following section.
To enable ‘My Records” filtering, as described step by step:
1.
Check the Enable Security for this Procedure box.
2.
Check the Enable “My Records” filtering box.
3.
Select the data column which is to store the user information to test against. This
column should be present in the browse procedure’s primary table. When you
design the database, be sure to provide that your master security table and any
tables you wish to provide “My Records” support for all include a field of the
same data type and length which you will use for these purposes. You may name
the columns whatever you wish; you need not specify the same name for the
column in every table for which it appears.
4.
Select the session variable to test against it.
119
In many cases, web sites use an email address as a unique identifier. Clarion/ASP’s
global level security dialog. Therefore in many cases, you’ll simply pick the UserEmail
session variable.
You may use the “My Records” variable to flexibly filter records, not only by user, but by
type of user (allowing for access by group), as in the following examples:
•
The Northwind sample database’s employee table contains a “reports to” column.
You may filter a browse which allows “managers” to see only their “direct reports”
by specifying the “reports to” column as the data column to compare, and using
the employee table as the security table, the employee ID as the user ID, and
then using the “UserID” session variable to test against the “reports to” column.
•
Similarly, you may declare an additional session variable, such as “Department,”
edit the login.asp page to assign the session variable based upon department
data which you would store in the security table, and then choose that session
variable to compare to a department value in your primary browse table. You
could similarly substitute “region,” “sales territory,” etc.
Once you’ve correctly set up the “My Records” options for each procedure, you need do
no more; Clarion/ASP automatically hides the necessary fields, applies the necessary
query filters, and takes care of setting the data defaults for new records.
Note that should you be applying the functionality to existing data and are adding a
column to a table that you must add the values necessary for the existing records, else
they will not appear within any users’ “My Records” filter.
Finally, note that you may place “My Records” on a form yet not place it on a browse, due
to the fact that each “procedure” within Clarion/ASP is isolated from the other due to the
nature of the web. This means that you may allow an end user to view all records within a
browse, but restrict editing, deleting, or viewing details to each owner by placing the “My
Records” filter on the form. This, as an example, could be useful for sales personnel
allowing only an owner to see the account details, but allowing everyone else to see an
account summary.
Security Level Required to Access Page
Specifying a level requires typing a number (1 – 99), which will then be checked against
the user database (as specified in the Global options). If the user meets or exceeds the
requirement, the page is then accessible to the user.
Note that this setting controls the display of the page in its entirety, i.e., whether the end
user may view the data within the browse. The options on the Security tab at the form
level provide further control for subsequent options; for example, whether the end user
will be allowed to call an update form from the browse.
Please refer to the previous sections in this manual, which deal with Security for an
overview of the topic.
120
Browse Options/Page Tab
Page Title
This allows you to specify the name of the page, as it will appear in the caption bar of the
browser.
Help URL
This specifies the name of the help page. Note that this assumes the page is located in a
directory called help one level below the asp page.
The help text appears in a popup window when the end user presses the help button in
the browse. You must produce the help text using an HTML editor. The popup help
window sizing is specified in the global options.
QBF Procedure
Select an update form in the application tree to provide a basis to lay out the QBF form.
This allows the end user to see a familiar form, and enter the data to search for in the
form.
After filling in a QBF procedure, the end user will view a browse containing records that
match the query, and can then, if you’ve provided a link to a form within that browse, view
or edit an individual record by selecting from the browse.
121
Add Procedure
Specifies the update procedure for the record. Choose from the dropdown list.
Select Mode Procedure
Check to indicate that this browse is a select browse, i.e., a list of records which should
appear in a popup window, and of which the end user should select a single record. After
the selection a value should then be returned to the calling procedure (not necessarily the
same field as that selected by the end user, but possibly another column of the same
row).
When checked, additional options will appear.
•
Column to Use as Hyperlink: receives the end user choice, i.e., is clicked upon
•
Column Assignments: this button leads to a dialog which allows you to specify
which column values to return to the calling procedure and in what order. Press
the button to open the Column Assignments dialog, and once the dialog opens,
press the Insert button to specify the column to fill from, and the target column (in
the calling procedure).
Select browses can be called with an optional range select or a ?WHR clause. No action
is necessary in the “browse side” of the template interface. You may set the range select
from the “update side,” by selecting a field on the update form, and a field on the select
browse. This will call the select browse with a WHERE limiting the browse to only those
rows in which the column matches the current value of the field on the update form. See
the instructions for the Update/Controls/Validation tab, Must be in File option.
Browse Options/HTML Table Tab
This tab controls the overall functionality of the HTML table which will contain your
browse data.
Populated From
This specifies the browse control within the window contained in the procedure. The
dropdown list displays the FEQ’s (Field Equates) of any browse boxes it finds.
122
Remember that the template limits you to the display of a single browse; however, it’s
easy to provide a link to a separate browse.
Clarion/ASP allows you to select a browse that may include fields from more than one
table. It will automatically generate the proper JOIN syntax necessary.
Note: if when debugging your application a browse composed of fields from multiple
tables creates an error, but browses from single tables do not, examine the SQL select
statement, copy and paste it into an SQL command line tool provided by your database
vendor, and verify that the syntax is correct for that particular database. If not, you must
customize the SQL statement (see below).
HTML Table Title
This box allows you to specify a string to appear at the top of the HTML table containing
the browse data.
List Box Primary Table
This allows you to select the primary file selected for the browse control.
Unique Key
This allows you to select a key to uniquely identify each record. If you pick a key allowing
duplicate values, the procedure will return with a “not found” message. this box will
default to the key in the dictionary with the primary attribute.
123
Populate an Entry Locator
This specifies that Clarion/ASP should generate a text box which shall appear above the
table, which allows the end user to type in a value and re-query the database. This is
useful for quickly applying a filter to a browse. This is particularly helpful in allowing a
user, for example, to quickly see all the names starting with a specific letter or
combination of letters.
When the value is entered, and the Locate button pushed, an SQL statement with a
WHERE fieldname LIKE ‘whatevertheusertypes%’ is sent to the database. The % is a
wildcard which includes any characters to the right side of what the user types.
For Clarion developers familiar with standard Clarion locators, please note that this is
very different. The end user cannot jump to the first record, and then browse backwards
from it, or past the end of those records that satisfy the filter. The resulting records are
only records that match the new query.
To un-apply the query filter, the end user may press the “All Data” link which appears in
the caption area whenever a query filter is active. After returning from the locate query,
the browse will reflect the query that existed before the end user typed anything in the
locator box.
Note that if the end user types additional text in the locator box when a query is active,
the new query will be applied only against the results of the previous query.
Locator Column
This allows you to specify a search column by choosing a field from a list. There are four
items to note:
•
For best performance, the search column should be a key component, or an
index should exist.
•
In the case of a string search, the search clause will take the form ‘where
searchfield like WhatTheUserTypes%’ which means that if the end user types in
‘A,’ then the search will return all values beginning with the letter ‘A.’
•
Any end user searches will append an SQL where clause to the clause which
populated the browse. If, for example, the original browse page included a filter
such as “State = ‘NY’,” and the search was for “CompanyName like ‘A%’” then
the search page results will be for “State = ‘NY’ and CompanyName like ‘A%’.”
•
The resulting search page will include a link back to the previous browse. You
may specify the precise text that the end user sees for this link (the Clear Filter
Prompt on the Messages tab of the Global and/or Page Overrides). The default
text is “All Data.” The resulting page will include any previous filter that was in
effect for the page prior to the search; therefore if your browse includes a default
where clause or other filter, it’s recommended that you change the text.
124
Final Note: should you wish to duplicate the functionality of an end user search, calling
the search results page from outside the Clarion/ASP pages, you may use parameters:
BrowsePageURL?Locate=TRUE&Field=FieldName&SearchValue=SearchValue"
In the example above, note that the browse must have a Locator specified for the field
named.
Browse Options/Default SQL Tab
Because the SQL to access the data is vitally important, Clarion/ASP allows you to view
the Select statement and customize it if necessary. This also provides a convenient way
to customize a browse filter (the Where clause) or ordering, should you wish.
Regenerate SQL
Should you insert or delete any of the columns on the Table Columns Tab (below), the
template will regenerate the SQL for the browse select only after closing and reopening
the Procedure Properties dialog. Some developers therefore may wish to immediately
press the Regenerate SQL button after making a change to the table column list, should
they wish to check the generated SQL.
Note, however, that should you edit the SQL by hand, then add or delete a column from
the list, Clarion/ASP will not change your hand-edited SQL; you must either change your
SQL statement by hand, or press the regenerate button (and then re-do your
customization).
125
Default SQL Select
This text box provides the base select statement. Note that should your browse contain
fields from more than a single table, it will automatically provide for a JOIN.
Important Note: if you’ve populated a field in the Data Columns tab for which Clarion/ASP
can’t resolve the proper syntax (for example, if you’ve populated a data variable in the list
box control for your browse), and the resulting page doesn’t display properly, examine
the SQL statement here. Should you find a statement with a blank for the field name (look
for an extra comma in the order that the suspect field appears in the data columns list, as
in Select fieldname,fieldname,,fieldname...), you may edit the statement here, or delete
the suspect column from the list. Such a problem should be very rare; for example,
should you have more than three JOINs.
Default SQL Where
The text in this box provides the Where clause, which is concatenated to the Select
statement. Important: because it’s possible that the developer may customize the
WHERE clause, the “Regenerate SQL” button does NOT erase this box. You must do so
manually if need be.
Default SQL Order by
The text in this box provides the Order clause, which is concatenated to the other parts of
the statement.
Browse Options/Data Columns Tab
The table columns tab allows you both to specify which columns should appear within the
browse, and their properties. Those controls initially auto populated correspond to the
listbox columns in the browse box which you selected as the “Populated From” choice on
the HTML Table Tab. To insert a column, press the insert button and choose a column
from the list. If the column does not appear in the listbox, it will not be available from this
list. To insert it into the listbox, open the window formatter, right click the listbox, choose
the listbox formatter, press the add column button, click on the table select the column. If
the column is from another table, click on the table, press the insert button, choose the
related table, then the column, and press the select button. After saving the listbox and
window changes, the new column will be available in the list. Clarion/ASP automatically
writes the correct JOIN clause in the SQL statement.
126
In general, you should approach the inclusion of data in ASP browse tables more
conservatively than desktop applications. When serving data over the Internet, it may be
more helpful to limit the number of columns in a browse, which results in less time waiting
for network transfers and a more readable page, than including many columns.
Clarion/ASP makes it easy to provide a view link, so that the end user needs only to click
once in order to see a page containing an update form, showing all or most fields, and
the page may be opened in view only mode, disallowing changes to the data.
Moreover, remember that these are HTML tables, not list boxes with horizontal scrolling
capability as in a desktop application. Therefore, populating a browse table with many,
many fields is liable to result in very narrow columns, compromising readability of the
data.
You can, however, group a column with the data from a previous column, in effect
making a cell into a multi line element. Place an HTML <br> tag in-between the fields to
provide this “stacking” effect. Place the HTML code for a non-breaking space, which is
nbsp; including the semi colon, to place two fields together with a space between them.
The illustration below contains multi-line data for the “Company” column. All fields
following “company” were specified as grouped with the previous field. The <BR> tag
precedes the first name, title, and address line 1, and city fields. the nbsp; keyword
precedes the last name, state, and zip code fields.
127
Additionally, note what we think may become a common error for experienced Clarion
programmers: when adding a date column, do not include the date component of the
Clarion group which the dictionary import procedure automatically places over the
date/time field. Use the date/time field. A simple way to detect this is to scan the data
columns list for any column named columnname_DATE, since the import automatically
appends the _DATE at import to the Clarion date field. The SQL date/time field should by
default not have the _DATE appended to it, and should have a picture of @s8.
The Data Columns Properties dialog allows you to specify both appearance and
functionality for the data in your ASP browse columns. The dialog is divided into tabs.
128
Data Columns/General Tab
This tab allows you to hide a column yet still include it in the SQL statement, and to
provide that the browse can be called with a range limiter.
•
Data Column: the field name as it appears in your dictionary.
•
Include in the SQL Select But Do Not Display: there may be situations in
which you wish to provide a custom SQL select statement, and not display a
particular field, as in, for example, a browse populated from two tables: you may
wish an ID number common to both tables to be present in the SQL statement,
but not within the displayed data, for which you wish to display only a last name
from the second table.
•
Include With Prior Column: this allows you to place two or more values within
the same “cell.” If one value is null, then the other values will still be displayed.
You may separate the values via HTML entered in the “Preceding Text” box. To
insert a space between the values, enter   (including the semi colon) which
indicates a non breaking white space.
•
Range Limit on the Column: should you wish to call the browse from elsewhere
within the application or from elsewhere within your site, and to use a value
parameter to pass a value as a range limiter, you may check this box. When
calling the browse, be sure to provide the ID1 parameter, as in
http://mysite/mybrowse.asp?ID1=’Smith’. You must only select this option for one
column only.
Checking this box will allow you this browse to be called with a range limit/filter,
such as Where columnname = parameter value. The browse will then display
only those records which match the filter. This allows you to match the
functionality of a Clarion parent/child linked browse box combination in ASP
(spread across two pages). To enable such a link, check this box in the child
browse. Be sure to check this box for only one column.
You can also easily create a browse to browse link, by specifying that your field
be a procedure link, passing the value of the range limiting field, choosing the
other browse procedure, and specifying List for the type of procedure. (see the
“Appearance” tab, below). Once the child browse is configured with the range
limit option, you may also call it from any other page on the site by passing the
?ID1= parameter with a range limit value.
You may also create the same functionality a different way; from the parent
browse, add a custom link on the table data columns or static columns tab, and
include the field value as a parameter to this page, passing the value of the
current row of the current field (for example,
“http://www.mydomain.com/browsepagename.htm?ID1=” &
129
CSTR(Request(“Customer_ID”)). Note that the first part of the URL is double
quoted.
Once you’ve added this option, you must insure that all calls to the browse page
include the ?ID1 parameter.
Should you check this option, and then later uncheck it, you must manually edit
the Where clause on the Default SQL tab. If the template were to clear the
clause, it might also delete any customize SQL you had previously placed in the
Where clause as well.
Data Columns Properties/Actions Tab
The Hyperlink groupbox allows you to specify that when the end user clicks on a data
item in this column, the browser will open another page.
130
To enable the link to open an update procedure (or another procedure, for that matter),
check the “Procedure Link” box and specify the name of the procedure from the
dropdown list. Remember to apply the ASP form procedure to the procedure you select.
Indicate in the second dropdown box the action to apply to the procedure: whether it’s to
view data only, or to add, edit, or delete a record, or to list data, as in the case of opening
up a browse on a child file.
The Custom Link choice allows you to add an HTML, VBScript, or Jscript link in the
Custom Link edit box below. You must provide the text of the complete link, from the <A>
to the </A> tag, as in, <a href="URL">Link Text</a>, or <a href="URL"><img
src="Image.GIF"></a>
•
Create column as a Link: optionally specify the link type (procedure or custom).
If not a link, the table merely displays the data as static. The default choice is
“No.”
•
Pass this Data: allows you to define which value to pass. choose Key Value,
Data Column, Session Variable, or Static Entry (text). Your choice will enable
one of the following four controls.
•
Key to Pass: allows you to define which key to pass the value(s) of. This allows
you to link to a form on a table with a multi component key.
•
Data Column to Pass: allows you to define a link on one column, yet pass a link
value from another. For example, to allow an end user to click on a product
name, but to pass the product ID as a parameter to a product update form. This
can be combined with hiding the Product ID in the browse, making the operation
“friendlier” to the end user.
•
Session Variable to Pass: allows you to define a session variable to pass to a
procedure.
•
Static Entry: allows you to pass a string to a procedure.
•
Additional Parameters: allows you to pass additional parameters when
specifying a procedure link with static entry. Fill in in the format
parametername=value, or parametername1=value1&parametername2=value2.
•
Procedure Link: to enable the link to open an update procedure (or another
procedure, for that matter), check the “Procedure Link” box and specify the name
of the procedure from the dropdown list. Remember to apply the ASP form
procedure to the procedure you select. Indicate in the second dropdown box the
action to apply to the procedure: whether it’s to view data only, or to add, edit, or
delete a record, or to list data, as in the case of opening up a browse on a child
file.
131
•
Type of Procedure: specify the type of Clarion/ASP the target procedure is (list,
view, add, edit, or delete).
•
Custom Link: allows you to add an HTML, VBScript, or Jscript link in the
Custom Link edit box below. You have complete control of the link, which means
that you may specify custom tags such as Flash files. The link will also not
automatically display your data; you must manually place it
Your code must include the <a> and </a> tags. It’s important to note that the text
you enter in this box will be temporarily stored in and ASP string variable, and
therefore will be surrounded with double quotes. The code surrounding yours
enclose it with double quotes, as in:
mylink = “<a href=’/HomePageContent.htm’>this is some text</a>”
When using a custom link for the data column, the value of the data column does
not appear in the browse table unless you place it there manually. In general, the
only reason to use a custom link for a data column instead of creating a custom
column (see below) is if you must include a custom link in-between columns,
rather than at the left or right of the table.
Please see the section on custom columns, below, for further information on
creating the actual link text for data columns acting as custom links.
Data Columns/Properties/Column Sorting Tab
•
Column Header Text: the text you wish to appear at the top of the column.
•
Enable Sorting by this Column: allows the end user to click on an image on the
column header to sort the column. Note that the default is sortable for all
columns, but in general, good DBMS management suggests that it’s best to
remove the “sort” capability from columns not part of any key components or for
which there’s little rationale for allowing a sort.
132
•
Ascending/Descending Sort SQL boxes: the template automatically includes
ORDER BY clauses (one for ascending, one for descending) in the text boxes
below. Note that you may manually override the default by typing in your own
clause.
•
Ascending/Descending Sort Images: the image files used to add a directional
icon for the sorts.
133
Data Columns/Properties/Appearance Tab
•
Alignment: because all data in the HTML form is a string, the cell alignment
options are left, center and right.
•
Width: this allows you to set a custom width (in pixels or percent) for this column.
Bear in mind that should the totals for all the columns exceed either 100% or the
available space in pixels, the browser’s rendering engine will adjust the column
size as necessary.
•
Formatting Function:
In the same way that you may specify conditional formatting by style for rows, you may
specify conditional formatting by style for columns, in effect allowing you to highlight
specific grid cells based on the data value. Simply check the box, pick a style and specify
the condition.
You may format a date/time (using standard VB functions), number, currency, or percent.
For each choice, an options tab will appear offering specific formatting options, such as
decimal places, currency signs, etc. The options are self-explanatory.
134
•
Enable Cell Style: check this box to enable conditional formatting for this cell
(i.e., within when the table grid appears in the end user’s browser, a value in this
column that meets certain conditions may optionally use a different style than
other columns, or even values in the same column above or below it. In this way
you may highlight a particular value with a red background, make the value bold,
etc. Note that you must have previously defined more than one Data Row Style
in the Style Sheet Editor to display a contrast between this cell and others. You
may make the visual differences as subtle or as overt as you wish.
•
Default Cell Style: select one of the Data Row Style Options you previously
defined in the Style Sheet as the default row formatting. The options appear in a
drop down list.
•
Use Additional Cell Style: select Conditional. ‘No” indicates that you wish to use
a single style. Conditional selects one or the other style dependent upon a field
value, chosen below.
•
Additional Row Style: select the “other” style. This will format the cells that meet
the condition.
•
Column to Test: when specifying a conditional option, select one of the fields in
the browse to test, by choosing from the drop down list.
•
Operator: choose an operator for the test from less than or equal to, equal to,
not equal to, or greater than or equal to.
•
Value: enter the value for the comparison.
Browse Options/Custom Columns Tab
This tab allows for similar functionality to the table columns tab, except that it does not
display row/value data. No field chooser drop down list appears, because it’s not
designed to display field data.
The custom columns are useful, for example, to display a small graphic to link to another
procedure. As an example, an ellipsis button in a parent browse can be added on this
tab, which could then link to a child browse, as explained in the Table Columns
Properties section, immediately above this text.
Likewise, the custom column could contain a graphic which might link to a page at the
site which was not generated by Clarion/ASP. For example, you might use a shopping
cart graphic to link to a shopping cart page, and pass a product ID as a parameter.
Or, the static column could provide a graphic containing any other type of custom link,
such as a link to create a blank email message in the end user’s email client, filling in the
subject line (mailto:[email protected]?subject= some subject).
135
By default, Clarion/ASP automatically populates one custom column, the Automatic
Detail Link, when you populate a browse. This places a graphic at the end of the row
which the end user may click on to view an update form (view only by default, or edit, by
option) for the selected row. This automatic population may be overridden on the browse
procedure’s overrides tab, and afterwards, the custom column deleted.
Use the Insert, Properties, or Delete button to add, edit, or delete static columns from the
list box, and edit the columns’ properties via the Custom Columns properties dialog,
detailed below:
Custom Columns Properties/Appearance Tab
•
Column Name: merely provides a convenient way to reference this column.
•
Alignment: right or left align the cell.
•
Location: the static column(s) must always appear either to the left of, or the
right of your data columns. Choose one.
136
•
Create this Column as Link: this group box allows you to specify that when the
end user clicks on an item in this column, the browser will open another page.
The default choice is “No.”
To enable the link to open an update procedure (or another procedure, for that
matter), check the “Procedure Link” box and specify the name of the procedure
from the dropdown list. Remember to apply the ASP form procedure to the
procedure you select. Indicate in the second dropdown box the action to apply to
the procedure: whether it’s to view data only, or to add, edit, or delete a record,
or to list data, as in the case of opening up a browse on a child file.
•
Hyperlink: allows you to add an HTML, VBScript, or Jscript link in the Custom
Link edit box below.
Note that the custom link capability is useful for more than just linking to a static
HTML page. You may provide, for example, an HTML parameter, such as
http://www.mydomain.com/page.htm?parametername=value. Or, you may
include field data as a parameter, passing the value of the current row of the
current field (in the following example, called “ID,” such as
“http://www.mydomain.com/page.htm?parametername=” & CSTR(Request(“ID”)).
Note that the first part of the URL is double quoted.
You are responsible for everything including the <A> to the </A> tags for this link.
You may concatenate strings and VB functions, and reference session and data
variables using VB Script functions.
It’s important to note that the text you enter in this box will be temporarily stored
in and ASP string variable, and therefore will be surrounded with double quotes.
The code surrounding yours will appear with yours as:
mylink = “YourText/CodeGoesHere”
This means that if you mix string and functions, you must watch your
concatenation. If your custom link is (1) string only, just type your string and not
worry about the quotes:
MyString
If your custom link is (2) a string with a function concatenated behind, don’t forget
to close the opening quote, concatenate your function, and then open the
following quote:
Mystring” & MyFunction(param) &”
137
If your custom link is (3) a function with a string concatenated behind, don’t forget
to close the opening quote, concatenate your function, and then don’t close the
following quote:
“ & MyFunction(param) & “mystring
If your custom link is (4) a function only, don’t forget to close the opening quote,
concatenate your function, and then close the following quote:
“ & MyFunction(param) & “
If you have several elements, just remember where the quotes will be.
To reference a session variable, use the VBScript function SESSION().
To reference a data element in the current form, use a VBScript function to return
it from the recordset: oRStablename(“fieldname”). You may use text functions to
trim and insure against returning a null variable, as in:
MID(TRIM(oRStablename("fieldname")),1,50).
Because the custom link options are almost completely free form, they serve as
very nearly a way to place embedded VBScript in your applications. Note that the
custom link capability is useful for more than just linking to a static HTML page.
You may provide, for example, an HTML parameter, such as
http://www.mydomain.com/page.htm?ID1=value. Or, you may include field data
as a parameter, passing the value of the current row of the current field. The
following example shows concatenating strings and VBScript functions to make a
dynamic URL incorporating the data from each cell as a parameter:
<A HREF=UpdateSuppliersView.asp?ID1=" &
MID(TRIM(oRSviewContacts.Fields("EditSupplier").Value),1,50) &"> <IMG
alt='Supplier Details' src='/images/supplierdetail32x32.GIF' border=0>
</A>
•
Image Button: press to provide details for displaying an image in this cell, when
selecting either a procedure or custom link.
If you’ve chosen to display an image in this column, you must fill out Image
dialog after pressing the button:
•
Populate From: specify whether the image resides as an external file or a binary
column in the database. Note that Clarion/ASP has tested binary images stored
in the MS SQL Server database.
•
File Name: if the Populate From option points to an external file, specify the file
name. An example use of a static image might be a small pencil image,
symbolizing a link to an update form. Remember that the file name must be
either relative to the application’s web directory, or to the web root directory.
138
•
ID Value Column: if the Populate From option points to an image stored in the
database, specify the unique ID column for the row.
•
Table With Image: if the Populate From option points to an image stored in the
database, specify the column containing the image. Making this a separate
option, allows the DBA to store the images in a table separate from the table
used for the browse.
•
ID Column: if the Populate From option points to an image stored in a separate
table in the database, specify the unique ID column for that table.
•
Image Column: if the Populate From option points to an image stored in the
database, specify the column containing the binary image data.
•
Image Type: if the Populate From option points to an image stored in the
database, specify jpg, gif or png.
An additional tab, called Column Header allows you to place a column text label
at the top of the column in which the images will appear.
•
Column Header Text: the text which should appear at the top of this column.
139
The ASP Form Extension Template
As noted previously, because the ASP templates do not assume that you wish to create
pages for all the procedures in your application, you must manually apply the proper
procedure template to those procedures for which you wish to generate ASP pages. The
application of the ASP browse template to a browse, however, will automatically build in a
link to the update form for that browse. You must separately apply the ASP form template
to the update form.
To add the Clarion ASP form extension template to an update procedure, open the
Procedure Properties dialog for the form, and press the Extensions button. In the Select
Extension dialog, press Insert, locate the ASP Form template and press Select.
The ASP Form Extension template provides the following options, on the following tabs:
Form Options/Global Overrides
You may override the global options for an individual form procedure by checking the
Override box in the browse procedure.
Important: once you check the override box for any procedure, no further changes you
make to a global option will affect the procedure. This is in order to prevent the system
from overwriting any of your custom settings. If, therefore, you change a global option,
and mean to change the setting for every procedure, you must remember to execute the
same change on every overridden procedure.
140
This allows you to override the following for this procedure:
•
Style Sheet
•
HTML Template
•
Generation of Help and/or HTML Files
•
Show Help Link
•
Show Navigation Buttons
•
Database Connection options
•
Titles and messages Associated With This Form (for example, instead of “Your
Insert Failed,” a message such as “Due to a database error your order was not
posted. If the error continues please contact the administrator” might be more
helpful to your users.
•
Includes
Please see the Global Options section for specific explanations of these options, except
Includes, which are explained in detail in chapter 9.
Note that the checkbox for security is only available if you’ve turned security on at the
global level. The “Enable security for this procedure” checkbox option allows you to turn
security off for this procedure. Note that the checkbox is only available if you’ve turned
security on at the global level. Additionally, by overriding the global security option you
may add ‘My Records” functionality, as explained below.
My Records
The Clarion/ASP “My Records” support allows you to specify ownership of records by
user. Each user then views and edits only those records for which they have ownership.
The general process is as follows:
•
At login the end user uniquely identifies themselves. This is stored in a session
variable (usually, UserEmail is used, because many sites have adopted the email
address as a common identifier; it’s unique to each person and easy to
remember).
•
When the user adds a record to a “My Records” update procedure, one of the
table columns receives the session variable (email); this is done without showing
the field on the form.
•
In a browse procedure, a filter is placed on all records limiting the rows viewed to
those with the email (or other session variable) in that particular column.
•
141
Similarly, delete, search and view form procedures limit their scope to the users’
records.
To enable all this functionality, first turn security on globally. You must enable “My
Records” support on a procedure by procedure basis (both browses and forms).
To enable “My Records” on a form, check the Override box on the Globals tab, then fill in
the Security sub tab, as described in the following section.
Form Options/GlobalsTab/Security Sub Tab
To enable ‘My Records” filtering:
1.
Check the Enable Security for this Procedure box.
2.
Check the Enable “My Records” filtering box.
3.
Select the data column which is to store the user information to test against. This
column should be present in the form procedure’s primary table. When you
design the database, be sure to provide that your master security table and any
tables you wish to provide “My Records” support for all include a field of the
same data type and length which you will use for these purposes. You may name
the columns whatever you wish; you need not specify the same name for the
column in every table for which it appears.
4.
Select the session variable to test against it.
In many cases, web sites use an email address as a unique identifier. Clarion/ASP’s
global level security dialog. Therefore in many cases, you’ll simply pick the UserEmail
session variable.
You may use the “My Records” variable to limit record access not only by user, but by
type of user, as in the following examples:
•
The Northwind sample database’s employee table contains a “reports to” column.
You may filter a form so that “managers” may edit only their “direct reports” by
specifying the “reports to” column as the data column to compare, and using the
employee table as the security table, the employee ID as the user ID, and then
using the “UserID” session variable to test against the “reports to” column. By not
enabling “My Records” on the browse, the managers can see a listing of all
employees, but then can only link to an edit form for their own employees.
•
Similarly, you may declare an additional session variable, such as “Department,”
editing the login.asp page to assign the session variable based upon department
data which you would store in the security table, and then choose that session
variable to compare to a department value in your primary form table. You could
similarly substitute “region,” “sales territory,” etc.
142
Once you’ve correctly set up the “My Records” options for each procedure, you need do
no more; Clarion/ASP automatically hides the necessary fields, applies the necessary
query filters, and takes care of setting the data defaults for new records.
Note that should you be applying the functionality to existing data and are adding a
column to a table that you must add the values necessary for the existing records, else
they will not appear within any users’ “My Records” filter.
Form Options/Global Tab/Database Tab
This sub tab allows you to override the ADO parameters which you set on the Database
tab of the global ASP extension. The default choices should work well with most
databases. We recommend that you change the settings only after consulting the
documentation for your particular database, should you wish to change them.
The four buttons in this group box allow you to manually set the connection string
parameters for ADO operations for each mode (update, edit, delete) of the form
operations.
The settings are:
•
Lock Type : provides for the isolation level. The settings are optimistic for the
write operations, and read only for the view mode.
•
Cursor Type: The settings are static for the write operations, and read only for
the view mode.
•
browser client.
•
provider to use its defaults; for add operations, adCommandTable provides for
adding a row to the table.
143
Security Levels
You may set separate security levels to permit adds, changes, deletes and viewing the
form. Specifying a level requires a number between 1 and 99 which will then be checked
against the user database (see Global Options). if the user meets or exceeds the
requirement, the page is then accessible. If not, a message is displayed, which is
configurable by the developer in the global settings.
Titles (Insert/Edit/Delete/View/Search)
These boxes allow you to specify the name of the page for each of the actions. The page
title appears in the caption bar of the end user’s browser.
Messages
These boxes allow you to override the default status messages which display following
the completion of the update procedure.
Navigation
These boxes allow you to override the navigation button “tool tips” as well as providing a
custom “first” or “last record reached” message.
Includes
You may include your HTML/JavaScript files at the following locations by entering the
include file name in the appropriate prompt.
Before/After <html> tag
Before/After </head> tag
Before/After <body> tag
Before/After </bg div> tag
144
Form Options/ActionsTab
The Actions tab allows you to set the update functionality, and whether following an
update the end user should see a status page or a custom page.
Allow (Insert/Edit/Delete/View)
Check the boxes for the actions you wish to enable. Note that View provides for a read
only form.
145
Page to Return To
Normally after an update, change or delete, the end user views a status page stating that
the update succeeded or failed, as below:
If instead you prefer that the end user is sent to a page of your choice, type a URL in the
box(es) marked “Page to return to” next to the action you wish to tie the page to. This
provides, for example, a convenient way to provide for “repeat adds,” via which the end
user is presented with a new blank add form following a successful insert. Or it may
simply return the end user to a “table of contents” page.
The “return” mechanism provides additional functionality in that you may add a template
symbol to your own HTML or ASP page, if you’ve defined it as the target, and
Clarion/ASP, following the insert, will merge the values of any known symbols into that
page, using a mechanism similar to the HTML runtime template technology. If you do not
insert any symbols, there will be no effect on the page the end user sees. The “return”
mechanism thus provides for the following additional functionality:
146
•
Display Security Variables or User Defined Variables in the Target Page: by
default, if security is active, the symbols available for insert are the security
session variables (@UserID@, @UserEmail@, and @UserName@). You may
insert any of these into the target HTML page and the merge routine will
substitute the values. Additionally, any user defined variables which you defined
at the global level, and which you stored values in (at previously executed embed
points) are available.
•
Return to Calling Browse or Query Form: you may also use the “return”
mechanism to deliver the end user back to a browse or query form after a
successful insert. Note that should you wish to return the end user to a browse
which had previously been filtered, you must add a URL parameter:
?SUBSET=TRUE.
•
Repeat Add Mode With Prefilled Fields: in some cases the developer may
wish to set certain fields on the add form to repeat the previous value, so that the
end user, in effects, fills in “half” the form, and each subsequent add only
requires that they fill in the other “half.” This requires embed code in the add
form. The general process for executing this would be: (1) declare user defined
variables for each of the repeated fields at the global variable, (2) examine the
ASP source for the Add page and identify the variable name used in the ASP
code (normally TableNameFieldName, found on a line such as):
TemplateText = Replace(TemplateText, "@CustomersCompanyName@",
CustomersCompanyName)
Then, (3) in an embed point such as prior to closing the record set, assign the
value of that variable to your user defined variable such as:
SESSION(“myUserDefinedVariable”) = CustomersCompanyName
Finally, (4) at an embed point after opening the record set, assign the opposite of
the above.
Note: Repeat Add Mode does not depend on the “return” mechanism; following
these guidelines this same functionality works for any add linked to from any
page (not necessarily a previous add), automatically retrieving the values
previously stored in user defined variables for that session. The “return”
mechanism merely provides a convenient entry point in that in many cases the
developer wishes the Repeat Add Mode functionality for a series of “rapid fire”
adds.
147
Builder Page Information
The Form Actions tab provides a convenient point at which to document the Builder
functions, though not directly controlled by the template interface.
The Add, and Edit actions are each divided into two separate ASP pages: a Builder and a
Processor. The Builder page retrieves the data and places the form before the end user.
These are the procedure pages ending in “add.asp,” or “edit.asp.” The Processor page
executes the update or change, then displays the status message or routes the end user
to the next page as defined in the Actions tab. These procedure pages end in “addx.asp,”
and “editx.asp.”
The merge function opens the HTML runtime template, locates all @symbols@, and
replaces each with the data and formatting instructions corresponding to each symbol.
The result is a complete HTML page, and that is what is output by IIS to the browser.
Within the Processor page, a variable called “mystatus” holds the “your insert/update
succeeded or failed” message which the end user normally sees after an operation. The
Processor page therefore performs the operation, and then displays that message.
If you wish to display that message in a page of your own, or to a different Clarion/ASP
generated target page (for example, displaying the “success” message at the top of the
next update form in a repeat add), you must use one of the Processor embeds (see
chapter 8) to store the message in a user defined variable (at the last embed point in the
Processor, simply assign ud_YourVariable = mystatus).
Whether or not you display the message in your page, by entering a page of your own in
the target action, as described above, after the update operation the Processor page will
open that file, search for any user defined @symbols@ (as listed in the user variables tab
of the global extension), merge/replace those symbols with the corresponding variables,
and then output your page to the end user.
This provides you with a flexible means of routing and informing the end user through
each update or insert operation.
Generate QBF
If checked, specifies the generation of an additional page containing a Query by Form.
Upon user entry, the form will automatically run the query and display the results in a
parent browse.
Parent Browse
Specify the name of the browse procedure which will link to the form, as well as the
browse which will appear subsequent to the Query by Form (if the previous box checked.
148
Form Options/Help
The Page tab allows you to set the help links for the page.
Help URL (Insert/Edit/Delete/View/Search)
Specify a URL for each of the appropriate actions. When the end user clicks on the link,
the help page you specify will appear in a popup window. Note: if your help text is
extensive, the window may cover the application window. Should this be the case you
must educate your users so that they know to close the help window to return to the
application pages.
Form Options/Data Access Tab
This tab allows you to customize the SQL used to manage the update form. It contains
the following three sub tabs:
149
Table Sub Tab
The form template is designed to retrieve and update a single table at a time. You may
not include fields from other tables (even as display only fields) on your form, except (1)
by populating the file drop control template in the window formatter, or (2) by editing the
.asp file post generation, modifying the FROM clause. Note that the latter process is
demonstrated in the Annotated Examples book.
•
•
•
•
Form Primary Table: the table to be updated. Choose a table from the
dictionary, using the ellipsis button to select from a list.
Unique Key: a unique key which identifies the row.
Enable range limit option should be checked when using a range limited
Browse procedure that calls this form. Press the ellipsis button and select the
valid Column that is used to range limit. This feature permits you to identify a
value (not necessarily the primary key) which will be "persisted" at several levels
and used for; returning to a list that is a subset, applying the range to a search
condition automatically, view form navigation of a subset, and priming of newly
inserted rows with the range value.
Regenerate SQL: should you change the form controls (using the WINDOW
structure), you may press this button to immediately update the SQL select
statements, else the SQL will regenerate only after you close and then reopen
the procedure properties.
SQL to Delete Row Sub Tab
This edit box displays the SQL statement to delete the row. You may edit the statement;
however, the programmer assumes full responsibility because there is no error checking
of your changes.
SQL for Selection Sub Tab
This displays the SQL statement to retrieve the row. You may edit the statement;
however, the programmer assumes full responsibility because there is no error checking
of your changes. Moreover, manually changing the select statment does not edit the
columns that the page will contain. If, for example, the programmer deletes two columns
from the select statement without deleting them from the window or choosing the “do not
populate” option, the runtime template will still display the columns as empty edit boxes.
Note that the default syntax will include both SQL and ASP code. The first part of the
select statement is the main select, but the second part is comprised of ASP, and forms
the value for the where clause, using the ASP Request function and the column name.
Thus, “SELECT (fieldlist) FROM Person WHERE Person.ID = “ & CSTR(Request(“ID”)).
Note the double quotes for the first part of the statement. The concatenated part provides
for a VBScript function to obtain the unique value for the ID field, as requested by the
calling page.
150
Form Options/Controls Tab
The Controls tab allows you to specify the properties for the columns which appear within
the form. Those controls auto populated correspond to the controls in the procedure’s
window, in the order they appear in that structure.
Important: if you wish to add or subtract a control, add it to or delete it from the window. If
you wish to change the control order, you must either edit the window structure as text
(using the ... button next to the Window button in the Procedure Properties dialog) or
change the tab order using the Window Formatter.
Note that the column properties for the control are picked up from the Dictionary with
some limitations due to the differences in available properties for HTML controls. It is
important to review the properties for each control. Example: formatting pictures do not
come from the dictionary; instead, they come from ADO. The MS SQL Server Northwind
sample database, as an example, includes a price field in the Products table. This data
type is “money.” Therefore, a Clarion/ASP application will correctly display a currency
symbol for this value, using the local currency symbol as set on the SQL Server. This
particular field is also defined in the database as having a precision of four. Therefore,
the ASP page correctly displays the value with four decimal places.
To review the control properties, select a control from the list and press the Properties
button. This presents the Controls dialog, which contains the following sub tabs and
options:
151
Appearance Sub Tab
•
Populate: enable or suppress (don’t generate) the control on the generated ASP
page.
•
HTML Form Element: the control type. Choose from Input (entry box), Check
(Checkbox), Radio, Select (List box), and Text area (multi line text box). Note
that the control type choice will affect the options in subsequent tabs. Bear in
mind that these are the native HTML control types, and the names used are
those used when populating an HTML form.
•
Caption: the equivalent of the prompt text for the control. Note that mnemonics
and accelerator keys are not possible.
•
Tool Tip: the “tool tip” will be inserted as an ALT tag for the control. Internet
Explorer and the latest version of Netscape utilize this text as a tool tip. Note that
older versions of Netscape do not.
•
Formatting Function: optionally select DateTime, Number, Currency or Percent
to specify formatting. Each choice provides additional appropriate options such
as the number of decimal places for number formatting, or short/long date format.
The pictures apply to both display and input; therefore it is vitally important that
on input, the end user must be educated on what the acceptable input is. If, for
example, a picture provides for two decimal places, but the end user types in
three, or if a long date is provided for but the end user types in a short date, the
server will return an ADO error.
Please note the following regarding the pop-up javascript calendar which
appears next to date fields. Clarion/ASP will add this pop-up (assuming you
152
haven’t disabled it in the global list defaults) under two conditions: (1) if the
dictionary provides for a date picture, such as @d1 or @d2 for the field, or (2) if
you you’ve specified a DateTime format in this dialog.
Note also that this is a change in behavior introduced in Clarion/ASP 1.2.
Previously, the template generated the the calendar lookup if the field name
included “date” in its name.
•
Case: optionally specify case conversion to normal, lower case, or upper case.
•
Password: optionally specify password field entry.
•
Read Only: check this box to disallow editing of the selected column.
•
Omit From QBF Page: this deletes the field from the Query by Form page.
There are excellent reasons for omitting fields from the Query by Form. Firstly,
the less fields, the simpler; chances are 80% of the queries will only require 20%
of the fields or less. Secondly, querying a non-indexed field may require greater
effort on the part of the DBMS.
Note: remember when populating a checkbox control on a query form that
unchecked does not mean null (or no choice for that field). It means the query
seeks records for which the value for that field is false. This concept could be
confusing for many end users; therefore we recommend that when using Queries
as a main navigation aid for your applications that you review the use of
checkboxes.
•
Maximum Characters: allows you to size the controls (width only).
•
Rows and Columns: for text area controls, allows you to specify the width in
characters and the height of the control in lines. Note that the typeface in all text
area controls in monospaced (the text looks like typewriter text). This is a
limitation of HTML, and there is no method of changing this.
Note that “My Records” filter fields will appear in the controls list as normal; however,
they will be hidden from the end user in the update form.
153
Validation Tab Sub Tab
This tab is enabled only when the HTML Element (on the Appearance tab) is an entry or
text box. This allows you to specify client side validation, which will help reduce network
traffic. Choose the validation options, and fill in the edit boxes according to the choice.
•
No Validation: self explanatory.
•
Cannot be Null: self explanatory. Be sure to fill in the Validation Alert Text
Message.
•
Must be in Numeric Range: self explanatory. Fill in at least one of the Numeric
Range options, and the Alert text. For the numeric ranges, check either lowest,
highest, or both, and fill in numeric values. If lowest is checked, than the
validation is greater than the value; highest, lesser than, and both, the value must
be in between low and high.
•
Must Be In List: this works in conjunction with the List options set in the
dictionary. You may not edit the list values here; they are provided only for
display. Should you wish to change the options you must change the dictionary.
•
Alert Text Message: this provides you with the ability to type in a string, which
will be presented to the end user in a message (or popup) box.
•
Must Be In File: allows you to specify a primary/foreign key relation as set in the
Clarion dictionary. You must additionally choose a select browse from the
dropdown list. This behavior (on an entry field or HTML input) mimics the Clarion
Lookup behavior. It automatically populates a select button next to the entry field.
154
The end user may then press the button, choose from the select browse popup,
and the entry box then receives the proper value according to whichever row in
the select browse the end user chooses.
You must manually choose the proper select browse for all the “Must be in File”
columns which appear in the update form; the procedures dropdown list will
default to the first browse in the application tree. If you forget to make a choice, it
is likely that the lookup button will display an entirely different browse in the
popup, one which may not even contain “clickable” fields from which to choose a
value. You must also apply the browse extension template to the Select Browse
procedure in order for Clarion/ASP to generate an ASP page for the select
browse.
You may specify a range limit for the select browse, utilizing the current value of
any of the entry fields in the current update form, matching it to a column in the
select browse. As an example, if the select is to choose a product ID, and the
end user has already specified a category ID, the select browse can range limit
to that category ID. Press the Insert button in the “Lookup from File” tab to
choose the source and target columns.
The Value to Pass dialog allows you to select a source column. This will call the
select browse with a WHERE limiting the browse to only those rows that match
the current value of that field on the update form. You must also specify the
target column of the select browse whose value should match this column. You
may have to insert the related table into the field chooser dialog.
155
Select Options Sub Tab
This sub tab is displayed only if the HTML Element (on the Appearance tab) is a SELECT
(listbox). As an alternative to placing a link to another browse to perform a “Select”
lookup, you may use a file loaded list box for your control (selecting it in the HTML
Element for Insert choice on the previous tab).
To initiate the automatic use of this feature (i.e., so that Clarion/ASP supplies it when you
apply the template extension to the form), place a FileDropCombo or a FileDropList into
the window. Clarion/ASP will then add the column in the related table to the controls list.
The HTML element will appear as a combo.
156
The Combo Options Sub Tab offers these options:
•
Unique ID Column: the column in the related table providing the unique value by
which to identify a choice selected from it.
•
Value Column: the column in the related table providing the value for the target
column in the form’s primary table.
•
Display Column: the column in the related table from which you which to display
data for the user to select.
•
Target Column: the column in the form’s primary file into which you wish to save
the value selected by the user from the related table.
•
Lookup SQL: if you’ve placed the template as above, you’ll see the SQL
statement to retrieve the values from the related table. In some cases it may be
necessary to edit this statement.
Form Options/Custom Controls Tab
The Custom Controls tab allows you both to specify that additional non-data columns
should appear within the form, and their properties. They may appear as images or
strings. To insert a column, press the insert button and define its properties.
To review the custom control properties, select a control from the list and press the
Properties button. This presents the Controls dialog, which contains the two sub tabs and
options. On the appearance tab:
•
Populate: this checkbox indicates that you wish to generate code for this custom
control.
•
Control Name: merely provides a convenient way to reference this column.
157
•
Caption: provides for a label which appears to the left of the field.
•
Control Location: specify that it appear either at the top of the form or at the
bottom of the form.
•
Populate From: specify static text (including null) or a session variable.
•
Enter Display Text: enter the text the end user should see, or a null string (leave
it empty) should you wish to display a graphic.
On the Actions tab:
•
Create this as a Link: specify the link type (procedure or custom) or not as a
link. In general, not creating a link is simply a means to populate a picture on the
form that doesn’t do anything. To populate a picture that leads the user to
another page, specify a procedure or custom link.
•
Pass this Data: allows you to pass the value of this control to a procedure.
•
Data Column to Pass: allows you to define which column from the form contains
the data to pass.
•
Session Variable to Pass: allows you to define a session variable to pass to a
procedure.
•
Static Entry: allows you to pass a string to a procedure.
•
Additional Parameters: allows you to pass additional parameters when
specifying a procedure link with static entry. Fill in in the format
parametername=value, or parametername1=value1&parametername2=value2.
•
Procedure Link: to enable the link to open an update procedure (or another
procedure, for that matter), check the “Procedure Link” box and specify the name
of the procedure from the dropdown list. Remember to apply the ASP form
procedure to the procedure you select. Indicate in the second dropdown box the
action to apply to the procedure: whether it’s to view data only, or to add, edit, or
delete a record, or to list data, as in the case of opening up a browse on a child
file.
•
Type of Procedure: specify the type of Clarion/ASP the target procedure is (list,
add, edit, or delete).
•
Custom Link: allows you to add an HTML, VBScript, or Jscript link in the
Custom Link edit box below. You have complete control of the link, which means
that you may specify custom tags such as Flash files.
158
You are responsible for everything starting with <A> to the </A> tags for this link.
You may concatenate strings and VB functions, and reference session and data
variables using VB Script functions.
It’s important to note that the text you enter in this box will be temporarily stored
in and ASP string variable, and therefore will be surrounded with double quotes.
The code surrounding yours will appear with yours as:
mylink = “ YourText/CodeGoesHere “
This means that if you mix string and functions, you must watch your
concatenation. If your custom link is (1) string only, just type your string and not
worry about the quotes:
MyString
If your custom link is (2) a string with a function concatenated behind, don’t forget
to close the opening quote, concatenate your function, and then open the
following quote:
Mystring” & MyFunction(param) &”
If your custom link is (3) a function with a string concatenated behind, don’t forget
to close the opening quote, concatenate your function, and then don’t close the
following quote:
“ & MyFunction(param) & “mystring
If your custom link is (4) a function only, don’t forget to close the opening quote,
concatenate your function, and then close the following quote:
“ & MyFunction(param) & “
If you have several elements, just remember where the quotes will be.
To reference a session variable, use the VBScript function SESSION(). To
reference a data element in the current form, use a VBScript function to return it
from the recordset: oRStablename(“fieldname”). You may use text functions to
trim and insure against returning a null variable, as in:
MID(TRIM(oRStablename("fieldname")),1,50).
<a href='BrowseProductsList.asp?WHR=dbo.Suppliers.SupplierID1=" &
MID(TRIM(oRSSuppliers("SupplierID")),1,50) & "'><img
src='/IMAGES/products.GIF' width='32' height='32 alt='Products'
border='0'></a>
Because the custom link options are almost completely free form, they serve as
very nearly a way to place embedded VBScript in your applications.
•
Image Button: press to provide details for displaying an image in this cell.
159
If you’ve chosen to display an image in this column, you must fill out Image
dialog after pressing the button:
•
Populate From: specify whether the image resides as an external file or a binary
column in the database. Note that Clarion/ASP has tested binary images stored
in the MS SQL Server database.
•
File Name: if the Populate From option points to an external file, specify the file
name. An example use of a static image might be a small pencil image,
symbolizing a link to an update form. Remember that the file name must be
either relative to the application’s web directory, or to the web root directory.
•
ID Value Column: if the Populate From option points to an image stored in the
database, specify the unique ID column for the row.
•
Table With Image: if the Populate From option points to an image stored in the
database, specify the column containing the image. Making this a separate
option, allows the DBA to store the images in a table separate from the table
used for the browse.
•
ID Column: if the Populate From option points to an image stored in a separate
table in the database, specify the unique ID column for that table.
•
Image Column: if the Populate From option points to an image stored in the
database, specify the column containing the binary image data.
•
Image Type: if the Populate From option points to an image stored in the
database, specify jpg, gif or png.
160
CLARION/ASP ASP Embeds
161
Ch. 8: ASP Embeds
The Clarion/ASP template provides the developer with the opportunity to write their own
VBScript, ADO and/or SQL code (dependent upon the embed selected) which will
execute inside and along with the code that Clarion/ASP generates, without fear of the
developer’s custom code being overwritten at generation time.
Clarion/ASP accomplishes this through embed points in the browse and form procedures.
The developer chooses an embed point (each is described below), and presses an Insert
button. The source code editor appears, and any VBScript added will be saved in the app
file.
In conjunction with user defined template symbols (which the developer is responsible for
inserting into the run time templates), the source code is executed when the page is
processed, and the output of the developer code (as assigned to the user defined
variable matching the template symbol) is merged into the output page, for the end user
to see.
The developer adds any user defined variable on a tab in the global extension;
Clarion/ASP inserts session variable declaration in the appdata.asp file, which means
that the variable and its value can be accessed by every page that executes. We suggest
using a prefix to your variables such as ud_ (user defined), as in ud_MyVariable. This
could make it easier to understand your generated pages and avoid name clashes. As an
example declaration:
IF IsNull(SESSION("ud_myDataVar")) THEN
SESSION("ud_myDataVar") = ""
END IF
In the code above, we first check that there’s not a variable already declared (since this is
called by every page), and if not, then we declare it.
As another example, the developer may declare a user defined template symbol called
ud_MyVariable. The developer might then insert a column into the runtime template for a
browse, and place the corresponding symbol there. The symbol should be the variable
name preceded and suceeded by an @ sign, as in @ud_MyVariable@.
Continuing the example, within the embed tree the developer locates the node labelled
“After start build (html) rows.” The end user inserts code that calculates whatever the
value should be for ud_MyVariable, and assigns it. (Remember that the ASP code written
by the developer has access to the values in the current record; thus, a running total, for
example, can be coded. The developer should also recall that they should destroy any
objects they create. Session objects may also be created and used).
162
At run time, that code executes, it gets merged, the value appears alongside the other
values in that row, and in all the other rows of the browse, according to what the proper
value should be. Other embed points are available; the embed point within a browse row
was just an example.
The templates exercise no limits on the ASP code you insert. You may, for example,
reuse a connection object, create a new SQL statement and recordset object, and add,
say, a count and grand total of all orders for a customer by opening a details table and
using an aggregate query, even though the ASP page generated by the template never
opens that particular table.
Global Template Declarations
To declare a user defined variable, open the ASP global extension. Scroll to the tab at
the extreme right called “User Data.” Press the Insert button and enter the user variable
name in the User Data dialog. Do not add @ signs to the variable name.
Assuming the developer wishes to display the results of their code within a page, the
developer or web designer edits the desired runtime template and inserts the
@variable@, i.e., the variable name surrounded by the @ sign at the appropriate place in
the page.
163
Accessing the Embed Points
To access the embed points, the developer selects a browse or form procedure with the
Clarion/ASP extension already populated, double clicks the embeds node in the right
hand pane of the Application tree, or right clicks the procedure in the left pane and
chooses embeds from the popup menu, or opens the Procedure Properties dialog and
presses the Embeds button.
By expanding the list of Embeds, the developer may then locate the top level
Clarion/ASP embed node. The nodes underneath represent the embed points.
To insert a new piece of code, the developer may select a CODE node underneath the
node with the description of the execution point desired and press the insert button. To
edit an existing embed, the developer may double click the node showing the first line of
their code. The Select Embed Type dialog appears. The developer should select Source
to write ASP code. The source code editor (also referred to as the Embeditor) appears
when inserting or editing code. The code is automatically saved when closed.
To delete existing embed code, select the node showing the code and press Delete.
Remember that any embed code will be evaluated by the VBScript engine, and must
therefore be valid ASP code.
Global Embed Points
The Clarion/ASP Global extension contains the following embed opportunities:
AppData include file (this file is included in all generated asp files)
•
•
After Opening file
Before Closing file
Login include file (included in all generated file when security is enabled)
•
•
•
•
•
•
•
•
After Opening file
Merge function - Before write
Login form - Before Merge
Login form - Before UserID fail Merge
User Table - Before closing
Before Password fail
Before User Level fail
Before Closing Login file
164
Browse Embed Points
The Clarion/ASP browse extension contains the following embed opportunities:
Connection Object
•
•
After Opening the Connection Object
Before Closing the Connection Object
Recordset Object
•
•
•
•
After Opening the RecordSet Object
After Starting to Build the Data Rows (this refers to the loop for each record
within the browse table, during which Clarion/ASP gets the contents of each field,
formats it, and stores it in the symbol for output. Use this embed point when
using a variable that should display a different value for each row of the browse
table. This allows you to execute your code before the first column value is
assigned; the record set is already open at this point).
Before Ending the Building of Data Rows (same as above, except after all the
column values have been assigned).
Before Closing the RecordSet Object
165
Merge Call
The merge call refers to the point at which the ASP code replaces the symbols in the
runtime HTML template with data values from the row. This allows, for example, the
ability to calculate a user defined variable which is to display in the page.
•
•
•
Before the Merge Call
Inside Merge Before Token Assignments Call
After the Merge Call
Form Embed Points
The form embeds have four separate subnodes for the four update modes: Add, Edit,
Delete and View. You may see the implementation of this when looking at the asp
directory, and seeing four separate pages for each procedure, in the format
UpdateProcedureNameMode.asp, with mode being “Add,” “Edit,” “Del,” and “View.”
Should the developer wish the same code to execute on more than one mode, the
developer must copy the code from one to the other.
Moreover, the Add and Edit modes each have two “phases:” Builder and Processor. You
may see the implementation of this when looking at the asp directory, and seeing two
pages each, ending in “Add.asp”, “AddX.asp”, “Edit.asp”, and “EditX.asp.” The page
without the X “builds” the html interface for the end user, in effect, retrieving the data and
presenting the entry controls. Hence, this page is called the “Builder.” The “X” page
receives the edits and processes them, submitting the update and providing the status
message with the results, and is called the “Processor.”
The embed opportunities in the form procedures can be organized as follows:
Connection Object
This allows the developer to insert code before and after connecting to the database,
allowing, for example, modifying the connection string.
•
•
•
After Opening the Connection Object
Before Closing the Connection Object
Before Executing the Delete (Delete mode only)
Recordset Object
This allows the developer to insert code before and after accesses to the record set,
allowing, for example, calculation of values for hidden fields, such as extended totals,
before saving.
•
After Opening the Recordset Object
•
Before Closing the Recordset Object
•
Before the Update (Add and Edit modes only)
166
•
After MoveFirst (this executes after opening the recordset and moving the cursor
to the first record; Edit and View modes only).
Merge Call
•
•
•
Before the Merge Call
After the Merge Call
Status Merge Call (Delete Only)
The merge call for a delete procedure has no interaction with an HTML runtime template;
however, the status message that appears is indeed a “merge.” This embed category
provides the developer with the opportunity to insert code before and after the status
message which appears at a delete operation.
•
•
•
Before Status Merge Call
After Status Merge Call
167
Examples
Form Embed
The example below modifies the customer view only update form from the Orders
example (see the Annotated Example book). The custom code uses the current
connection, declares a new recordset, defines the SQL select using the current customer
value, opens the Orders table (which otherwise would not have been open), retrieves the
orders for that customer, sorts them by date descending, gets the first (most recent) date,
assigns it to the user defined variable, then closes the record set. In the runtime template,
a symbol corresponding to the variable is placed at the bottom of the form, and at
runtime, the most recent order for that customer appears.
In effect, your custom code therefore performs a “related” task to that performed by the
Clarion/ASP procedure. It could just as easily have called a stored procedure, done some
other maintenance, etc.
Step One: Define the User Variable
•
Press the global extensions button.
•
Select the ASP extension.
•
Select the User Data tab.
•
Press the Insert button.
•
Name the variable to be used (ud_lastpurchase), press OK and return to the
application tree.
Step Two: Add the Code
•
Select the UpdateCustomers procedure in the application tree. Right click and
choose Embeds from the popup menu.
•
Locate the Clarion/ASP view mode nodes in the embed tree.
•
Select the ViewMode/BuilderPage/RecordSetObject/AfterMoveFirst/Code node
and press Insert.
•
Select Source Code/Source.
168
We’ve commented the embed code (note that should you wish to cut and paste it into the
embed point you must clean up any word wrapping!):
' display last purchase date
' declare a new recordset and SQL string variable
' use some unique prefix to prevent name clashes
' with generated variable names
'
' Declare the new record set variable and the string
' for the new SQL select statement
DIM ud_oRSTemp, ud_MySQL
' Prepare the record set
SET ud_oRSTemp = Server.CreateObject("ADODB.Recordset")
' Initialize the SQL select statement
' Concatentate the current customer ID from the Customers recordset
' which is already open. Do not forget that that value is a string
' so you have to add the single quotes!
ud_MySQL = "SELECT dbo.Orders.OrderDate FROM dbo.Orders WHERE
dbo.Orders.CustomerID = '" & _
oRSCustomers.Fields("CustomerID").Value & "' ORDER BY
dbo.Orders.OrderDate DESC"
'
' Open the recordset using the existing connection object
' and move to the first record
ud_oRSTemp.Open ud_MySQL , objCN, adOpenStatic, adLockReadOnly
ud_oRSTemp.MoveFirst
' Test that it is not empty otherwise the customer never ordered
' anything and display the word never
IF (IsEmpty(ud_oRSTemp.Fields("OrderDate").Value) OR
IsNull(ud_oRSTemp.Fields("OrderDate").Value)) THEN
ud_LastPurchase = "Never"
ELSE
ud_LastPurchase =
FormatDateTime(ud_oRSTemp.Fields("OrderDate").Value, vbShortDate)
END IF
' Do not forget to clean up!
ud_oRSTemp.Close
SET ud_oRSTemp = NOTHING
•
Save the embed.
•
Within the extension properties for the procedure, check the “Do Not Generate
HTML” on the overrides tab (you must now edit the runtime template, and you
don’t wish to overwrite the changes at the next regeneration).
169
•
Save the .app and generate the ASP source.
•
Open html\UpdateCustomersView.htm in your HTML editor.
•
Add a symbol (perhaps at the bottom of the current form) for
@ud_lastpurchase@. Note that the ASP merge routine is case sensitive, so it
must match your declaration. If you wish it to match the rest of the fields on the
view form, be sure that to use the “input” class. Add a prompt, such as “Last
Purchase” to the runtime template, and optionally use the “label” class for the
prompt.
•
Deploy and test. The end result should look something like this:
Additional Form Embed
Since it’s a useful code snippet, and to better aid your understanding, the following code,
inserted at the same point above, and using a user defined variable called
ud_SumPurchases, queries the necessary tables and places the sum of all this
customer’s purchases (from the Order Details) into that variable. As before, we apologize
for any extraneous word wrapping:
'
'
'
'
'
display total purchases
declare a new recordset and SQL string variable
use some unique prefix to prevent name clashes
with generated variable names
170
' Reuses the record set variable and the string
' for the new SQL select statement from the last embed
' DIM ud_oRSTemp, ud_MySQL
' Prepare the record set which was previous set to nothing
SET ud_oRSTemp = Server.CreateObject("ADODB.Recordset")
' Initialize the SQL select statement
' Concatentate the current customer ID from the Customers recordset
' which is already open. Do not forget that that value is a string
' so you have to add the single quotes!
ud_MySQL = "SELECT SUM([Order Subtotals].Subtotal) AS SumTotal,
Orders.CustomerID " & _
"FROM Orders INNER JOIN [Order Subtotals] ON Orders.OrderID =
[Order Subtotals].OrderID " & _
"WHERE Orders.CustomerID = '" &
oRSCustomers.Fields("CustomerID").Value & _
"' GROUP BY Orders.CustomerID"
' Open the recordset using the existing connection object
' and move to the first (and presumably only) record
ud_oRSTemp.Open ud_MySQL , objCN, adOpenStatic, adLockReadOnly
ud_oRSTemp.MoveFirst
' Test that it is not empty otherwise the customer never ordered
' anything and display the word none
' and use the vb format currency function with 2 decimals
IF (IsEmpty(ud_oRSTemp.Fields("SumTotal").Value) OR
IsNull(ud_oRSTemp.Fields("SumTotal").Value)) THEN
ud_sumPurchases = "No Orders"
ELSE
ud_sumPurchases = FormatCurrency(ud_oRSTemp.Fields("SumTotal").Value,
2, 0 )
END IF
' Do not forget to clean up!
ud_oRSTemp.Close
SET ud_oRSTemp = NOTHING
171
Browse Embed
The example below provides a line item total for the Order_Details table of the MS SQL
Server Northwind sample database. The fields used in the example are Quantity,
UnitPrice and Discount (Quantity times UnitPrice, minus Discount, equal the
LineItemTotal). Should you wish to create an equivalent example, wizard an application
on this table, set the Order_ID field as the range select (be sure that your URL includes a
valid ?ID1 parameter, such as ?ID1=10248), apply the global and browse template, and
then follow these steps:
Step One: Define the User Variable
•
Press the global extensions button.
•
Select the ASP extension.
•
Select the User Data tab.
•
Press the Insert button.
•
Name the variable to be used (ud_LineItemTotal), press OK and return to the
application tree.
Step Two: Add the Code
•
Select the BrowseOrder_Details procedure in the application tree. Right click and
choose Embeds from the popup menu. The “concept” for this example is that you
wish to calculate the value at the point for each row at which the code is ready to
place the values into the symbols in the HTML embeds, hence, the record set is
open to each of the records in turn, and your embed code can do a calculation on
the fields.
•
Select the RecordSetObject/AfterStartBuild/Code node and press Insert.
•
172
We’ve commented the embed code (note that should you wish to cut and paste it into the
embed point you must clean up any word wrapping!):
‘ First check that Quantity isn’t 0
IF oRSOrder_Details.Fields("Quantity").Value > 0 THEN
‘ Now you can get the recordset variables and calculate
ud_LineItemTotal = (oRSOrder_Details.Fields("Quantity").Value *
oRSOrder_Details.Fields("UnitPrice").Value) oRSOrder_Details.Fields("Discount").Value
ELSE
‘ otherwise, clear the variable
LineItemTotal = ""
END IF
Step Three: One More Line of Code
To make this work properly in case you’re at the end of the table, have only three rows of
data, but ten rows of “browse,” you’ll need to make sure the variable is cleared after each
pass. To do so:
•
Select the RecordSetObject/BeforeEndBuild/Code node and press Insert.
•
Type the following code. All this line does is clear the variable after we’ve merged it into
the form:
ud_LineItemTotal = ""
173
The simple browse below contains no customizations, data formatting nor style sheet
customizations, but merely demonstrates the code. Note that the HTML runtime template
was edited with an HTML editor, a column inserted at the end with no style tag, and the
symbol @ud_LineItemTotal@ placed in the cell in that column.
174
CLARION/ASP HTML Includes
Ch. 9:
175
HTML Includes
Clarion/ASP includes the ability to specify include files which will be incorporated into the
runtime HTML template, at the time the data is merged into the page. This provides for
server side include functionality. The include file may contain either HTML or javascript
(for client side execution).
Though not limited to only these three, the general areas of functionality that these
include points may provide for are:
•
Javascript function libraries for client side execution.
•
Standard “boiler plate” HTML sections such as company contact information or
even banner ads, which allow for a single update throughout a site whenever
something changes.
•
An almost “componentalized” approach to the HTML layouts for your application.
Through use of the HTML includes you can include different sections above and
below the Clarion/ASP elements on a procedure by procedure basis, allowing
you to provide related functionality to any procefure, based on the procedure.
Understanding the Process
The actual mechanism simply opens the include file and writes it into the runtime HTML
template at the time the end user requests the document; however to understand when
and where the include occurs will help you to use this feature to extend your applications.
To take advantage of this feature, your design time template must include the HTML
comments highlighted below. If you don’t use the includes feature, then they’re not
required. Note that it’s a simple matter to take a “blank.htm” file, auto generated by the
templates, and cut and paste the lines into an existing design time HTML template.
Finding the correct places in your design time template to insert the comments should be
a simple matter; just locate the proper tags (<html>, <head>, <title>, <body>) which will
no doubt be located in your design time template.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>

<head>

<title></title>

</head>
<body>


@Clarion/ASP@

176

</body>

</html>
The illustration below displays the template interface:
A note on the <bg> tags: the “after open” and “before close” <bg> tags in the template
interface refer to tags which will be inserted at the time the runtime templates are
generated (when you run the Generate All command in the development environment),
and are not present in the design time template. This allows you to provide for an include
inside the portion of the page which will include the Clarion/ASP components.
The template interface includes a tab on the Global extension called Includes. It provides
edit boxes corresponding to all the insertion points above. Type in a file name in a box or
boxes. Remember that the path must be a relative reference to the location of your asp
page within your web. (For example, should you place a file called myinclude.htm in the
project/asp/html directory, then the box should read html/myinclude.htm.
At the time that the end user requests the asp page that corresponds to the HTML
runtime template page, the script in the asp page will be executed, the merge function will
CLARION/ASP HTML Includes
177
read the runtime template and any “included” files, placing the content of the included
files into the spot chosen, and then turn the combined document over to IIS to output the
page.
What to Use it For
The most obvious uses are HTML boiler plate, javascript function libraries, include files
with meta tag keywords, and server side commands:
•
For boiler plate such as a standard site footer, simply include the file at the
@BODY_BEFORE_CLOSE@ symbol. Some may prefer to place the static
HTML directly in the design time template; it’s simply a matter of preference on
the developer’s part. Many web designers prefer to use includes for standard
boiler plate elements, and if that is the standard operating procedure at your site,
it’s a good idea to do it this way, and not incorporate it in the design template;
else, you must regenerate when the boiler plate information changes.
Should you wish to merely experiment, feel free to include the index.htm file
which will be automatically generated by Clarion/ASP, and you’ll see a “table of
contents” below your Clarion/ASP elements.
•
For java script function libraries, simply make sure that the <script> tags are
present in the include file, and place the include at the
@HEAD_AFTER_OPEN@ include. Note that should you wish to include more
than one file in one include point, you’ll create an include file that merely includes
the other include files, and that will be the file you place in the template interface.
•
For non printing HTML items such as meta tags, it may very well be the case that
you wish to define these on a procedure by procedure basis rather than on a
global basis (which might normally be done in the design time template).
Remember that you may override the includes on a procedure by procedure
basis, allowing you to create an include file only with the meta tags that you wish
for a specific procedure. By using the includes, the developer need not edit the
individual runtime HTML template for the procedure (saving the necessity of
editing four templates for an update procedure). The keyword usage of the meta
tag might typically be something like the following, and should be placed within
the <head> tags:
<META NAME =”keywords” CONTENT=”lions, tigers, bears>
It may also be the case that you wish to set cookies on a procedure by procedure
basis, which can also be done with an include, such as:
<META HTTP-EQUIV=”Set-Cookie”
CONTENT=”cookievalue=xxx;expires=Tuesday, 31-Dec-02 16:14:21 GMT;
path=/”>
178
Note that IIS does not support HTML server side commands and functions such as those
typically used to obtain system environment variables such as the current time, the end
user’s IP address, and so forth. The preferred means to do this in IIS is ASP scripting.
You can access these through vbscript embed points, and output to a user defined
variable.
Final Notes
The procedure overrides provide exactly the same insertions as the global; the only
difference is that the explanatory text does not appear above the edit boxes. Remember
to check the override box to enable access to the sub tab.
CLARION/ASP ASP Source Procedure
179
Ch. 10: ASP Source Code Procedure
The function of the ASP Source Procedure template is to allow you to execute VBScript
code in-between pages. This provides for any number of possible applications that may
not be desired to execute until after a procedure is finished, such as redirection to other
pages of interest to the end user based on the outcome of the previous page, updating
counters, analysis pages which might summarize data after the end user has entered
data... because the developer may place any code whatsoever in the source code
procedure, you may use the source code procedure for whatever you can think of.
This is not meant as a substitute for triggers, but if the application uses MS Access, for
example, you may utilize the source code procedure for trigger-like functionality.
Additionally, the source code procedure provides an alternative to writing VBScript
embed code in multiple procedures, allowing you to place the code in a single page,
though this may not always be useful should the code need to reference elements such
as recordsets, which would still be in the procedure.
Application
To create an ASP source code procedure, add a procedure to the Application Tree by
selecting an existing procedure, then choosing Procedure > New from the development
environment menu. Name the procedure and choose Source as the type of procedure.
Once the Procedure Properties dialog opens, press the Extensions button, and apply the
ASPSource extension. (Note: you can apply the extension to existing procedures; we
simply suggest a new procedure for organizational purposes, and to make it easier to
remember where you placed the code.)
180
Once the extension is applied, you will see a new embed node called Clarion/ASP for the
procedure, and you may use the Embeditor to write the ASP code.
At the time you apply the extension, you will also note a “page to return to” box. This will
be the page that the end user is redirected to after the source code procedure page
executes. This can be overwritten via a page parameter (?toURL).
181
At generation time, the page generated will be named in the format
ProcedureNameSource.asp. Note that a default security level of 1 is applied to the page,
should security be applied to the application. To change the security level, edit the
generated code.
Usage
The normal means of routing the end user to the source code page is either linking to it
as a normal HTML link from within the referring page, or setting the source code page as
the “page to return to” for the Actions of an Insert, Edit, or Delete page. The latter method
is more appropriate, since this is designed as something to execute between actions.
Assume a case in which a session variable is used to keep a running total of daily sales
by a particular representative for that session. It would be a simple matter to insert
embed code to display a user variable at the top of every page, and query the database
each time a new page displayed; but there’s no necessity to tax the DBMS with a query
which returns the same result every time except if an insert, edit, or delete was made
(this assumes no other operator may change the representative’s records). In this case,
the query could be stored as a source procedure, the result stored in the session
variable, and the source procedure could be called only after an edit change or delete.
The procedure to accomplish this would require the following steps:
•
Declare a the user defined variable for the running total, such as
ud_MyRunningTotal. When added in the global extension, Clarion/ASP
automatically creates the session variable.
•
Insert the @ud_MyRunningTotal@ symbol in the design time template, assuming
that the intention is to display the running total on every single procedure. (for
example, in this case the designer might create a box in a top corner of the page
in a bright color, and in the box, display the running total).
•
Create a source code procedure (named, for example, DisplayMyRunningTotal).
Set the “to URL” to whatever page is desired to be viewed after an operation, for
example, “MyStartPage.asp.”
•
Apply the ASP Source Code extension to the procedure.
•
Add embed code to the procedure declaring a connection object, running the
query, and storing the return value in the session variable (note: we apologize for
any word wrap problems):
182
‘
‘Declare connection object, recordset, and query string
DIM objCN, oRSMyRecordSet, mySQL
‘
' create the connection object
Set objCN = Server.CreateObject("ADODB.Connection")
objCN.ConnectionTimeout = Application("app_ConnectionTimeOut")
objCN.CommandTimeout = Application("app_CommandTimeOut")
objCN.CursorLocation = Application("app_CursorLocation")
objCN.Open Application("app_ConnectionString")
CheckError
‘
‘Create the record set
SET oRSMyRecordSet = Server.CreateObject(“ADODB.Recordset”)
‘
‘ store the query in a string; assume this is representative # 123
‘ if this were a real application, we’d probably store the rep ID
‘ in a session variable and concatentate it to the query string!
mySQL = “SELECT SUM(ExtendedTotal) AS RunningTotal FROM dbo.ORDERS WHERE
dbo.ORDERS.RepID=123”
‘
‘ Open the recordset using the connection object
‘ and move to the first (and only) record
oRSMyRecordSet.Open mySQL , objCN, adOpenStatic, adLockReadOnly
oRSMyRecordSet.MoveFirst
‘
‘ Use the vb format currency function with 2 decimals
‘ and store it in the session variable
Session(“ud_MyRunningTotal”) =
FormatCurrency(oRSMyRecordSet.Fields(“RunningTotal”).Value,
2, 0 )
‘
‘ Clean up!
oRSMyRecordSet.Close
SET oRSMyRecordSet = NOTHING
‘
•
Save the embed, and then open the update procedure for Orders. On the Actions
tab, set the “Page to return to” for insert, update, and delete to (in this case)
DisplayMyRunningTotalSource.asp.
•
Generate and test.
183
184
CLARION/ASP Style Sheet Editor
185
Ch. 11: Style Sheet Editor
The style sheet editor allows you to create your own style sheets and specify the fonts,
formatting, alignment, and positioning formatting for the parts of the tables and forms
you’ll be creating with Clarion/ASP. The concept is very simple: each of these parts has a
style class name which we’ve defined. The style sheet editor lists all the parts and allows
you to set the appearance options. These options are stored in a file (with an extension of
.CSS) for your use. You may make a style sheet in which the table background is blue.
You may create a different one for which the style sheet is red. It may be that you use the
one style sheet for one project, and the other for another. Or you may specify that one
browse use the first, and a second use the other. You may specify that two applications
use the same style sheet (just give it the same name and copy it to the styles directory),
promoting a uniform look. The only things which don’t change are the style classes
themselves; just the formatting options associated with them, which can vary from style
sheet to style sheet. You can create as many style sheets as you wish.
Note that the Annotated Examples manual provides a great deal of detail, including step
by step instructions for matching the colors and other formatting options used in the
sample applications.
For creating pages which seamlessly merge into an existing site, we recommend that you
collaborate with your web designer and have on hand the RGB values for the preferred
site colors and the font names used at the site. You may then duplicate those using the
style sheet editor.
Overall, the process by which you work with the style sheet editor is:
•
Create a new style sheet by name within the global extension template.
•
Use the style sheet editor to walk through the list of browse and form
components, and choose your formatting.
•
Deploy the .CSS file to your site when deploying the .ASP pages.
•
Should you wish to change only the site appearance, you may create another
.CSS sheet at any time, and simply place it at your site, overwriting the original
style sheet.
•
If you wish to use a style sheet from one project in another project, you must
copy it into the current styles directory and enter the style sheet file name, plus
the name of the data row style(s) into the new project. Turn off CSS generation in
the new project.
To begin the process of editing your style sheet, open the ASP global extension template,
and on the global tab press the Style Sheet Editor button.
186
If editing an existing style sheet, select it and press Properties. To create a new style
sheet, press the Insert Button. To delete an existing style sheet, select it and press
Delete.
After choosing Insert or Properties, you may now format the individual elements in the
Style Sheet dialog.
There is one important thing to remember when choosing colors, through this dialog.
Because we’re using the default color pickers within the Clarion template interface, at the
top of the color picker dialog you’ll see the choice for Windows component colors (such
as the window background, button highlights, etc). As you know these are valid choices
for a Windows program, but invalid for an HTML application, unless using Cascading
Style Sheet specification 2.0, which means that older browsers will not be able to resolve
that color choice. Be sure to choose either a color box or a custom color. The template
system will resolve your choice to a hexadecimal value (red/green/blue).
187
Style Sheet Tab
The first tab provides an option of changing the style sheet name plus the ability to set
hyperlink formatting.
•
File Name: type in a valid file name. It will automatically receive a .CSS
extension.
•
Hyperlinks: you’ve probably observed that the default hyperlink colors for most
browsers are blue for unvisited, red for visited, and that the link appears
underlined. Other than that, a plain text link simply appears as plain text.
There are four possible states of a hyperlink which you may format individually.
For each state a button appears, and you may choose the exact formatting in the
subsequent dialog. The states are:
•
Normal: The hyperlink is unvisited, does not have the keyboard focus, and the
mouse is not over it.
•
Active: The hyperlink had keyboard focus. The normal browser behavior is to
display a dotted rectangle around it.
•
Hover: The mouse has paused over the hyperlink.
188
•
Visited:The page pointed to by the hyperlink has been visited previously.
To format each of the options, press the appropriate button (labelled for each). The dialog
which appears contains a check box which specifies that you wish to override the default
browser settings (to undo your customizations at any time, simply uncheck the box).
The formatting options for each of the above categories are as follows:
•
Color: provides access to the Color picker dialog. Select a color from the boxes
or specify a custom color. Remember that should you choose an item from the
Standard Colors dropdown, such as desktop color, that this will be supported
only by CSS 2.0 compliant browsers (browser versions 5.x and higher). Please
note also that in some browsers, and in most operating systems, if the color
depth is not set to 24 or 32 bit, there may be color substitutions.
Note that the color value returned by the picker will be hexidecimal (the Windows
Color Picker uses decimal, but HTML uses hex), in blue-green-red order,
prepended with a zero, and followed by an ‘h.”
•
Text Decoration: this provides simple text effects, i.e., underline, over-line (line
above), line through (crossed out) and blinking text.
•
Text Transformation: this provides simple character formatting options, i.e.,
capitalize, upper case, lower case, none, and inherit (from whatever tag this tag
is embedded in, i.e., from any page, table, etc. in the default template).
•
Font Style: normal or italic. Note that “bold” is provided for via Font weight.
189
•
Font Weight: note that this setting is comparative to the default browser font
settings. Choose from normal, lighter, bold, or bolder.
•
Font Size: note that this setting is comparative to the default browser font
settings. Choose from larger or smaller, or from extra-small to double-extra-large.
Body Tag Tab
The body style is particularly important in that it sets the width plus other major aspects of
the “background area” in which the browses and forms will display. If you set the body to
only 400 pixels wide, than your forms will be no wider than 400 pixels.
This tab presents the following options:
•
Width: specify a value either in pixels (the number you wish, followed by “px”
without the quotes, or, as a percent. To specify that the body should fill the
maximum width of the browser window (or of the frame, should you place the
generated ASP page inside a frame), enter 100%.
•
Background Color: choose a color from the color picker. Remember that your
browses and forms will be placed on top of the background; therefore don’t select
clashing colors. Note: to choose no color, delete any value in this box, or type
COLOR:NONE.
•
Text Alignment: choose left, right or center.
190
•
Font Button:
Whenever you choose a font for web content, the formatting options must be
limited to what the majority of browsers will support. A web developer can’t
simply choose a font from their machine and specify it for a page element. The
end user may not have the same font. You should not even presume that fonts
that are standard with Windows, such as Arial or Times New Roman will exist on
the browser, because the browser may not be on the Windows platform.
Therefore, generic font lists can be specified, such as serif or sans-serif. Serifs
are the small hooks and curls at the ends of individual letters in some fonts. They
make fonts more readable, the theory being that the hooks and curves help the
eye move from letter to letter in a quicker motion. In the print world, traditionally,
large portions of text, such as articles usually are printed in a serif font, such as
Times, which is what this paragraph uses. Small bits of text such as headlines,
which stand out best for being “cleaner,” without the hooks, are usually
composed in a sans-serif font such as Helvetica, which is used in the section
headlines in this document. Note: “sans” is French for “without.”
For web development, what has generally transpired is that you provide a list of
fonts separated by quotes. For example: “Times New Roman, Times, SansSerif.” The browser checks to see if Times New Roman is present on the system.
If not, then it checks for Times. If there is still no match, then it checks the
browser preferences for the default serif font, of which there will certainly be one.
You can specify anything in such a font list, but in the real world, given the
penetration of the Windows platform, most font lists have settled on a few
Windows names such as Arial and Times New Roman.
Clarion/ASP adds Tahoma and Verdana to these. Tahoma comes with Microsoft
Office, and so is present on many machines. Verdana was specially designed as
a screen font (i.e., it looks good at low resolutions), and is distributed with
Internet Explorer, and thus present on even more machines than Tahoma.
191
The following options are present in the Font dialog:
•
•
Style: choose normal or italic.
•
Weight: choose lighter, bold or bolder.
•
Size: choose smaller or larger, or between extra-small to double-extra-large.
•
Family: as described above. The choice lists are: “Verdana, Arial, Helvetica,
Sans Serif,” “Tahoma, Arial, Helvetica, Sans Serif,” “Arial, Helvetica, Sans Serif”
“Times New Roman, Times, Serif,” “Courier New, Courier, monospace,” “serif,”
“sans-serif,” “cursive,” or “monospace.”
You will see the Font dialog at many points within the style sheet editor.
•
Margins Button:
The margins button sets up the spacing on the side of the text, top of page,
bottom of page, and left/right sides of the page.
You may choose a value from zero to ten in pixels for each side.
192
Background Class Tab
The “class” refers to the browse and form tables; in other words, this tab sets the base
options for the tables which display your data.
This tab presents the following options:
•
without the quotes, or, as a percent for the data background area.
•
Note that the color value returned by the picker will be hexadecimal (the
Windows Color Picker uses decimal, but HTML uses hex), in blue-green-red
order, prepended with a zero, and followed by an ‘h.”
Data Tab
All your data is presented as a table within a table. The outside table is governed by the
Background Class, described previously. Placing tables within tables is a solution to the
limited page layout possibilities of HTML.
193
Therefore the Data tab is particularly important in that it provides the most immediate
place setting for your data. Within this tab are buttons that format all the data elements:
header (a header for the entire table), column headers, data rows, footer area (for
navigation) input labels (prompts), and inputs (the entry boxes and data controls
themselves).
Each of the buttons leads to additional options appropriate to formatting each of the
elements in turn.
•
without the quotes, or, as a percent for the actual data area of the HTML table.
•
Color: choose a color from the color picker. Remember that your browses and
forms will be placed on top of colors selected previously for other elements;
therefore don’t select clashing colors.
Borders Button - Data Tab
This formats the rules (or lines) that surround the data grid. You may format the top,
bottom and sides separately, specifying:
194
•
Width: specify thin, medium, thick, or zero to ten pixels.
•
Style: specify dotted, dashed, solid, double, groove, ridged, inset, outset or none.
•
Margins Button - Data Tab
The margins button sets up the spacing on the side of the data grid, top, bottom, and
left/right sides.
You may choose a value from zero to ten in pixels for each side.
Padding Button - Data Tab
This sets interior margins for the data cells. You may choose a value from zero to ten in
pixels for each side. Note that padding differs from margins, in that padding values may
be added to the normal height and width values for the particular element, whereas
margins may not, depending on the element and possibly, the browser.
195
Header Button - Data Tab
The header is the equivalent to a caption bar area, in effect being the place in which the
data grid’s “title” appears.
You may set the following options:
•
Background Color: provides access to the Color picker dialog. Select a color
from the boxes or specify a custom color. Remember that should you choose an
item from the Standard Colors dropdown, such as desktop color, that this will be
supported only by CSS 2.0 compliant browsers (browser versions 5.x and
higher). Please note also that in some browsers, and in most operating systems,
if the color depth is not set to 24 or 32 bit, there may be color substitutions.
•
Text Alignment: choose from left, right, or center.
•
Font (button): choose the color, style, weight, size and family from the dialog.
This dialog is identical to other font dialogs throughout the style sheet editor.
•
Padding (button): set the inside padding for left, right, top and center in pixels
from zero to ten. This dialog is identical to other padding choices dialogs
throughout the style sheet editor.
196
Column Label Button - Data Tab
The column label is the header at the top of each column, functioning as the place where
you name the column. Note that Clarion/ASP automatically adds an up/down arrow on
the sorted column to indicate the sort order.
•
•
•
•
Data Rows Button - Data Tab
Clarion/ASP allows you to optionally format rows based upon either an odd/even order
(improves readability), or upon a conditional test based upon some value you define,
usually based upon the value in a particular column.
You must name each style option within this dialog (you may think of this as a style name
for each condition), and set the formatting options here. Within the browse properties,
you will set the conditions and choose the conditional style. The first style named in the
197
list within this dialog acts as the default formatting should you not set a condition within
the browse.
Note that these row styles can be applied to individual cells via conditional column
formatting. For example, if you wish to create a style with a red background and yellow
letters, you may specify it here.
Then, when you wish either a row or cell to stand out based upon a data value, you
specify the different style as a conditional style. Therefore, you must define at least two
styles so that one can “stand out.” If you expect to use a green bar effect, but want to
make selected cells or columns stand out, you’ll require a third data row style.
The first step is to create your style option names.
•
Insert: press Insert to create a new name.
•
Properties: press Properties to edit an existing name.
•
Delete: press Delete to delete an existing name.
•
Up/Down: you may use the up and down arrow buttons to move a style name
into the first position, which is the one that acts as the default.
•
Grid Line Size: sets the lines within the data grid. Choose between zero and
nine pixels.
198
Within the Properties for each of the style option names, you may set the following
options:
•
Name: this allows you to rename the style option name.
•
•
•
This dialog- is identical to other font dialogs throughout the style sheet editor.
•
Footer Button: Data Tab
The footer provides the background area at the bottom of the data grid or form, upon
which the navigational controls appear. You may set the following options:
•
199
•
•
•
Padding (button): set the exterior padding for left, right, top and center in pixels
Input Label: Data Tab
The input label is the prompt for your update form data controls. You may set the
following options:
•
200
•
•
•
Input: Data Tab
The input formatting options work differently for update forms vs. view only forms. In both
cases, the formatting affects the HTML table cell. For an update form, the table cell
contains not text but an HTML control. The control will take on the appearance of
whatever the host operating system specifies for that type of control; the style sheet does
not format the control. The background of the cell in which the control is contained will
adopt the appearance of the formatting options you place here. In other words, you can’t
specify the font/style/color of the text the user types inside an edit box; you will specify
the background color outside the edit box. This applies to update forms only. For viewonly forms, the html places text formatted exactly to your specifications.
The option of formatting color, etc. appears for data in update forms for three reasons: for
consistency; for those who wish to edit the cell after generating the ASP page; and most
importantly, for View Only forms and fields, which dispense with the control and simply
print the data in the cell.
•
201
•
•
•
202
Style Sheets
After defining at least one style sheet, you may press the button and choose your default
global styles from the dropdown boxes. You may override the choices within each
procedure. The style sheets specify color, style, alignment, and sizing for each of the
components which appear in the generated pages. As you will note in the chapter that
documents the Style Sheet Editor, Clarion/ASP allows you to customize the appearance
of each individual element to if not the maximum allowable with HTML, then very close to
it.
Desktop developers may have to make a slight adjustment in their thinking in regards to
differences between those controls allowed by the Windows operating system, and those
provided under HTML 4.0 standards. We have tried to highlight the most major
differences in this chapter on the Style Sheet Editor.
The choices to implement within this dialog are as follows:
•
Global: sets the global style sheet choice if no other choice is set.
•
List: sets the style sheet choice for browse procedures should the procedure not
override.
•
Form: sets the style sheet choice for update and query procedures should the
procedure not override.
•
Help: sets the style sheet choice for help text windows should the procedure not
override; though should you create your own HTML help pages, they will not
apply unless you link the style sheet and use the style names. Such a task is
much easier with an HTML editor than using a text editor.
CLARION/ASP Index
203
Index:
?WHR...................................................... 158
<a> .......................................................... 131
<A>.................................................. 136, 158
<br> ......................................................... 126
access level............................................... 35
Actions tab............................................... 144
Add Button................................................. 89
Add Procedure ........................................ 124
Additional Cell Style ................................ 134
Additional Parameters............................. 130
Additional Row Style ....................... 116, 134
Administration.......................................... 109
ADO.....................24, 25, 36, 39, 46, 97, 109
Alert Text Message ................................. 153
alignment................................................. 185
Alignment ........................................ 133, 135
All Data.................................................... 123
ALT text ..................................................... 90
Annotated Examples ......................... 37, 185
Anonymous Access............................. 44, 67
Appearance ............................................. 151
application directory .................................. 66
application object ...................................... 29
Application Protection ............................... 23
Application Timeout................................... 73
application wizard...................................... 11
Ascending/Descending Sort.................... 132
ASP Script Timeout................................... 23
Automatic Detail Link .............................. 135
Back Button ............................................... 87
Background Class ................................... 192
Body Tag ................................................. 189
Borders.................................................... 193
Browse extension template ..................... 114
Browse template ....................................... 47
Browse to Browse ..................................... 55
Builder page ............................................ 147
calendar................................................... 151
Calendar Popup ........................................ 91
Cannot be Null ........................................ 153
Caption ............................................ 151, 157
cascading style sheets .............................. 78
Cascading Style Sheets .............................. 9
CDONTS .................................................109
checkbox on query form ..........................152
child browse...............................................55
Clear Filter ...............................................123
Clear Filter Prompt ....................................90
client side validation ....................13, 31, 153
Client/Server..............................................25
Color picker dialog...................................191
Column Header Text ...............................131
column label ............................................196
Column Name..........................................135
Column to Test ........................................134
Column With Value to Return..................121
Combo Options........................................156
Command Timeout....................................98
conditional row formatting .......................115
Conditional row formatting.......................116
connection builder .....................................98
Connection Builder ............................14, 104
connection object ................................25, 82
connection pooling ....................................24
Connection Properties...............................98
connection string ...................................9, 42
Connection String......................................46
Connection Timeout ..................................98
Control Location ......................................157
Control Name ..........................................156
Cookies....................................................108
Create column as a Link..........................130
Create Detail Link......................................88
Create this as a Link................................157
Create this Column as Link .....................136
Custom Controls......................................156
custom link...............................................134
Custom Link.............................130, 131, 157
Data Column to Pass ......................130, 157
Data Columns..........................................125
data dictionary ...........................................11
Data Records per HTML List.....................88
Data Row.................................................134
database dictionary .............................10, 31
Debug mode ..............................................96
Default Cell Style .....................................134
204
Default Row Style.................................... 116
Default SQL............................................. 124
default web site ................................... 65, 69
Delete ...................................................... 143
Delete Form............................................... 54
Delete Row.............................................. 149
Design Time HTML Template ................... 75
Directory Security...................................... 67
Display Column ....................................... 156
do not populate ......................................... 10
Do Not Populate ........................................ 12
DreamWeaver ........................................... 74
Edit .......................................................... 143
email........................................................ 140
Email ....................................................... 109
E-Mail ...................................................... 106
embed point............................................. 147
Enable Buffering........................................ 23
Enable Cell Style ..................................... 134
Enable Security ....................................... 118
Enable Sorting by this Column................ 131
Enhanced ADO Error Reporting.............. 110
Enter Display Text................................... 157
Execute Permissions................................. 66
Execute Scripts ......................................... 43
Field Lookup Buttons ................................ 14
File Drop Lists ........................................... 14
file loaded list box.................................... 155
File Properties ........................................... 12
font .................................................. 185, 190
Font ......................................................... 188
Form Button Text ...................................... 93
Form Defaults............................................ 91
form extension......................................... 139
form fields.................................................. 79
Form Message Text .................................. 93
Form Primary Table ................................ 149
form template ............................................ 48
Form Titles ................................................ 93
Form Validation ......................................... 95
formatting ................................................ 185
Formatting Function ................................ 133
formatting options.................................... 185
formatting tags........................................... 27
ftp server ................................................... 74
Full Pathname ........................................... 12
generation ................................... 61, 77, 185
Generation...........................................95, 96
global extension.........................................85
global extension template..........................14
global template ..........................................46
Global Template ........................................46
Global.ASA ................................................70
GLOBAL.ASA ............................................25
greenbar ..................................................116
header .....................................................195
help..........................................................148
Help ...........................................................61
Help Link....................................................87
Help Pages ................................................97
Help URL ...........................................61, 120
Home Directory..........................................23
Hover .......................................................187
HTML controls ...........................................34
HTML design time template ......................14
HTML editor.........................................35, 75
HTML Element.........................................155
HTML Form Element ...............................151
HTML Pages..............................................96
HTML parameter .......................................81
HTML run-time template............................32
HTML template ................................9, 35, 75
Hyperlink..................................................136
hyperlink colors........................................187
ID Value Column .....................................138
Image Button ...................................137, 159
Image Column .................................138, 159
Image Sizes.............................................112
images .......................................................32
Images.....................................................111
Include in the SQL Select But Do Not
Display .................................................128
Include With Prior Column.......................128
index.htm ...................................................81
input label ................................................199
Insert........................................................143
Internet Information Server..............9, 17, 65
Internet Services Manager ........................65
ISAM databases ........................................11
Javascript ..................................................13
JOIN ................................................122, 125
key .............................................................12
Key ............................................................48
Key to Pass .............................................130
CLARION/ASP Index
LIKE......................................................... 123
link ......................................... 55, 81, 83, 134
Link............................................................ 51
links ....................................................... 9, 27
list defaults ................................................ 88
localhost .................................................... 72
Location................................................... 135
locator........................................................ 90
Locator .................................................... 123
Login Screen Text ................................... 107
Lookup..................................................... 153
Lookup SQL ............................................ 156
margins............................................ 191, 194
Maximum Characters .............................. 152
menu ......................................................... 34
merge ........................................................ 75
Microsoft Access ................................. 11, 25
Microsoft Jet Engine............................ 25, 36
Microsoft Management Console ............... 65
Microsoft SQL Server................................ 40
MS Access .............................................. 105
MS SQL Server ....................................... 104
Must Be In File ........................................ 153
Must be in List ........................................... 95
Must Be In List ........................................ 153
Must be in Numeric Range...................... 153
Must be in table ......................................... 15
Must be in Table.................................. 33, 59
My Records .........32, 35, 116, 118, 140, 152
Navigation Bar........................................... 89
nbsp;........................................................ 127
No Records Found .................................... 90
No Validation ........................................... 153
Northwind sample database.... 119, 141, 150
NT Option Pack......................................... 21
Numeric Field ............................................ 95
ODBC ........................................................ 98
ODBC database drivers ............................ 36
ODBC DSN ............................................... 39
ODBC tracing ............................................ 39
OLE DB ..................................................... 36
OLE DB provider ..................................... 101
OLE Provider for ODBC ............................ 39
Omit From QBF Page ............................. 152
Order clause............................................ 125
override ................................................... 115
Override................................................... 139
205
Padding ...................................................194
Page Naming Conventions........................82
Page Title ................................................120
parent browse............................................55
Parent Browse .........................................147
Pass this Data .................................130, 157
pixels .......................................................133
Populate ..................................................156
Populate From .................................137, 157
Populated From ...............................121, 125
popup calendar........................................112
popup window............................................97
precision ..................................................150
Primary File ...............................................48
Primary Table ..........................................122
Procedure Link ................................130, 157
Processor page .......................................147
Processor Pages .......................................31
project directory .........................................22
Provider ...................................................101
QBF Procedure........................................120
Query by Form.............................50, 54, 147
Query By Form Button...............................89
query form .................................................49
Range Limit .......................................55, 128
range select ...............................................50
Read Only................................................152
read only form..........................................144
Read Permission .......................................43
Regenerate SQL..............................124, 149
repeat add ...............................................147
Repeat Add Mode ...................................146
Request and Response objects ................29
Required Field .....................................92, 95
resultset .....................................................25
return mechanism....................................145
Return to Filtered Browse........................146
Row Style ................................................115
Rows and Columns .................................152
Run Time HTML Template ........................76
runtime user ID ..........................................98
scalable .....................................................36
Search .....................................................143
Search Mode .............................................92
secure http.................................................35
security ..............................................12, 140
Security............................................115, 119
206
Security Level.................................. 107, 143
security model ................................... 32, 105
security options ......................................... 14
security scheme ........................................ 35
select browse ...................... 57, 97, 121, 154
Select Mode Procedure........................... 121
Select Options ......................................... 155
Session Timeout ....................................... 23
session variable ................ 82, 119, 137, 140
Session Variable to Pass ................ 130, 157
SESSION() .............................................. 158
shopping cart........................................... 134
Show Help ................................................. 86
Site Title .................................................. 109
smtp......................................................... 109
SQL .............................25, 36, 122, 124, 149
SQL date/time field.................................. 127
SQL Delimiters ........................................ 105
SQL for Selection .................................... 149
Standard Colors ...................................... 191
stateless ................................................ 9, 81
stateless protocol ...................................... 29
Static Entry ...................................... 130, 157
status message ....................................... 147
status messages ..................................... 143
Status Text ................................................ 94
style sheet ........................................... 9, 202
Style Sheet ................................................ 96
style sheet editor ..................................... 185
style sheets ............................................... 32
Table Title................................................ 122
Table With Image .................................... 159
target ......................................................... 79
Target Column ........................................ 156
Target Language....................................... 86
target page .............................................. 147
template chains ......................................... 13
test/debug page ........................................ 72
Test/Debug page.......................................96
Text Alignment.........................................189
Text Decoration .......................................188
Text Transformation ................................188
timeout.......................................................35
token..........................................................76
Tool Tip....................................................151
Tool Tips....................................................90
tooltips .......................................................12
Tooltips ......................................................87
triggers.......................................................12
TRN file......................................................86
TRN files....................................................36
Type of Procedure...........................131, 157
unencrypted...............................................35
Unique ID Column ...................................156
Unique Key ......................................122, 149
Update Form........................................51, 54
URL ...........................................................49
URL parameters ........................................32
User Based Security................................106
user defined variable ...............................147
User Table ...............................................106
Validity Checks ............................................9
Value Column ..........................................156
variant........................................................29
VBScript.........................17, 27, 29, 137, 158
view ...........................................................12
View.........................................................143
View Form .................................................91
Virtual Directories ......................................22
virtual directory ..........................................65
web designer .....................................32, 185
Where clause...........................................125
Width .......................................................133
window control types .................................13
Window Size..............................................97
Windows XP ........................................40, 67

Cover Here

Transcription

Similar documents

Contact no.(M):9780893349 jalandhar city

Computer Settings For NAUTIKOS

Kuluin prep powerpoint

assistant head/upper school director ap/ib news from the academic

Mikko Hypponen Chief Research Officer, F-Secure Mikko

assistant head/upper school director ap/ib news from the academic

CLARION HOTEL ARLANDA AIRPORT

ASPects July 2012 Convention Special Issue