Conventions

This chapter is about usage guidelines for the GGF classes.

 

Windows and Dialogs

Each GGF application consists of several pages, called windows and dialogs. An application can have one or more windows open (in one or more browser windows).

 

Dialogs belong to one window and are modal. That means, you cannot enter anything into a window as long as the dialog is active. (by the way this is implemented very simple: by displaying the dialog with replacing the window in the web-browser. When the dialog is closed, GGF redisplays the window automatically).

 

The guiding idea behind GGF framework is, that all code, specifying the contents of  one window or dialog encapsulated in one class/PHP file. Window and dialog classes are derived from the classes GGFControlWindow and GGFControlDialog.

 

Classes for GUI Elements

The GUI elements in a window or dialog are constructed with controls. A control is a passive (for instance static text, picture) or active (push button, menu) user interface element. GGF provides a set of classes (derived from GGFControl) that model these user interface elements. All control classes know how to render GUI elements on the screen: they can produce HTML code that creates their visual representation. The goal (although not yet completely achieved) in GGF is, that the application developer does not need to know much about HTML to create his web applications.

 

In the initWindow method of a window class the control objects are instantiated  They are added to a GGFControlPane object. Every window has such a control pane object that serves as a container for controls. Control panes can be nested to contain other control panes. They can either be rendered in the normal PHP echo way or they can be rendered to a frame. In this case the pane where they are contained in, has to define a frameset. In the GGFControlBrowserWindow class you see a rather sophisticated sample of how to support frames with nested GGFControlPanes.

 

In the fillControls method, the controls are filled with data. In the openHTML method they are rendered. The GGFControl classes know themselves how they can be rendered. By the way:: “rendering” means here: generating HTML.

 

Active user interface elements like buttons, issue an HTML request that is redirected by GGF automatically to so-called callback functions of the class that defined the window contents. Callback functions are always named ‘eventXXX’. In this way the definition of a window contents and the functionality to handle, what the user can do in the window (for instance processing the input data from entry fields) are encapsulated in the same class.

 

Filters and Sorters

When composing SQL statements we recommend strongly to use the classes GGFSqlFilter and GGFSqlSorter. See GGFControlBrowserWindow for a sample how to use them. This allows to implement CRUD (create, read, update, delete) applications easily and quickly.

 

Queries

GGFQuery object store a filter, a sorter, a column selection and column size information. Thus defining exactly a set of datarecords. GGFControlBrowserWindow can save and retrieve Query-Objects.

 

MVC pattern

 

For every window a persistent context object is created. The class GGFContext handles contexts as well as context switches (opening a sub-dialog, returning to the parent window).

 

Every context contains a model-object ($myContext->model). The model is an array.

 

For insert and update dialogs:

 

$model[0] … contains the primary key value

$model[1] … contains the row

 

Data Safety

 

We recommend using data replication services of the MySQL database. This is an excellent means to prevent loss of data. However this does not prevent data losses from programming errors or misusing an application. For this GGF offers functionality to feed a history table every time data is modified. See the execSQL function in the GGFDatabase class. The history table can tell, who, when modified what.

 

The System Tray

 

Per default every GGF window contains a set of hyperlinks with standard functions. This enhances the user-friendliness of application very much.

 

 

system tray in windows and in dialogs

 

The contents of the system tray is defined in GGFControlWindow and can be enhanced or modified in derived classes.

 

It contains the following functions:

�       This allows to write down (and view) a note. Notes can be tied to the currently displayed object (database row), or may be general for the window. This allows you to create your personal context sensitive annotations. Notes can be public (to be seen by everyone) or private (only for you). – (in 2.3.1 only tech preview)

ü       Although this is a hyperlink, you should not click on it. It provides a so-called 'direct access link'. This is something like a shortcut from outside of the application directly to your data. You can use your browser's 'copy shortcut' function to get an URL, that you can send per mail to someone else. With this URL the receiver (if he has access to the application) can directly open the current dialog with the same data, without a need to navigate through the application. It enables you to send references to database-records via e-mail. (this icon is visible only in dialogs that support this functionality; Here you can try such a: direct access link . It provides access to specific record in the demo installation.)

�    Export the model-object in csv format. You may use your browsers 'save as'-function to store the data into a file. This file then can be imported into spreadsheets etc.

i       Displays a context-sensitive help for the window.

J      Allows to send a feedback mail to the system administrator of the application.

i      Displays help info for the system tray.

 

Direct Access Links

If you want to know what the concept of direct access links is all about, just jump to the list of tables in the pool bar. Got it? GGF allows defining a query, and then allows opening this defined set of data from everywhere.

 

Entity-Relationship Models

 

With GGF 2.0 we have introduced the idea to encapsulate HTML in a family of GGFControl classes. Now in GGF 3.0 we provide a means to separate SQL and the knowledge about the entity-relationship model (= database model) from the application logic. The new file GGFERModel contains classes to describe the structure of the ER model. GGF.php assumes that a class

$appname.'Model' exists. This contains entities and relationships between them. The model itself then is accessible in all Windows via $this->ERModel or via global variable $_SESSION["_ERModel"] elsewhere. For an example of a simple ER-Model, see the file GGFDemo.php. It creates two Entitytypes: user and GGFNote (inherited) and a relationship type between them.

 

Note: ER models are optional, if you don't want to use them, you can use the GGFDemoModel class instead. Just copy GGFDemoModel.php as <yourappname>Model.php. This initializes everything required by the framework. Of course we recommend that you use the new model classes.

 

This is, what is required to do so:

 

·                First you need a model class for your app. Just take GGFDemoModel.php as an example.

 

·                Second you should tell your windows, what "their" entity type is. In the constructor assign $this->ETypeName the name of the entityttype. See for example the constructor of GGFControlBrowserWindow. Of course there may be windows or dialogs that work on more than one entity type, but the concept is easy to extend. Just add additional instance variables to your window class for them.

 

So what is the benefit of having models?

 

Look for instance into the function GGFControlBrowserWindow>>createColumns. This is now perfectly reusable.

The same is with createFilter. (Note: we have GGFERFilters now. These know their entitytype) Look also on the createSelect function. It does not contain any SQL anymore and is completely reuseable.

 

Another fine example for reusability is the default implementation of  GGFControlDialog>>modelObjectPrimaryKeyValuesString() . 

 

Model Generator

 

The Model Generator is a tool written in GGF that generates PHP classes from a database table structure.

A demo video shows the usage of the Model Generator (1.8 MB, needs the TSCC codec) .

The zip file of GGF 3.3 contains a draft document pf a model generator description.