NAME

HTML::Merge::App::Repository - A sample of a complex application

DESCRIPTION

Overview

The goal of the HTML::Merge::App::Repository is to provide a form builder multi language design environment. In order to accomplish that all form design meta data are stored in a databases where each record represent a form element. A rendering engine has been created to render the form from the database. The project is lacking a GUI interface for populating the form meta data database.

Database

The entire project is stored on tables residing on HTML::Merge system database (tested on SQLite and MySQL). The table creation and initing code reside in the class HTML::Merge::App::Repository and it is being utilize in the mergecreateinstance script. HTML::Merge::App::Repository also relay on definition stored on the tbl table populated by the 'private/sql/tbl.dat' pipe delimited file. This actually break the possibility of treating the Repository as an add-on module since it taints the mergecreateinstance and relay on default data from the basic system tbl table, but this design flows can easily be repaired.

tbl - master table

FLDTYP - contains all form elements types.

example of a text fields:

tbl:         "FLDTYP"
langug_code: "" - nothing, not language dependent information.
code:        "1" - unique identifier.
name:        "TEXT_FIELD" - widget description.
number:      "1" - A boolean value indicating if this object requires 
                   a text label to accompany the widget.
note:        "<input type=text #fldstatus# value=``#value#`` size=``#size#`` 
              maxlength=``#maxlength#`` @STDATR@ @STDEVNT@ #field_data#>|0|" 
              - this data is what the rendering engine will use to 
              create the HTML result. 
realm_id:    "" - Not used.

MACROS - contain macros to support the FLDTYP methodology.

example of standard events macro:
tbl: "MACROS"
langug_code: "" - nothing, not language dependent information.
code: "1" - unique identifier.
name: "STDATR" - widget description.
number: "0" - Not used.
note: "name=``#field_name#`` id=``#field_name#`` style=``width: #width#; 
      height: #height#; background-color: 
realm_id: "" - Not used.

FLDSTS - Look up for the HTML::Merge::App::Repository field status.

contains: 
    1 - normal
    2 - read only
    3 - disabled
    4 - hidden 

FLDMTX - A per language matrix for describing field status.

LANGUG - All supported languages and definitions: ISO code, direction.

STATUS - Record state.

contains: 
    0 - deleted
    1 - blocked
    2 - active

FRMSTR -

Form strings, holds form elements basic text according to the selected
system language. For instance the grid 'alt' text for sorting or the
record left text at the grid bottom.

templates_t - System templates catalog

id: Unique identifier.

templatename: The template file name relative to the template directory.

description: The template description.

tag: extra data associated with the template - never been used.

epitaph: Mark deleted templates.

instance_id: the instance id from instance_t table indicating which merge 
     instance this template belong to (in case of a multi instance environment)

instance_t - HTML::Merge instances catalog

id: Unique identifier.

instancename: The instance merge.conf file path.

description: The instance description.

tag: extra data associated with the instance - never been used.

epitaph: Mark deleted instances.

This table is managed automatically by merge.

repository_t - forms meta repository

 rid: Unique identifier.

 template_id: The specific template

 field_parent_repository_id: Mark an rid value of a repository entry which it's

     template_id equals zero. All of the row data is inherited to the non filled fields 
      in the current row.
 field_name: The description of the field - will be used as the HTML field id and name value.

 fldtyp_code: The tbl table FLDTYP code field value.

 note: A place for comments.

 src: Used for widgets which have an external data source - 
      image, combo box  and data grid.

 value: Used for all widget which their HTML code contain a value key.
 size:  Used for all widget which their HTML code contain a size key and also   
        for the data grid to indicate number of visible rows.
maxlength: Used for all widget which their HTML code contain a maxlength  
        key and also for the data grid to indicate the maximum number of  
        rows fetched in a single request.

width: Used by all widgets - style sheet width.

height: Used by all widgets - style sheet width.

class: Used by all widgets - the widget encapsulating DIV class key;

fldsts_code: The tbl table field status code.

realm_id: field creation permissions based on HTML::Merge security module.

arrangement: The drawing and placement order of the widgets in the form 
     (z order).

onBlur: The content of the HTML result onBlur key.

onClick: The content of the HTML result onClick key.

onDblClick: The content of the HTML result onDblClick key.

onChange: The content of the HTML result onChange key.

onMouseOver: The content of the HTML result onMouseOver key.

onMouseMove The content of the HTML result onMouseMove key.

onMouseOut The content of the HTML result onMouseOut key.

field_data: Extra data to the HTML result which can't be
             created using the other fields. for example 
             giving class data to the widget and no the 
             encapsulating DIV.
pos_x: The screen x position in pixels.

pos_y: The screen y position in pixels.

background: The widget background in HTML keyword or RGB notation   (#xxyyzz).

border: The encapsulating DIV border in CSS notation. 

example: "1px solid black".

pos_delta: The length delta in pixels of the length between the widget and it's lablel.

status_code: The tbl table code indicating the record state only value of "2"    
             will be drawn.

repository_language_matrix - widgets multi lingual captions

rid: Unique identifier.

repository_id: The repository_t rid value.

langug_code: The tbl table language code value.

caption: The form caption.

The repository rendering engine

The rendering engine is the template "Repository/build_form.inc" which is included in pages usually Between a form element.

The engine then:

1.Load all macros from the tbl table.  

2.Invokes the template "Repository/repository_query.inc" - 
  which loads the specific template data from the database 
  repository_t + the field type definition from the tbl 
  table + all user_realm data curtsey's of the 
  "Reposiotry/get_user_realms.inc" template.

3.Replace all "@"  encapsulated fields in the field definition 
  with the corresponding macro. For example @STATR@.

4.Replace all "#"  encapsulated fields in the field definition
  with specific database value. For example #class# will be 
  replaced with the current record value of the class field.

5.Replace all "``" with '"' to avoid placement problems.

6.Replace all '`' with "'" to avoid placement problems.

7.Run the result through Merge so Merge tag like RINCLUDE 
  will be translated.

8.Create two DIV elements: [field_name]_fld - which holds the widget, 
  [field_name]_cap which holds the label if needed by the widget.

Since there is a sub form widget which let us encapsulate other forms inside the current form, The engine handle a stack for saving all different query engines that will be used in the page creation so no query data will interfere with top level queries. This is done using the "Repository/repush.inc" and "Repsoiotry/repop.inc" templates.

The engine uses the following RVAR as init variants: 1.dir - The direction of the rendering. Option are "rtl" ( right to left) or "ltr" (left to right) 2.__DEBUG__ - Paints border on all encapsulating DIV element. 3.repository_query_engine - Specify your own query engine. 4.repository_template - Specify the template to be rendered. Default: the current template.

The repository widgets - The widget list based on the tbl table

1. TEXT_FIELD - HTML standard text field + corresponding caption.
2. LABEL - A <pre></pre> encapsulated text.
3. COMBO BOX - HTML standard combo box + corresponding caption. The src field
   is used to specify a template which will create (usually by  querying the db) 
   the <option> section of the select. 
   Source  templates are usually marked with "bnd" file extension.
4. IMAGE -  HTML standard image.
5. BUTTON - HTML standard button.
6. CHECK_BOX - HTML standard check box + corresponding caption.
7. RADIO - HTML standard radio button + corresponding caption.
8. PASSWORD - HTML standard password field + corresponding caption.
9. RECTANGLE - Used to create boxes using the border and background attribute.
   usefull for grouping elements. 
10. GRID - A complex combination of HTML::Merge and Javascript that create a data
    grid based on an SQL query. The grid builds an array of objects called
   "grid_array" from the query and render itself based  on that array. 
The grid also support triggering of events an automatic ordering of the 
grid  by manipulating the SQL query.
  

parameters:

size - number of shown records.
                maxlength - maximum number of record to fetch in a request.
src - The template which needs to contain an RVAR called     
      "qrid_query" which holds the SQL query that the grid    
       is bases upon.
width - specify a fix width.
height - override the size definition and specify the grid   height in pixels.
field_data - is used to specify in a key=value;key=vale ...
              notation special parameters to the grid.
              uid: the specific name of the field in the sql                
                   query which is used as a unique row identifier.
              quote_data: boolean if true all function  returning 
                          field data will return the data quoted
                          with semicolons.
 background - The background color of the field titles.

events: On all supported events you can specify a pointer to a Javascript function (the name without the parameters section). when this function will be invoked the grid will send an object to the function containing three elements:

                   uid: The referred row uid database val.
                 rowid: The physical position of the row in the grid.
                  flag: Boolean actioned or not actioned. 

onDblClick -  Triggered when double clicking the grid row (also
              referred to as zooming) 
              the function will be
              invoked.

onChange - Triggered when pressing on the side control for   
           highlighting a row.

onClick - Triggered when pressing on the title for sorting (never
           been tested).

API: The grid is a class. The automatic created instance is named as follows: "c_[field_name]_grid" the following methods where design to help the programmer interact with the grid.

         Refresh(line_offset): Redraw the grid based on the "grid_array"
         starting from a specify line_offset First line is 1.

         Rebuild(extra,obj,suppress_header_rebuild,line_offset,form):
         Rebuild the grid from the database.

 extra - Name of a template the should be run before the fetching the data 
         from the database. Usually used for  doing Insert or Update.

 obj - An object  containing element which should be
       passed to the extra template.

 suppress_header_rebuild - don't redraw the fields title line.

 line_offset - Same as in the refresh method.
 form - name of a form which can be used to transfer the  
        data to the server through. if not defined a url string  
        will be created, and the location.href method will be  
        used (limited to 255 charecters).

GetMarkedUid() - Return all highlighted rows "uid" as an array.
GetMarkedUidAsStr() -  Return all highlighted rows "uid" as a      coma delimited row.
GetMarkedRowid() - Return all highlighted rows "rowid" as an array.
GetMarkedUidAsStr() -  Return all highlighted rows "rowid" as a      coma delimited row.
GetZoomedUid() - Return zoomed row "uid".
GetZoomedRowid() - Return zoomed row "rowid".
SetHeaderCaptionByID(id) - Change the title caption.
SetHeaderCaptionByFieldName(field_name) - Change the title       caption.
GetHeaderCaptionByID(id) - Get the title caption.
GetHeaderCaptionByFieldName(field_name) - Get the title       caption.
GetFieldByRowAndCol(row,col) - Get the grid data of a specific cell.
DelColumnByID(id) - Dells an entire column based on the id.
DelColumnByFieldName(field_name) - Dells an entire column        based on the column        name.
GetZoomColor() - Get the grid zoom color (the row color when       double clicking).
SetZoomColor(color) - Set the zoom color automatically.
GetCursorColor() - Get the grid cursor color.
SetCursorColor(color) - Set the grid cursor color.

Stracture: "Repository/Grid/grid.inc" - Basic CSS and constructor initting.

    "Repository/Grid/grid_build_data.inc" - Do the actual build of       
        the "grid_array" from the database.

    "Repository/Grid/grid_refresh.html" - The request to the server 
        triggered when sorting or calling the Rebuild method.

    "javascript/Repository/Grid/grid.js" - The grid class.
         
11. SUMBIT - HTML standard submit button.
12. LINE  - Create horizontal and vertical lines based on the
            pos_x,pos_y,width,height attributes
13. TEXT - Just plain text.
14. DATE_BOX - Not finished should open our standard date box automatically.
15. SUB_FORM - creates a sub form which runs inside the template specified in t     the "src" element. 

The road ahead

- Add a delta_y column.

- Change the grid "grid_arr" to a faster created storage type.

- Render all CSS attribute as a style sheet (INPUT:my_field). that way the code will be more consistent and more important it will be possible not to render empty attributes. and cut down the result HTML size dramatically.

- rewrite "build_form.inc" when HTML::Merge performance issues will be solved.

- render the result of the build_form operation so that it won't have to be rendered from the database everytime. Could be done inside HTML::Merge (compilation time) Or outside HTML::Merge by dynamically creating templates for the rendered result Or even compiled templates in the cache directory.

COPYRIGHT

(c) RAZ Information Systems Ltd 1999 - 2008.

The HTML::Merge::App::Repository is licensed under the same terms Perl is licensed.

Permission is granted to copy, distribute, and/or modify this document under the

terms of the GNU Free Documentation License,

Version 1.1 or any later version published by the Free Software Foundation.