HTML::Merge::App::Repository - A sample of a complex application
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.
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.
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.
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.
contains: 1 - normal 2 - read only 3 - disabled 4 - hidden
contains: 0 - deleted 1 - blocked 2 - active
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.
- 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.
(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.
2 POD Errors
The following errors were encountered while parsing the POD:
You can't have =items (as at line 89) unless the first thing after the =over is an =item
You forgot a '=back' before '=head2'
To install HTML::Merge, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::Merge
CPAN shell
perl -MCPAN -e shell install HTML::Merge
For more information on module installation, please visit the detailed CPAN module installation guide.