Php 11 Users Guide

CLARION/PHP

User’s Guide

CLARION/PHP User’s Guide 2

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. Version 1.1 SoftVelocity Incorporated 2335 East Atlantic Blvd. Suite 410 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 (1104)


Contents: Ch. 1: Introduction 7

Overview....................................................................................................................... 7 Road Map ..................................................................................................................... 9 Preparation ................................................................................................................. 11 Creating/Modifying the Application............................................................................. 13

Adding Clarion/PHP ............................................................................................. 14 Procedure Customizations................................................................................... 15 Generating and Incorporating .............................................................................. 16

Ch. 2: Setup 17 Clarion/PHP Template Installation.............................................................................. 17 Apache Web Server Setup (Windows)....................................................................... 18

Installation Notes.................................................................................................. 18 Testing and Starting Apache................................................................................ 22 More on Testing ................................................................................................... 24 Final Note on Apache Setup ................................................................................ 24

Installing PHP (Windows) ........................................................................................... 25 Install Steps.......................................................................................................... 25 Testing the PHP Installation................................................................................. 29 Confirm the PHP Path.......................................................................................... 31

Installing ADOdb (Windows)....................................................................................... 32 Installation of ADOdb ........................................................................................... 32 Testing ADOdb..................................................................................................... 35

Linux Installation Issues ............................................................................................. 36 Apache and PHP: Testing.................................................................................... 37 ADODB ................................................................................................................ 38 Installation of ADOdb ........................................................................................... 38 PHP Include Path................................................................................................. 39 Database Setup ................................................................................................... 40 Running Clarion on Linux..................................................................................... 41

Default Virtual Images Directory................................................................................. 42 PHP, ADODB and Database Access ......................................................................... 42

PHP/ADODB Applications ................................................................................... 43 Database Access ................................................................................................. 44 Clarion Programmers and PHP/ADODB.............................................................. 45

FAQs and Troubleshooting ............................................................................................... 46 Configuring PHP......................................................................................................... 46

How can I make sure that PHP will find the ADOdb support source files, when my generated code has a statement such as include(“adodb.inc.php”)?.................. 46 I am using MSSQL and I have an image on my form but it doesn’t display? ...... 46 How does PHP know what type of databases that it must support? ................... 47 Is there special configuration rules for PHP used with Apache? ......................... 47 Is there a simple way to keep all program images in the same place? ............... 47


ADODb ....................................................................................................................... 48 How do I install ADODb to my target server? ...................................................... 48 What is the best way to test an ADODb connection? .......................................... 48

Configuring Apache .................................................................................................... 49 How do I create a “virtual directory” using Apache? ............................................ 49

Deployment FAQ ........................................................................................................ 50 What do I need to do in order to deploy my application generated by the Clarion/PHP templates?....................................................................................... 50 What do I need to do in order to see the icons and images generated by the Clarion/PHP templates?....................................................................................... 50

HTML (Hypertext Markup Language)......................................................................... 51 PHP Language ........................................................................................................... 53

Ch. 3: PHP Template Concepts 55 How PHP Fits In with Clarion ..................................................................................... 55

What’s Special About Our PHP Code.................................................................. 56 Interaction with Dictionary.................................................................................... 57

Navigational Links in Clarion/PHP.............................................................................. 58 Window and Control Formatting ................................................................................. 59 Security Levels ........................................................................................................... 59 Language.................................................................................................................... 60 Database Access - DBMS Requirements .................................................................. 60

Ch. 4: Getting Started Exercises 61

Ch. 5: How-Tos 63 Application How-Tos................................................................................................... 63

Application of Global Template ............................................................................ 63 Application of Browse Template .......................................................................... 64 Application of Form Template .............................................................................. 65 Browse/Form/Browse or Query/Browse/Form ..................................................... 66 Link a Browse and Form ...................................................................................... 67 Form Without a Browse........................................................................................ 70 A Query Page....................................................................................................... 70 Browse to Browse ................................................................................................ 71 Select Browses .................................................................................................... 73 Table Loaded Selects on Forms .......................................................................... 74 How to Prime a Field on an Update Form............................................................ 75 Help and Popup Windows.................................................................................... 75

Testing How-To’s........................................................................................................ 77 Testing on Your Local Machine ........................................................................... 77

Integration/Deployment How-To’s .............................................................................. 79 HTML Template ................................................................................................... 79 Style Sheets ......................................................................................................... 80 Collected Data from Forms on Your Site ............................................................. 81 Passing Data to Other Parts of Your Web ........................................................... 81


Ch. 6: Integrating with Your Site 83 Links ........................................................................................................................... 83

Site Standard Page Format ................................................................................. 85 Ch. 7: PHP Template Reference 87

PHP Global Template Options ................................................................................... 87 Global Options/Global Tab................................................................................... 87 Global Options/Cascading Style Sheets .............................................................. 89 HTML Design Time Templates ............................................................................ 89 List Defaults ......................................................................................................... 90 Form Defaults Button ........................................................................................... 93 Global Options/Generation Tab ........................................................................... 97 Global Options/Database Tab.............................................................................. 99 Connection Parameters: .................................................................................... 102 Global Options/Security Tab .............................................................................. 103 Global Options/Administration Tab .................................................................... 107 Images ............................................................................................................... 109 User Data ........................................................................................................... 110 Includes.............................................................................................................. 111

The PHP Frame Extension Template....................................................................... 112 The PHP Browse Extension Template ..................................................................... 113

Browse Options/Globals Tab ............................................................................. 113 Browse Options/Page Tab ................................................................................. 117 Browse Options/HTML Table Tab...................................................................... 119 Browse Options/Default SQL Tab...................................................................... 122 Browse Options/Data Columns Tab................................................................... 123 Data Columns/General Tab ............................................................................... 126 Data Columns Properties/Actions Tab............................................................... 127 Data Columns/Properties/Column Sorting Tab.................................................. 130 Data Columns/Properties/Appearance Tab ....................................................... 131 Browse Options/Custom Columns Tab.............................................................. 132 Custom Columns Properties/Appearance Tab .................................................. 134

The PHP Form Extension Template......................................................................... 138 Form Options/Global Overrides ......................................................................... 138 Form Options/ActionsTab .................................................................................. 142 Page to Return To.............................................................................................. 143 Form Options/Help ............................................................................................. 145 Form Options/Data Access Tab......................................................................... 146 Form Options/Controls Tab................................................................................ 147 Form Options/Custom Controls Tab .................................................................. 153


Ch. 8: PHP Embeds 157 Global Template Declarations .................................................................................. 158 Accessing the Embed Points.................................................................................... 159 Browse Embed Points .............................................................................................. 159 Examples .................................................................................................................. 163

Form Embed ...................................................................................................... 163 Additional Form Embed...................................................................................... 166 Browse Embed................................................................................................... 167

Ch. 9: HTML Includes 169 Understanding the Process ...................................................................................... 169 What to Use it For..................................................................................................... 172 Final Notes................................................................................................................ 173

Ch. 10: PHP Source Code Procedure 175 Application ................................................................................................................ 175 Usage ....................................................................................................................... 177

Ch. 11: Style Sheet Editor 179 Style Sheet Tab ........................................................................................................ 180 Body Tag Tab ........................................................................................................... 183 Background Class Tab ............................................................................................. 186

Borders Button - Data Tab ................................................................................. 188 Margins Button - Data Tab................................................................................. 189 Padding Button - Data Tab ................................................................................ 189 Header Button - Data Tab.................................................................................. 190 Column Label Button - Data Tab ....................................................................... 191 Data Rows Button - Data Tab ............................................................................ 192 Footer Button: Data Tab..................................................................................... 194 Input Label: Data Tab......................................................................................... 195 Input: Data Tab .................................................................................................. 195

Style Sheets.............................................................................................................. 197 Index: 199


Ch. 1: Introduction This chapter summarizes Clarion/PHP programming and deployment.

Clarion/PHP generates PHP pages (“PHP” originally stood for “Personal Home Pages” but has outgrown that acronym considerably), 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 Apache, specifically public or high volume sites using Apache, whether *nix or Windows based. Clarion/PHP 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 php code.

Clarion/PHP uses an open source data access library called ADODB which allows data access from PHP code.

Clarion/PHP is one component (the other is Clarion/ASP) of the Clarion web templates. Both Clarion/ASP and Clarion/PHP can be applied within a single application, and be managed with the same extension options (other than certain global settings such as database access).

Overview The following is meant to convey a conceptual summary of the Clarion/PHP code generation process, for the developer familiar with creating desktop applications:

• The modular application pages that Clarion/PHP generates fit together with links. You therefore apply Clarion/PHP to the individual procedures for which you want to provide web access. Clarion/PHP reads your data dictionary and builds a default procedure (as an extension to your existing procedure). Then you customize the Clarion/PHP 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 ADODB 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/PHP 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/PHP 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) 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 PHP is a scripting language. You (and your web administrator) are then free to further customize the generated pages (for appearance, application behavior, etc.).

• Apache, PHP and ADODB are available for all current Windows platforms, so 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 Apache server, which is equivalent to deploying the application.

Note that you apply the Clarion/PHP 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 PHP for five browse and five form procedures, you’ll first apply the global template, then apply the PHP 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 Oracle, IBM DB2, Postgres, mysql, 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/PHP 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.

• The developer runs the application wizard (or creates an empty .app file and manually populates browse and form procedures).

• The developer applies the Clarion/PHP global extension template, specifying, at that time, the database, type of access, the database server, 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 PHP 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/PHP generated menu page and optionally, a local copy of Apache.


• 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 PHP pages, and upload the PHP pages for deployment.


Preparation As with normal Clarion programming, start with a data dictionary. In general, Clarion/PHP, if applied to an existing application procedure, ignores the control formatting customizations in the procedure, and instead reads the customizations in the dictionary. It only 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/PHP was not designed for ISAM databases. All the access syntax generated in your php procedure pages will be ADO/SQL specific.

• Every table you require should exist in the dictionary.

• 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 PHP 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/PHP 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/PHP outputs only PHP 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/PHP application. Note that Clarion/PHP 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/PHP 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 list box within a browse procedure. (Note: in this case, “entry” refers to any control that 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/PHP 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.

• 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/PHP 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/PHP can generate JavaScript client side validations. In general, the more client side validity checking your PHP 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/PHP 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 PHP Application extension to an existing application and then take the procedures you wish and “PHP-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/PHP to applications utilizing either the Clarion or ABC template chains).

This is merely a recommendation. Many developers will prefer to keep everything (desktop PHP and ASP) in one code repository. The reality is that the desktop and PHP 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 PHP 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:

• 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/PHP will automatically add the JOIN syntax and display data from the three tables. You may then instruct PHP not to display any unwanted fields, such as ID numbers.


Adding Clarion/PHP

You’ll apply Clarion/PHP as a global extension template, by choosing the “PHP 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 PHP browse and form procedure templates to the procedures for which you wish to generate PHP pages.

You cannot apply the procedure extension templates until you’ve added the global extension, and you will not generate any PHP procedure pages unless you’ve then added the PHP procedure templates to a procedure(s).

When you add the global extension, you must define a connection string. Your PHP application does not use Clarion drivers. It uses the ADODB libraries, which provide for an ADO-like syntax on many OS platforms, which allows us to standardize the access code for both PHP and ASP.

A connection string is merely a list of parameters that ADODB requires to access the database. The Connection will provide a dialog for you to choose your database target and 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/PHP, 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/PHP 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.


Procedure Customizations

You’ll apply the procedure extension template only to those procedures for which you wish to generate PHP pages.

In many cases, you’ll elect to edit the list of fields contained within the browse. There are two reasons for this; your data displays in a table that is not scrollable, and, 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. Custom links provide you with total control of the link code, from <a> to </a>. They require a little HTML knowledge but can be very powerful.

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 that 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, we suggest testing them using a web server either on your development machine or within your Intranet. Afterwards, 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/PHP form by posting the data from forms that may already exist at the site. Or you may wish to collect data on a Clarion/PHP form and post that to an existing form.

You’ll find that Clarion/PHP pages work well with existing pages in the site, and that this manual documents how such cooperation works.


Ch. 2: Setup In addition to providing simple setup directions for the Clarion/PHP templates, this section will also provide:

• basic setup instructions for Apache, PHP and ADODB (because it’s anticipated that those products will be new to many Clarion developers). Based on our research, we think that the Apache Web Server is the most popular platform for PHP applications.

• basic testing instructions for these Apache, PHP and ADODB (to help insure that the developer installed them properly)

• notes regarding setting up Apache, PHP, ADODB, and MySQL on Gnu/Linux (because it’s anticipated that this will also be an important deployment platform)

This introductory section will also begin with an overview of PHP technology to Clarion and other database developers who may only have passing familiarity with it, to help you understand what you’re installing.

PHP has so far been the province of web designers who have learned something of development tools because they had to. Clarion/PHP comes from the opposite direction... it’s for developers who want to create PHP. 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, PHP is a form of server side scripting. PHP can be executed from either an Apache module or as a standalone CGI (Common Gateway Interface) application. The former (Apache) requires fewer resources. It receives a request from the web server for a page whose file extension is .PHP. The PHP 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 that produced it.

When running as a module, the script has access to all the resources that the Apache user account on the web server has.

Clarion/PHP Template Installation The Clarion/PHP setup program is straightforward, and will install the templates. Make sure to exit the development environment completely before running the template installation.


Apache Web Server Setup (Windows) Many developers will wish to install Apache on their development machine, allowing for quick and immediate testing of applications. The first step is to download the Apache software.

NOTE: At the time of this release, it is recommended that you install Apache 2 for testing purposes only. It is not currently recommended for the production environment. For the production environment on Unix or Windows, use the latest Apache 1 version. This of course may change.

Visit http://www.apache.org for the home page of the Apache Software Foundation. This is a valuable resource not just for downloads but for news of patches and other products. Once you’ve opened the page, before installing the Windows version on your development machine, click on the link for "HTTP Server," to determine the current version. A "Download from a Mirror" link is also on that page, which when launched contains a list of cooperating FTP servers maintaining copies of the current release, Choose a mirror and locate the proper download file. Note that your download may be located in a directory called httpd. The "d" stands for daemon, which is the *nix term for what Windows calls a "service." The Windows version will have "win32" in the file name.

Note: if you wish to update a version of Apache on your Linux server, you may wish to visit the home page of your distribution, in order to locate an RPM or apt-get package, which may be easier to install/upgrade. Normally the syntax for upgrading an rpm is "rpm -Uvh apache*," and apt-get is usually just apt-get and the package name.

Note that in many distributions, such as RedHat, Apache is installed by default. If running a distribution using RPMs, “rpm -q Apache,” will display whether Apache is installed, and which version if installed.

In this section, we will document the Windows install.

Installation Notes

You may already have a web server (IIS, Personal Web Server, Clarion Application Server) installed on your development machine. This chapter documents the installation of Apache 2.0.39 (Windows 32, no Secure Sockets Layer) on Windows 2000. The installation/setup file, as downloaded from an Apache mirror, was called apache_2.0.39-win32-x86-no_ssl.exe. The installer uses the Windows installer; double click the installer to begin.

http://www.apache.org/


The installation wizard begins with a simple introductory screen.

The License screen, if you've never installed open source software, may be surprisingly brief:


Next is a small screen of information and links for additional information. Following that, you may choose a few important properties for your server:

• Your domain... this does not necessarily mean a Windows domain. Remember that Apache runs the majority of web servers on the Internet, and the domain in that context is usually a dot.com, dot.org or dot.net domain! But if you're running on a Windows domain for development purposes, feel free to leave the NT/2000 domain information in. It won't "hurt," and you can change it later.

• Your server name, followed by the domain information.

• Your administrator email address. It need not be in the same domain, though it's usually traditional.

• Probably the most important setting to specify on this screen is the server port. Note that if you are not already running another web server, you may set Apache to install itself on port 8080 (the normal web server port is 80), and if so, it's assumed that you wish the server to be started manually (as opposed to every time you boot the system). You can change both settings later; however these are reasonable defaults for a development machine.

The next installation wizard panel allows you to specify typical or custom installation. Typical installation is probably OK for most developers. The only component not installed with the typical option are the build headers and libraries; unless you think you wish to modify and compile the Apache source, choose Typical.


The next panel simply asks you to specify the installation destination directory (press the button should you wish to specify another, and then an announcement panel states that everything is ready, and that you can press the Install button to begin copying the files.

Following the copying of the files, you should see a final panel stating that installation was successful.


Testing and Starting Apache

Assuming that you elected for manual Apache startup, the first thing to do is to test the configuration. Apache creates a program link group called "Apache HTTP Server 2.0.52" (your install version number may vary). A sub program group called "Configure Apache Server" provides a command called "Test Configuration." This runs a console command. Pay attention: an "OK" will flash by very quickly, and any subsequent running of the command will probably make it even faster. The following screen documents the actual command and response:

This is a good introduction to Apache. It works with little flash, and without fancy configuration tools. Some of the Linux distributions have already begun adding graphical configuration tools for Apache, but you'll not find anything on the level of Internet Services Manager.

In general, to edit your Apache configuration, you'll edit a text configuration file (called httpd.conf). The basic options, which are probably no further than you'll need to touch on a development machine, are straightforward. The more complicated options, which can indeed be vital in the "real" world of the World Wide Web have had books written about them.

In Windows, a typical install places it at

C:\Program Files\Apache Group\Apache2\conf\httpd.conf


Here are some sections of the configuration file that you might want to change after installation. # Listen: Allows you to bind Apache to specific IP addresses and/or # ports, in addition to the default. See also the <VirtualHost> # directive. # # Change this to Listen on specific IP addresses as shown below to # prevent Apache from glomming onto all bound IP addresses (0.0.0.0) # Listen 12.34.56.78:80 Listen 8080 # # ServerName gives the name and port that the server uses to identify itself. # This can often be determined automatically, but we recommend you specify # it explicitly to prevent problems during startup. # # If this is not set to valid DNS name for your host, server-generated # redirections will not work. See also the UseCanonicalName directive. # # If your host doesn't have a registered DNS name, enter its IP address here. # You will have to access it by its address anyway, and this will make # redirections work in a sensible way. ServerName your-machine-name:8080 # Timeout: The number of seconds before receives and sends time out. Timeout 300 #

After installation, to start Apache (assuming you've set it up for manual start as had been recommended above):

Start > Programs > Apache HTTP Server 2.0.52 > Control Apache Server > Start Apache Server in Console.

Again, your version number may vary.

This should lead to a completely blank console box. Don't be alarmed... that's how it's supposed to look. Simply minimize it.

If you chose to install Apache as a service, it should already be running. To control it, you'll find an applet on the taskbar. This will also be installed should you choose not to installed as a service, though it may have less "relevance"


In the illustration above, the Apache applet icon is the one at the right. To turn Apache off, or to turn it back on again, use the popup menu from the toolbox applet, choose the "Open Services" command, then locate Apache in the Windows services applet, and turn it on or off by double clicking and choosing an option.

More on Testing

The proper way to test Apache is to open your browser and type in http://localhost:8080 (delete the :8080 if you installed to port 80). Immediately following an installation, without having configured a default page, you should see the following:

Likewise, you can open task manager (or wintop, one of the kernel toys for Windows 98) to verify that the Apache.exe process is running (or possibly two such tasks.

Final Note on Apache Setup

Once Apache is started, the toolbox applet provides an "Open Apache Monitor" command. The monitor is for monitoring remote Apache installations.


Installing PHP (Windows) PHP, (whose initials stem from its original name Personal Home Page) can be downloaded from the PHP group at http://www.php.net/. PHP is a project of the Apache Software Foundation, the site is run by the PHP Group, and PHP is also open source.

Many Linux distributions pre-install PHP.

To download for your Windows development machine, click on the Downloads link at the page mentioned above, and locate the Windows Binaries section. You should see both a zip and an Installer version. Unfortunately, the installer for Windows doesn't install everything you need to work with Apache for Windows, even if you choose the custom install, and specify Apache. We strongly recommend that you use the zip install.

Install Steps

This documents the installation of the zipped version of PHP.

The zip install will contain two “versions” of PHP; a CGI (Common Gateway Interface, in which commands are executed from the web server) and a SAPI (Server Application Programming Interface, in which the web server calls PHP functions directly. The PHP Group recommends the latter, however the SAPI version will not run with Windows 2000 at the time this manual was written. Therefore, this section documents the use of the PHP/CGI interface.

The latest version of PHP at the time of this release is PHP 5, but we will use the more established PHP 4 version as our base install example. Will we mention differences in install configurations throughout this document where appropriate.

Download the zip file, which for this “example” installation is named php-4.3.9-Win32.zip (the latest PHP 4 version at the time of this writing), and open it with your favorite zip management tool. Locate the file Install.txt and be sure to review it (in case there are any differences in subsequent versions vs. the following steps). The install.txt file also contains instructions for different platforms and alternative configurations not covered in this document.

After reviewing the instructions, follow these steps carefully to install. Please be careful not to skip any steps.

1. Create a directory for your PHP installation, such as C:\PHP (the standard suggestion) or C:\Program Files\PHP.

2. Unzip the entire compressed file to that directory. If your extraction utility requires you to specify a parameter or choose an option to create subdirectories under the target directory, be sure to do so (Note: unzipping should create several sub folders).

http://www.php.net/


3. A file called php.ini-dist will have been copied to the target directory. Copy it to the Windows directory (typically C:\Windows for Windows 9x and XP, or C:\Winnt for Windows NT/2000).

4. In the Windows directory, locate php.ini and open it in Notepad or a text editor.

5. Locate the string “extension_dir =” and change the value to the directory to which you unzipped all the files to, being careful to place double quotes around the directory should it contain any blank spaces.

Example: ; Directory in which the loadable extensions (modules) reside. extension_dir = "c:\PHP"

6. Locate the string “cgi.force_redirect = 1” which should be on a line that is commented out (it begins with a semi colon). Remove the semi colon and the space after it, leaving only the string.

Example: cgi.force_redirect = 1

7. Save and Close the php.ini file.

8. Stop Apache if it’s currently on.

9. Locate the Apache httpd.conf file, which should be located in a directory called conf, which is located in a directory called Apache 2 (or Apache in earlier versions), which should be located under the directory in which you installed Apache. Open the httpd.conf file in notepad (or your favorite text editor). It may be necessary to create a file association, using the Open With... dialog. Also, because of the case sensitive nature of this file, it is strongly recommended that you back up your httpd.conf file before editing. If you make a mistake, you will most likely not be able to restart Apache.

10. Search for the string “Addtype.” You should find it in a section with some comments above; the following is the default section found in our installation:

# # AddType allows you to add to or override the MIME configuration # file mime.types for specific file types. # AddType application/x-tar .tgz


Insert the following lines below those lines, substituting the name of your PHP install directory for c:/PHP, if you installed to a different target. Note that the file locations use a slash character, and not a backslash character, and that the lines starting with # are just comments: # # inserted by YourNameHere for PHP Support ScriptAlias /php/ "c:/php/" AddType application/x-httpd-php .php Action application/x-httpd-php "/php/php.exe"

If you are installing PHP to use the CGI binary with Apache 2.0, add the following lines to your httpd.conf file:

ScriptAlias /php/ "c:/php/" AddType application/x-httpd-php .php # For PHP 4 Action application/x-httpd-php "/php/php.exe" # For PHP 5 Action application/x-httpd-php "/php/php-cgi.exe"

If you are installing PHP to use the Apache module DLL with Apache 2.0, add the following lines to your httpd.conf file:

# For PHP 4 do something like this: LoadModule php4_module "c:/php/sapi/php4apache2.dll" AddType application/x-httpd-php .php # For PHP 5 do something like this: LoadModule php5_module "c:/php/php5apache2.dll" AddType application/x-httpd-php .php # configure the path to php.ini PHPIniDir "C:/php"


If you are installing PHP to use the Apache module DLL with Apache 1.3.x, add the following lines to your httpd.conf file:

# For PHP 4 do something like this: # Add to the end of the LoadModule section LoadModule php4_module "c:/php/sapi/php4apache.dll" # Add to the end of the AddModule section AddModule mod_php4.c # For PHP 5 do something like this: # Add to the end of the LoadModule section LoadModule php5_module "c:/php/php5apache.dll" # Add to the end of the AddModule section AddModule mod_php5.c #For both add the following: # Add this line inside the <IfModule mod_mime.c> conditional brace AddType application/x-httpd-php .php # For syntax highlighted .phps files, also add AddType application/x-httpd-php-source .phps

11. Save and close the httpd.conf file.


Testing the PHP Installation

You may create a one-line text file to test that PHP is working properly.

1. In Explorer, open the Apache2 directory, which should be located directly beneath the installation directory you chose for Apache, then the htdocs directory, which should be one level below that. This is the default web root.

2. Right click and choose New > Text File in a blank area of the Explorer window. Name the file “test.php,” or a similar name. If you receive an alert regarding changing a file name extension, ignore it.

3. Open the “test.php” file with notepad. It may be necessary to create a file association in the “Open With” dialog.

4. Type the following line in notepad, save the file, and close it. Note that PHP is case sensitive: <?php phpinfo();?>

5. Save the file and start Apache. Now verify the httpd.conf file is OK, by opening a command console and typing the following at the c:\> prompt. Be sure to include the double quotes:

"C:\Program Files\Apache Group\Apache2\bin\Apache.exe" -t -f "C:\Program Files\Apache Group\Apache2\conf\httpd.conf" -d "C:\Program Files\Apache Group\Apache2\."

A “Syntax OK” message should appear; if not, you may have typed the section above wrong.

6. Open your browser, and type the following URL in the address box: http://localhost:8080/test.php. (Note: if you did not choose port 8080, omit the :8080).


The result should be a page looking like the one below. You’ve now enabled PHP support.


Confirm the PHP Path

A final checkpoint is to make sure that the CGI and CLI binaries, and the web server modules all require the php4ts.dll (php5ts.dll) file to be available to them. You have to make sure that this file can be found by your PHP installation. The search order for this DLL is as follows:

The same directory from where php.exe is called, or in case you use a SAPI module, the web server's directory (e.g. C:\Program Files\Apache Group\Apache2\bin).

Any directory in your Windows PATH environment variable.

To make php4ts.dll / php5ts.dll available you have three options: copy the file to the Windows system directory, copy the file to the web server's directory, or add your PHP directory, C:\php to the PATH. For better maintenance, we advise you to follow the last option, add C:\php to the PATH, because it will be simpler to upgrade PHP in the future.


Installing ADOdb (Windows) The ADOdb database library for PHP is an open source project whose home page is http://adodb.sourceforge.net. The purpose of ADOdb is to provide a database abstraction layer allowing PHP to use a standardized syntax for access to different databases. This allows Clarion/PHP to connect using the same SQL commands to different DBMS’s. The databases supported by ADPdb are MySQL, PostgreSQL, Interbase, Informix, Oracle, MSSQL 7, Foxpro, Access, ADO, Sybase, DB2 and generic ODBC (when the server is Windows).

The most current download is found at the page above. Note that sometimes the text description will note that a previous version may be more stable than the most current version.

For downloading to a development machine or a Windows based server, you will wish to download a zip file. For downloading to a *nix based server, you will download a .tgz file and run configure and an install script. A section later in this chapter discusses server installation.

Installation of ADOdb

This section documents the installation of version 4.53 for Windows, as contained in adodb-4.53-for-php. (This was the latest version at the time this document was released).

Using your favorite compression utility tool, unzip all files to a directory accessible to your web server, preserving the directory structure of the zip file. If you’re simply following these “How tos” and have freshly installed Apache, you probably haven’t set up any virtual directories yet. The simplest way to get started is to create an ADOdb directory under your Apache2\htdocs directory (your default web root), and then extract the files to that location.

If you have the ADOdb directory in another location, please review the following configuration settings, and change the PHP.INI file where needed:

1. In the PHP.INI file, search for "include_path =", and change as follows:

If you are using Apache2.0.x:

If ADOdb is installed under \Apache2\htdocs\:

; Windows: "\path1;\path2"

include_path = ".;C:\Program Files\Apache Group\Apache2\htdocs\ADOdb;C:\Program Files\Apache Group\Apache2\htdocs\ADOdb\drivers"

http://adodb.sourceforge.net/


If ADOdb is installed under C:\PHP\: ; Windows: "\path1;\path2" include_path =".;c:\php;c:\php\adodb;c:\php\adodb\drivers"

If you are using Apache1.3.3.x:

If ADOdb is installed under \Apache\htdocs\:

; Windows: "\path1;\path2"

include_path = ".;C:\Program Files\Apache Group\Apache\htdocs\ADOdb;C:\Program Files\Apache Group\Apache\htdocs\ADOdb\drivers"

If ADOdb is installed under C:\PHP\:

; Windows: "\path1;\path2" include_path =".;c:\php;c:\php\adodb;c:\php\adodb\drivers"

2. In the PHP.INI file, search for 'extension_dir', and change as follows:

; Directory in which the loadable extensions (modules) reside. ;For PHP 5 extension_dir = C:\PHP\ext ;For PHP 4 extension_dir = C:\PHP\extensions

3. Next, search for 'session.save_path', and edit as follows: ; Argument passed to save_handler. In the case of files, this is the path ; where data files are stored. Note: Windows users have to change this ; variable in order to use PHP's session functions. session.save_path = C:\PHP\SessionData Note: Make sure that 'C:\PHP\SessionData' is created, as it is not part of the install.


3. Finally, search for 'Windows Extensions', and remove the ';' before the DLL that you are using to connect to the database, as follows:

;Windows Extensions ;Note that MySQL and ODBC support is now built in, so no dll is needed ;for it. ;for PHP 5: ;extension=php_ming.dll extension=php_mssql.dll ;extension=php_oci8.dll ;for PHP 5 only: extension=php_mysql.dll

4. Save and close the PHP.INI file.

In the above example, we are using the MSSQL and MySQL drivers.

You may wish to review the information found in the FAQs and Troubleshooting section if you have trouble with the setup or testing in this section.

You’ll also find a file called readme.htm. Review that document in case there are changes to the install procedure in the next product updates.


Testing ADOdb

The tests directory, which will be located below the target ADOdb installation directory, contains a page called test.php, which will help you test that ADOdb is properly installed.

When first loaded, the page should look like the following:

Because connections strings differ depending on what database you may have, the test page will not successfully connect to any database right away. The quickest, easiest test is to set up an ODBC data source for one of the sample databases that are hard coded into the test. When you check one of the boxes and press the “Submit Query” button, an error message will tell you what the test page expects “on the other end.”

As an example, check the “Access” box, press the button, and the error message will advise: “ERROR: Access test requires a Windows ODBC DSN=nwind, Access driver.”

To test further, load the ODBC Data Sources applet in Control Panel/Administrative Tools, and create a DSN named nwind, and point it to the northwind.mdb sample database in the Microsoft Office\Office\samples directory (if you have MS Office installed). If ADOdb is working correctly, the connection creates a table in the northwind database called “ADOXYZ,” inserts test data, retrieves and displays it, as illustrated below:


With the installation of ADOdb, you’ve now installed all the supporting components necessary for Clarion/PHP.

Linux Installation Issues It’s anticipated that many Clarion developers will wish to use a single machine for development and testing, which means installing Apache, PHP and ADODB on Windows, as described above.

For deployment, we anticipate that most sites will actually run Apache on Linux or UNIX. In most cases, those responsible for maintaining the site will probably have good familiarity with installing and configuring the necessary components, as well as seeking help in the many newsgroups should problems occur. Therefore this section is not meant to be a comprehensive guide to Linux setup. Moreover, Linux servers will most likely have Apache, PHP, and most likely, mysql, a popular open source database, installed as part of their Linux distribution.

Because, however, we anticipate that ADODB and PHP-mysql interaction will be the two most common areas in which questions may arise, this section will focus on installation and configuration issues for those two components. Additionally, this section will also touch upon Linux add on products which will allow developers to develop using Clarion and test locally on a Linux machine.


In general, with Linux, your starting point will be to test Apache and PHP, add ADODB, and optionally add a database such as mysql. We will take the approach of starting and configuring a Linux machine in your local intranet, or more specifically, one that you have access to so as to allow the installation of any missing software.

Apache and PHP: Testing

Many Linux distributions automatically install Apache and PHP. RedHat 7.3, for example, installs Apache 1.3 and PHP 4.1.2. PHP is installed as an Apache module. This means that when PHP is invoked, only a single process is run for all requests and clients. The alternative is to run PHP as a standalone process from cgi-bin. This uses more resources, and is not necessary for Clarion/PHP.

Begin by testing Apache. Open a browser. If testing on the local machine, type http://localhost. You’ll see the exact same default document that Windows Apache servers provide.

If you did not see the “Test Page,” then perhaps Apache was not set to automatically start on that machine. The command to start Apache varies from distribution to distribution. In RedHat 7.3, the command to start Apache, which must be run as root, is:

/etc/rc.d/init.d/httpd start

Just as you did for PHP with Windows, you must create a test page for PHP. Use the text editor of your choice and create a file whose contents are as follows:

<?php phpinfo();?>

Usually, the default Apache web root can be found as /var/www/html, though it’s simple to change that. Save your text file to a directory within the web tree, to a file name such as test.php. Remember that Apache/Linux/unix is case sensitive! If you save the file to test.php, and type http://localhost/mydirectory/Test.php, you will receive a page not found error.

Load the page in your browser; it should look something like:

If the test page did not display, check to see that it’s installed. The command to check varies by distribution, but in RedHat, you may display the installation information by logging in as root and typing:

rpm -q php


This should return a string such as “php-4.1.2-7.3.4,” which is the package name and version. Should you not have PHP installed, you may load your installation disks or download a package from the web. Again, in the case of RedHat 7.3, the command to install PHP, assuming installation disk #2 is loaded in the CDROM, and that the root is logged in:

rpm -ivh /mnt/cdrom/RedHat/RPMS/php-4.1.2-7.i386.rpm

In this case, most knowledgeable users would replace all characters to the right of php-4 with an asterisk. Note also that the package manager will notify should any dependencies require installation first, and finally, that in any other version the version numbers following “php” would be different.

As a reminder, on any machine in which you’ve specified during installation that the machine is to be a web server, both Apache and PHP should have been installed for you. Finally, remember in case any of the daemons fail to work, check the messages log (tail /var/log/messages) as root.

ADODB

The ADOdb database library for PHP is an open source project whose home page is http://adodb.sourceforge.net. The purpose of ADOdb is to provide a database abstraction layer allowing PHP to use a standardized syntax for access to different databases. This allows Clarion/PHP to connect using the same SQL commands to different DBMS’s. The databases supported by ADPdb are MySQL, PostgreSQL, Interbase, Informix, Oracle, MS SQL 7, Foxpro, Access, ADO, Sybase, DB2 and generic ODBC (when the server is Windows).

The ADODB libraries will not have been installed on a default installation of any distribution that we know of. Therefore you must obtain and install them. The most current download is found at the page above. Note that sometimes the text description will state that a previous version may be more stable than the most current version, and guide you to that version. You will download a .tgz file and run configure and an install script; just look for the Download link.

Installation of ADOdb

Create a directory and download the file to it. Once there, depending on the actual file name, run gzip and uncompress it, which should be something like:

gzip -d adodb221.tgz

It’s not necessary to make and compile the libraries. The simplest way to extract and install, in fact, is to load the resulting tar file in a file manager which treats a tar archive as a folder, and copy the contents to a directory you create for it in your web root. In our case, we named the directory /var/www/html/adodb.

http://adodb.sourceforge.net/


PHP Include Path

Before you can use the ADODB libraries, you must edit the php.ini file (yes, it really is called that, though it’s on a Linux server) to include them.

On a RedHat distribution, you’ll find the php.ini file in /etc. Open the file as root, and search for the string “include_path” at the beginning of a line. In the default installation under RedHat, the default line began with a semi colon, commenting it out:

;include_path = “.:/php/includes”

You must uncomment this (or add a path, if already uncommented) to include the directory to which you’ve extracted the ADODB libraries. For example:

include_path = “/var/www/html/adodb”

If PHP 5 is installed, and you plan to use MSSQL, make sure to edit the PHP.INI in the Windows directory to "activate" the needed DLL extension. In addition, there are default that needs to be changed in the MSSQL section of php.ini: ; Valid range 0 - 2147483647. Default = 4096. mssql.textlimit = 2147483647 ; Valid range 0 - 2147483647. Default = 4096. mssql.textsize = 2147483647

Values given here are the ones that replaced the default. This will allow forms with images to be displayed correctly.


Database Setup

At this point you could test ADODB; however, generating test data is not as easy as under windows. Should you wish, load http://localhost/adodb/tests/test.php (assuming you’ve installed ADODB to the same location as noted above), and follow the directions in that page to create a database table and display it. (Frankly, given a well configured system, it’s probably easier to test ADODB with a Clarion/PHP app!).

In many cases, you’ll first wish to install mysql, should you be creating an in house test bed for your application. It’s very likely that this database was not installed with your distribution. To install mysql, using RedHat 7.3 as an example, insert disk 3 in the CD ROM drive, and as root:

rpm -ivh /mnt/cdrom/RedHat/RPMS/mysql*

Should any additional dependencies be necessary, you’ll be notified and should install the appropriate packages.

There’s still one more package to install, which is necessary in order for PHP to work with mysql. Again, from disk 3:

rpm -ivh /mnt/cdrom/RedHat/RPMS/php-mysql*

You now have mysql installed. To start it, again, using RedHat as an example, logging in as root:

/etc/rc.d/init.d/mysqld start

You should also at this point be able to pull up the PHP test page again and verify that PHP can talk to mysql by looking at the test page, and scrolling down to the mysql section. As always, should there be a problem started the mysql daemon, check the messages log as root (tail /var/log/messages).

Remember that your command line client on Linux starts simply with the mysql command, that you’ll use the “use” command to load a database, or the “show databases;” command to display the databases available, and the “grant” command to add an account, and finally, that the sample database is called “test.” The terminal screen below shows a short mysql client session, a quick verification that everything is running, and a yet to be executed command to add a new user.

At this point you’ve got everything in place to begin testing, though you’ll probably wish to begin creating your mysql database if you don’t have one already. The online mysql documentation is quite comprehensive, and is located at http://www.mysql.com/doc/en/index.html

http://www.mysql.com/doc/en/index.html


Running Clarion on Linux

Clarion will not run on Linux with binary compatibility libraries such as wine; but it can be run via virtual machine based products such as vmware and win4lin. This allows the Clarion developer to compile and test using Clarion along with Linux/apache/php/adodb/mysql (or other databases) on a single machine.

Much of the testing of the system related to the development of this manual was done using a notebook computer running RedHat Linux 7.3 and Netraverse’s win4lin with Windows 98. Note that both win4lin and Windows 98 require proper licensing (in other words, neither is open source or free). The other advantage of this setup is that Dreamweaver can also be run on the same machine, facilitating editing design time and runtime HTML templates for your Clarion/PHP application.


Default Virtual Images Directory As a final note relating to setup, note that many web sites have a 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 Apache up on your development machine you should create this directory under your Apache web root, and copy the images from (your Clarion directory)\images\php there, so that the Clarion/PHP 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.”

PHP, ADODB and Database Access For database access, the ADODB library is the means of access. The library interfaces between PHP and Apache on the one side, and the database client library (or optionally the ODBC layer if Apache/Windows) on the other. The library itself is modeled after the Microsoft ADO libraries, for the purpose of providing a common access syntax for many database back ends.

In essence, this means that the script uses ADODB to frame queries or other requested actions for the database, and receives a resultset (query result) from the ADODB library. the PHP script then examines this object and generates a web page with some result.

PHP manages resources efficiently, making the solution quite scalable.


PHP/ADODB Applications

Think of your PHP application, therefore, as a browser-based interface to a powerful back end application. The Apache/PHP/ADODB platform has its strengths and weaknesses:

Strengths:

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

• The server itself, i.e., Apache, PHP and ADODB, can run on a huge number of server operating systems and be hosted on public servers with a minimum of effort.

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.

• The scripting languages, and the programming structure for them may not be as fully featured as other languages.


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 ADODB methods; however, they are important if you wish to understand the generated PHP code.

ADODB works within PHP 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 ADODB code, unless you wish to be concerned. 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/PHP is designed for use with Client/Server SQL databases exclusively.


Clarion Programmers and PHP/ADODB

This section provides a very brief introduction to how experienced Clarion programmers will work with Clarion/PHP. 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 PHP 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 PHP pages, and apply the PHP 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 PHP equivalents; however, any control you wish to appear on the PHP 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 PHP Browse or PHP Form extension dialog.

• These dialogs provide for a great deal of customization, both in appearance and functionality.

• To generate the PHP 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 PHP options and scripts.

• As always, the Application Generator will safely regenerate new code when you make changes without losing old customizations.


FAQs and Troubleshooting The following section provides tips and checkpoints to ensure proper configuration and setup options for ADOdb, Apache, and PHP.

Configuring PHP

How can I make sure that PHP will find the ADOdb support source files, when my generated code has a statement such as include(“adodb.inc.php”)?

The PHP.INI file has an entry called include_path. You must enter in the string value all the directories where ADOdb support files are located. Each directory is separated in the string by a semicolon.

For example, a typical entry in the PHP.INI for include_path may look like:

include_path = “.;c:\php\includes;C:\ADODb;C:\ADODb\drivers;C:\PHP\Pear;C:\PHP\Pear\go-pear-bundle”

The drive letter in the string is the drive letter on the server where the files are located.

Make sure that you always stop Apache and restart it after you edit your PHP.INI file.

If the ADO database test fails from the test PROCS.HTM page, this path issue is most likely the cause.

I am using MSSQL and I have an image on my form but it doesn’t display?

There is a section in the PHP.INI related to MSSQL where the default may be not enough for large images. The entries that need to be modified are:

Mssql.textlimit

Mssql.textsize

Both default to 4096 in size. Adjust these entries to the biggest size an image can have.


How does PHP know what type of databases that it must support?

The PHP.INI contains 2 sections that need to be edited to add target database support. The first entry in the INI file that needs to be edited is:

extension_dir = C:\PHP\Ext

In this example, C:\PHP\Ext is the directory on the server where the PHP extensions DLLs (i.e., php_mysql.dll) are located. You need to enter the name of the directory where those DLLs are located.

The other entry that needs to be “activated” is in the extension section. Search the PHP.INI file for this location:

;extension-php_myslq.dll

Note the semicolon preceding the extension entry. To activate this database, or any other database type for PHP use, remove the semicolon in front of the line corresponding to the target DLL.

Is there special configuration rules for PHP used with Apache?

Depending of the version of PHP and/or Apache, you may find invaluable configuration and setup information at the following site and links:

www.php.net Is the definitive and best reference for anything PHP.

Also, http://www.php.net/manual/en/install.windows.apache2.php contains information specific to Apache 2 and PHP versions

http://www.php.net/manual/en/install.windows.apache1.php contains information specific to Apache 1.3 and PHP versions

and for general Apache information: www.apache.org

Is there a simple way to keep all program images in the same place?

The best way is to create an Alias for the images in Apache httpd.conf configuration file. See the Configure Apache topic in this FAQ section for steps on how to create an alias.

http://www.php.net/

http://www.php.net/manual/en/install.windows.apache2.php

http://www.php.net/manual/en/install.windows.apache1.php

http://www.apache.org/


ADODb This section covers important install and configuration issues regarding ADOdb used with PHP.

How do I install ADODb to my target server?

ADODb is a straightforward install process. You simply need to create a target directory on the web server and unzip the files to that location. After that, it is recommended to edit the PHP.INI located on the web server and add the target directory to the include_path entry.

Example:

include_path = ".;c:\php\includes"

What is the best way to test an ADODb connection?

There is a file distributed with ADOdb that serves this purpose. The PHP source file for testing is named test.php and it is located in the tests subdirectory of the ADOdb install root. In order to use it, you must edit the testdatabases.inc.php file located in the same directory. This file contains hard coded values for server name, user id, password and the DSN for various database drivers. You must change the values to the one that will correspond to your needs.


Configuring Apache

How do I create a “virtual directory” using Apache?

In Apache, a virtual directory is called an Alias.

The way to create an Alias is to edit the httpd.conf file and create an entry similar to this:

Alias /Orders “C:/MyApp/PHP/Orders” <Directory “C:/MyApp/PHP/Orders”> Options Indexes MultiViews AllowOverride None Order allow,deny Allow from all </Directory>

Case sensitivity is important! Double-check and compare your entries to other Alias entries already defined.

Just make sure to stop Apache before editing the file and restart it when done. If everything is entered properly, you will be able to restart Apache, and it should now be possible to use Orders in the URL address to reach the directory specified in the Alias entry.


Deployment FAQ

What do I need to do in order to deploy my application generated by the Clarion/PHP templates?

The Clarion/PHP template generates all necessary files under the target application directory in a directory named PHP. Go in that directory and copy everything to the directory on the web server where the application should reside. Ideally, this will be moved in a directory to the server where an Alias statement was created in the Apache configuration file.

If Apache and PHP are configured properly, your application will run as generated.

On the server, it is a good idea to have an Alias created for images, and in the PHP.INI, to have the include_path statement reference the appropriate ADODb directories.

What this configuration, all you need to do to deploy the application is to create an Alias for the target directory and copy the files there.

What do I need to do in order to see the icons and images generated by the Clarion/PHP templates?

Create a directory for all images in the Apache root as follows:

C:\Program Files\Apache Group\Apache2\htdocs\Images (Apache 2)

or

C:\Program Files\Apache Group\Apache\htdocs\Images (Apache 1)

Next, copy all the PHP images from \Clarion6\Images\php\ directory to that location.


HTML (Hypertext Markup Language) In order for us to introduce the PHP 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/PHP 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 PHP pages you generate; or you can have a designer or web master edit the appearance of the pages you produce.


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:


PHP Language The scripting language itself is derived from Microsoft Basic. Perhaps more important for PHP than the basic language elements and statements are the built in classes and objects for page and component access.

Chief among these are the getRequest, getForm and Print statements, which refer to the incoming http request, values in any submitted form, and the outgoing http response respectively: the URL, parameters and posted data (fill in form data) that your PHP 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 getForm(“FillThisIn”).

To write a string out to the clients browser containing the contents of a variable, the developer may use the statement Print($myvariable). (String variables must be prepended with a “$” character.

Scripts are enclosed in tags: <?PHP at the top of the file, and ?> at the end. Statements inside those tags must end with a semi colon character. Curly braces define statement blocks, and double forward slashes define comments.

A global declaration script (YourAppNameappdata.app) declares the equivalent of global static variables; these store essential items not expected to change frequently, such as the connection string, and the values are loaded from the text file.

Individual variables which are unique to each user are maintained via _Session structures.

Those developers used to Clarion/ASP will be pleased to hear that PHP is more structured, and more like an ordinary programming language than just a scripting language. For instance, it provides for eight data types as opposed to the one supported by vbscript, used by Clarion/ASP.

Clarion programmers only need to write PHP should they wish to customize the behaviors in the generated web pages.


Ch. 3: PHP 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, and indeed, on non Microsoft platforms. Clarion has generated database applications on DOS, Windows and IP platforms for nearly two decades.

How PHP 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/PHP represents the first time the Clarion environment has been used to generate source code modules with no Clarion code targeted (as an option) for a non-Windows environment.

Clarion/PHP 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/PHP creates Clarion type applications for browser clients/Apache servers.


What’s Special About Our PHP Code

The PHP/ADODB code generated by the application generator is highly compact and efficient, yet features robust error checking.

• “Processor Pages,” which complement each of the .php pages that Clarion/PHP generate for your procedures contain database access code that writes a record. The processors consist of small, tight loops that smoothly handle difficult access issues such as column names with embedded spaces, null values, which are particularly troublesome in PHP, and type conversions.

• Compact JavaScript functions provide for rapid client side validation.

• Customization support within the template interface which essentially allows the developer to place HTML/PHP code alongside the Clarion/PHP 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 PHP page is called from a page not generated by Clarion/PHP.

• 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/PHP. (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/PHP 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 PHP 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.

Interaction with Dictionary

There are two guidelines to keep in mind when working with Clarion/PHP:

• 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 implies you rely as much as possible on the global level options (via the dictionary and the Global PHP extension dialog) to set control behavior rather than on the window formatter. The only information that Clarion/PHP will pick up from your WINDOW structures is the list of available controls.


Navigational Links in Clarion/PHP 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 that 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.

PHP 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/PHP 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.

It’s therefore quite simple to go from browse to browse. For Clarion developers who in the past have stuck closely the templates, Clarion/PHP 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/PHP provides an index page with a dropdown menu organized by procedure category. 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/PHP generates.


Window and Control Formatting A key concept to understand when creating PHP 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/PHP 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.

After the page is generated, however, you can load the runtime HTML template that Clarion/PHP 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/PHP 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.

Language Clarion/PHP’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, French, German and Dutch. 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 *LG??.TRN, where ?? is a two letter abbreviation for a language. “EN” = English, “FR” = French, 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/PHP is designed to work with ADODB, which is designed for SQL. The PHP 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.


Ch. 4: Getting Started Exercises Our Annotated Examples PDF included with this product provides very detailed instructions for creating the sample applications.

We suggest that you use these as a starting point for working with Clarion/PHP. Most specifically, the “Tasks” example provides a quick and easy demonstration of significant functionality yet takes only a short time to complete.


Ch. 5: How-Tos The subsequent topics provide step-by-step directions for implementing Clarion/PHP for your business applications. The “How-Tos” cover preparation, application, testing, and Site Deployment/Integration.

Application How-Tos

Application of Global Template

This section provides and overview and describes the essential/required steps involved in applying the Clarion/PHP 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 “PHP 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/Connection properties/Insert/Call Connection Builder Button: this displays the PHP DBConnection Builder dialog. Choose an access library on the DB Selection tab, and place the server and logon information on the Connection Parameters tab. Without this information, the web server cannot provide the ADODB 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.


Application of Browse Template

This section provides and overview and describes the essential steps involved in applying the Clarion/PHP browse template. A more complete description is available in the Reference section of this document.

To apply the PHP 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.


4. Select the PHP Browse extension 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 PHP Browse template.


Application of Form Template

This section provides and overview and describes the essential steps involved in applying the Clarion/PHP form template. A more complete description is available in the Reference section of this document.

To apply the PHP 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.


4. Select the PHP 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.


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 PHP 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/PHP 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/PHP does not pass the name of the field, because that might 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

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 PHP page with the correct URL.

The following are examples of the ways in which you can link to the PHP pages from either the top level contents page, from a frame, from any other pages (not produced by Clarion/PHP) 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 PHP file with the browse will be called /myapp/BrowseProductsList.php) a column containing 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.php.

• 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.php. Note: Microsoft Internet Information Server is case insensitive.)


• Browse (with a range select on one field): in the PHP 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.php?ID1=Potatoes. Note that Clarion/PHP 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.php?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.php?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.php

• Blank Update Form: no parameter is necessary from the calling page. The URL would be /myapp/UpdateProductsAdd.php.

• 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/UpdateProductsAdd.php?ID1=“Ford Model T Black.”

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 PHP 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. (The only time that you should be concerned that the template may have misidentified the parent browse is in a highly customized window containing many browse control templates).

1. On the update procedure, be sure the PHP 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.



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 PHP 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 PHP 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\php\images directory, or to the /images directory of your web server).

9. Use the file selector to choose the image file.



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.

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.php?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.php?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.php?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.php.

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.

To link to the query from an outside page, link to /myapp/myprocedureSearch.php. 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/PHP 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 PHP 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.

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 PHP 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 PHP 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).

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

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/PHP to generate an PHP 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/PHP can automatically generate a dropdown list of those values for your update forms. In the illustration below, from the one of the sample applications, an update form for the products table fills dropdown lists from the suppliers and categories tables; the dropdown is open on the categories list:

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 list box 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 PHP statement 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.

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=" . trim($oRSOrders->fields["OrderID"]) . "

In the above example, txtOrder_DetailsOrderID is the control name. The trim function trims any white spaces, and the $oRSOrders is the name of the record set (oRS, plus the table name), “fields” retrieves the requested column, and the column name is placed in square brackets. Then the trailing double quote is appended.

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/PHP 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/PHP 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 php directory called help, the help URL’s should be in the format “help/helpfilename.htm.”


Note that for a small PHP 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.


Testing How-To’s

Testing on Your Local Machine

If you have not already done so, you should install and test that Apache is running correctly on your local machine. You’ll find instructions that will help you with this task in the Setup chapter of this manual

• If not using a local copy of Apache, once you’ve generated an application, you’ll copy all the files in the project\php directory and below to your web server, via ftp, samba, or whatever method is most convenient for your site. On the server, the simplest method of enabling access to the application is to create a directory under the web root and copying the files there. You may also edit the Apache configuration file, or create a soft link from the web root to a directory residing somewhere else (just be sure that the apache user account has access).

• If using a local copy of Apache on a Windows system, either create a new directory below your web root and copy the files there, or edit the Apache configuration file.

Loading the Test/Debug Page

To test begin testing Clarion/PHP, open the URL http://localhost/yourvirtualdirectorypath/procs.htm. Procs.htm is a default “start page” that Clarion/PHP creates for your PHP procedure pages. The default start page provides a simple dropdown menu. (Note: this assumes you’ve already generated the PHP pages after applying the PHP 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.

Before clicking any of the procedure links on this page, please run the Utilities menu items. This will be the link in the menu just left to the Help. The Test Database item opens the ADODB connection used by your application, iterates through the tables, and tests that PHP/ADODB 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 public 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 finished 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 your database connection settings.

• Any problems documented in the last section indicate a security settings issue.

• Any problems documented in the middle indicate a database connection problem specific to a table or view.

After a successful connection, begin testing the procedures. Some may appear blank, but this is normal and only indicates that it is a filtered procedure and may require a parameter. For more information regarding this, see the Links on page 83 in this PDF.


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 PHP code that Clarion/PHP generates for data access is a combination of HTML and PHP pages and headers, all processed by the PHP module, 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/PHP data elements are of a reasonable size, they should fit well into a site with or without frames. Clarion/PHP 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\php\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/PHP to insert the code it generates (i.e., the place where you want your browses, forms, etc., to appear), place the text @Clarion/WEB@. (Don’t type the period at the end of the sentence).

You must type in the name of your template in the Global Options dialog for the PHP 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/PHP generated procedures.


Many sites use HTML includes to create standardized page sections. You may include these in the HTML template, so that the Clarion/PHP 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 PHP 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.

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.

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/PHP 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/PHP 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/PHP style sheet to match.

You’ll find more information on Clarion/PHP’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/PHP update form. In order to do that, the web administrator will need to know how the form fields on the Clarion/PHP 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 were 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.php?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/PHP files. Each .php 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/PHP below: FormDeclaration = "<form name='form1' id='form1' method='POST' action='BrowseviewContactsList.php'>"

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.


In the above example, changing the action page is as simple as: FormDeclaration = "<form name='form1' id='form1' method='POST' action='/mysite/otherpage.php'>"

(Note that the PHP page will be regenerated the next time you generate the project! When you must edit the .php page, set the file property to Read Only using Explorer).

The “otherpage.php” 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/PHP produced HTML equivalent of the PHP page (in the html directory below the PHP page), the web developer may easily view all the form field names.


Ch. 6: Integrating with Your Site It’s anticipated that most developers will use Clarion/PHP 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/PHP 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 PHP 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 procs.htm page generated by Clarion/PHP can be used from anywhere within the site, or from anywhere within the Clarion/PHP 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 procs.htm page generated by Clarion/PHP 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 way of testing the Clarion/PHP generated pages.


Persistence of Data

It’s important to understand that each time a Clarion/PHP page makes a request to the database for data, PHP creates a new connection object, gets the data, and closes the connection object.

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 Apache for each user’s session, plus the session variables that Clarion/PHP declares.

When, for example, a user opens a browse, PHP 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.

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/PHP pages from inside or outside the pages:

Page Naming Conventions

• Browse: clarionbrowseprocedurenamelist.php

• Update Form: clarionupdateprocedurenameedit.php

• Blank Update Form: clarionupdateprocedurenameadd.php

• Read Only Update (View) form: clarionupdateprocedurenameview.php

• Delete Confirmation Form: clarionupdateprocedurenamedel.php

• Query Form: clarionupdateprocedurenamesearch.php

• Processor Pages: (contain the PHP code for database access) same names as above, ending in x.php.

• HTM Pages: (contain the elements in which the PHP pages place their data; you may change some layout characteristics by editing these pages, but not all) same names as above, ending in .htm.


• Finally, please note that *nix servers are case sensitive; differences in capitalization will lead to a broken link.

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.php">link text</A>

• Browse, filtered: URL plus unique field value as parameter, such as: <A href="/path/clarionbrowseprocedurenamelist.php?ID1=1093">link text</A>

• Query form: URL only, such as: <A href="/path/clarionupdateprocedurenamesearch.php">link text</A>

• Update form, new blank record: URL only, such as: <A href="/path/clarionupdateprocedurenameadd.php">link text</A>

• Update form, update a specific record: URL plus unique field value as parameter, such as:

<A href="/path/clarionupdateprocedurenameadd.php?ID1=1093">link text</A>

• Update form, delete a specific record: URL plus unique field value as parameter, such as:

<A href="/path/clarionupdateprocedurenamedel.php?ID1=1093">link text</A>

• Update form, view a specific record: URL plus unique field value as parameter, such as:

<A href="/path/clarionupdateprocedurenameview.php?ID1=1093">link text</A>

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/PHP, we call this a design time template. All that you need do is open the template, insert the symbol @Clarion/WEB@ 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/PHP 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/WEB@ symbol inside it. Note that the colors in the style sheet were designed to mimic those in another table found at the site:


Ch. 7: PHP Template Reference PHP 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.

Target Language

All default Clarion/PHP 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 *_LG??.TRN, where ?? is a two letter abbreviation for a language. “EN” = English, “FR” = French, 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.

Tooltips

Clarion/PHP 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:

• 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 contains 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/PHP 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/PHP 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/PHP 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/PHP 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/PHP to insert the code it generates (i.e., the place where you want your browses, forms, etc., to appear), place the text @Clarion/PHP@. (Don’t type the period at the end of the sentence).

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.

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

Place Database Navigation Bar on List Pages

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

Navigation Button Tool Tips

Clarion/PHP 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.

Show Add Button on DB Navigation Bar

Use this checkbox to enable or disable adding records from the browse, and specify the tooltip 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.

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.


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/PHP 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.


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/PHP 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.

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

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, which will appear to the end user in a message page should the condition described in the list below apply:

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

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.


Global Options/Generation Tab

The options on the Generation tab allow you to optionally specify and control the additional non-PHP pages be generated when the Generate All command is executed, and whether the resulting PHP pages should enable debug mode.

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.

Developers who have previously worked with Clarion/PHP may be surprised to find that the debug information generated by Clarion/PHP is more comprehensive; this is simply because PHP provides a great deal of information, which the template code merely passes on.


In debug mode, Clarion/PHP passes all Apache, PHP and/or ADO errors through to the page. In non-debug mode, Clarion/PHP attempts to provide a “friendly” explanation.

Note also that the Test/Debug page described in the Testing on Your Local Machine section is also an efficient means of testing the critical parts of your PHP application.

Popup Help Window Size

Clarion/PHP 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.

Suppress File Generation

The three components besides PHP that are produced by Clarion/PHP 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\php\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/PHP 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 .php pages that Clarion/PHP produces corresponds to a procedure. The .php pages each require a corresponding .htm page which provides a “setting” for the controls and data that the .php page places there. The .php page merges the logic from the .php 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 throughout. 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.

• Help Pages: Clarion/PHP 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 a text editor 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.

Global Options/Database Tab

The database tab helps you define the connection settings for the ADODB connection from the web server to the database server. Though your data structures continue to take their definitions from the data dictionary, the actual connection information resides in the global extension settings maintained in this tab. Additionally, the General sub-tab allows you to specify database specific SQL generation options.

Miscellaneous Box

• Using Access Database: checking this box (Windows servers only) specifies that Clarion/PHP should generate non-standard SQL for use with the Microsoft Jet Engine.

• SQL String Delimiter: should your database require it, you may specify the double quote character instead of the default single quote character for delimiting string values.


• SQL Date Delimiter: should your database require it, you may specify double quote or pound sign characters instead of the default single quote character to delimit data values.

Connection Information box

PHP depends on your application providing a connection string. The connection string simply tells PHP which ADODB library it must use to access the database, plus any necessary options for that database. You will use the connection builder to build the connection string.

Your PHP 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, insert for creating a connection object and press the Call Connection Builder button. This will display the PHP DBConnection Builder dialog, which provides prompts for the runtime user name, password, and other connection parameters, plus a list so that you may choose the proper ADODB library.

Note that because Clarion/PHP supports both Windows and *nix servers, the lists which allow you to specify the target libraries display a legend to help “remind” you which target libraries are supported on which platforms.


PHP DBConnection Builder Dialog

This dialog contains two tabs. The first selects the database type and database access method, and the second allows you to enter the server/login parameters.

The DB Selection tab is straightforward: simply pick a database from the list. The following note provides additional information:

• Use the checkboxes at the top of the dialog to filter the choices in the list. Remember that ADODB is cross platform. If your Apache target is *nix, then you do not wish to use ODBC or ADO, and have no need to view those choices. If your Apache target is Windows, then you will very possibly use them. In general, if your target is *nix, check only Unix and Native Client DLL. If your target is Windows, check Windows and all three of the “layer” check boxes.

As you look through the choices in the list itself, you’ll note that “X” marks each column’s support or not for that particular target OS or access method.


• Note that for normal mysql support, choose mysql; not mysqld. The latter is for mysql installations using non default “types,” such as InnoDB, which provides transaction support with mysql. These are usually not installed as defaults by most Linux distributions.

• Note that for ADO support (Windows target only), the ADODB libraries automatically manage all ADO options. In general, if you wish to use ADO, you’re probably better off using the Clarion/ASP product.

• The functionality of ADO to MS SQL Server is limited; we recommend using Clarion/ASP and IIS/ASP to connect to that database. If you must use Apache/PHP, we suggest using the native dblib; however note that this option does not support unicode data types.

• ODBC support in for Apache/PHP/ADODB/Windows is good.

Connection Parameters:

This tab allows you to input the specific server and login information necessary to access the database chosen on the DB Selection tab.

• Server/DNS: enter the name of the server on which the DBMS resides. If targeting Windows/ODBC, you will instead enter the DSN.

• Runtime User Name: enter a user ID which PHP will use to log into the database.

• Runtime User Password: enter a password which PHP will use to log into the database.


Note: This password is different than the security built into Clarion/PHP. Clarion/PHP must have access to the database first, in order to check the user/password tables which are stored in the database. The end user does not have access to the runtime user/password, as per the description of the DSN options, above.

• Database: enter the name of the database to be used by your application.

Global Options/Security Tab

The security model built into Clarion/PHP is user based, and assumes a database table consisting of user names and security levels. Upon login, Clarion/PHP 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 PHP 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:


Provide User Based Security

Check this box to enable security. When checked, the fields below will be enabled.

Data Connection

This dropdown control allows you to select the connection object used for the security tables.

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 should also be included.

Unique ID Column

Select the name of the primary key column, or another unique key.

Login Name Column

Select the name of the column containing the database login name.

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.

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.

User Name Column

Select the name of the column containing this information.


If the user name is in two columns…

This allows for FILE structures containing separate columns for first and last names.

Note that the PHP code generated containing these items remains on the Apache 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 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/PHP 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.php page (search for the string “mydate”).

Additionally, please note that the user name and password are stored as plain text within the cookie file.


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

• Enter Retry: text to instruct the user how to retry the login

• Submit and Reset button labels: (self explanatory)

• User ID and Password prompts: labels for the text boxes in which the end user enters the information.


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/PHP 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.

Note that this error displays only if the PHP library reports back an ADO error. If the database operation simply times out, which can often be the case, then PHP 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 ADODB 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

• PHP Script File Name

• Script URL

• Query String Parameters

• Referring Page

• Local IP Address

• Fully Qualified PHP Script File Name


Images

The Images tab allows you to define the location of the various button images which 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/PHP images to the /images directory should you not be using /Clarion6/images/php 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.

A reminder: when running on *nix, all file and directory names are case sensitive. If your pages are missing “button” images, the first thing to check is that the correct directory is named, and the second thing to check is the case of the file names.


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

Once you define a variable, you are responsible for adding the symbol name (in the format @symbolname@) to any HTML runtime template that you wish to display the variable. Or you may optionally name a custom control with the same name as the variable, and Clarion/PHP 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.php 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.


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 further information.


The PHP Frame Extension Template The PHP Frame Extension Template allows you to create a starting menu page to use with your PHP applications. You can control which PHP enabled procedures you need to launch, and also create additional menu items to hyperlink to other web pages!

This extension creates the following files:

php\index.htm php\Main_Menu.js php\coolmenu4.js styles\coolmenu4.CSS

The coolmenu4.js JavaScript and associated style sheet is generated by the template, which was originally obtained from

http://www.dhtmlcentral.com/projects/coolmenus/

To add the Clarion PHP Frame extension template to the Frame procedure, open the Procedure Properties dialog for the Frame, and press the Extensions button. In the Select Extension dialog, press Insert, locate the PHP Frame template and press Select.

The PHP Frame Extension template provides the following options:

Generate Test Menu Item Check this box to instruct the template to generate a test menu, identical to the Utilities menu found in the generated procs.htm file. This will allow you to test the database connection from this generated HTML page. Generate Only Used Items Check this box to instruct the template to only generate menu items for procedures that include any PHP extension. Keep in mind that the base menu items in the Frame (File, Edit, Help, etc.) are not affected by this option. You must omit them as described below.

In each menu item, there is a PHP Options button available on the Actions tab when this extension is populated. On the subsequent dialog, you have the available options:

Omit Item Check this box to instruct the template to not generate a link to this item when this page is generated.

Overwrite Procedure Call - Hyperlink to this page If this menu item is enabled, you also have the option to navigate to an alternative web page that you designate here. It can be a local HTML page, or any valid URL address.

http://www.dhtmlcentral.com/projects/coolmenus/


The PHP Browse Extension Template Because the PHP 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 PHP pages.

To add the Clarion PHP 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 PHP Browse template and press Select.

The PHP 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 greenbar effect or conditional row formatting on this tab. By default, the templates provide “greenbar” 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.

Among the settings you can override are the following:

• Style Sheet

• HTML and Help file generation

• HTML Template

• Showing a Help Link

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

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 greenbar 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, Greenbar, 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.

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/PHP “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.

In many cases, web sites use an email address as a unique identifier. Clarion/PHP’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.php 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/PHP 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/PHP 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.

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

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 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. 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/PHP 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.

Populate an Entry Locator

This specifies that Clarion/PHP 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.

Final Note: should you wish to duplicate the functionality of an end user search, calling the search results page from outside the Clarion/PHP 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/PHP 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/PHP 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).


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/PHP 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 list box 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 list box, it will not be available from this list. To insert it into the list box, open the window formatter, right click the list box, choose the list box 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 list box and window changes, the new column will be available in the list. Clarion/PHP automatically writes the correct JOIN clause in the SQL statement.


In general, you should approach the inclusion of data in PHP 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/PHP 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.

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 PHP browse columns. The dialog is divided into tabs.


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.php?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 PHP (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=” . 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 group box allows you to specify that when the end user clicks on a data item in this column, the browser will open another page.

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 PHP 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 or JavaScript 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 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 PHP 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/PHP the target procedure is (list, view, add, edit, or delete).

• Custom Link: allows you to add an HTML, PHP, or JavaScript 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 a 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.

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

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

• 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/PHP. 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).

By default, Clarion/PHP 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.

• 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 PHP 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 or JavaScript 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=” . 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 JavaScript functions, and reference session and data variables using JavaScript functions.

It’s important to note that the text you enter in this box will be temporarily stored in and PHP 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 (using a “.” character in PHP), 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 getSession function (from the generated utils.php). To reference a data element in the current form, use a php code to return it from the recordset: $oRStablename->fields["fieldname"]. You may use text functions to trim and insure against returning a null variable, as in: trim($oRStablename->fields["fieldname"]). Because the custom link options are almost completely free form, they serve as very nearly a way to place embedded PHP code 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 PHP code to make a dynamic URL incorporating the data from each cell as a parameter: <A HREF=UpdateSuppliersView.php?ID1=" . trim($oRSviewContacts->fields["EditSupplier"]) . "> <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/PHP 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.

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.


The PHP Form Extension Template As noted previously, because the PHP 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 PHP pages. The application of the PHPbrowse template to a browse, however, will automatically build in a link to the update form for that browse. You must separately apply the PHPform template to the update form.

To add the Clarion PHPform 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 WEB Form template and press Select.

The PHP 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.


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

• 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/PHP “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).

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 that 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/PHP’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.php 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.

Once you’ve correctly set up the “My Records” options for each procedure, you need do no more; Clarion/PHP 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.

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.

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.

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 PHP page, if you’ve defined it as the target, and Clarion/PHP, 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:

• 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 PHP source for the Add page and identify the variable name used in the PHP 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.

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 PHP 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.php,” or “edit.php.” 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.php,” and “editx.php.”

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/PHP 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 that will link to the form, as well as the browse that will appear subsequent to the Query by Form (if the previous box checked.

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:

Connections

This tab allows you to select the connection object you want to use for a specific action

Table 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 .php 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.

SQL Tab

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


Because you may manage both PHP and ASP applications with the same extension, and because the PHP statement to retrieve the URL parameter identifying the unique ID will be different for the two platforms, you may manually edit the SQL/PHP statements separately. Choose one tab or the other.

Additionally, should you wish to edit the statements manually, check the “Freeze SQL Statements” box, so that opening the procedure after editing the window or pressing the Regenerate SQL button does not override your manual changes.

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 statement 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 PHP code. The first part of the select statement is the main select, but the second part is comprised of PHP, and forms the value for the where clause, using the PHP Request function and the column name. Thus, “SELECT (fieldlist) FROM Person WHERE Person.ID = “ . getRequest(“ID1”). Note the double quotes for the first part of the statement. If you’re used to ASP, note the PHP concatenation operator is “.” The concatenated part provides for a PHP function to obtain the unique value for the ID field, as requested by the calling page.

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/PHP 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 PHP 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:

Appearance Sub Tab


• Populate: enable or suppress (don’t generate) the control on the generated PHP 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.

• 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, this 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.

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. 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/PHP to generate an PHP 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.


Select Options Sub Tab

This sub tab is displayed only if the HTML Element (on the Appearance tab) is a SELECT (list box). 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/PHP supplies it when you apply the template extension to the form), place a FileDropCombo or a FileDropList into the window. Clarion/PHP will then add the column in the related table to the controls list. The HTML element will appear as a combo.


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.

• 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 PHP 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/PHP the target procedure is (list, add, edit, or delete).


• Custom Link: allows you to add an HTML or JavaScript 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.

You are responsible for everything starting with <A> to the </A> tags for this link. You may concatenate strings and Java functions, and reference session and data variables using JavaScript functions.

It’s important to note that the text you enter in this box will be temporarily stored in and PHP 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, refer to ti as $SESSION(“variablename”). To reference a data element in the current form, use an ADODB function to return it from the recordset: oRStablename(“fieldname”). You may use text functions to trim the string, as in: trim(oRStablename("fieldname")). <a href='BrowseProductsList.php?WHR=dbo.Suppliers.SupplierID1=" . 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 a close facsimile to placing embedded JavaScript in your applications.

• Image Button: press to provide details for displaying an image in this cell.

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/PHP 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.


Ch. 8: PHP Embeds

The Clarion/PHP template provides the developer with the opportunity to write their own PHP, ADODB and/or SQL code (dependent upon the embed selected) which will execute inside and along with the code that Clarion/PHP generates, without fear of the developer’s custom code being overwritten at generation time.

Clarion/PHP 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 PHP script 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/PHP inserts session variable declarations in the appdata.php 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(getSession("ud_myDataVar")) : $SESSION["ud_myDataVar"] = ""; endif;

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 labeled “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 PHP 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).


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 PHP 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 PHP page generated by the template never opens that particular table.

Global Template Declarations To declare a user defined variable, open the PHP 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.


Accessing the Embed Points To access the embed points, the developer selects a browse or form procedure with the Clarion/PHP 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/PHP 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 PHP 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 PHP module, and must therefore be valid PHP code.

Browse Embed Points The Clarion/PHP 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/PHP 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

Form Embed Points

The form embeds have four separate sub nodes for the four update modes: Add, Edit, Delete and View. You may see the implementation of this when looking at the php directory, and seeing four separate pages for each procedure, in the format UpdateProcedureNamemode.php, 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 php directory, and seeing two pages each, ending in “add.php”, “addx.php”, “edit.php”, and “editx.php.” 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)

• After MoveFirst (this executes after opening the recordset and moving the cursor to the first record; Edit and View modes only).

Merge Call

The merge call refers to the point at which the PHP 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

• 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


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/PHP 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 PHP 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/PHP view mode nodes in the embed tree.

• Select the RecordSetObject/AfterMoveFirst/Code node and press Insert.

• Select Source Code/Source.


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 the last purchase date // First, declare and init the variable for the SQL statement $ud_MySQL = "SELECT dbo.Orders.OrderDate FROM dbo.Orders WHERE dbo.Orders.CustomerID = '" . $oRSCustomers->Fields("CustomerID") . "' ORDER BY dbo.Orders.OrderDate DESC"; // Declare a recordset variable and create it by using the Connection object Execute method and the SQL statement $ud_rsTemp = &$objConn1->Execute($ud_MySQL); // Check if there are recors $ud_OrderCount = $ud_rsTemp->RecordCount(); // if so... if ($ud_OrderCount > 0): // Move to the first record $ud_rsTemp->MoveFirst(); // and assign the ud_lastpurchase variable $ud_lastpurchase = $ud_rsTemp->Fields("OrderDate"); else: // else, clear the variable $ud_lastpurchase = ""; endif; // Close the recordset $ud_rsTemp->Close(); // and dispose it unset($ud_rsTemp);

• 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).

• Save the .app and generate the PHP 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 PHP 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:

<<< example code will change >>> // display total purchases // declare a new recordset and SQL string variable // use some unique prefix to prevent name clashes // with generated variable names // // Reuses the record set variable and the string // for the new SQL select statement from the last embed // 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") . "' GROUP BY Orders.CustomerID" // Open the recordset using the existing connection object // and move to the first (and presumably only) record $ud_oRSTemp = &$objConn1->Execute($ud_MySQL); // Test that it is not empty otherwise the customer never ordered // anything and display the word none // and use the format currency function (found in utils.php) $ud_RecCount = $ud_oRSTemp->RecordCount(); if ($ud_RecCount > 0): $ud_oRSTemp->MoveFirst(); $ud_sumPurchases = FormatCurrency($ud_oRSTemp->Fields("SumTotal")); else: $ud_sumPurchases = ""; endif; // Do not forget to clean up! $ud_oRSTemp->Close(); unset($ud_oRSTemp);


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


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") > 0): // Now you can get the recordset variables and calculate $ud_LineItemTotal = ($oRSOrder_Details->Fields("Quantity") * $oRSOrder_Details->Fields("UnitPrice")) - $oRSOrder_Details->Fields("Discount"); else: // otherwise, clear the variable $ud_LineItemTotal = ""; endif;


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 = "";

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.


Ch. 9: HTML Includes Clarion/PHP 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/PHP elements on a procedure by procedure basis, allowing you to provide related functionality to any procedure, 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/PHP@   </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/PHP 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 .php page within your web. (For example, should you place a file called myinclude.htm in the project/php/html directory, then the box should read html/myinclude.htm.


At the time that the end user requests the PHP page that corresponds to the HTML runtime template page, the script in the PHP page will be executed, the merge function will 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 Apache 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 procs.htm file which will be automatically generated by Clarion/PHP, and you’ll see a “table of contents” below your Clarion/PHP 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=/”>


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.


Ch. 10: PHP Source Code Procedure The function of the PHP Source Procedure template is to allow you to execute PHP code inbetween 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 MySQL, for example, which does not yet support triggers, you may utilize the source code procedure for trigger-like functionality.

Additionally, the source code procedure provides an alternative to writing php 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 a PHP 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 PHPSource 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.)

Once the extension is applied, you will see a new embed node called Clarion/PHP for the procedure, and you may use the Embeditor to write the PHP 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).

At generation time, the page generated will be named in the format ProcedureNameSource.php. 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/PHP 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.php.”

• Apply the PHP 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):

// //Declare connection object, recordset, and query string $objConn1 = &ADONewConnection(“mssql”); $objConn1->PConnect(“YourServer”, “UserID”, “Password”, “northwind”); // Set the SQL statement $ud_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 $ud_oRSRecordset = &$objConn1->Execute($ud_mySQL); $ud_oRSRecordSet->MoveFirst(); // // Use the format currency function with 2 decimals // and store it in the session variable $ud_MyRunningTotal = formatCurrency($ud_oRSecordSet->Fields(“RunningTotal”)); // // Clean up! $ud_oRSRecordSet->Close(); unset($ud_oRSRecordset); $objConn1->Close(); unset($objConn1);

• 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.php.

• Generate and test.


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/PHP. 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 .php 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 PHP global extension template, and on the global tab press the Style Sheet Editor button.


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

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.

• 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 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.”

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

• 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 PHP 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.


• 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, Sans-Serif.” 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/PHP 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.


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.


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:

• Width: specify a value either in pixels (the number you wish, followed by “px” without the quotes, or, as a percent for the data background area.




Data Tab

All your data is presented as a table within a table. The Background Class, described previously, governs the outside table. Placing tables within tables is a solution to the limited page layout possibilities of HTML.

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.

• Width: specify a value either in pixels (the number you wish, followed by “px” 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:

• Width: specify thin, medium, thick, or zero to ten pixels.

• Style: specify dotted, dashed, solid, double, groove, ridged, inset, outset or none.

• 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 would 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.


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.


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.


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/PHP automatically adds an up/down arrow on the sorted column to indicate the sort order.








Data Rows Button - Data Tab

Clarion/PHP 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 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. thus, 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 greenbar 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.

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.




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



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:





• Padding (button): set the exterior 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.


Input Label: Data Tab

The input label is the prompt for your update form data controls. You may set the following options:






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 view-only 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 PHP page; and most importantly, for View Only forms and fields, which dispense with the control and simply print the data in the cell.








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/PHP 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.


Index: ?WHR...................................................... 155 <a> .......................................................... 129 <A>.................................................. 135, 155 <br> ......................................................... 124 access level............................................... 59 Actions tab............................................... 142 Add Button................................................. 92 Add Procedure ........................................ 122 Additional Cell Style ................................ 132 Additional Parameters............................. 128 Additional Row Style ....................... 115, 132 Administration.......................................... 107 ADO.................................44, 60, 63, 99, 107 Alert Text Message ................................. 151 alignment................................................. 179 Alignment ........................................ 131, 134 All Data.................................................... 121 ALT text ..................................................... 91 Annotated Examples ......................... 61, 179 Appearance............................................. 148 application wizard........................................ 9 Ascending/Descending Sort.................... 130 Automatic Detail Link .............................. 133 Back Button............................................... 88 Background Class ................................... 186 Body Tag................................................. 183 Borders.................................................... 188 Browse extension template ............. 112, 113 Browse template ....................................... 64 Browse to Browse ..................................... 71 Builder page ............................................ 144 Calendar Popup ........................................ 93 Cannot be Null ........................................ 150 Caption ............................................ 149, 154 cascading style sheets .............................. 80 Cascading Style Sheets .............................. 7 CDONTS ................................................. 108 checkbox on query form.......................... 149 child browse .............................................. 71 Clear Filter............................................... 121 Clear Filter Prompt .................................... 92 client side validation ....................12, 56, 150 Client/Server.............................................. 44 Color picker dialog .................................. 185 Column Header Text ............................... 130

column label ............................................191 Column Name..........................................134 Column to Test ........................................132 Column With Value to Return..................119 Combo Options........................................153 conditional row formatting .......................114 Conditional row formatting.......................114 connection builder ...................................100 Connection Builder ....................................14 connection object ................................44, 84 Connection Properties.............................100 connection string .........................................7 Control Location ......................................154 Control Name ..........................................154 Cookies....................................................105 Create column as a Link..........................128 Create Detail Link......................................91 Create this as a Link................................154 Create this Column as Link .....................134 Custom Controls......................................153 custom link...............................................133 Custom Link.....................................128, 155 Data Column to Pass ......................128, 154 Data Columns..........................................123 data dictionary ...........................................11 Data Records per HTML List.....................91 Data Row.................................................132 database dictionary ...............................9, 55 Debug mode..............................................97 Default Cell Style .....................................132 Default Row Style....................................114 Default SQL.............................................122 Delete ......................................................142 Delete Form...............................................70 Delete Row..............................................147 Design Time HTML Template ...................79 Display Column .......................................153 do not populate............................................9 Do Not Populate ........................................12 Edit ..........................................................142 email ........................................................140 Email........................................................107 E-Mail ......................................................105 embed point.............................................145 Enable Cell Style .....................................132


Enable Security ....................................... 116 Enable Sorting by this Column................ 130 Enhanced ADO Error Reporting.............. 108 Enter Display Text................................... 154 Field Lookup Buttons ................................ 13 File Drop Lists ........................................... 13 file loaded list box.................................... 152 font ..................................................179, 184 Font ......................................................... 182 Form Button Text ...................................... 94 Form Defaults............................................ 93 form extension......................................... 138 form fields.................................................. 81 Form Message Text .................................. 95 Form Primary Table ................................ 146 form template ............................................ 65 Form Titles ................................................ 95 Form Validation ......................................... 96 formatting ................................................ 179 Formatting Function ................................ 132 formatting options.................................... 179 formatting tags........................................... 51 generation ...................................75, 80, 179 Generation........................................... 97, 98 global extension ........................................ 87 global extension template ......................... 14 global template.......................................... 63 Global Template........................................ 63 greenbar .................................................. 115 header ..................................................... 190 help.......................................................... 145 Help ........................................................... 75 Help Link ................................................... 88 Help Pages................................................ 99 Help URL........................................... 75, 118 Hover....................................................... 181 HTML controls ........................................... 59 HTML design time template ...................... 14 HTML editor......................................... 59, 79 HTML Element ........................................ 152 HTML Form Element............................... 149 HTML Pages ............................................. 98 HTML parameter ....................................... 83 HTML run-time template ........................... 57 HTML template................................ 7, 59, 79 Hyperlink ................................................. 135 hyperlink colors ....................................... 181

ID Value Column .....................................136 Image Button ...................................136, 156 Image Column .................................136, 156 Image Sizes.............................................110 images .......................................................56 Images.....................................................109 Include in the SQL Select But Do Not

Display .................................................126 Include With Prior Column.......................126 input label ................................................195 Insert........................................................142 ISAM databases ........................................11 Javascript ..................................................12 JOIN ................................................119, 123 key .............................................................11 Key ............................................................65 Key to Pass .............................................128 LIKE.........................................................121 link .........................................71, 83, 85, 133 Link ............................................................68 links .......................................................7, 51 list defaults.................................................90 localhost ....................................................77 Location ...................................................134 locator........................................................92 Locator.....................................................120 Login Screen Text ...................................106 Lookup.....................................................151 Lookup SQL.............................................153 margins............................................185, 189 Maximum Characters ..............................150 merge ........................................................79 Must Be In File.........................................151 Must be in List ...........................................96 Must Be In List.........................................150 Must be in Numeric Range......................150 Must be in table .........................................15 Must be in Table..................................58, 74 My Records .........56, 60, 114, 115, 140, 150 Navigation Bar ...........................................91 nbsp;........................................................125 No Records Found ....................................92 No Validation ...........................................150 Northwind sample database....116, 141, 148 Numeric Field ............................................96 Omit From QBF Page..............................149 Order clause............................................123


override ................................................... 113 Override................................................... 138 Padding ................................................... 189 Page Naming Conventions ....................... 84 Page Title ................................................ 118 parent browse............................................ 71 Parent Browse......................................... 145 Pass this Data ................................. 128, 154 pixels ....................................................... 131 Populate .................................................. 154 Populate From................................. 136, 154 Populated From............................... 119, 123 popup calendar ....................................... 110 popup window ........................................... 99 precision .................................................. 148 Primary File ............................................... 65 Primary Table.......................................... 120 Procedure Link ................................ 128, 154 Processor page ....................................... 144 Processor Pages....................................... 56 procs.htm.............................................. 77,83 QBF Procedure ....................................... 118 Query by Form ............................67, 70, 145 Query By Form Button .............................. 92 query form ................................................. 66 Range Limit ....................................... 71, 126 range select............................................... 67 Read Only ............................................... 149 read only form ......................................... 143 Regenerate SQL ............................. 122, 146 repeat add ............................................... 145 Repeat Add Mode ................................... 144 Required Field..................................... 94, 96 resultset..................................................... 44 return mechanism ................................... 143 Return to Filtered Browse ....................... 143 Row Style ................................................ 114 Rows and Columns ................................. 150 Run Time HTML Template........................ 80 runtime user ID........................................ 100 scalable ..................................................... 60 Search ..................................................... 142 Search Mode............................................. 94 secure http................................................. 60 security .............................................. 11, 140 Security ........................................... 114, 117 Security Level.................................. 105, 141

security model ...................................56, 103 security options..........................................14 security scheme ........................................59 select browse.......................73, 98, 118, 151 Select Mode Procedure...........................118 Select Options .........................................152 session variable.........................84, 116, 140 Session Variable to Pass ................128, 154 SESSION() ..............................................155 shopping cart ...........................................133 Show Help .................................................88 Site Title...................................................107 smtp.........................................................108 SQL .............................44, 60, 119, 122, 147 SQL date/time field..................................125 SQL for Selection ....................................147 Standard Colors ......................................185 stateless ................................................7, 83 Static Entry ......................................128, 154 status message .......................................144 status messages .....................................142 Status Text ................................................95 style sheet ...........................................7, 197 Style Sheet ................................................98 style sheet editor .....................................179 style sheets................................................57 Table With Image ....................................156 target .........................................................81 Target Column.........................................153 Target Language .......................................88 target page ..............................................144 template chains .........................................13 test/debug page.........................................77 Test/Debug page.......................................98 Text Alignment.........................................183 Text Decoration .......................................182 Text Transformation ................................182 timeout.......................................................59 token..........................................................80 Tool Tip....................................................149 Tool Tips....................................................91 tooltips .......................................................11 Tooltips ......................................................88 triggers.......................................................11 TRN file......................................................88 TRN files....................................................60 Type of Procedure...................................155


unencrypted............................................... 60 Unique ID Column................................... 153 Unique Key.............................................. 146 Update Form ....................................... 68, 70 URL ........................................................... 66 URL parameters........................................ 56 User Based Security ............................... 104 user defined variable............................... 145 User Table............................................... 104 Validity Checks............................................ 7

Value Column..........................................153 VBScript...................................................155 view ...........................................................11 View.........................................................142 View Form .................................................93 web designer .....................................57, 179 Where clause...........................................123 Width .......................................................131 window control types .................................12 Window Size..............................................98

Php 11 Users Guide

Documents

Transcript of Php 11 Users Guide