-change data_type into type

Document Sample
-change data_type into type Powered By Docstoc
					FLAKE = Fast and Loose Application Kreator, Eh?
Author: Mike Cantelon, Last revised: June 2, 2005 (for FLAKE release
1.0.0)

"Documentation programs the programmer." - Professor Bushy

What is FLAKE?

FLAKE is a toolkit for PHP web application development. It provides objects
for abstracting interface element definitions, rendering, and behaviour.
Development started in June of 2003.

FLAKE is an open source project by Neo Code Software, a company specializing in custom web application development
and content management (this site is powered by Publish Button, our flagship product).

Where can FLAKE be used?

FLAKE is licensed under the GPL and can be used freely.

What does FLAKE require to deploy?

FLAKE requires PHP 4.x (higher versions may work, but are untested) and, if using its database capabilities, MySQL and
ADODB.

Why Should I use FLAKE?

Development using FLAKE gives you:
   Speed - Rapid prototyping becomes easy.
   Abstraction - Things that don’t have to be unique can be generic.
   Painless Deployment - FLAKE builds on standard foundations (PHP/MySQL) so deployment is easy.
   Easy Maintenance - Code written in FLAKE is easy to read and easy to update.

How is FLAKE different from other application frameworks?

Conventional program architecture has a Presentation Layer, which encapsulates the look and interface, and an
Application Logic Layer, which encapsulates behaviour. This enables designers to work on the Presentation Layer and
programmers to work on the Application Layer. The problem with this is the Presentation Layer has no defined "handles"
with which to interface with the Application Logic Layer. The interface is somewhere in between the Presentation Layer
and the Application Logic Layer, and is left to be negotiated.

FLAKE solves this problem by creating an Interface Abstraction Layer which lies between the Presentation and
Application Logic Layers. Its role is to define interface elements that can be incorporated into the other layers.

In a typical FLAKE applications the Application Logic Layer is composed of PHP files, the Interface Abstraction Layer
is composed of FLAKE object definitions, and the Presentation Layer is composed of FLAKE HTML templates.

In addition to providing interface abstraction, FLAKE can also abstract application logic. The advantage of this is reduced
implementation time, but the disadvantage is less flexibility. Application logic abstraction, however, is optional. FLAKE
interface objects can be used independently.
SETTING UP FLAKE

FLAKE is fairly easy to set up. It requires PHP with the “register_globals” option set to “on” in php.ini (see note below)
(this limitation may be addressed in a subsequent version). To use any FLAKE objects with database capabilities, ADODB
is required. ADODB is used for database abstraction (FLAKE has only been tested with MySQL).

    Note: To simulate registration of globals, you can use the following code at the beginning of your script (after any
     session variables have been registered).

     # create local references to session variables
     $current_panel = &$_SESSION["current_panel"];
     $search_terms = &$_SESSION["search_terms"];

     # localize variables passed through forms and links
     if ($_GET) {
           reset($_GET);
           while (list($key, $val) = each($_GET)) {
                       $$key = $val;
           }
     }
     if ($_POST) {
           reset($_POST);
           while (list($key, $val) = each($_POST)) {
                       $$key = $val;
           }
     }

To create a FLAKE-ready PHP script, you may simply use an example from the manual as a basis, or follow these
instructions:

1.   Download and untar FLAKE to your directory of choice.
2.   If it isn’t already on your server, download ADODB.
3.   In your PHP script, include ADODB and connect to your MySQL database. For example:

     # Include database abstraction layer
     include(“adodb/adodb.inc.php”);

     # Connect to database
     $db_host = “your hostname”;
     $db_user = “database user”;
     $db_password = “database password”;
     $db_name = “database name”;
     $conn = &ADONewConnection(“mysqlt”);
     $conn->Connect($db_host, $db_user, $db_password, $db_name);

4.   In your PHP script, specify the directory where FLAKE was put by defining the FLAKE_DIR constant. For example:

     define(“FLAKE_DIR”, “flake/”); # the FLAKE_DIR constant must be set

5.   In your PHP script, specify the absolute or relative web path to where FLAKE images are. For example:

     define(“FLAKE_IMAGE_DIR”, “images/”);

6.   In your PHP script, include the default script that includes all FLAKE classes. For example:

     include(FLAKE_DIR . “include_classes.php”);
FLAKE FORM OBJECT

The FLAKE form object handles the creation and processing of forms. FLAKE forms can be “database-bound”, where
form data is added to, updates, or is drawn from a database table. FLAKE forms can be rendered in HTML with a
standard look, or HTML templates can be used to create custom form layouts. FLAKE forms can also handle data
validation, allowing one or more forms of validation to be bound to each form element.

DEFINING FORMS

To define a new form, simply start with the following line:

$form = new form();

A number of attributes can be set to determine the look and behaviour of the form:

     action

               The action is the URL to which form data will be submitted. By default it is the current URL.

     method

               The method is the HTTP method for sending data: GET or POST. POST is the default as it can send larger
                amounts of data and hides form parameters (the GET method shows form parameters in the URL upon
                form submission).

     template

               The template property is used to specify an HTML template to use as the basis of form rendering (see
                section xxx). ALL FOLLOWING FORM ATTRIBUTES ARE OVERRIDDEN WHEN A TEMPLATE IS
                SPECIFIED.

     width

               The width is the width of the HTML table in which to render the form. This is irrelevant if using a template.

     bgcolor

     bgcolor1  impliment

     bgcolor2  impliment

     label_class

               The label_class property specifies the CSS style with which to display label text.*

     no_labels

               The no_labels property, if set, stops the output of a label column.*

     data_class

               The data_class property specifies the CSS style with which to display data text.*

     cell_padding

               The cell_padding property specifies KJKLJKLJLKJKLJKL.*

     cell_spacing

               The cell_padding property specifies KJKLJKLJLKJKLJKL.*

     border

               The border property specifies the width, in pixels, of the border of the HTML form output.*

     width

               The width property specifies the width of the HTML form output.*
* This attribute has no effect if a template has been specified.
FORM->DATABASE INTERACTION

Form data can be associated with a database table (“database-bound”), allowing row inserts and updates to be
automatically handled after submission, providing the form object is redefined on the response page and the data_handler
method is called (see next example).

In order for this to work, ADODB must be used. The ADODB connection object must be passed to the FLAKE form object
for methods where the database is accessed.

To allow a form object to behave this way, the following properties should be set:

     table_name

              The table_name property should be set to the name of the database table the form is to add to or update

     primary_key

              The primary_key property should be set to the name of the primary key column in the specified database
               table

     key_value

              The key_value property gets set after the form object is called upon to handle submitted form data

     mode

              After the form object is called upon to handle submitted form data, mode gets set to “add” or “update”,
               depending on whether a user is adding or updating a record
              If mode is manually set to “view” and a form is database bound, data will be displayed

Here is an example PHP script using FLAKE for database inserts/updates.

          <HTML>
          <HEAD>
                    <TITLE>Form example</TITLE>
          </HEAD>
          <BODY>
          <?
          # Include database abstraction layer
          include("adodb/adodb.inc.php");

          # Connect to database
          $db_host = "your hostname";
          $db_user = "database user";
          $db_password = "database password";
          $db_name = "database name";
          $conn = &ADONewConnection("mysqlt");
          $conn->Connect($db_host, $db_user, $db_password, $db_name);

          # Include FLAKE classes
          define("FLAKE_DIR", "flake/"); # the FLAKE_DIR constant must be set
          include(FLAKE_DIR . "include_classes.php");

          # Define form
          $form = new form();
          $form->table_name = "companies";
          $form->primary_key = "company_id";

          $form->add_column("company_name");
          $form->set("company_name", "label", "Name");

          $form->add_column("company_description");
          $form->set("company_description", "label", "Description");
          $form->set("company_description", "type", "textarea");

          $form->add_element("submit");
          $form->set("submit", "type", "submit");
          $form->set("submit", "value", "Submit");

          # Handle submitted data, if any
          $form->data_handler($conn);

          # Provide user feedback
          if ($form->key_value) {

                     if ($form->mode == "add") {
                                print "Record added. You may update it if it is incorrect. ";
                     } else {
                                print "Record updated. ";
                     }

                     print "Thanks.<p>";
          } else {
                     print "Please enter the name and description of your company.<p>";
          }

          # Output form HTML
          $form->output($conn);
          ?>
          </HTML>

Here is SQL to create the database/table for this example:

          CREATE DATABASE company_database;

          USE company_database;

          CREATE TABLE companies (
            company_id int(11) unsigned NOT NULL auto_increment,
            company_name varchar(255) default '',
            company_description longtext,
            PRIMARY KEY (company_id)
          );

DEFINING FORM ELEMENTS

To add an element to a form, the following syntax is used:
$form->add_element(element_name);

If an element represents a column in a database table, the following syntax is used:
$form->add_column(column_name);

In addition to adding an element or column, you will likely want to set a number of its properties, such as type. To do this,
the following syntax is used:
$form->set(element_name, attribute, value);

FORM ELEMENT TYPES

          hidden

          Hidden form elements are often used to pass information that is hidden from the user. To set a form element to
          be hidden, set the type property to hidden.

          select

          Select form elements are used to allow the user to select one or more options from a number of choices (either
          statically defined, or created by a lookup – see the LOOKUPS section below).

          Options on a select form element can be set by assigning an array of options (such as the example below) to
          the options attribute of a column or form field.

                     Example:

                                $export_types = array(
                                          "value" => array('palm', 'ics', 'quark'),
                                          "display" => array('Palm', 'iCal (ICS)', 'Quark')
                                );

          Or, more easily, the add_option method may be used to create options (see XXXXX).
          The allow_blank property determines whether a blank select option is created if looking up data (see
          XXXXX). test with non-lookup

          checkbox

          Checkboxes are used to get boolean (yes or no, on or off, etc.) input from a user.

          Checkbox checking and unchecking is handled automatically if a form is associated with a database table.

          checkboxes

          The checkboxes form element allows the user to select any number of options from a number of choices (either
          statically defined, or created by a lookup – see the LOOKUPS section below).

          Options on a checkboxes form element can be set by assigning an array of options (such as the example
          below) to the options attribute of a column or form field.

                     Example:

                                $export_types = array(
                                          "value" => array('palm', 'ics', 'quark'),
                                          "display" => array('Palm', 'iCal (ICS)', 'Quark')
                                );

          Or, more easily, the add_option method may be used to create options (see XXXXX).

          textarea

          A textarea form element is used to input larger amounts of text than standard form elements. The rows and cols
          properties specificy the size of the form element in characters;

                     Example textarea:

                                $form->add_element(“employee_bio”);
                                $form->set(“employee_bio”, “type”, “textarea”);
                                $form->set(“employee_bio”, “rows”, “5”);
                                $form->set(“employee_bio”, “cols”, “60”);

          create_date and mod_date

          Create and modification date form elements are used with database-bound FLAKE forms.

          Create date form elements are hidden when a form is displayed to add a new row. When the user submits the
          form, and the row is added to the table, the current date is automatically entered as the create date. When a
          form to update a row is displayed the create date is shown in the form (but cannot be modified).

          Modification date form elements are hidden when a form is displayed to add a new row. When the user submits
          the form, and the row is added to the table, the modification date is shown as "00/00/0000". When the user
          used the form to modify the table date, the current date is automatically entered as the modification date.

OTHER FORM METHODS

To add options to a select or checkboxes or radio type form element, the following syntax is used:
$form->add_option(column name, display text, option value);

To add a section to a form, for readability, the following syntax is used:
$form->add_section(section name);

To get the value of a form element attrubute, the following syntax is used:
$form->get(column name, attribute);

To set the values of a non-database-bound form to submitted values, the following syntax is used:
$form->set_all();

LOOKUPS

A form column or element value can be populated with a value or values from a database table. In order to do this,
specifiy the table name, value column, and, if applicable, display column (display columns are used to provide human-
friendly display data to lookup-generated select and checkboxes form elements).
NEED BETTER EXAMPLE!!!
For example, the lookup below is used to provide an examplee’s default company name by pulling data from the first row
of a table:

$form->add_column(“employee_ department_id”);
$form->set(“employee_department_id”, “table_name”, “company_info”);
$form->set(“employee_department_id”, “value_column”, “company_info_name”);

For another example, the lookup below is used to generate a menu to select which department an employee belongs to
by pulling all rows from a table:

$form->add_column(“employee_department_id”);
$form->set(“employee_department_id”, “type”, “select”);
$form->set(“employee_department_id”, “allow_blank”, 0); # don’t create a blank option
$form->set(“employee_department_id”, “table_name”, “departments”);
$form->set(“employee_department_id”, “value_column”, “department_id”);
$form->set(“employee_department_id”, “display_column”, “department_name”);

OTHER FORM ELEMENT PROPERTIES

     value

               The value property can be used to set the value of a form element

     size

               The size property can be used to set the size (in characters) of the form element

     align

               The align property can be used to set the horizontal alignment of the form element (“left”, “right”, or
                “center”)

     label_align

               The label align property can be used to set the horizontal alignment of the form element’s label (“left”,
                “right”, or “center”)

     class

               The class property specifies a CSS class for the form element being displayed

     plugin

               If a form is in view mode (where data is pulled from a database for display), a plugin function can be
                specified for display outputting (see the COLUMN PLUGINS section in the hitlist section of this
                documentation for how this works)

OUTPUTTING FORMS

Forms can either be rendered directly to output using the output method or returned using the render method (so
the rendered HTML can be stored in a variable, filtered, etc.).

An example of direct output:
$form->output($conn);

An example of storing rendered HTML in a variable:
$output = $form->render($conn);

Form HTML is automatically generated by these functions, unless a template is specified in which case the
template file is used as the basis.

TEMPLATES

To use an HTML template with a form, simply set the template attribute of the form object. For example:

$form->template = “templates/company.html”;

To position form elements in the template, put the form element name enclosed in curly braces. For example: a form
element called company_name would be represented in a template as {company_name}.
FORM VALIDATION

FLAKE forms can handle data validation, allowing one or more forms of validation to be bound to each form element.

To add validation to a form element or column, use the following syntax:
$form->add_validation(element or column name, validation type)

The following validation types may be used:

     not_empty

                Restricts data to non-null values

     numeric

                Restricts data to numberic values

     alphanumeric

                Restricts data to alphanumeric values

     integer

                Restricts data to integer (whole number) values

     email

                Restricts data to syntactically valid email addresses

     date

                Restricts data to valid dates (in mm/dd/yyyy format)

If validation fails, the error property of the form object will be set. The validate method can also be used to check validity
of submitted form data.

Below is an example of using FLAKE form object-based validation:

            <HTML>
            <HEAD>
                      <TITLE>Form validation example</TITLE>
            </HEAD>
            <BODY>
            <?
            # Include FLAKE classes
            define("FLAKE_DIR", "flake/"); # the FLAKE_DIR constant must be set
            include(FLAKE_DIR . "include_classes.php");

            # Create instance of form
            $form = new form();

            # Make any values submitted available for redisplay in the form
            # (if validation has failed)
            $form->localize_form_data();

            # Define form columns and validation types
            $form->add_element("number");
            $form->set("number", "label", "Lucky Number!");
            $form->add_validation("number", "numeric");
            $form->add_validation("number", "not_empty");

            $form->add_element("submit");
            $form->set("submit", "type", "submit");
            $form->set("submit", "value", "Submit");

            # If form doesn't validate, show validation error and display form
            if (!$form->validate()) {
                   print $form->error;
                   print "<p>";
                   $form->output();
} else {
# ...otherwise, show thank you message
      print "Thanks for letting me know your lucky number. Ho ho ho.";
}

?>
</BODY>
</HTML>
FLAKE HITLIST OBJECT

The FLAKE hitlist object handles the output of database query results. FLAKE hitlists can be rendered in HTML with a
standard look, or HTML templates can be used to create custom hitlist layouts (DOCUMENT THIS!!!!!!!). FLAKE hitlists
can also handle paging through and sorting results.

ADODB is used for database connectivity. The ADODB connection object must be passed to the FLAKE hitlist object for
methods where the database is accessed.

DEFINING HITLISTS

To define a new hitlist, simply start with the following line:

$hitlist = new hitlist();

A number of attributes can be set to determine the look and behaviour of the hitlist:

      name

                 The name is the hitlist’s unique identifier (used when dealing with multiple hitlists displayed at once)

      table_name

                 The table_name property should be set to the name of the database table the hitlist is to query

      primary_key

                 The primary_key property should be set to the name of the primary key column in the specified database
                  table

      query

                 The SQL query used by the hitlist to draw results from

      skip_rows

                 The skip_rows property specifies how many rows to skip before displaying rows of the hitlist

      show_rows

                 The show_rows property specifies how many rows to show in the hitlist

      bgcolor

      bgcolor1

      bgcolor2

      label_class

                 The label_class property specifies the CSS style with which to display label text

      data_class

                 The data_class property specifies the CSS style with which to display data text

      link_class

                 The link_class property specifies the CSS style with which to display HTML links

      cell_padding

      border

      width

      view_action
         The view_action is the value to set the argument function to when a user clicks the view icon (the
          magnifying glass, by default) in a hitlist row. If view_action isn’t set, no view icon will be shown in each
          row. If the hitlist is being initialized by a FLAKE app object, there is no need to set the view_action as it
          will be automatically set.

view_alt_text

         The view_alt_text property is the text to show when a user’s mouse hovers over the view icon (the
          magnifying glass, by default) in a hitlist row

edit_action

         The edit_action is the value to set the argument function to when a user clicks the edit icon (the pencil,
          by default) in a hitlist row. If edit_action isn’t set, no edit icon will be shown in each row. If the hitlist is
          being initialized by a FLAKE app object, there is no need to set the edit_action as it will be automatically
          set.

edit_alt_text

         The edit_alt_text property is the text to show when a user’s mouse hovers over the edit icon (the pencil,
          by default) in a hitlist row

delete_action

         The delete_action is the value to set the argument function to when a user clicks the delete icon (the
          trash can, by default) in a hitlist row. If delete_action isn’t set, no delete icon will be shown in each row. If
          the hitlist is being initialized by a FLAKE app object, there is no need to set the delete_action as it will be
          automatically set.

delete_alt_text

         The delete_alt_text property is the text to show when a user’s mouse hovers over the delete icon (the
          trash can, by default) in a hitlist row

promote_action

         The promote_action is the value to set the argument function to when a user clicks the promote icon (the
          up arrow, by default) in a hitlist row. If promote_action isn’t set, no promote icon will be shown in each
          row.

promote_alt_text

         The promote_alt_text property is the text to show when a user’s mouse hovers over the promote icon (the
          up arrow, by default) in a hitlist row

demote_action

         The demote_action is the value to set the argument function to when a user clicks the demote icon (the
          down arrow, by default) in a hitlist row. If demote_action isn’t set, no demote icon will be shown in each
          row.

demote_alt_text

         The demote_alt_text property is the text to show when a user’s mouse hovers over the demote icon (the
          down arrow, by default) in a hitlist row

next_button

         The next_button property specifies the URL of the graphic to use as a button the user clicks for the next
          page of the hitlist

previous_button

         The previous_button property specifies the URL of the graphic to use as a button the user clicks for the
          previous page of the hitlist

default_results_per_page
                The default_results_per_page property specifies the value to set the results per page of the hitlist if not
                 yet specified by the user

DEFINING HITLIST COLUMNS

To add a column to a hitlist, the following syntax is used:
$hitlist->add_column(column_name);

In addition to adding a column, you will likely want to set a number of its properties, such as label. To do this, the
following syntax is used:
$hitlist->set(column_name, attribute, value);

HITLIST COLUMN PROPERTIES

     label

                The label property specifies the text to put at the top of the hitlist to indicate the column’s name or purpose

     link

                ?

     width

                The width property specifies the desired width of the column, in pixels

     limit

                The limit property specifies the maximum number of characters to display as each row’s column data

     plugin

                The plugin property allows column data to be processed by an external function. The plugin property
                 should be set to the name of that function. See the COLUMN PLUGINS section for an example.

     sort_order

                The sort_order property ???

     no_sort

                If the no_sort property is set to any value, a sort arrow icon won’t be shown in the hitlist for that column

     align

                The align property sets the horizontal alignment of column data.

     label_align

                The label_align property sets the horizontal alignment of column labels.

OUTPUTTING HITLISTS

Hitlists can either be rendered directly to output using the output method or returned using the render method (so
the rendered HTML can be stored in a variable, filtered, etc.).

An example of direct output:
$hitlist->output($conn);

An example of storing rendered HTML in a variable:
$output = $hitlist->render($conn);

Hitlist HTML is automatically generated by these functions, unless a template is specified in which case the
template file is used as the basis. THIS DOESN’T WOORK YET

Here’s an example, extending the the earlier form example, that adds the ability to browse/edit/delete records via a
FLAKE hitlist object:

             <HTML>
<HEAD>
          <TITLE>Hitlist example</TITLE>
</HEAD>
<BODY>
<?
# Include database abstraction layer
include("adodb/adodb.inc.php");

# Connect to database
$db_host = "your hostname";
$db_user = "database user";
$db_password = "database password";
$db_name = "database name";
$conn = &ADONewConnection("mysqlt");
$conn->Connect($db_host, $db_user, $db_password, $db_name);

# Include FLAKE classes
define("FLAKE_DIR", "flake/"); # the FLAKE_DIR constant must be set
include(FLAKE_DIR . "include_classes.php");

$form = new form();
$form->localize_form_data();

if (!$function) {

           # Define hitlist
           $hitlist = new hitlist();

           $hitlist->table_name = "companies";
           $hitlist->primary_key = "company_id";

           $hitlist->query = "select * from companies";

           $hitlist->edit_action = "edit_company";

           $hitlist->add_column("company_name");
           $hitlist->set("company_name", "label", "Name");
           $form->set("company_name", "no_sort", "1");

           $hitlist->add_column("company_description");
           $hitlist->set("company_description", "label", "Description");
           $form->set("company_description", "no_sort", "1");

           $hitlist->output($conn);

} else {

           # Define form
           $form = new form();
           $form->table_name = "companies";
           $form->primary_key = "company_id";

           $form->add_column("company_name");
           $form->set("company_name", "label", "Name");

           $form->add_column("company_description");
           $form->set("company_description", "label", "Description");
           $form->set("company_description", "type", "textarea");

           $form->add_element("submit");
           $form->set("submit", "type", "submit");
           $form->set("submit", "value", "Submit");

           # Handle submitted data, if any
           $form->data_handler($conn);

           # Provide user feedback
           if ($form->key_value) {

                       if ($form->mode == "add") {
                                           print "Record added. You may update it if it is incorrect. ";
                                } else {
                                           print "Record updated. ";
                                }

                                print "Thanks.<p>";
                     } else {
                                print "Please enter the name and description of your company.<p>";
                     }

                     if ($function == "edit_company") {
                                 # the $id argument is sent by clicking the edit icon link in the hitlist
                                 $form->key_value = $id;

                                $form->add_column("function");
                                $form->set("function", "type", "hidden");
                                $form->set("function", "value", "update_company");
                     }

                     # Output form HTML
                     $form->output($conn);

                     print "<p><a href='" . $PHP_SELF . "'>Back to hitlist</a>";

          }
          ?>
          </BODY>
          </HTML>

COLUMN PLUGINS

The plugin column property allows you to use a function to process row data. Here is an example (that simply uses a
plugin to output data in red):

          function show_status($fields) {
                    $output = “”;

                     $output = “<font color=red>” . $fields[“status”] . “</font>”;

                     return $output;
          }

          $hitlist->add_column(“status”);
          $hitlist->set(“status”, “plugin”, “show_status”);

HANDLING PAGING

Paging is handled internally by the hitlist object. Paging is kept track of in the “search_terms” session variable, so add the
following line to the start of your PHP script to allow this to happen:

session_register(“search_terms”);

Before showing next/back buttons, call the $hitlist->paging_handler(). If the user has previously moved around paging-
wise, this method will handle the calculation of the current position in paging.

To show next/previous buttons, use the $hitlist->output_paging_options() method (or, to return the resulting HTML into a
variable, use the $hitlist->render_paging_options() method). Next/back buttons are usually shown after the hitlist is output.

To find the position of a specific row, simply provide the get_position method with the primary key value. This can be used
to start displaying hitlist results at a certain row. For example:
$hitlist->skip_rows = $hitlist->get_position(id)

HANDLING SORTING

Sorting is handled internally by the hitlist object. Paging is kept track of in the “search_terms” session variable, so add the
following line to the start of your PHP script to allow this to happen:

session_register(“search_terms”);
Sorting arrows are shown next to column labels. If you don’t define labels for your columns, you won’t see sorting arrows.
If you don’t want the hitlist to be sortable by a certain column, simply set the no_sort attribute for that column.

PRESERVING STATE DURING SORTING/PAGING

You may want to have state data relayed when a user pages through or sorts a hitlist. In order to do this you can use the
add_arg method. For example:

$hitlist->add_arg(“function”, “edit_conference”);

ORDERING

Rows in a table can be given an arbitrary order than can be manually manipulated by clicking up and down arrows in a
FLAKE hitlist. Rows created by a FLAKE form can automatically designate that the new row be at the end of this order.

To have this happen one must specify the column storing the order data by setting the order_column property in the
FLAKE hitlist or form object.

Here is an example PHP script using a FLAKE hitlist and form for ordering data. It shows a hitlist that can be sorted or
paged through (if more than 10 records exist in the table) and ordered (using the up/down arrows).

          <?

          session_register("search_terms");

          ?>
          <HTML>
          <HEAD>
                    <TITLE>Hitlist Ordering example</TITLE>
          </HEAD>
          <BODY>
          <?
          # Include database abstraction layer
          include("adodb/adodb.inc.php");

          # Connect to database
          $db_host = "your hostname";
          $db_user = "database user";
          $db_password = "database password";
          $db_name = "database name";
          $conn = &ADONewConnection("mysqlt");
          $conn->Connect($db_host, $db_user, $db_password, $db_name);

          # Include FLAKE classes
          define("FLAKE_DIR", "flake/"); # the FLAKE_DIR constant must be set
          include(FLAKE_DIR . "include_classes.php");

          #
          # Define form for adding
          #

          $form = new form();
          $form->table_name = "companies_sorted";
          $form->primary_key = "company_id";
          $form->order_column = "company_sortorder";

          $form->add_column("company_name");
          $form->set("company_name", "label", "Name");

          $form->add_column("company_description");
          $form->set("company_description", "label", "Description");
          $form->set("company_description", "type", "textarea");

          $form->add_element("submit");
          $form->set("submit", "type", "submit");
          $form->set("submit", "value", "Submit");

          # Handle submitted data, if any
          $form->data_handler($conn);
          # Provide user feedback
          if ($form->key_value) {

                     if ($form->mode == "add") {
                                print "Record added.<p>";

                               $form2 = new form();

                               $form2->add_element("submit");
                               $form2->set("submit", "type", "submit");
                               $form2->set("submit", "value", "Add Another");
                     }
          } else {
                     print "Please enter the name and description of a company to add.<p>";

                     # Output form HTML
                     $form->output($conn);
          }

          print "<p>";
          print "Use the up/down arrows to re-order the hitlist.";
          print "<p>";

          #
          # Define hitlist for display/ordering
          #

          $hitlist = new hitlist();
          $hitlist->table_name = "companies_sorted";
          $hitlist->primary_key = "company_id";
          $hitlist->order_column = "company_sortorder";

          $hitlist->add_column("company_name");
          $hitlist->set("company_name", "label", "Name");

          $hitlist->add_column("company_description");
          $hitlist->set("company_description", "label", "Description");

          # Handle paging/sorting requests, if any
          $hitlist->paging_handler($conn);

          # Output hitlist HTML
          $hitlist->output($conn);

          # Output paging buttons
          $hitlist->output_paging_options($conn);

          ?>
          </HTML>

Here is SQL to create the database/table for this example:

          CREATE DATABASE company_database;

          USE company_database;

          CREATE TABLE companies_sorted (
            company_id int(11) unsigned NOT NULL auto_increment,
            company_name varchar(255) default '',
            company_description longtext,
            company_sortorder int(10),
            PRIMARY KEY (company_id)
          );
FLAKE MENUBAR OBJECT

The FLAKE menubar object handles the output of navigation bars (optionally incorporating Javascript rollovers). By
default, it also handles button selection (storing the currently selected button in the $current_panel[<menubar name>]
session variable) when a menubar is rendered or output.

DEFINING MENUBARS

To define a new menubar, simply start with the following line:

$menubar = new menubar();

A number of attributes can be set to determine the look and behaviour of the menubar:

     name

               A menubar’s name differentiates it from other menubars on the same page

     default

               Default defines the default menubar button

     html_to_prepend

               HTML can be prepended before each menubar button

     html_to_append

               HTML can be appended before each menubar button

     keep_active_item_on

               If keep_activate_item_on is set to any value and button graphics are defined, the active button will be
                stay on its “on” rollover position after being clicked by a user.

     image_path

               The image path is the path where button and separator graphics will be sought.

     separator_text

               If separator text is set, the separator text will be shown between buttons

     separator_graphic

               If separator graphic is set to an image filename, the separator graphic will be shown between buttons

     html_highlight_begin

               If using text buttons, the HTML specified in this property will be displayed before the text

     html_highlight_end

               If using text buttons, the HTML specified in this property will be displayed after the text

DEFINING MENUBAR BUTTONS

To add a button to a menubar, the following syntax is used:
$menubar->add_button(element_name);

In addition to adding a button, you will need to set a number of its properties. To do this, the following syntax is used:
$menubar->set(button_name, attribute, value); FIXXXX

MENUBAR BUTTON PROPERTIES

     text

               A button’s text property should be set to the text to be shown for the button (if on and off graphics aren’t to
                be used)
     on_graphic

               A button’s on_graphic property should be set to the filename of the “on” graphic for the button

     off_graphic

               A button’s off_graphic property should be set to the filename of the “off” graphic for the button

     url

               A button’s url property should be set to a desired target URL

     status_text

               A button’s status_text property should be set to the text you’d like displayed when a user hovers over the
                button (in the browser status area if using graphical buttons and in the link’s alt and title properties if using
                text links)

     url_target

               A button’s url_target property, if set, will specifiy the name of the window where the page will reload

     align

               A button’s align property, if set, specifies the alignment of a graphic button

ADDING ARGUMENTS TO BUTTON URLS

To add an argument to a button URL, such as “function=logout”, use the following syntax:

$menubar->add_url_arg(button_name, arg_name, arg_value);

For example, the following would add “function=logout” to the URL of the logout_button button:
$menubar->add_url_arg(“logout_button”, “function”, “logout”);

DETERMINING THE ACTIVE BUTTON

To determine which button is active, use the following syntax:
$activate_button = $menubar->find_index_of_active_menubar_item();

OUTPUTTING MENUBARS

Menubars can either be rendered directly to output using the output method or returned using the render method (so
the rendered HTML can be stored in a variable, filtered, etc.).

An example of direct output:
$menubar->output($conn);

An example of storing rendered HTML in a variable:
$output = $menubar->render($conn);

MENUBAR EXAMPLES

Here is an example PHP script using FLAKE menubars to allow a user to navigate "panels" and "subpanels":

           <?

           session_register("current_panel");

           ?>
           <HTML>
           <HEAD>
                     <TITLE>Text Menubar Example</TITLE>
           </HEAD>
           <BODY>
           <?
           # Include FLAKE classes
           define("FLAKE_DIR", "flake/"); # the FLAKE_DIR constant must be set
           include(FLAKE_DIR . "include_classes.php");
#
# Define main menubar
#

$menubar = new menubar();
$menubar->name = "main";
$menubar->keep_active_item_on = 1;
$menubar->default = "home";
$menubar->separator_text = " ";

$menubar->add_button("home");
$menubar->set("home", "text", "Home");

$menubar->add_button("contact");
$menubar->set("contact", "text", "Contact Us");

$menubar->output();

print "<p>";

if ($current_panel["main"] == "home") {

          $menubar = new menubar();
          $menubar->name = "home";
          $menubar->keep_active_item_on = 1;
          $menubar->default = "about";
          $menubar->separator_text = " ";

          $menubar->add_button("about");
          $menubar->set("about", "text", "About Us");

          $menubar->add_button("history");
          $menubar->set("history", "text", "Project History");

          $menubar->output();

          print "<p>";

          if ($current_panel["home"] == "about") {
                     print "About Us";
          }

          if ($current_panel["home"] == "history") {
                     print "Project History";
          }
}

if ($current_panel["main"] == "contact") {

          $menubar = new menubar();
          $menubar->name = "contact";
          $menubar->keep_active_item_on = 1;
          $menubar->default = "info";
          $menubar->separator_text = " ";

          $menubar->add_button("info");
          $menubar->set("info", "text", "Contact Info");

          $menubar->add_button("faq");
          $menubar->set("faq", "text", "Fequently Asked Questions");

          $menubar->output();

          print "<p>";

          if ($current_panel["contact"] == "info") {
                     print "Contact Info";
          }
                   if ($current_panel["contact"] == "faq") {
                              print "Frequently Asked Questions";
                   }
         }

         ?>
         </HTML>

Here is another example PHP script using FLAKE menubars with graphical buttons:

         <?

         session_register("current_panel");

         ?>
         <HTML>
         <HEAD>
                   <TITLE>Graphical Menubar Example</TITLE>
         </HEAD>
         <BODY>
         <?
         # Include FLAKE classes
         define("FLAKE_DIR", "flake/"); # the FLAKE_DIR constant must be set
         include(FLAKE_DIR . "include_classes.php");

         #
         # Define main menubar
         #

         $menubar = new menubar();
         $menubar->name = "main";
         $menubar->keep_active_item_on = 1;
         $menubar->default = "home";
         $menubar->image_path = "images/";

         $menubar->add_button("home");
         $menubar->set("home", "on_graphic", "home-on.gif");
         $menubar->set("home", "off_graphic", "home-off.gif");

         $menubar->add_button("contact");
         $menubar->set("contact", "on_graphic", "contact-on.gif");
         $menubar->set("contact", "off_graphic", "contact-off.gif");

         $menubar->output();

         print "<p>";

         if ($current_panel["main"] == "home") {

                   $menubar = new menubar();
                   $menubar->name = "home";
                   $menubar->keep_active_item_on = 1;
                   $menubar->default = "about";
                   $menubar->separator_text = "<br>";
                   $menubar->image_path = "images/";

                   $menubar->add_button("about");
                   $menubar->set("about", "on_graphic", "about-on.gif");
                   $menubar->set("about", "off_graphic", "about-off.gif");

                   $menubar->add_button("history");
                   $menubar->set("history", "on_graphic", "history-on.gif");
                   $menubar->set("history", "off_graphic", "history-off.gif");

                   $menubar->output();

                   print "<p>";

                   if ($current_panel["home"] == "about") {
                              print "About Us";
          }

          if ($current_panel["home"] == "history") {
                     print "Project History";
          }
}

if ($current_panel["main"] == "contact") {

          $menubar = new menubar();
          $menubar->name = "contact";
          $menubar->keep_active_item_on = 1;
          $menubar->default = "info";
          $menubar->separator_text = "<br>";
          $menubar->image_path = "images/";

          $menubar->add_button("info");
          $menubar->set("info", "on_graphic", "info-on.gif");
          $menubar->set("info", "off_graphic", "info-off.gif");

          $menubar->add_button("faq");
          $menubar->set("faq", "on_graphic", "faq-on.gif");
          $menubar->set("faq", "off_graphic", "faq-off.gif");

          $menubar->output();

          print "<p>";

          if ($current_panel["contact"] == "info") {
                     print "Contact Info";
          }

          if ($current_panel["contact"] == "faq") {
                     print "Frequently Asked Questions";
          }
}

?>
</HTML>
FLAKE APP OBJECT

The FLAKE app object abstracts application behavior, offering functionality for opening/closing page HTML, specifying
CSS definitions, application and database initialization, user access (logging in or out), search query and form generation,
passive interface elements (such as frames and prompts), and application navigation. The FLAKE app object integrates
with FLAKE form and hitlist objects, but its use is optional.

FLAKE app object integration with the FLAKE menubar object is planned.

The addition of logic to give session variables names incorporating the app object name is planned (to prevent
interference between running multiple FLAKE apps in multiple browsers).

The idea of making panel functionality modular by defining it by components is also being considered.

PANELS

Panels, in FLAKE terminology, are analogous to pages. Panels present a simple interface for interacting with a certain
kind of data. As an example, companies could be handled by one panel and employees by another. A panel, by default,
will handle the addition of new records to data, searching of data, viewing of data, and editing of data.

THE START METHOD

The start method performs a number of application initialization tasks:
         checks if user has requested to be logged out
         registers session variables used by FLAKE
         handles user requests to change the current panel and sets the current panel to the default if no current panel
          has yet been been selected
         initializes the ADODB database connection (global variables must be set to provide access info: $db_host,
          $db_user, $db_password, and $db_name)
         returns opening HTML (containing CSS code, if specified)

THE AUTHORIZATION METHOD

The authorization method currently returns a boolean value (1 or 0) based on whether the submitted username and
password match the settings of the admin_username and admin_password properties of the FLAKE app object.

In the future, an authorization_plugin property will be added to the FLAKE app object to allow username/password to be
checked from a database/LDAP/etc.

THE PANEL HANDLER METHOD

The panel_hander method handles the following:
        Setting of search criteria entered by user in search form
        Setting of sort order indicated by user (by clicking on a sort arrow icon in a hitlist)
        Creation of search query based on search criteria and sort order
        Deletion and display of delete confirmation prompts
        Display of add button for adding records
        Generation of search form (or optional inclusion search form specification)
        Configuration of hitlist (column specification must be included)
        Configuration of form for adds and updates (column specification must be included)
        Opening and closing of HTML frames

THE STOP METHOD

The stop method merely returns closing HTML.

APP OBJECT OUTPUT

There are three points of output for the app object, trigged by three methods.

The start method, among other things, outputs HTML needed to open the page.

For example:
print $app->start();

The stop method outputs HTML needed to close the page.

For example:
print $app->stop();
The panel_handler method does the bulk of the app object’s work, and should be placed between the start and stop
methods.

For example:
print $app->panel_handler();

Here’s an example of a script using the FLAKE app object:

         <?
         # Include database abstraction layer
         include("adodb/adodb.inc.php");

         # Connect to database
         $db_host = "your hostname";
         $db_user = "database user";
         $db_password = "database password";
         $db_name = "database name";

         # Include FLAKE classes
         define("FLAKE_DIR", "flake/"); # the FLAKE_DIR constant must be set
         include(FLAKE_DIR . "include_classes.php");

         # Start app
         $app = new app();
         $app->default_panel = "companies";
         $app->name = "Test Application";
         $app->include_css = "includes/admin.css";
         $app->admin_username = “admin username”;
         $app->admin_password = “admin password”;
         print $app->start();

         # Processing / Output

         # Because $app->admin_username and password are set,
         # a login prompt will be shown if they are not logged in
         if ($app->authorization()) {

              # Define panels

              $app->add_panel("companies");
              $app->set("companies", "friendly_name", "Company");
              $app->set("companies", "plural_name", "Companies");
              $app->set("companies", "table_name", "companies");
              $app->set("companies", "primary_key", "company_id");
              $app->add_search_criteria("companies", "company_name", "like", “Name”);
              $app->add_search_criteria("companies", "company_description", "boolean", “Description”);
              $app->set("companies", "include_hitlist", "includes/hitlists/company-hitlist.inc.php");
              $app->set("companies", "include_form", "includes/forms/company-form.inc.php");

              # Define and output menubar

              include("includes/menubars/menubar.inc.php");
              print $menubar->render($conn);

              # Handle panel functionality

              print $app->panel_handler();

         } else {
               print $app->show_login();
         }

         print $app->stop();
         ?>
FLAKE HELP OBJECT

The FLAKE help object handles the display of help documents and the display of pop-up links to help documents. Help
documents can use HTML templates for formatting. Links to other help documents can easily be embedded without
HTML.

USING THE HELP OBJECT

To use the help object in an application, you must call the handler function before any other application output. This
handler, if triggered, will display the requested help.

For example, your application could include these lines early on:

          $help = new help();
          $help->path = "<path to my help directory>"; # set the path to your help files
          $help->template = "templates/help.html"; # set the path to your help HTML template
          $help->handler(); # handle any help document requests

Later in your application you might add a line to display a link to a help document.

          print $help->return_link("some_help_document.html");

Within the help document could be a link to another help document. For example:

          Click {some_other_help_document.html|here} to view help for another thing.

				
DOCUMENT INFO
Shared By:
Categories:
Stats:
views:11
posted:2/26/2010
language:English
pages:25