CLARION/PHP User's Guide

Document Sample
CLARION/PHP User's Guide Powered By Docstoc
					CLARION/PHP

User’s Guide
2                                                                      CLARION/PHP User’s Guide


COPYRIGHT 1994-2003 SoftVelocity Incorporated. All rights reserved.

This publication is protected by copyright and all rights are reserved by SoftVelocity Incorporated. It
may not, in whole or part, be copied, photocopied, reproduced, translated, or reduced to any
electronic medium or machine-readable form without prior consent, in writing, from SoftVelocity
Incorporated.

This publication supports Clarion. It is possible that it may contain technical or
typographical errors. SoftVelocity Incorporated provides this publication “as is,” without
warranty of any kind, either expressed or implied.



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)
CLARION/PHP User’s Guide                                                                                                                  3


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
4                                                                                           CLARION/PHP User’s Guide

          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
CLARION/PHP User’s Guide                                                                                                                   5

   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
6                                                                                               CLARION/PHP User’s Guide


    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
CLARION/PHP User’s Guide                                                                           7


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
8                                                                CLARION/PHP User’s Guide

            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.
CLARION/PHP User’s Guide                                                                            9


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.
10                                                         CLARION/PHP User’s Guide

     •   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.
CLARION/PHP User’s Guide                                                                           11


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
12                                                                  CLARION/PHP User’s Guide

             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.
CLARION/PHP User’s Guide                                                                          13


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.
14                                                                 CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                         15


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.
16                                                                CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                       17


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.
18                                                                CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                    19


      The installation wizard begins with a simple introductory screen.




      The License screen, if you've never installed open source software, may be surprisingly
      brief:
20                                                                CLARION/PHP User’s Guide

     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.
CLARION/PHP User’s Guide                                                                           21




      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.
22                                                                CLARION/PHP User’s Guide

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
CLARION/PHP User’s Guide                                                                           23


      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"
24                                                                 CLARION/PHP User’s Guide




     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.
CLARION/PHP User’s Guide                                                                            25

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).
26                                                              CLARION/PHP User’s Guide

     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
CLARION/PHP User’s Guide                                                                            27


      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"
28                                                            CLARION/PHP User’s Guide


     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.
CLARION/PHP User’s Guide                                                                          29


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).
30                                                           CLARION/PHP User’s Guide


     The result should be a page looking like the one below. You’ve now enabled PHP
     support.
CLARION/PHP User’s Guide                                                                          31


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.
32                                                                   CLARION/PHP User’s Guide


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"
CLARION/PHP User’s Guide                                                                        33

      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.
34                                                              CLARION/PHP User’s Guide


     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.
CLARION/PHP User’s Guide                                                                       35

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:
36                                                               CLARION/PHP User’s Guide




      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.
CLARION/PHP User’s Guide                                                                         37

      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
38                                                                     CLARION/PHP User’s Guide


      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.
CLARION/PHP User’s Guide                                                                             39


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.
40                                                                CLARION/PHP User’s Guide


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
CLARION/PHP User’s Guide                                                                         41

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.
42                                                               CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                     43


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.
44                                                              CLARION/PHP User’s Guide


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/PHP User’s Guide                                                                       45


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.
46                                                                     CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                       47


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.
48                                                                 CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                          49


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.
50                                                                   CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                         51


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.
52                                                              CLARION/PHP User’s Guide


     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:
CLARION/PHP User’s Guide                                                                        53


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.
54   CLARION/PHP User’s Guide
CLARION/PHP User’s Guide                                                                     55


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.
56                                                               CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                       57


      •       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.
58                                                                 CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                         59

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.
60                                                                CLARION/PHP User’s Guide


     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.
CLARION/PHP User’s Guide                                                                     61


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.
62   CLARION/PHP User’s Guide
CLARION/PHP User’s Guide                                                                        63


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.
64                                                             CLARION/PHP User’s Guide


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.

     3.     Press the Insert button in the Extension and Control Templates 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.
CLARION/PHP User’s Guide                                                                     65


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.

      3.      Press the Insert button in the Extension and Control Templates 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.
66                                                                 CLARION/PHP User’s Guide


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.)
CLARION/PHP User’s Guide                                                                          67

      •       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.
68                                                                 CLARION/PHP User’s Guide

     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.

     4.      Save changes and regenerate.
CLARION/PHP User’s Guide                                                                          69

      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.

      10.     Save changes and regenerate.
70                                                                  CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                          71

      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.
72                                                                  CLARION/PHP User’s Guide

     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.
CLARION/PHP User’s Guide                                                                            73

      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.
74                                                                 CLARION/PHP User’s Guide

     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.
CLARION/PHP User’s Guide                                                                         75

      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.”
76                                                               CLARION/PHP User’s Guide

     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.
CLARION/PHP User’s Guide                                                                           77


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.
78                                                             CLARION/PHP User’s Guide




     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.
CLARION/PHP User’s Guide                                                                        79

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.
80                                                                  CLARION/PHP User’s Guide


      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.
CLARION/PHP User’s Guide                                                                          81


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.
82                                                              CLARION/PHP User’s Guide


     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.
CLARION/PHP User’s Guide                                                                            83


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.
84                                                               CLARION/PHP User’s Guide

     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.
CLARION/PHP User’s Guide                                                                           85

      •       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.
86                                                                CLARION/PHP User’s Guide


     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:
CLARION/PHP User’s Guide                                                                      87


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.
88                                                                CLARION/PHP User’s Guide

     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.”
CLARION/PHP User’s Guide                                                                         89


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.
90                                                                  CLARION/PHP User’s Guide


      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.
CLARION/PHP User’s Guide                                                                        91

      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
92                                                                CLARION/PHP User’s Guide

     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.
CLARION/PHP User’s Guide                                                                         93


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.
94                                                                  CLARION/PHP User’s Guide

     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
CLARION/PHP User’s Guide                                                                        95

      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.
96                                                                 CLARION/PHP User’s Guide

     •       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.
CLARION/PHP User’s Guide                                                                     97

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.
98                                                                 CLARION/PHP User’s Guide

     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
CLARION/PHP User’s Guide                                                                       99

              .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.
100                                                                CLARION/PHP User’s Guide

      •       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.
CLARION/PHP User’s Guide                                                                       101


      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.
102                                                               CLARION/PHP User’s Guide

      •       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.
CLARION/PHP User’s Guide                                                                       103

      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:
104                                                                CLARION/PHP User’s Guide

      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.
CLARION/PHP User’s Guide                                                                           105

      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.
106                                                                   CLARION/PHP User’s Guide


      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.
CLARION/PHP User’s Guide                                                                       107

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.
108                                                               CLARION/PHP User’s Guide


      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
CLARION/PHP User’s Guide                                                                       109


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.
110                                                                CLARION/PHP User’s Guide


      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.
CLARION/PHP User’s Guide                                                                    111




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.
112                                                                CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                    113


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”
114                                                                CLARION/PHP User’s Guide

      •       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
CLARION/PHP User’s Guide                                                                         115

              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.
116                                                                CLARION/PHP User’s Guide

      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.
CLARION/PHP User’s Guide                                                                          117

      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
118                                                                CLARION/PHP User’s Guide

      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).
CLARION/PHP User’s Guide                                                                        119




      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).
120                                                                 CLARION/PHP User’s Guide




      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.
CLARION/PHP User’s Guide                                                                       121

      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.
122                                                             CLARION/PHP User’s Guide


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).
CLARION/PHP User’s Guide                                                                           123

      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.
124                                                               CLARION/PHP User’s Guide




      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.
CLARION/PHP User’s Guide                                                                        125


      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.
126                                                                CLARION/PHP User’s Guide


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 &nbsp; (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.
CLARION/PHP User’s Guide                                                                         127

      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.
128                                                                CLARION/PHP User’s Guide

      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.
CLARION/PHP User’s Guide                                                                         129


      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.
130                                                         CLARION/PHP User’s Guide

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.
CLARION/PHP User’s Guide                                                                    131

      •     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.
132                                                                 CLARION/PHP User’s Guide


      •       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.
CLARION/PHP User’s Guide                                                                        133

      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:myemailaddress@mysite.com?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:
134                                                               CLARION/PHP User’s Guide

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.
CLARION/PHP User’s Guide                                                                         135

      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.
136                                                                CLARION/PHP User’s Guide

      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.
CLARION/PHP User’s Guide                                                                    137

      •       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.
138                                                              CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                    139




      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.
140                                                                 CLARION/PHP User’s Guide

      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.
CLARION/PHP User’s Guide                                                                        141


      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.
142                                                               CLARION/PHP User’s Guide

      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.
CLARION/PHP User’s Guide                                                                      143

      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.
144                                                                CLARION/PHP User’s Guide

      •       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
CLARION/PHP User’s Guide                                                                      145

      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.
146                                                                CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                         147



      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
148                                                                CLARION/PHP User’s Guide

      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
CLARION/PHP User’s Guide                                                                        149

      •       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.
150                                                                 CLARION/PHP User’s Guide


      •       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.
CLARION/PHP User’s Guide                                                                       151

      •       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.
152                                                                CLARION/PHP User’s Guide




      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.
CLARION/PHP User’s Guide                                                                    153




      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:
154                                                                CLARION/PHP User’s Guide

      •       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).
CLARION/PHP User’s Guide                                                                         155

      •       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>
156                                                                CLARION/PHP User’s Guide


      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.
CLARION/PHP User’s Guide                                                                       157


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).
158                                                               CLARION/PHP User’s Guide


      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.
CLARION/PHP User’s Guide                                                                     159

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).
160                                                                  CLARION/PHP User’s Guide

      •       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.”
CLARION/PHP User’s Guide                                                                         161


      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
162                                                             CLARION/PHP User’s Guide


      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
CLARION/PHP User’s Guide                                                                       163


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.
164                                                               CLARION/PHP User’s Guide


      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.
CLARION/PHP User’s Guide                                                       165


      •     Deploy and test. The end result should look something like this:
 166                                                                            CLARION/PHP User’s Guide


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);
CLARION/PHP User’s Guide                                                                     167


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.

      •       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!):
             // 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;
168                                                                 CLARION/PHP User’s Guide

      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.

      •       Select Source Code/Source.

      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.
CLARION/PHP User’s Guide                                                                       169


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.
170                                                              CLARION/PHP User’s Guide


      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>
      <!--@HTML_AFTER_OPEN@-->
      <head>
      <!--@HEAD_AFTER_OPEN@-->
      <title></title>
      <!--@HEAD_BEFORE_CLOSE@-->
      </head>
      <body>
      <!--@BODY_AFTER_OPEN@-->
      <!--@BG_BEFORE_OPEN@-->
      @Clarion/PHP@
      <!--@BG_AFTER_CLOSE@-->
      <!--@BODY_BEFORE_CLOSE@-->
      </body>
      <!--@HTML_BEFORE_CLOSE@-->
      </html>
CLARION/PHP User’s Guide                                                                     171



      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.
172                                                                  CLARION/PHP User’s Guide


      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=/”>
CLARION/PHP User’s Guide                                                                 173

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.
174   CLARION/PHP User’s Guide
CLARION/PHP User’s Guide                                                                    175


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.
176                                                                 CLARION/PHP User’s Guide




      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.
CLARION/PHP User’s Guide                                                                       177


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.
178                                                             CLARION/PHP User’s Guide


      •     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.
CLARION/PHP User’s Guide                                                                       179


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.
180                                                                 CLARION/PHP User’s Guide




      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.
CLARION/PHP User’s Guide                                                                     181




      •       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).
182                                                                 CLARION/PHP User’s Guide




      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.
CLARION/PHP User’s Guide                                                                        183

      •       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.
184                                                                    CLARION/PHP User’s Guide


      •       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.
CLARION/PHP User’s Guide                                                                      185


      The following options are present in the Font dialog:

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

      •       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.
186                                                               CLARION/PHP User’s Guide


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.

      •       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.”
CLARION/PHP User’s Guide                                                                         187

      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.

      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.”
188                                                                CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                      189


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.
190                                                                 CLARION/PHP User’s Guide


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.

      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 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.
CLARION/PHP User’s Guide                                                                          191

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.




      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.

      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 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.
192                                                                 CLARION/PHP User’s Guide


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.
CLARION/PHP User’s Guide                                                                           193

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

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

      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 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.
194                                                                 CLARION/PHP User’s Guide


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:




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

      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 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 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.
CLARION/PHP User’s Guide                                                                          195


Input Label: Data Tab
      The input label is the prompt for your update form data controls. 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.

      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 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 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: 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
196                                                                 CLARION/PHP User’s Guide

      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.




      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.

      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 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 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.
CLARION/PHP User’s Guide                                                                   197


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.
198   CLARION/PHP User’s Guide
CLARION/PHP User’s Guide                                                                                                         199


Index:
?WHR...................................................... 155       column label ............................................191
<a> .......................................................... 129   Column Name..........................................134
<A>.................................................. 135, 155       Column to Test ........................................132
<br> ......................................................... 124   Column With Value to Return..................119
access level............................................... 59       Combo Options........................................153
Actions tab............................................... 142       conditional row formatting .......................114
Add Button................................................. 92       Conditional row formatting.......................114
Add Procedure ........................................ 122           connection builder ...................................100
Additional Cell Style ................................ 132           Connection Builder ....................................14
Additional Parameters............................. 128               connection object ................................44, 84
Additional Row Style ....................... 115, 132                Connection Properties.............................100
Administration.......................................... 107         connection string .........................................7
ADO................................. 44, 60, 63, 99, 107             Control Location ......................................154
Alert Text Message ................................. 151             Control Name ..........................................154
alignment................................................. 179       Cookies....................................................105
Alignment ........................................ 131, 134          Create column as a Link..........................128
All Data.................................................... 121     Create Detail Link......................................91
ALT text ..................................................... 91    Create this as a Link................................154
Annotated Examples ......................... 61, 179                 Create this Column as Link .....................134
Appearance ............................................. 148         Custom Controls......................................153
application wizard........................................ 9         custom link...............................................133
Ascending/Descending Sort.................... 130                    Custom Link.....................................128, 155
Automatic Detail Link .............................. 133             Data Column to Pass ......................128, 154
Back Button ............................................... 88       Data Columns..........................................123
Background Class ................................... 186             data dictionary ...........................................11
Body Tag ................................................. 183       Data Records per HTML List.....................91
Borders.................................................... 188      Data Row.................................................132
Browse extension template ............. 112, 113                     database dictionary ...............................9, 55
Browse template ....................................... 64           Debug mode ..............................................97
Browse to Browse ..................................... 71            Default Cell Style .....................................132
Builder page ............................................ 144        Default Row Style ....................................114
Calendar Popup ........................................ 93           Default SQL .............................................122
Cannot be Null ........................................ 150          Delete ......................................................142
Caption ............................................ 149, 154        Delete Form...............................................70
cascading style sheets .............................. 80             Delete Row ..............................................147
Cascading Style Sheets .............................. 7              Design Time HTML Template ...................79
CDONTS ................................................. 108         Display Column .......................................153
checkbox on query form.......................... 149                 do not populate............................................9
child browse .............................................. 71       Do Not Populate ........................................12
Clear Filter............................................... 121      Edit ..........................................................142
Clear Filter Prompt .................................... 92          email ........................................................140
client side validation .................... 12, 56, 150              Email........................................................107
Client/Server.............................................. 44       E-Mail ......................................................105
Color picker dialog .................................. 185           embed point.............................................145
Column Header Text ............................... 130               Enable Cell Style .....................................132
 200                                                                                       CLARION/PHP User’s Guide

Enable Security ....................................... 116           ID Value Column .....................................136
Enable Sorting by this Column................ 130                     Image Button ...................................136, 156
Enhanced ADO Error Reporting.............. 108                        Image Column .................................136, 156
Enter Display Text................................... 154             Image Sizes.............................................110
Field Lookup Buttons ................................ 13              images .......................................................56
File Drop Lists ........................................... 13        Images.....................................................109
file loaded list box.................................... 152          Include in the SQL Select But Do Not
font .................................................. 179, 184         Display .................................................126
Font ......................................................... 182    Include With Prior Column.......................126
Form Button Text ...................................... 94            input label ................................................195
Form Defaults............................................ 93          Insert........................................................142
form extension......................................... 138           ISAM databases ........................................11
form fields.................................................. 81      Javascript ..................................................12
Form Message Text .................................. 95               JOIN ................................................119, 123
Form Primary Table ................................ 146               key .............................................................11
form template ............................................ 65         Key ............................................................65
Form Titles ................................................ 95       Key to Pass .............................................128
Form Validation ......................................... 96          LIKE.........................................................121
formatting ................................................ 179       link .........................................71, 83, 85, 133
Formatting Function ................................ 132              Link ............................................................68
formatting options.................................... 179            links .......................................................7, 51
formatting tags........................................... 51         list defaults.................................................90
generation ................................... 75, 80, 179            localhost ....................................................77
Generation........................................... 97, 98          Location ...................................................134
global extension ........................................ 87          locator........................................................92
global extension template ......................... 14                Locator.....................................................120
global template .......................................... 63         Login Screen Text ...................................106
Global Template ........................................ 63           Lookup.....................................................151
greenbar .................................................. 115       Lookup SQL.............................................153
header ..................................................... 190      margins............................................185, 189
help.......................................................... 145    Maximum Characters ..............................150
Help ........................................................... 75   merge ........................................................79
Help Link ................................................... 88      Must Be In File.........................................151
Help Pages................................................ 99         Must be in List ...........................................96
Help URL........................................... 75, 118           Must Be In List.........................................150
Hover....................................................... 181      Must be in Numeric Range......................150
HTML controls ........................................... 59          Must be in table .........................................15
HTML design time template ...................... 14                   Must be in Table ..................................58, 74
HTML editor......................................... 59, 79           My Records .........56, 60, 114, 115, 140, 150
HTML Element ........................................ 152             Navigation Bar ...........................................91
HTML Form Element............................... 149                  nbsp;........................................................125
HTML Pages ............................................. 98           No Records Found ....................................92
HTML parameter ....................................... 83             No Validation ...........................................150
HTML run-time template ........................... 57                 Northwind sample database....116, 141, 148
HTML template................................ 7, 59, 79               Numeric Field ............................................96
Hyperlink ................................................. 135       Omit From QBF Page..............................149
hyperlink colors ....................................... 181          Order clause ............................................123
CLARION/PHP User’s Guide                                                                                                         201

override ................................................... 113     security model ...................................56, 103
Override................................................... 138      security options..........................................14
Padding ................................................... 189      security scheme ........................................59
Page Naming Conventions ....................... 84                   select browse.......................73, 98, 118, 151
Page Title ................................................ 118      Select Mode Procedure...........................118
parent browse............................................ 71         Select Options .........................................152
Parent Browse......................................... 145           session variable.........................84, 116, 140
Pass this Data ................................. 128, 154            Session Variable to Pass ................128, 154
pixels ....................................................... 131   SESSION() ..............................................155
Populate .................................................. 154      shopping cart ...........................................133
Populate From................................. 136, 154              Show Help .................................................88
Populated From............................... 119, 123               Site Title...................................................107
popup calendar ....................................... 110           smtp.........................................................108
popup window ........................................... 99          SQL .............................44, 60, 119, 122, 147
precision .................................................. 148     SQL date/time field..................................125
Primary File ............................................... 65      SQL for Selection ....................................147
Primary Table .......................................... 120         Standard Colors ......................................185
Procedure Link ................................ 128, 154             stateless ................................................7, 83
Processor page ....................................... 144           Static Entry ......................................128, 154
Processor Pages....................................... 56            status message .......................................144
procs.htm.............................................. 77,83        status messages .....................................142
QBF Procedure ....................................... 118            Status Text ................................................95
Query by Form ............................ 67, 70, 145               style sheet ...........................................7, 197
Query By Form Button .............................. 92               Style Sheet ................................................98
query form ................................................. 66      style sheet editor .....................................179
Range Limit ....................................... 71, 126          style sheets................................................57
range select............................................... 67       Table With Image ....................................156
Read Only ............................................... 149        target .........................................................81
read only form ......................................... 143         Target Column.........................................153
Regenerate SQL ............................. 122, 146                Target Language .......................................88
repeat add ............................................... 145       target page ..............................................144
Repeat Add Mode ................................... 144              template chains .........................................13
Required Field ..................................... 94, 96          test/debug page.........................................77
resultset..................................................... 44    Test/Debug page.......................................98
return mechanism ................................... 143             Text Alignment.........................................183
Return to Filtered Browse ....................... 143                Text Decoration .......................................182
Row Style ................................................ 114       Text Transformation ................................182
Rows and Columns ................................. 150               timeout.......................................................59
Run Time HTML Template........................ 80                    token..........................................................80
runtime user ID........................................ 100          Tool Tip....................................................149
scalable ..................................................... 60    Tool Tips....................................................91
Search ..................................................... 142     tooltips .......................................................11
Search Mode ............................................. 94         Tooltips ......................................................88
secure http................................................. 60      triggers.......................................................11
security .............................................. 11, 140      TRN file......................................................88
Security ........................................... 114, 117        TRN files....................................................60
Security Level.................................. 105, 141            Type of Procedure...................................155
 202                                                                                      CLARION/PHP User’s Guide

unencrypted............................................... 60        Value Column ..........................................153
Unique ID Column................................... 153              VBScript...................................................155
Unique Key.............................................. 146         view ...........................................................11
Update Form ....................................... 68, 70           View.........................................................142
URL ........................................................... 66   View Form .................................................93
URL parameters........................................ 56            web designer .....................................57, 179
User Based Security ............................... 104              Where clause...........................................123
user defined variable............................... 145             Width .......................................................131
User Table............................................... 104        window control types .................................12
Validity Checks............................................ 7        Window Size..............................................98

				
DOCUMENT INFO
Shared By:
Stats:
views:770
posted:8/13/2010
language:English
pages:202
Description: CLARION/PHP User's Guide