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

