
=head1 NAME

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

=head1 DESCRIPTION

=head2 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.

=head2 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.

=over 4

=item tbl - master table

=over 4

=item 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.

=item 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: #background#`` #field_data#" - this data is what the rendering engine will use to create the HTML result. 
  realm_id: "" - Not used.

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

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

=item FLDMTX - A per language matrix for describing field status.

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

=item STATUS - Record state.

       contains: 
           0 - deleted
           1 - blocked
           2 - active

=item 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.

=back

=item 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)

=item 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.

=item 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.
2.5. 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.


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











4.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.
Perfect 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.

=back

=head1 COPYRIGHT

 (c) RAZ Information Systems Ltd 1999 - 2005.
 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. 

=cut


