Embed Size (px)
Citation preview
Openbiz 2.4 ManualOpenBiz is a PHP application framework for professional IT developers and
consultants to build web-based enterprise applications.
Release 1.0
Author: Rocky Swen
Designer: Wang Ou
Editor: Hu ShaoXin
2009-09-11
1
Openbiz 2.4 Manual
Index
Index .......................................................................................................................... 1
Openbiz 2.4 Overview................................................................................................ 6
Installation........................................................................................................... 6
Download and Install Openbiz 2.4 ............................................................... 6
Install demo applications ............................................................................. 7
Set the database.......................................................................................... 7
Access latest source code with SVN ........................................................... 7
What is new in Openbiz 2.4 ................................................................................ 8
Presentation Layer Changes ....................................................................... 8
EasyForm Metadata ...................................................................................11
EasyForm and EasyView Configuration Guide .......................................... 18
Metadata Generation Wizard ..................................................................... 18
Screenshots............................................................................................... 18
Openbiz 2.4 EastView and EasyForm metadata............................................... 22
EasyView metadata DTD file. .................................................................... 22
EasyForm metadata DTD file..................................................................... 22
Openbiz Architecture Overview................................................................................ 25
Metadata-driver framework ............................................................................... 25
Multi-layer Object Oriented Design ................................................................... 25
Openbiz's implementation of MVC.................................................................... 26
Openbiz's implementation of persistent object and ORM ................................. 27
Openbiz security model .................................................................................... 28
Openbiz Architecture Stacks ............................................................................. 30
Openbiz Source Code Structure ....................................................................... 30
Openbiz Class Structure ................................................................................... 32
Openbiz Configuration Guide................................................................................... 34
Manage metadata ............................................................................................. 34
Introduction of metadata ............................................................................ 34
Sample metadatas..................................................................................... 35
2
Openbiz 2.4 Manual
Manage metadata with module.................................................................. 36
Use Simple Expression in your metadata ......................................................... 37
Using Expressions..................................................................................... 38
Literals ....................................................................................................... 38
Operators................................................................................................... 38
Variables.................................................................................................... 39
Functions ................................................................................................... 41
Examples................................................................................................... 41
Configuration of Data Object............................................................................. 42
Map BizDataObj to Tables ......................................................................... 42
Query Language in BizDataObj ................................................................. 43
Data type and format of BizFields.............................................................. 44
Data validations ......................................................................................... 46
Dynamic value set on record update/creation............................................ 47
Primary key (Id) generation ....................................................................... 47
Composite key support .............................................................................. 48
Audit the data change................................................................................ 49
BizDataObj metadata................................................................................. 49
BizDataObj Element .................................................................................. 49
Object/Relationship Mapping ............................................................................ 51
Map a table to a BizDataObj ...................................................................... 51
Map multiple tables to a BizdataObj .......................................................... 52
Many to one relationship between BizDataObjs ........................................ 54
One to one relationship between BizDataObjs .......................................... 55
One to many relationship between BizDataObjs........................................ 55
Many to many relationship between BizDataObjs...................................... 56
Configuration of View and Form ....................................................................... 57
Map BizDataObj relationship of Forms ...................................................... 57
Basic Form layout ...................................................................................... 58
Bind Form with Data object........................................................................ 58
View/Form navigation flow......................................................................... 59
Present data with various HTML elements ................................................ 61
Element classe and attributes matrix ......................................................... 62
3
Openbiz 2.4 Manual
Event handling in Form.............................................................................. 66
Bind data to Listbox ................................................................................... 68
Form controls dependency ........................................................................ 70
Build a multi-step wizard view.................................................................... 71
Configuration of record-selecting popup BizForm...................................... 74
Shortcut key support (Keyboard navigation).............................................. 75
Context menu support ............................................................................... 77
Configure Tree Structure............................................................................ 78
To see the sample of the tree structure, please check
baseapp/modules/easy/f_tree_structure_list.xml. The test url is
http://host/baseapp/bin/controller.php?view=easy.v_tree_structure.
................................................................................................................... 79
Multi-selection (multi-delete) support ......................................................... 79
Application tabs and sub tabs support ....................................................... 80
Other Navigation widgets........................................................................... 81
Use Theme ....................................................................................................... 82
Use theme in openbiz application.............................................................. 82
Theme settings .......................................................................................... 83
Upgrade old version application with theme .............................................. 84
Theme and template file ............................................................................ 84
Openbiz Development Guide................................................................................... 85
View access url ................................................................................................. 85
Manage your code ............................................................................................ 87
4
Openbiz 2.4 Manual
Use BizDataObj functions ................................................................................. 88
Use Form functions........................................................................................... 91
User input validation ......................................................................................... 92
Client side form validation.......................................................................... 92
Server side input validation........................................................................ 93
Error message display ............................................................................... 94
Extend OpenBiz classes................................................................................... 95
Extend server side classes ........................................................................ 95
Example: Extend BizDataObj and EasyForm ............................................ 95
Extend client side classes.......................................................................... 96
Implement Plug-in Service ................................................................................ 98
Openbiz core services ............................................................................... 99
Configure a service.................................................................................... 99
Write a service ......................................................................................... 100
Call a service method .............................................................................. 101
Implement authentication and access control ................................................. 101
User authentication.................................................................................. 101
Role-based view access control .............................................................. 102
Attribute-based data access control......................................................... 103
Implement dataobject events trigger ............................................................... 104
Define a dataobject trigger metadata....................................................... 104
Use message and enable multi-language....................................................... 107
Messages in Openbiz application ............................................................ 107
Define messages..................................................................................... 108
Support multi languages .......................................................................... 108
Use Cache ...................................................................................................... 109
More security ...................................................................................................110
Control the look and feel with css files .............................................................110
Control BizForm table style.......................................................................111
Control tabs style ......................................................................................111
Control menu style....................................................................................112
Control tree style.......................................................................................112
Control rich text editor (RTE) style............................................................112
5
Openbiz 2.4 Manual
Date and Datetime picker .........................................................................112
Debug strategies..............................................................................................112
Logging.....................................................................................................112
Debugging ................................................................................................113
Openbiz Design Tool Guide ....................................................................................114
Openbiz Tool Overview ....................................................................................114
Installation ................................................................................................114
Set up the databases................................................................................115
Manage Openbiz application ...........................................................................115
Metadata Wizard..............................................................................................116
Metadata Editor................................................................................................119
6
Openbiz 2.4 Manual
Openbiz 2.4 Overview
Openbiz 2.4 branches out a new Openbiz presentation layer. This new branch has new
names as "EasyView" and "EasyForm" which are new classes under openbiz/bin/easy.
The old presentation BizView and BizForm are kept under openbiz/bin/ui.
Openbiz 2.4 removes the display modes concepts used in previous releases. The
benefits:
Without confusing display mode in a form, the definition of the metadata is
clear and easy to manage.
Each view/form has single display which is browser backward/forward
button friendly, bookmark friendly as well as search engine friendly
The single display is used by most consumer facing web
applications.Openbiz are good for both enterprise and consumer web
development
Openbiz 2.4 redesigns the UI element with 20+ new element classes. The benefits:
This makes writing custom element class much easier than in previous
release which has big base UI element class HTMLControl.
Another advantage of using different element class is that different class has
its own attributes defined in metadata - this brings flexibility with no
confusion.
Openbiz 2.4 uses EasyView/EasyForm to implement common data management UI
patterns which are "list, detail, edit (LDE)"
Installation
Download and Install Openbiz 2.4
Openbiz 2.4 source is available at sourceforge openbiz project site. Third party
libraries are included under openbiz/bin/others. User are free to download latest
releases of Zend Framework, Smarty engine from their own websites.
7
Openbiz 2.4 Manual
Developer can pull Openbiz 2.4 latest code from 2.4 SVN repository. Third party
libraries are NOT included in the SVN. Please download latest releases of Zend
Framework, Smarty engine from their own websites.
Install demo applications
Use Openbiz web installer to install new easy application, demo application and trac
application.
To install easy application (as default demo), launch
http://server_path/openbiz_install_path/baseapp/index.php. Follow the install
wizard.
To install demo application, launch
http://server_path/openbiz_install_path/baseapp/index_demo.php. Follow the install
wizard.
To install trac application, launch
http://server_path/openbiz_install_path/baseapp/index_trac.php. Follow the install
wizard.
Set the database
Open baseapp/metadata/Config.xml. You cam configure multiple database connections.
Each Database element allows user to set
Name
Driver
Server (hostname, or IP address)
Port. Database host port number
Charset. Databsae charset. E.g. utf8
User. Username to access database
Password. Password to access the database
Access latest source code with SVN
User can pull the latest 2.4 source from SVN repository
8
Openbiz 2.4 Manual
https://bigchef.svn.sourceforge.net/svnroot/bigchef/branches/2.4/
The latest SVN snapshot can be downloaded here
http://bigchef.svn.sourceforge.net/viewvc/bigchef/branches/2.4.tar.gz?view=tar.
If you want to contribute (add features or fix bugs) to SVN repository, you need to have a
sourceforge account. To apply for sourceforge account, go to
http://sourceforge.net/account/newuser_emailverify.php. Then email your account to
[email protected], your account will be added to openbiz project. After that you
should be able to check in/out openbiz SVN repository.
What is new in Openbiz 2.4
Presentation Layer Changes
New Display Pattern
No matter in enterprise or consumer web applications, the most commonly adopted data
management flow is shown below. The new Openbiz 2.4 demo application (built on
EasyView and EasyForm) is a sample implementation of the pattern.
9
Openbiz 2.4 Manual
New Features
Openbiz 2.4 is a redesign on its presentation layer. It supports (or will support) basic and
advanced UI functionality in previous release.
There are enhancements in Openbiz 2.4
Presentation Layer
Replace HTMLControl and FieldControl class with 20+ element classes.
Replace the heavy popup window with DHTML window based on the
javascript library prototype-window.xilinus.com.
Replace old-fashion jsval with jsvalidate as client side validation library.
Support rendering with Smarty (done) and PHP template (next release)
Add SearchPanel in the form metadata - this makes defining search very
10
Openbiz 2.4 Manual
easy
Data Layer
Throw Exception on BizDataObj query error.
Add log on each query call in BizDataObj
Service
Add csv import in ExcelService as it is a popular feature
Drop IOService as ExcelService does the same job
Replace PhpMailer with Zend_Mail in MailService
Baseapp
Use header and footer templates in the default view template
Naming convention of view, form, data metadata files
"v_" for view metadata file
"f_" for form metadata file
"d_" for data metadata file
New Code Structure
The UI code in /bin/easy directory is rewritten with the following class structure.
View Class Description
EasyView Base view class
DynaView Dynamic view class, dynamic view can be given any
form to display
ViewRenderer Render view with Smarty or PHP template
Form Class Description
EasyForm Base form class
PickerForm Special form class for record picker
FormRenderer Render form with Smarty or PHP template
Element Class Description
Element Base UI element class. It won't be used in metadata.
InputElement Base input element class. It won't be used in metadata.
InputText Input box element
Textarea Text area element
Password Password element
File File element for upload
11
Openbiz 2.4 Manual
Button Image/Text button element
HTMLButton Standard button element
ResetButton Reset button element
SubmitButton Submit button element
RichText Rich text editor element
AutoSuggest Auto suggestion input element
InputDate Date input element
InputDatetime Datetime input element
InputPicker Input box element with picker
RowCheckbox Row selection checkbox element
Hidden Hidden element
OptionElement Base option element. It won't be used in metadata.
Listbox List box element
Checkbox Checkbox element
Radio Radio button element
LabelText Label+ field text element
ColumnText Column + field text element
EasyForm Metadata
The details of the EasyForm metadata is given below. (A) stands for attribute, (E) stands
for element.
EasyForm Element
Name (A) -
Name of the form object. It must be same as the metadata file name.
Description (A) -
Form description.
Class (A) -
Form implementation Class. By default it is EasyForm. Developers can put custom
form class here.
FormType (A) -
The type of the form. It can be LIST, NEW, EDIT. Default value is empty string. It
12
Openbiz 2.4 Manual
indicates a READ (or VIEW) forms.
jsClass (A) -
Name of the javascript Class. By default it is jbForm which is in
baseapp/js/clientUtil.js. It can be custom javascript class drived from jbForm.
Title (A) -
Title of the form.
BizDataObj (A) -
The name of the Data Object.
PageSize (A) -
The number of the rows in one page.
SearchRule (A) -
Query rule of this form.
TemplateEngine (A) -
The name of the template engine. Currently it can only be Smarty. Once PHP
template is supported, it can be either Smarty or PHP.
TemplateFile (A) -
The template file name. Openbiz locates the template files first under
baseapp/modules/my_mod/templates, then baseapp/modules/my_mod/common,
then baseapp/templates/.
DataPanel (E) -
the area that contains data elements
ActionPanel (E) -
the area that contains action trigger elements like button, link ...
NavPanel (E) -
the area that contains navigation lement
Element (E) –
the html element
Name (A) -
Name of the element. It plays as an Id. It must be unique in the
EasyForm xml file.
Class (A) -
Element implementation class. Unlike 2.3 Control element, this attribute
is required. Otherwise, the element won't be rendered. Developer can
13
Openbiz 2.4 Manual
put predefined Element class (in above table) here or custom class
drived from Element class.
Description (A) -
Element description.
FieldName (A) -
Data object's BizField name
Label (A) -
Label of the element
Text (A) -
Text value of the element
Image (A) -
Image file name. This is used in Button class.
Link (A) -
URL string. This is used in ColumnText class
Hidden (A) -
The visibility flag of the element. It should be either 'Y' or 'N'
Enabled (A) -
The flag indicating if the element is enabled or not. It should be either 'Y'
or 'N'
Sortable (A) -
The flag indicating if the element can be sorted or not. It should be
either 'Y' or 'N'
Required (A) -
The flag indicating if the element is a required input field or not. It should
be either 'Y' or 'N'
DefaultValue (A) -
The default value when creating a new record.
ValuePicker (A) -
The name of the picker form that is used to pick a record from a popup
window to base page.
SelectFrom (A) -
It defines the list of the values that are shown on the Listbox.
Width (A) -
14
Openbiz 2.4 Manual
Width of the element
Heigh (A) -
Height of the element
CssClass (A) -
css class name
Style (A) -
css style string
HTMLAttr (A) -
Any html attributes can be given here.
EventHandler (E) -
Event handling definition
Name (A) -
Event handler name
Event (A) -
Event name. Please refer to
http://www.w3.org/TR/REC-html40/interact/scripts.html, 18.2.3
Intrinsic events.
Function (A) -
The name of the method (with parameters) of the Form object.
FunctionType (A) -
The type of the function call from browser to server side. It can be
RPC (Ajax, this is default), Page (same as GET), Form (same as
POST), Popup (display the content in a normal popup window) and
Prop_Window which display content in a DHTML window popup.
RedirectPage (A) -
URL of the page redirect after the function call is completed
successfully.
ShortcutKey (A) -
It associates a shortcut key to the function
ContextMenu (A) -
It associates a context menu ite to the function
Element type and its attributes
15
Openbiz 2.4 Manual
Element
Class InputText Textarea Password File Button HTMLButton
Name x x x x x x
Description x x x x x x
FieldName x x x x
Label x x x
Text x x x x
Image x
Link
Hidden x x x x x x
Enabled x x x x x x
Sortable
Required x x x x
DefaultValue x x
ValuePicker
SelectFrom
Width x x x x x x
Height x x x x x x
CssClass x x x x x x
Style x x x x x x
HTMLAttr x x x x x x
Element
Class ResetButton SubmitButton RichText AutoSuggest InputDate
Name x x x x x
Description x x x x x
FieldName x x x
Label x x x
Text x x x x
Image
16
Openbiz 2.4 Manual
Link
Hidden x x x x x
Enabled x x x x x
Sortable
Required x x x
DefaultValue x x x
ValuePicker
SelectFrom
Width x x x x x
Height x x x x x
CssClass x x x x x
Style x x x x x
HTMLAttr x x x x x
Element
Class InputDatetime InputPicker RowCheckbox Hidden Listbox
Name x x x x x
Description x x x x x
FieldName x x x x x
Label x x x
Text x
Image
Link
Hidden x x x x x
Enabled x x x x
Sortable
Required x x x
DefaultValue x x x
ValuePicker x
SelectFrom x
17
Openbiz 2.4 Manual
Width x x x x x
Height x x x x x
CssClass x x x x x
Style x x x x x
HTMLAttr x x x x x
Element
Class Checkbox Radio LabelText ColumnText HTMLBlock
Name x x x x x
Description x x x x x
FieldName x x x
Label x x x x
Text x x x
Image
Link x
Hidden x x x x
Enabled x x
Sortable x
Required x x
DefaultValue x x
ValuePicker
SelectFrom x x
Width x x x x
Height x x x x
CssClass x x x x x
Style x x x x
HTMLAttr x x x x
18
Openbiz 2.4 Manual
EasyForm and EasyView Configuration Guide
Not yet done. Please refer http://www.phpopenbiz.org/jim/manual/2_2x/view as a
reference.
Metadata Generation Wizard
To help quick Openbiz 2.4 metadata file creation, a xtweb tool is developed in Openbiz 2.4
alpha build 0715. This wizard will ask user to
1. Select a database instances which are declared in /metadata/Config.xml
2. Select a table from the database
3. Select columns of the table
4. Give a component name and generate metadata files
5. After the metadata files are generated, a link is presented to user to test the view
The following metadata files will be generated in the user defined path.
Data object file
View object files
Form object files - List form, Detail form, Edit form and New form
To run the tool, enter url http://host/baseapp/bin/tool.php
(e.g. http://localhost/ob/ob24/baseapp/bin/tool.php)
Screenshots
1. Section defined in an EasyForm
19
Openbiz 2.4 Manual
2. Full function list page with child list page
3. Drilldown to Detail page
20
Openbiz 2.4 Manual
4. Edit page
5. New Page
21
Openbiz 2.4 Manual
6. New in-page picker popup
22
Openbiz 2.4 Manual
Openbiz 2.4 EastView and EasyForm metadata
EasyView metadata DTD file.
<!--OpenBiz EasyView metadata DTD-->
<!ELEMENT EasyView (ControlList, Parameters) >
<!ATTLIST EasyView Name CDATA #REQUIRED >
<!ATTLIST EasyView Description CDATA #REQUIRED >
<!ATTLIST EasyView Class CDATA #REQUIRED >
<!ATTLIST EasyView TemplateEngine CDATA #REQUIRED >
<!ATTLIST EasyView TemplateFile CDATA #REQUIRED >
<!ELEMENT FormReferences(Reference+) >
<!ELEMENT Reference EMPTY >
<!ATTLIST Reference Name CDATA #REQUIRED >
<!ATTLIST Reference SubForms CDATA #IMPLIED >
EasyForm metadata DTD file.
<!--OpenBiz EasyForm metadata DTD-->
<!ELEMENT EasyForm (DataPanel, SearchPanel, ActionPanel, NavPanel) >
<!ATTLIST EasyForm Name CDATA #REQUIRED >
<!ATTLIST EasyForm Description CDATA #REQUIRED >
<!ATTLIST EasyForm Class CDATA #REQUIRED >
<!ATTLIST EasyForm FormType CDATA #REQUIRED >
23
Openbiz 2.4 Manual
<!ATTLIST EasyForm jsClass CDATA #REQUIRED >
<!ATTLIST EasyForm Title CDATA #REQUIRED >
<!ATTLIST EasyForm BizDataObj CDATA #REQUIRED >
<!ATTLIST EasyForm PageSize CDATA #REQUIRED >
<!ATTLIST EasyForm SearchRule CDATA #IMPLIED >
<!ATTLIST EasyForm TemplateEngine CDATA #REQUIRED >
<!ATTLIST EasyForm TemplateFile CDATA #REQUIRED >
<!ELEMENT DataPanel(Element+) >
<!ELEMENT ActionPanel(Element+) >
<!ELEMENT NavPanel(Element+) >
<!ELEMENT SearchPanel(Element+) >
<!ELEMENT Element (EventHandler+) >
<!ATTLIST Element Name CDATA #REQUIRED >
<!ATTLIST Element Class CDATA #REQUIRED >
<!ATTLIST Element Description CDATA #REQUIRED >
<!ATTLIST Element FieldName CDATA #IMPLIED >
<!ATTLIST Element Label CDATA #IMPLIED >
<!ATTLIST Element Text CDATA #IMPLIED >
<!ATTLIST Element Image CDATA #IMPLIED >
<!ATTLIST Element Link CDATA #IMPLIED >
<!ATTLIST Element Hidden CDATA #IMPLIED >
<!ATTLIST Element Enabled CDATA #IMPLIED >
<!ATTLIST Element Sortable (Y|N) "" >
<!ATTLIST Element Required (Y|N) "" >
<!ATTLIST Element DefaultValue CDATA #IMPLIED >
24
Openbiz 2.4 Manual
<!ATTLIST Element ValuePicker CDATA #IMPLIED >
<!ATTLIST Element SelectFrom CDATA #IMPLIED >
<!ATTLIST Element Width CDATA #IMPLIED >
<!ATTLIST Element Height CDATA #IMPLIED >
<!ATTLIST Element CssClass CDATA #IMPLIED >
<!ATTLIST Element Style CDATA #IMPLIED >
<!ATTLIST Element HTMLAttr CDATA #IMPLIED >
<!ELEMENT EventHandler EMPTY >
<!ATTLIST EventHandler Name CDATA #REQUIRED >
<!ATTLIST EventHandler Event CDATA #REQUIRED >
<!ATTLIST EventHandler Function CDATA #REQUIRED >
<!ATTLIST EventHandler FunctionType CDATA #IMPLIED >
<!ATTLIST EventHandler RedirectPage CDATA #IMPLIED >
<!ATTLIST EventHandler ShortcutKey CDATA #IMPLIED >
<!ATTLIST EventHandler ContextMenu CDATA #IMPLIED >
25
Openbiz 2.4 Manual
Openbiz Architecture Overview
Metadata-driver framework
The goal of Openbiz framework is to make design, development and maintenance of web
applications easy. Openbiz is XML metadata-driven framework, which means openbiz
objects are constructed based on description in their metadata files. Building an
application means design and development of metadata files in most time. Due to the
self-explanation nature of XML language, the application is easy to maintain. Meanwhile
Openbiz is an extensible framework due to the extensible nature of XML.
How does Openbiz create objects from metadata?
Openbiz objects are defined with XML metadata
Metadata describes the properties and behaviors of an object
Metadata describes the relationship between objects
Openbiz create objects on the fly from ObjectFactory
Multi-layer Object Oriented Design
OpenBiz provides a PHP framework that assists you to build complicated web application
in an easy way.
OpenBiz is designed as a multi-layer architecture as the figure below.
26
Openbiz 2.4 Manual
Usually a business application can be modulated to 3 layers - Data layer, Business Logic
layer and Presentation layer. In OpenBiz architecture, these 3 layers map to 3 packages,
Presentation layer is refined to logic which is implemented by BizView package and GUI
layers which is implemented by jbForm javascript package. Business Logic layer is
implemented by BizDataObj package. 3rd party package ADODB handles Database layer.
Plugin services provide functional service components that can be invoked by both
presentation and data layer objects.
Openbiz's implementation of MVC
One of the key advantages of Openbiz is that it is a framework that follows the
Model-View-Controller (MVC) design pattern. This makes Openbiz applications much
more manageable because the presentation code (View) is cleanly separated from the
application data and logic (Model). All user interactions with the application are handled by
a front-end controller.
27
Openbiz 2.4 Manual
Comparing Openbiz MVC with existing MVC frameworks in market such as JSF and
Struts, Openbiz is more close to JSF because both are component based architecture.
Openbiz's View layer comprises components of View, Form and Element. These
components are accessible during request processing.
Openbiz's implementation of persistent object and
ORM
Similar with popular Hibernate approach, Openbiz uses session to maintain the
persistency of objects. Unlike J2EE web container who has objects pool in memory, PHP
objects are be constructed and released for each request (this is called shared-nothing
architecture). To keep the persistency of objects, openbiz persistent objects (Data,
Form ...) save a set of states in session, then reconstruct the object with these states. Also
to avoid multiple object instances of same class in the same session, Openbiz use
ObjectFactory to ensure object singleton.
28
Openbiz 2.4 Manual
Openbiz implements necessary object/relational mapping (ORM) features to allow
BizDataObj represents the data and relationships of database tables. The following table
list the features of Openbiz ORM.
Flexible
mapping
table-per-class, N table to 1 class
Many to one, one to many, many to many, one to one
Query
facilities
SQL like query language - support SQL functions and operators, support
SQL aggregate functions, support group by, having and order by
Metadata
facilities
XML metadata describe the mapping
Openbiz security model
Openbiz supports web security in three ways - user authentication, view access control
and data access control. Openbiz mainly uses plugin services to control security. This
implementation allows customers to plugin their own logic to the services. The details will
discussed in the developer guide - Implement authentication, view and data access
control.
User authentication flow:
29
Openbiz 2.4 Manual
View access control flow:
Security
concept Openbiz implementation with plugin services
User
authentication
Openbiz uses authentication service (bin/service/authService.php) to
authenticate username and password
Role-based view
access control
Openbiz uses profile service (bin/service/profileService.php) to get
user profile that includes "role". Then match this role to access
service (bin/service/accessService.php) to determine the users'
accessibility to the view
Attribute-based
data access
Openbiz uses profile service (bin/service/profileService.php) to get
user profile that includes attributes. Then based on these attributes
30
Openbiz 2.4 Manual
control to determine browser/update/delete permission of data record. The
data access permissions are controlled in BizDataObj.
Openbiz Architecture Stacks
Openbiz Source Code Structure
Openbiz source code includes two main folders - openbiz and baseapp.
Openbiz core library
openbiz_root/
---bin/ (openbiz core php source)
------data/ (data layer classes)
----------private/ (data layer non-public classes)
------easy/ (new presentation layer classes, new in 2.4)
----------element/ (html element classes)
------service/ (openbiz core service classes)
------ui/ (presentation layer classes)
----------private/ (presentation layer non-public classes)
------util/ (utility helper classes)
31
Openbiz 2.4 Manual
---languages/ (languages files)
---medadata/ (openbiz metadata files)
------service/ (service package)
---others/ (third party libraries)
------phpmailer/ (phpmailer lib)
------Smarty/ (smarty package)
------zendfrwk/ (Zend Framework)
Openbiz base application
baseapp/ (baseapp web pages)
---bin/ (baseapp php source)
------languages (language generation tool)
------shared/ (baseapp shared library)
------service/ (baseapp service library)
---css/ (baseapp style sheets)
---files/ (baseapp files)
------cache/ (cache files)
----------data/ (data cache files)
----------metadata/ (metadata compiled files)
------sec_upload/ (secured uploaded files)
------tmpfiles/ (temporary files)
------upload/ (public accessed uploaded files)
---js/ (baseapp javascript files)
---pages/ (baseapp HTML files)
---images/ (baseapp images)
---log/ (baseapp logs)
---medadata/ (baseapp metadata files)
------shared/ (baseapp shared package)
------service/ (baseapp service package)
---modules (baseapp modules files)
------demo/ (demo module)
----------templates/ (template files of demo module)
------easy/ (easy module, new in 2.4)
32
Openbiz 2.4 Manual
----------templates/ (template files of easy module)
------trac/ (trac module)
----------tempaltes/ (template files of trac module)
---session (baseapp session files)
---templates (baseapp smarty templates files)
------cpl (baseapp smarty compiled templates)
------cfg (baseapp smarty configuration files)
Openbiz Class Structure
The Data layer class structure
Data Layer Class Description
BizDataObj_Abstract This class handles metadata related and general functions
BizDataObj_Lite This class handles readonly functions such as search. This can
improve the performance of many readonly pages.
BizDataObj A fully functional object that can handle search, new, update,
delete. join, add/remove through object reference
BizDataObj_Assoc BizDataObj_Assoc takes care of add and remove record
according to data object association
BizDataSql BizObjSql constrcuts SQL statement for BizDataObj
BizDataObj_SQLHelper BizDataObj_SQLHelper is a helper class that builds sql for
BizDataObj
DataRecord DataRecord has ActiveRecord-like interface. BizDataObj query
returns results in format of record array. DataRecord is an
object wrapper on such record array
BizRecord BizRecord is the container class of BizField
BizField BizField defines logic field which maps to a table column, or
SQL expression, or calculated value.
TableJoin TableJoin defines the table join used in BizDataObj
ObjReference ObjReference defines the object reference of a BizDataObj
The UI code in /bin/easy directory is rewritten with the following class structure in 2.4
33
Openbiz 2.4 Manual
View Class Description
EasyView Base view class
DynaView Dynamic view class, dynamic view can be given any form to display
ViewRenderer Render view with Smarty or PHP template
Form Class Description
EasyForm Base form class
PickerForm Special form class for record picker
FormRenderer Render form with Smarty or PHP template
Element Class Description
Element Base UI element class. It won't be used in metadata.
InputElement Base input element class. It won't be used in metadata.
InputText Input box element
Textarea Text area element
Password Password element
File File element for upload
Button Image/Text button element
HTMLButton Standard button element
ResetButton Reset button element
SubmitButton Submit button element
RichText Rich text editor element
AutoSuggest Auto suggestion input element
InputDate Date input element
InputDatetime Datetime input element
InputPicker Input box element with picker
RowCheckbox Row selection checkbox element
Hidden Hidden element
OptionElement Base option element. It won't be used in metadata.
Listbox List box element
Checkbox Checkbox element
Radio Radio button element
LabelText Label+ field text element
ColumnText Column + field text element
34
Openbiz 2.4 Manual
Openbiz Configuration Guide
Manage Metadata
Configuration of Data Object
Object Relationship Mapping
Configuration of View and Form
Manage metadata
Introduction of metadata
The core concept of the Openbiz is metadata-driven mechanism. What is metadata? From
the dictionary, metadata is a component of data which describes the data. It is "data about
data". Metadata files in Openbiz are actually the configuration files of Openbiz classes. All
Openbiz classes are general classes. They represent different things with association to
different metadata. For example, when d_Student.xml links to BizDataObj class, this
BizDataObj instance is a student object. While when d_school.xml links to BizDataObj
class, then this BizDataObj instance becomes a school object.
Because Openbiz classes are described with metadata, authoring metadata files is same
as implementing a class. Thus, application development means authoring metadata files
in most time, instead of traditional programming. Applicaiton described with the metadata
files should have more clear logic and design.
What can metadata do:
Describe the properties of objects
Describe relationship of objects
Describe rendering behavior of objects
Describe validation of the data
Describe user interaction on a page
What can't metadata do:
35
Openbiz 2.4 Manual
Logic of funcitonality - this is implemented in real program classes. The "Class"
attribute of a metadata can bind any custom class with the metadata.
Sample metadatas
Let's show two simple metadata samples - d_Event.xml represents an event data object
and f_EventEdit.xml represents an editing event form. The the meaning the xml should be
self-explained.
d_Event.xml
<?xml version="1.0" encoding="UTF-8"?>
<BizDataObj Name="d_Event" Description="Event BizDataObj" Class="BizDataObj"
DBName="" Table="events">
<BizFieldList>
<BizField Name="Id" Column="SYSID"/>
<BizField Name="Name" Column="NAME" Required="Y"/>
<BizField Name="Location" Column="LOCATION"/>
<BizField Name="Start" Column="START" Type="Datetime" Format="%m/%d/%Y
%H:%M:%S"/>
<BizField Name="End" Column="END" Type="Datetime" Format="%m/%d/%Y
%H:%M:%S"/>
<BizField Name="Host" Column="HOST"/>
</BizFieldList>
</BizDataObj>
f_EventEdit.xml
<?xml version="1.0" encoding="UTF-8"?>
<EasyForm Name="f_EventEdit" Class="EasyForm" FormType="Edit" jsClass="jbForm"
Title="Sports Events" BizDataObj="easy.d_Event" TemplateEngine="Smarty"
TemplateFile="detail.tpl">
36
Openbiz 2.4 Manual
<DataPanel>
<Element Name="fld_id" Class="LabelText" FieldName="Id" Label="Event Id"/>
<Element Name="fld_name" Class="InputText" FieldName="Name" Label="Name"
Width="200"/>
<Element Name="fld_host" Class="InputText" FieldName="Host" Label="Host"
Width="200"/>
<Element Name="fld_loc" Class="InputText" CssClass="jsrequired"
FieldName="Location" Label="Location" Width="400"/>
<Element Name="fld_start" Class="InputDatetime" FieldName="Start"
Label="Start" Width="200" />
<Element Name="fld_end" Class="InputDatetime" FieldName="End" Label="End"
Width="200"/>
</DataPanel>
<ActionPanel>
<Element Name="btn_save" Class="Button" Text="Save" CssClass="button">
<EventHandler Name="onclick" Event="onclick" Function="SaveRecord()"
RedirectPage="..."/>
</Element>
<Element Name="btn_cancel" Class="Button" Text="Cancel"
CssClass="button">
<EventHandler Name="onclick" Event="onclick"
Function="js:history.go(-1)"/>
</Element>
</ActionPanel>
</EasyForm>
Manage metadata with module
A good designed applications are usually built upon modules. Openbiz recommends
37
Openbiz 2.4 Manual
developers to create their metadata under app/modules/ directory. Openbiz metadata files
can be organized by module name and sub direcotry names. It is like the package concept
used in Java. For example,
PackageX.PackageY.metaA.xml refers to the metaA.xml under
modules/PackageA/PackageB directory.
There are several ways to store your metadata files
1. metada files in single module directory. (ok for small module)
Example:
/modules/trac/ includes all data, form and view files.
2. separate files by functions.
Example:
/modules/trac/admin/ includes data, form and view files.
/modules/trac/ticket/ includes data, form and view files
3. separate files by data, form, view
Example:
/modules/trac/ includes only view metadata files
/modules/trac/data/ includes only data metadata files
/modules/trac/form/ includes only form metadata files
4. separate files by functions and data, form, view (good for big module)
Example:
/modules/trac/ticket/ includes only ticket view metadata files
/modules/trac/ticket/data/ includes only ticket data metadata files
/modules/trac/ticket/form/ includes only ticket form metadata files
Use Simple Expression in your metadata
In order to adding flexibility of metadata configuration, Openbiz accepts simple expression
language in metadata files. If a statement has {expr} pattern, expr will be evaluated as
simple expression. Basically, the simple expression is a single PHP statement which
38
Openbiz 2.4 Manual
returns a value. If users need more complicated logic which can't be put in a simple
expression, they can associate an object with user-defined class where they put special
code.
Using Expressions
Simple expression is to support dynamic value binding of metadata attributes. Users can
use simple expression in the following place in metadata files.
BizDataObj
SearchRule, SortRule, OtherSQLRule, AccessRule, UpdateCondition, DeleteCondition.
These attributes are query related attributes of BizDataObj element, [field_name] is not
evaluated to field value. [field_name] is the syntax of query lanaguage, it will be replaced
by table column name. Please see Query Language in BizDataObj for details.
BizField
Required, Validator, Value, DefaultValue
Element
Link, Style, Hidden, Enabled, SelectFrom
EventHandler
Function, RedirectPage
Literals
The simple expression language defines the following literals:
Boolean: true and false
Integer: as in PHP
Floating point: as in PHP
String: with single and double quotes; " is escaped as \", ' is escaped as \', and \ is
escaped as \\.
Null: null
Operators
The simple expression language provides the following operators:
39
Openbiz 2.4 Manual
Arithmetic: +, - (binary), *, / and div, % and mod, - (unary)
Logical: and, &&, or, ||, not, !
Relational: ==, !=, <, >, <=, >=. Comparisons can be made against other values, or
against boolean, string, integer, or floating point literals.
Conditional: A ? B : C. Evaluate B or C, depending on the result of the evaluation of A.
Variables
Simple expression allows developers to use variables of openbiz metadata objects:
@object_name:property_name
get the given property of the given object.
@BOEvent:Name
@FMEvent:Title
@object_name:*[child_name].property_name
get the given property of the given object's child element
@BOEvent:Field[Id].Value
@FMEvent:Control[evt_id].Value
@:property_name or @this:property_name
get the given property of this object ("this" object is the object defined in the metadata file)
In BOEvent, @:Name or @this:Name means getting the "Name"
property of BOEvent.
@:*[child_name].property_name or @this:*[child_name].property_name
get the given property of this object's child element
40
Openbiz 2.4 Manual
In BOEvent, @:Field[Id].Value or @this:Field[Id].Value means
getting the "Id" field value of BOEvent.
[field_name]
get the value of a given BizField of this BizDataObj.
It is evaluated to field value only if it is used in BizField element
In BOEvent, [Id] means getting the "Id" field value of BOEvent.
@profile:property_name
get the user profile property.
User profile is provided with ProfileService.
@profile:ROLEID
@svcname:method(arg1, arg2 ...)
invoke the registered plugin service method and get the returned value.
Currently registered plugin services are
@validation - validation service
@query - query service
In a LabelText Element,
text="{@query:FetchField(easy.d_Event,
[Id]=@:Element[fld_evtid].Value, Name)}"
As implied from the implementation, developers can add more property support by
modifying/overriding GetProperty() method. The input of GetProperty() can be
either "property_name" or "*[child_name]" or something new that supported by
customer code.
41
Openbiz 2.4 Manual
Simple expression language also allow developers to use any global variables
supported by PHP. Please read http://us2.php.net/manual/en/reserved.variables.php
for details
Functions
Developers can invoke any PHP functions in simple expression. A user defined functions
can be invoked if the file that contains such function is included. For example, if the
metadata object A is based on a customer class, the class file is A.php that includes
another A_help.inc. In this case, you can invoke functions defined in A_help.inc in simple
expression.
Examples
<BizDataObj SearchRule="[Start]>'date(\"Y-m-d\")'">
<BizDataObj AccessRule="[OwnerId]='{@profile:USERID}'">
<BizDataObj UpdateCondition="[OrgId]=={@profile:ORGID}">
<BizDataObj DeleteCondition="'admin'=={@profile:ROLEID}">
<BizField Name="NeedApprove" Required="{[Amount]>1500}"/>
<BizField Name="Fee" Validator="{[Fee]>=15}"/>
42
Openbiz 2.4 Manual
<BizField Name="FullName" Value="{[LastName]},
{@:Field[FirstName].Value}"/>
<Element Name="fld_evtname" Class="LabelText" FieldName=""
Label="Event Name" text="{@query:FetchField(easy.d_Event,
[Id]=@:Element[fld_evtid].Value, Name)}"/>
Configuration of Data Object
Map BizDataObj to Tables
Openbiz maps database tables to object with BizDataObj. This chapter introduces the
concept of mapping tables with BizDataObj, the next chapter "ORM" has full details of the
mapping configuration. A BizDataObj must have table name and mapping between table
columns to BizDataObj fields.
Specify the databsae which is defined in metadata/Config.xml.
<BizDataObj Name="BizDataObjName" DBName="demo" ...>.
If DBName is left as empty, "default"databaase entry in Config.xml will be used.
Specify the base table
<BizDataObj Name="BizDataObjName" Table="TableName" ...>
Map Column to BizField
<BizField Name="FieldName" Column="ColumnName"....>.
One of BizFields must have name as "Id". This is required. This Id field usually
map to the primary key column of a table.
Map SQL Function to BizField
Users can assign a BizField with SQL functions provided by the database engine.
43
Openbiz 2.4 Manual
The syntax is
<BizField Name="FieldName" Column=""
SQLExpr="FUNC([FieldName1]...[FieldName2]...)">.
Make sure that the Column attribute is empty. For example:
<BizField Name="FullName" Column=""
SQLExpr="CONCAT([FirstName],' ',[LastName])"...>.
Please note that SQLExpr is a query related attributes, [FieldName] is not
evaluated to field value. [FieldName] is the syntax of query lanaguage.
Specify default value of BizField
<BizField Name="FieldName" Column="ColumnName"
DefaultValue="default_value">.
Use DefaultValue attribute to give default value to the BizField when dataobject
creates a new record.
Query Language in BizDataObj
Openbiz users won't worry about the composing complicated SQL statements.
BizDataObj support more intuitive query language at the object level. The basic syntax is
"[FieldName] opr 'Value' AND/OR [fieldName] opr 'Value'..." Here "opr" is SQL operator. At
runtime, openbiz convert [FieldName] to column name and generate SQL statement.
Openbiz also put table relationship in generated query statements.
Specify the default query in SearchRule
<BizObj Name="BOCalendar" Description="Calendar BizObj"
Table="calevts" SearchRule="[Start]>'1999-10-20'" ...>
Specify the default sort in SortRule
<BizObj Name="BOCalendar" Description="Calendar BizObj"
Table="calevts" SortRule="[Start] ASC" ...>
44
Openbiz 2.4 Manual
Specify additional SQL statement in OtherSQLRule
<BizObj Name="BOCalendar" Description="Calendar BizObj"
Table="calevts" OtherSQLRule = "GROUP BY [EvtId] HAVING
[Fee]>10" ...>
Data type and format of BizFields
BizField supports following data types and formats in its Type and Format attributes.
Text
None
Text is the default type
Number
format supported by printf
<BizField ... Type="Number" Format="%..." ...>
%5.2f to print a float number
"Int" - integer format according locale
<BizField ... Type="Number" Format="Int" ...>
If locale=enu, 12345.678 is displayed as 12,346
"Float"- float format according locale
<BizField ... Type="Number" Format="Float" ...>
If locale=enu, 12345.678 is displayed as 12,345.68
Date
45
Openbiz 2.4 Manual
In default read-only mode, a date can be formatted according to the Date format.
<BizField ... Type="Date" Format="date format" ...>
6/21/2003 can be formatted as %A, %b %d %Y - Saturday, Jun 21 2003 if system
locale is enu
Datetime
In default read-only mode, a date can be formatted according to the Date format.
<BizField ... Type="Datetime" Format="datetime format" ...>
6/22/2003 9:30am can be formatted as %m/%d/%Y %H:%M:%S - 06/22/2003
09:30:00 if system locale is enu
Currency
Formatted according to locale setting
<BizField ... Type="Currency" Format="Currency" ...>
1456.89 is formatted as $1,456.89 (enu)
1456.89 is formatted as F1 456,89 (fra)
Phone
Formatted according to given mask #
<BizField ... Type="Phone" Format="mask string" ...>
1234567890 is formatted as
mask=(###) ###-####, phone=(123) 456-7890
mask=###-###-####, phone=123-456-7890
If a phone number starting with "*", it represents international phone number, it won't be
formatted
46
Openbiz 2.4 Manual
*123 4567890 is treated as international number
Blob
None
<BizField ... Type="Blob" ...>
Data validations
Required
Indicates the field can accept empty value or not
<BizField Name="Name" Required="Y" Column="NAME"/>
Validator
Validate field with simple expression language
<BizField Name="Fee" Type="Currency" Format="Currency"
Validator="{[Fee]>=15}" Column="FEE">
Validate field with validation service
<BizField Name="Email" Column="EMAIL"
Validator="{@validate:email('[Email]')}"/>
<BizField Name="Phone" Column="PHONE"
Validator="{@validate:phone('[Phone]')}"/>
Uniqueness
47
Openbiz 2.4 Manual
Check the uniqueness of the given fields.
Syntax: Uniquess = "fld1,fld2;fld3,fld4;...."
Openbiz will check the uniqueness of (fld1,fld2) and (fld3,fld4)
<BizDataObj Name="User" ...
Uniqueness="LastName,FirstName"/>
Dynamic value set on record update/creation
Sometimes we want to set value to certain fields on record creation and update. For
example, when a record is create, we want to set the current time in "create_time" column.
And when this record is updated, we want to set the current time in "update_time" column.
Openbiz introduces 2 new attributes in BizDataObj to take are of such work.
ValueOnCreate can set the value on record creation
ValueOnUpdate can set the value on record update.
You can find example in baseapp/modules/trac/DO_Ticket.xml
<BizField Column="changetime" Name="changetime"
Type="Datetime" ValueOnCreate="{date('Y-m-d H:i:s')}"
ValueOnUpdate="{date('Y-m-d H:i:s')}"/>
Primary key (Id) generation
BizDataObj supports multiple id generation algorithms. Add a BizDataObj attribute
IdGeneration="Openbiz|Identity|Sequence:seqname|GUID|UUID|Other...".
Openbiz (default)
Id is generated using "ob_sysids" table which stores SYSID information for all tables who
have SYSID column
Apply to all database types
Identity
Primary key column is generated by database engine.
48
Openbiz 2.4 Manual
Id is called "Identity" column in SQL Server, also called "auto-increment" column in
MySQL.
MySQL, SQL Server, Sybase, DB2
Sequence:seqname
Primary key column is generated by database sequence. "seqname" is the sequence
name used to generate PK.
Oracle, PostgreSQL, DB2
GUID
Primary key column is database-generated GUID
MySQL, SQL Server, Oracle
UUID
Primary key column is generated with php uuid function
Apply to all database types
Other
Developers can write customer specific Id generation algorithm by modifying function
GetNewID(...) in genIdService class under openbiz/bin/service/genIdService.php
decided by customer
Composite key support
BizDataObj supports composite key as well. This feature would be useful when working
with legacy database tables who does not have single primary key column. The syntax of
BizDataObj whose Id field maps >2 primary key columns is:
<BizDataObj Name="" Table="" ... IdGeneration="None">
49
Openbiz 2.4 Manual
<BizField Name="fpk1" Column="PK1"/>
<BizField Name="fpk2" Column="PK2"/>
<BizField Name="Id" Column="PK1,PK2" />
<!-- make sure you place the Id field after PK1, PK2 fields.
-->
...
Audit the data change
BizDataObj works with Openbiz audit trail Service to audit data change of specified fields.
To enable auditing on field, you can simply set OnAudit="Y" in the BizField. For example,
<BizField Name="comments" ... OnAudit="Y" .../>.
More details will be given in the Audit Service section.
BizDataObj metadata
The details of the EasyForm metadata is given below. (A) stands for attribute, (E) stands
for element.
BizDataObj Element
Name (A) -
Name of the dataobject. It must be same as the metadata file name.
Description (A)
DBName (A)
Table (A)
IDGeneration (A)
SearchRule (A)
SortRule (A)
OtherSQLRule (A)
50
Openbiz 2.4 Manual
AccessRule (A)
UpdateCondition (A)
DeleteCondition (A)
Uniqueness (A)
BizFieldList (E)
BizField (E)
Name (A)
Join (A)
Column (A)
SQLExpr (A)
Type (A)
Format (A)
Value (A)
DefaultValue (A)
Required (A)
Validator (A)
ValueOnCreate (A)
ValueOnUpdate (A)
OnAudit (A)
TableJoins (E)
Join (E)
Name (A)
Description (A)
Table (A)
Column (A)
JoinRef (A)
ColumnRef (A)
JoinType (A)
ObjReferences (E)
Object (E)
Name (A)
Description (A)
Relationship (A)
51
Openbiz 2.4 Manual
Table (A)
Column (A)
FieldRef (A)
CascadeDelete (A)
XTable (A)
XColumn1 (A)
XColumn2 (A)
XDataObj (A)
Object/Relationship Mapping
To support more advanced O/R mapping, TableJoin and ObjectReference are introduced
to BizDataObj metadata file.
To understand the O/R mapping, a sample is listed below:
attendee:regist = 1:M (one to many),regist:attendee = M:1 (many to one)
events:regist = 1:M (one to many),regist:events = M:1 (many to one)
attendee:events = M:M (many to many)
Map a table to a BizDataObj
To map a table to a BizDataObj, you only need to configure the BizFieldList part in the
metadata.
52
Openbiz 2.4 Manual
<BizDataObj Name="BOEvent" Table="events" ...>
<BizFieldList>
<BizField Name="Id" Column="SYSID"/>
<BizField Name="Name" Column="NAME"/>
</BizFieldList>
</BizDataObj>
Map multiple tables to a BizdataObj
You can map multiple tables to a BizDataObj through Join. Joined table is referred by a
foreign key column in the base table of the BizDataObj, that says the base table has a
foreign key points to joined table's column. If Join is not given, the column is from the main
table of BizDataObj.
<BizDataObj Name="BORegist" Table="regist" ...>
<BizFieldList>
<BizField Name="Id" Column="SYSID"/>
<BizField Name="EvtId" Column="EVENT_ID"/>
<BizField Name="AttendeeId" Column="ATTENDEE_ID"/>
<BizField Name="AttdLName" Join="attendee" Column="LASTNAME"/>
<BizField Name="AttdFName" Join="attendee" Column="FIRSTNAME"/>
</BizFieldList>
<TableJoins>
<Join Name="attendee" Table="attendee" Column="SYSID" ColumnRef="ATTENDEE_ID"
JoinType="INNER JOIN"/>
</TableJoins>
53
Openbiz 2.4 Manual
Join Attribute Description
Name The name of the join. It is referred in the Join attribute of BizField
Table The joined table name
Column The joined column name
JoinRef If JoinRef is empty, the joined table joins to the base table. User
can specify the JoinRef in the 2-level join.
ColumnRef ColumnRef refers to the column of the base table (or the JoinRef
table). It contains the foreign key of the Join column.
JoinType INNER JOIN, LEFT JOIN, RIGHT JOIN, or FULL OUTER JOIN.
The query SQL is like
SELECT ... FROM BaseTable
INNER JOIN JoinedTable
ON BaseTable.ColumnRef=JoinedTable.JoinedColumn …
In the above example, the SQL is
SELECT T0.SYSID, T0.EVENT_ID, T0.ATTENDEE_ID, T1.LASTNAME, T1.FIRSTNAME
FROM regist as T0
INNER JOIN attendee as T1
ON T0.ATTENDEE_ID = T1.SYSID
- More explanation about the JoinRef
JoinRef is to support cascade-join. For example, in a query, table A joins B and table B
joins C. Table A and C is joined through table B. User can use the following part to link C
and A together.
<TableJoins>
<Join Name="join_b" Table="B" Column="B_PK" ColumnRef="A_FK_B" JoinType="LEFT
OUTER JOIN"/>
<Join Name="join_c" Table="C" JoinRef="join_b" Column="C_PK" ColumnRef="B_FK_C"
54
Openbiz 2.4 Manual
JoinType="LEFT OUTER JOIN"/>
</TableJoins>
Many to one relationship between BizDataObjs
Many to one relationship between two tables means that table 1 has a column that
contains the foreign key pointing to a key/unique column in table 2. To map such
relationship between two BizDataObjs, use an Object in ObjectReference section.
<BizObj Name="BORegist" Package="demo" Class="BizObj" Table="regist" ...>
<BizFieldList>
<BizField Name="Id" Column="SYSID"/>
<BizField Name="EvtId" Column="EVENT_ID"/>
<BizField Name="AttendeeId" Column="ATTENDEE_ID"/>
<BizField Name="AttdLName" Join="attendee" Column="LASTNAME"/>
<BizField Name="AttdFName" Join="attendee" Column="FIRSTNAME"/>
</BizFieldList>
<TableJoins>
<Join Name="attendee" Table="attendee" Column="SYSID" ColumnRef="ATTENDEE_ID"
JoinType="INNER JOIN"/>
</TableJoins>
<ObjReferences>
<Object Name="BOEvent" Description="" Relationship="M-1" Table="events"
Column="SYSID" FieldRef="EvtId"/>
</ObjReferences>
</BizObj>
Object Attribute Description
55
Openbiz 2.4 Manual
Name The name of the referred BizDataObj
Relationship Relationship between this dataobj and the referred dataobj
Table The table of the referred dataobj
Column The column of the referred dataobj's table
FieldRef The field mapping to the foreign key column in base table
One to one relationship between BizDataObjs
One to one relationship is a special case of many to one relationship.
One to many relationship between BizDataObjs
One to many relationship between two tables means table 2 has a column that contains
the foreign key pointing to a key/unique column in table 1. To map such relationship
between two BizDataObjs, use an Object in ObjectReference section.
<BizDataObj Name="BOEvent" Description="Event BizDataObj" Package="demo"
Class="BizDataObj" Table="events" ...>
<BizFieldList>
<BizField Name="Id" Column="SYSID"/>
<BizField Name="Name" Column="NAME"/>
</BizFieldList>
<ObjReferences>
<Object Name="BORegist" Description="" Relationship="1-M" Table="regist"
Column="EVENT_ID" FieldRef="Id" CascadeDelete="Y"/>
</ObjReferences>
</BizDataObj>
Object Attribute Description
Name The name of the referred BizDataObj
56
Openbiz 2.4 Manual
Description
Relationship Relationship between this dataobj and the referred dataobj
Table The table of the referred dataobj
Column The column of the referred dataobj's table. This column contains
the foreign key to the base table
FieldRef The field mapping to the column in base table
CascadeDelete Indicate whether deleting a record in base table will cause the
deletion of all related record in referred table.
Many to many relationship between BizDataObjs
Many to many relationship between two tables means an intersection table (also called
cross reference table, or correlation table) contains the foreign key columns pointing to a
key/unique column in table 1 and table 2. To map such relationship between two
BizDataObjs, use an Object in ObjectReference section.
<BizDataObj Name="BOEvent" Table="events" ...>
<BizFieldList>
<BizField Name="Id" Column="SYSID"/>
<BizField Name="Name" Column="NAME"/>
</BizFieldList>
<ObjReferences>
<Object Name="BOAttendee" Description="" Relationship="M-M" Table="attendee"
Column="SYSID" FieldRef="Id" CascadeDelete="Y" XDataObj="BORegist"
XColumn1="EVENT_ID" XColumn2="ATTENDEE_ID"/>
</ObjReferences>
</BizDataObj>
Object Attribute Description
Name The name of the referred BizDataObj
57
Openbiz 2.4 Manual
Description
Relationship Relationship between this dataobj and the referred dataobj
Table The table of the referred dataobj
Column The column of the referred dataobj's table. This column contains
the foreign key to the base table
FieldRef The field mapping to the column in base table
CascadeDelete Indicate whether deleting a record in base table will cause the
deletion of all related record in intersection table.
XTable The intersection table name
XColumn1 The intersection table column that has the foreign key of the base
table
XColumn2 The intersection table column that has the foreign key of the
referred table
XDataObj BizDataObject whose base table is the intersection table that is
XTable. When user associates one record from referred
DataObject to the base DataObject, a new record is created from
the XDataObj and added in the intersection table.
Configuration of View and Form
View is the container of presentation elements. For browser, view is a web page. Form is a
logic presentation unit. Form can be a typical HTML form or combincation of multiple
elements that present a logic dataset. An Openbiz form is more list the Form concept used
in Visual Basic. Forms are contained in a view which can defined the relationship between
forms. The layout of view and form are defined in template files (smarty or php template).
Map BizDataObj relationship of Forms
If more than one Forms are placed in a View and they can be linked by specifying
Parent-Child relationship in the View. The Forms need to have the relationship of their
underline BizDataObj. Here is a sample.
58
Openbiz 2.4 Manual
<EasyView Name="EventView" ...>
<FormReferences>
<Reference Name="easy.f_event" SubForms="easy.f_attendee"/>
<Reference Name="easy.f_attendee" />
</FormReferences>
</EasyView>
SubForms attribute has syntax like
SubForms="childform1_name;childform2_name;...". In the above sample,
f_event is the parent form and f_attendee is the child form. This means children forms
data may change along the change of the parent form. Because on the DataObj level
Event and Attendee have many to many relationship, the event form and attendee form
will take the M-M as their relationship. They present the underline data relationship to user
interface
Basic Form layout
Openbiz Form is composed with four parts - data panel, action panel, navigation panel
and search panel
Data panel is the area showing the data. It can be shown as list, table, form, tree and
so on.
Action panel is a list of controls where users can invoke command on the form.
Navigation panel is a set of controls that controls data navigation such as paging,
scrolling.
Search panel usually includes the search entries and search button.
Bind Form with Data object
Form is to present data defined in BizDataObj. Form defines the mapping between
elements in the BizForm and the fields in BizDataObj. Here's an example.
<EasyForm Name="f_RegistList" ... BizDataObj="d_Regist" ...>
59
Openbiz 2.4 Manual
<DataPanel>
<Element Name="reg_id" FieldName="Id" Class="ColumnText" Label="Registration
Id"/>
<Element Name="reg_attdfn" FieldName="AttdFName" Class="ColumnText" Label
="First Name"/>
<Element Name="reg_attdln" FieldName="AttdLName" Class="ColumnText"
Label="Last Name"/>
</DataPanel>
</EasyForm >
View/Form navigation flow
In Openbiz 2.4, in default display patterm follows the navigations between views. This
means users
see list of data in a "list" view
create a new record in a "new" view
edit a record in a "edit" view
see record details in "detail" view
For heavy data crowded screen, the above display pattern requires many page reloads.
To resolve the problem and archieve the same user interactivity supported by 2.3 BizForm,
the practice below can be used. Assume the default form of a view is a list form.
1. Popup. Use popup dialog or window to display the edit/new/details form - same as 2.3
BizForm Modal/Window.
2. Toggle. Render edit/new/details form in the same area of the list form - same as 2.3
BizForm display modes toggling.
The sampel implementation of above 2 approaches can be found in baseapp Attendee tab.
New attendee form is a Toggel form with list form. Edit Attendee form is a Popup form.
Screen: Popup form set on Edit button
60
Openbiz 2.4 Manual
Screen: Toggle form set by New button
61
Openbiz 2.4 Manual
Present data with various HTML elements
Element of a form can be linked to different Element class to present different type of UI
unit. Openbiz core provides 20+ basic and advanced element classes. Developers would
be able to bind an element with the following types:
Element type Class Special tricks beyond comment configuration
Single line text input InputText Using HTMLAttr="maxlength=N" sets the limit the
maximum number of characters that the user can
enter.
Multiple line text
input
Textarea
List box or Combo
box
Listbox By default show comboBox. If
HTMLAttr="size=N", show N-row listbox
Checkbox SelectFrom="Value" means this checkbox returns
the Value when user check the checkbox
Radio Button By default the radion buttons are arranged
horiztionally. If Width="1", you can force them
arranged vertically
Label and field LabelText
Grid cell ColumnText
Image Button Button
Standard Button HTMLBUtton
Reset Button ResetButton
Submit Button SubmitButton
Password input box Password
File upload input File
Hidden Hidden
Date input InputDate DHTML calendar 1.0 (LGPL license) provided by
dynarch.com. The DHTML calendar is well
documented at
http://www.dynarch.com/demos/jscalendar/doc/ht
ml/reference.html. Many thanks to Nik Chankov
62
Openbiz 2.4 Manual
for his help on integrating openbiz with DHTML
calendar. Openbiz by default uses system style
for the calenar
Datetime input InputDatetime Same as Date Input
Rich text editor RichText
Auto suggstion
input
AutoSuggest
Input picking box InputPicker
Area with pure html
code
HTMLBLock "<" and ">" used in HTML block have to be
replaced by "<" and ">". Please refer to
http://www.w3schools.com/html/html_entities.asp
for more details.
Checkbox for row
selection of a grid
RowCheckbox
Editable Combobox EditCombobox Editable combobox is limited with element
value=text.
Element classe and attributes matrix
Not all attributes in Element is used by all classes. Element class will optionally use the
attributes. Please see the classs and attributes mapping matrix below.
Element Class InputText Textarea Password File Button HTMLButton
Name x x x x x x
Description x x x x x x
FieldName x x x x
Label x x x
Text x x x x
Image x
Link
Hidden x x x x x x
Enabled x x x x x x
63
Openbiz 2.4 Manual
Sortable
Required x x x x
DefaultValue x x
ValuePicker
SelectFrom
Width x x x x x x
Height x x x x x x
CssClass x x x x x x
Style x x x x x x
HTMLAttr x x x x x x
Element Class ResetButton SubmitButton RichText AutoSuggest
Name x x x x
Description x x x x
FieldName x x
Label x x
Text x x x x
Image
Link
Hidden x x x x
Enabled x x x x
Sortable
Required x x
DefaultValue x x
ValuePicker
SelectFrom
Width x x x x
Height x x x x
CssClass x x x x
Style x x x x
HTMLAttr x x x x
64
Openbiz 2.4 Manual
Element Class InputDate InputDatetime InputPicker RowCheckbox
Name x x x x
Description x x x x
FieldName x x x x
Label x x x
Text
Image
Link
Hidden x x x x
Enabled x x x x
Sortable
Required x x x
DefaultValue x x x
ValuePicker x
SelectFrom
Width x x x x
Height x x x x
CssClass x x x x
Style x x x x
HTMLAttr x x x x
Element Class Hidden Listbox Checkbox Radio LabelText
Name x x x x x
Description x x x x x
FieldName x x x x x
Label x x x x
Text x x
Image
Link
Hidden x x x x x
Enabled x x x
65
Openbiz 2.4 Manual
Sortable
Required x x x
DefaultValue x x x
ValuePicker
SelectFrom x x x
Width x x x x x
Height x x x x x
CssClass x x x x x
Style x x x x x
HTMLAttr x x x x x
Element Class ColumnText HTMLBlock EditCombobox
Name x x x
Description x x x
FieldName x
Label x x
Text x x x
Image
Link x
Hidden x x
Enabled x
Sortable x
Required x
DefaultValue x
ValuePicker
SelectFrom x
Width x x
Height x x
CssClass x x x
Style x x
HTMLAttr x x
66
Openbiz 2.4 Manual
Event handling in Form
Openbiz allows setting event handling functions to element. Event handling is defined in
following syntax.
<Element Name="" Class="">
<EventHandler Name="ehName" Event="eventName" Function="…" FunctionType="…"
RedirectPage=""/>
</Element>
More than event handlers can be associated to an element. In EvenHandler element,
- Event is the html element event name. Please refer to
http://www.w3.org/TR/REC-html40/interact/scripts.html, 18.2.3 Intrinsic events.
- Function gives a BizForm method name and arguments. Server side should have a
corresponding BizForm method. When the request hits BizController, it is routed to the
BizForm method. If the method doesn't exist, an error is returned. Function with syntax of
<EventHandler ... Function="objectName.methodName(arg1, arg2...)" .../>.
The objectName can be empty, this means it calls method of current BizForm. For
example
<EventHandler ... Function="SaveRecord()" .../>
User can only invoke method of objects whose have metadata files. These objects include
BizForm, BizDataObj, BizView and PluginService. BizForm methods and PluginService
methods are recommended to be callable from client side.
- FunctionType can be either RPC or Page or Form, Popup, Prop_Window or
Prop_Dialog. It defines how the function is invoked.
RPC
the function with type RPC is invoked on server side by HTTPRequest (AJAX). RPC is
67
Openbiz 2.4 Manual
default value if nothing is specified.
example New record button:
<EventHandler Name="onclick" Event="onclick" Function="NewRecord()"
FunctionType="RPC"/>
Page
the function with type Page is invoked on server side with page reload, form data is not
passed to server
example Export button to bring up a file save dialog in the page
<EventHandler Name="onclick" Event="onclick"
Function="CallService(ioService,exportXML)" FunctionType="Page"/>
Form
the function with type Form is invoked on server side by form submission
example Save button when there's file to upload in the form:
<EventHandler Name="onclick" Event="onclick" Function="SaveRecord()"
FunctionType="Form"/>
Popup
the function with type Popup is invoked on server side targeting to a new popup window
example Excel output button to show excel format in a popup:
<EventHandler Name="onclick" Event="onclick"
Function="CallService(excelService,renderHTML)" FunctionType="Popup"/>
68
Openbiz 2.4 Manual
Prop_Window
the function with type Prop_Window is invoked on server side targeting to a new prototype
window (DHTML in-page window)
example Add record button to show the picker form in a in-page window:
<EventHandler Name="onclick" Event="onclick"
Function="LoadPicker(easy.v_Picker,easy.f_AttendeePicker)"
FunctionType="Prop_Window"/>
Prop_Dialog
the function with type Prop_Dialog is invoked on server side targeting to a new
prototype dialog (DHTML in-page modal window)
example Edit record button to show the edit form in modal dialog:
<EventHandler Name="onclick" Event="onclick" Function="EditRecord()"
FunctionType="Prop_Dialog"
RedirectPage="form=easy.f_AttendeeEdit&fld:Id={@:Elem[fld_id].Value}"/>
- RedirectPage is the redirected page/view after an action is taken successfully.
RedirectPage normally defines a URL that will be redirected after the function call.
If RedirectPage starts with "form=...", it will rend the form (not a full page/view)
overlay on the current form in case of FunctionType=""
in a window in case of FunctionType="Prop_Window"
in a dialog in case of FunctionType="Prop_Dialog"
Bind data to Listbox
Openbiz allows binding static or dynamic data to Listbox element as well as other
elements that use SelectFrom attribute.
- Bind simple list to Listbox
69
Openbiz 2.4 Manual
In your form, you can assign SelectFrom="Selection(Option1|Option2|Option3|...)" for an
Element. Then the listbox will have Option1, Option2 and Option3 in the list.
- Bind static list from xml file to Listbox
In your form, you can assign SelectFrom="Selection(Fee)" for an Element, which means
this field element is a Listbox whose data is from the "Fee" elements in Selection.xml file.
What's in the Selection.xml?
<Fee Value=""/>
<Fee Value="15"/>
<Fee Value="20"/>
Also, you can give both value and text. If only give value, openbiz uses the value as the
display text.
<ChartOption Value="AAA" Text="BarLine Chart"/>
<ChartOption Value="BBB" Text="Pie Chart"/>
<ChartOption Value="CCC" Text="GroupBar Chart"/>
You can make up your own xml file that has list of values for selection.
- Bind dynamic list (Table column) to Listbox
In your BizForm, you can assign SelectFrom="BizDataObjName[BizFieldName]"
for a Element, which means this field control is a Listbox whose data is from the table
column mapping to the BizFieldName of the BizObjName. To avoid same values appear in
the Listbox, you need to make sure the BizObj query returns an unique list.
Format
SelectFrom="BizDataObjName[BizFieldName4Text:BizFieldName4Value]"
is supported so that users can show BizFieldName4Text field in Listbox and set
BizFieldName4Value for value.
A SearchRule can be applied on the SelectFrom with syntax as
SelectFrom="BizDataObjName[BizFieldName4Text:BizFieldName4Value],
70
Openbiz 2.4 Manual
SearchRule_of_the_BizDataObj". For example
<BizCtrl Name="" ... SelectFrom="BOEvent[Name], [Name] LIKE '%Soc%'"/>.
Form controls dependency
In a complex form, there's usually some elements depending the values of other elements.
When the driving element changes, its children controls change accordingly. This is so
called form controls dependency.
With the help of expression language, elements' relationship can be specified in BizForm
metadata file. With the help of event handlers, events on driving control will cause the
dynamical changes on its children controls. Here is a sample.
<DataPanel>
<Element Name="fld_combo1" Class="Listbox" FieldName="" Label="Event test combo
box" SelectFrom="easy.Selection(TestEvent)">
<EventHandler Name="onchange" Event="onchange" Function="UpdateForm()"/>
<EventHandler Name="onmouseover" Event="onmouseover"
Function="js_onMouseOverCombo1()"/>
</Element>
<Element Name="fld_edit1" Class="InputText" FieldName="" Label="Enable/disable
switch" Enabled="{(@:Elem[fld_combo1].Value == 'EnblCtrl')?'Y':'N'}">
</Element>
<Element Name="fld_edit2" Class="InputText" FieldName="" Label="Hide/show
switch" Hidden="{(@:Elem[fld_combo1].Value == 'HideCtrl')?'Y':'N'}">
</Element>
<Element Name="fld_combo2" Class="Listbox" FieldName="" label="cascade
combobox" SelectFrom="easy.Selection({@:Elem[fld_combo1].Value}_opt)">
</Element>
<Element Name="fld_edit3" Class="InputText" FieldName="" label="change value
71
Openbiz 2.4 Manual
with js function">
</Element>
</DataPanel>
The first combobox is the driving control. Based on its value,
- 2nd control will be enabled or disabled (BizForm configuration)
- 3rd control will be hidden or shown (BizForm configuration)
- 4th control will have different lists (BizForm configuration)
- 5th control will change value and color when monuseover the 1st control (customer js
class extending from jbForm)
Build a multi-step wizard view
Wizard is a sequence of forms (questionnaires) which guide users to complete a
complicated task. An example is filling an expense report which include different types
(hotel, airfare, other activities...) of expenses.
Openbiz supports wizard by easy metadata configuration. Openbiz wizard has following
features:
Each form has "Next", "Back", "Cancel" and "Finish" navigation buttons.
If user clicks cancel button, user input data is not saved to database.
72
Openbiz 2.4 Manual
User input data won't to commit to database until user clicks finish button.
To see sample of wizards, go to Miscellaneous tab, click on "Wizard tests +" submenus.
Or copy the url as http://host/baseapp/bin/controller.php?view=easy.v_EventWizard
Configuration of wizard view
Openbiz wizard is a regular view that contains several wizard forms. So configuring a
wizard in openbiz is no harder than configuring a View. The difference between a wizard
view and regular view is wizard view show the wizard forms one by one based on the their
sequence in view metadata file, but regular view show all forms in one page. Below is an
example of a wizard view metadata file.
<?xml version="1.0" standalone="no"?>
<EasyView Name="v_EventWizard" Description="Openbiz Demo - Events Wizard"
Class="EasyViewWizard" TemplateEngine="Smarty" TemplateFile="view_wizard.tpl">
<FormReferences>
<Reference Name="easy.f_EventNewWiz" Description="Create Event"/>
<Reference Name="easy.f_AttendeeNewWiz" Description="Create Attendee"/>
</FormReferences>
</EasyView>
Configuration of wizard forms
A wizard form is a regular form with class as EasyFormWizard. The form usually needs to
configure next, back, cancel and finish buttons. For cancel and finish button, redirect page
can be given to route the user navigation.
73
Openbiz 2.4 Manual
This is a typical wizard form metadata file.
<?xml version="1.0" encoding="UTF-8"?>
<EasyForm Name="f_EventNewWiz" Class="EasyFormWizard" FormType="New"
jsClass="jbForm" Title="Create an event" Description=""
BizDataObj="easy.d_Event" DefaultForm="Y" TemplateEngine="Smarty"
TemplateFile="detail.tpl">
<DataPanel>
<Element Name="fld_name" Class="InputText" FieldName="Name" Label="Name"
Width="200"/>
<Element Name="fld_host" Class="InputText" FieldName="Host" Label="Host"
Width="200"/>
<Element Name="fld_loc" Class="InputText" FieldName="Location"
Label="Location" Width="400"/>
<Element Name="fld_start" Class="InputDatetime" FieldName="Start"
Label="Start" Width="200"/>
<Element Name="fld_end" Class="InputDatetime" FieldName="End" Label="End"
Width="200"/>
<Element Name="fld_desc" Class="Textarea" FieldName="Description"
Label="Description" Width="400" Height="200" text=""/>
</DataPanel>
<ActionPanel>
<Element Name="btn_next" Class="Button" Text="Next >"
CssClass="button">
<EventHandler Name="next_onclick" Event="onclick"
Function="GoNext()"/>
</Element>
<Element Name="btn_cancel" Class="Button" Text="Cancel"
CssClass="button">
<EventHandler Name="cancel_onclick" Event="onclick"
Function="DoCancel()" RedirectPage="controller.php?view=easy.v_Home"/>
74
Openbiz 2.4 Manual
</Element>
<Element Name="btn_finish" Class="Button" Text="Finish"
CssClass="button">
<EventHandler Name="finish_onclick" Event="onclick"
Function="DoFinish()" RedirectPage="controller.php?view=easy.v_EventList"/>
</Element>
</ActionPanel>
...
</EasyForm>
If application has speical logic, Openbiz suggests developers to write their own wizard
form class drived from core classes. By overriding GoPrev(), GoNext(), DoCancel() and
DoFinish() methods, developers can do different handling on navigation buttons events.
Configuration of record-selecting popup BizForm
Users can pick record from a different form on the following cases:
Add/change the child record (parent-child is M-1) by picking another child record.
Add a child record in the child form (parent-child is M-M) by picking an existing child
record
Add/change the joined fields by picking a record from joined dataobj.
Note: Openbiz keeps only one instance of a metadata object (of DataObj, Form, View) in
a user session, so always configure a different object when two instances of same entity
needed in one view. For example, on an Event form (FMEvent / BOEvent), we usually
configure an event popup as (FMEventPopup / BOEventX). There're two ways to
configure a record-selecting popup BizForm.
Configure Element to show popup
To configure element to show popup form, users can set "LoadPicker(viewName,
FormName)" in the EventHandler Function attribute and set
FunctionTarget="Popup" or "Prop_Window". This configuration can be used in
75
Openbiz 2.4 Manual
picking a child record (M-1 or M-M) in the child form.
Sample:
<EventHandler Name="onclick" Event="onclick"
Function="LoadPicker(easy.v_Picker,easy.f_AttendeePicker)"
FunctionTarget="Popup"/>
On the popup form, add a button to call AddToParent() to add the current selected
record to the parent form (the form trigger the popup).
Configure InputPicker to show popup
In order to pick values from a popup window and populate them to base form
elements, you can use InputPicker element that has the pick button at the right side of
an input box. To configure the InputPicker element, ValuePicker and PickerMap need
to be specified correctly.
ValuePicker attribute. ValuePicker gives the view and form to be shown in
the popup.
It has syntax as ValuePicker="viewName,formName,elementName".
PickerMap attribute. PickerMap is used to map the picked record from a
popup form to the base record that initiates the popup. Openbiz will pick
values from popup form according to the mapping.
The syntax of PickerMap is
PickerMap="thisform_control_1:popup_control_1,
thisform_control_2:popup_control_2, ..."
Sample:
<Element Name="fld_attdln" Class="InputPicker" FieldName="AttdLName"
Label="Last Name" Width="200"
ValuePicker="easy.v_Picker,easy.f_AttendeePicker,fld_attdln"
PickerMap="fld_attdid:fld_id,fld_attdfn:fld_fname,fld_attdln:fld_lname"/>
On the popup form, add a button to call JoinToParent() to join the current selected
record to the parent form (the form trigger the popup).
76
Openbiz 2.4 Manual
Shortcut key support (Keyboard navigation)
Keyboard navigation support on Form is enhanced on top of excellent shortbut.js library (form http://www.openjs.com/scripts/events/keyboard_shortcuts/). Once shortcut keys are defined on BizForm, users are able to use keyboard to to navigate records and pages, create/edit/delete record. Users can have the rich client experience on browser.
Shortcut keys are defined in Form metadata files. EventHandler of controls can have a ShortcutKey attribute to associate the shortcut key to a function. The syntax is
<Element Name="" ...>
<EventHandler Function="" ShortcutKey="key_combination".../>.
</Element>
Form only recognizes shortcut keys defined in controls of its Toolbar and Navbar.
Openbiz recognizes keys including:
Key input key text to use in ShortcutKey attribute
0,1,...9 0,1,...9
a,b,...z or A,B,...Z A,B,...Z
Ctrl key Ctrl
Shift key Shift
Alt key Alt
Enter key Enter
Escape key Escape
Page up key PageUp
Page down key PageDown
Left arrow key Left
Right arrow key Right
77
Openbiz 2.4 Manual
Up arrow key Left
Down arrow key Down
Insert key Insert
Delete key Delete
F1,F2,...F12 F1,F2,...F12
Developers can configure combination of Ctrl and/or Shift and/or Alt with other key, just
use "+" to link them together. Be aware of not conflicting with default shortcut keys of
browsers. Openbiz shortcut keys can usually override the browser default keys.
See shortcut key sample in demoapp/modules/easy/f_EventList.xml.
Shortcut key Command to execute
Shift_Right go to next page
Shift+Left go to previous page
Ctrl+E edit the selected record
Delete delete the selected record
Enter run search, or save record
Escape cancel search or cancel editing
Context menu support
Openbiz Form allows user to override browser right click behavior by defining
ContextMenu attribute for EventHandler of Toolbar/Navbar controls. User can see context
menu by right-clicking mouse on grid.
78
Openbiz 2.4 Manual
Example of adding context menu (in baseapp/modules/easy/f_EventList.xml)
<Element Name="" ...>
<EventHandler Name="onclick" Event="onclick" Function="SearchRecord()"
ShortcutKey="Ctrl+Shift+Q" ContextMenu="Search"/>.
</Element>
Configure Tree Structure
Tree structure is commonly used to describe objects with hierarchy. For example,
company internal organization, product catalog ... Openbiz provides supports for tree
structure in 2.4 beta based on popular jstree 0.9.8 . The steps of configurating a tree form
are:
1. Design an table to capture tree relationship. Normally such table has schema like
(id, parent_id, name, object_id). We can call this table as tree index table.
o id is the PK of the record. Of course, the table may have different name
other than "id" as its PK column.
o parent_id is the FK pointing to parent record "id" column. Again "parent_id"
is just a pseudo name
o name is the name of the tree node. Again "name" is just a pseudo name
o object_id is the FK pointing to another table who has the real object data.
Again "object_id" is just a pseudo name
2. Design another table to capture the real object data. We can call this table as tree
object
table.file:///D:/Apache2/htdocs/ob/ob24/baseapp/modules/easy/f_tree_structure_li
st.xml
o The "id" of this table is same as "object_id" in the tree index table.
3. Define a dataobj xml that needs to have
o "Table" as tree index table
o "Id" field mapping to "id" column
o "PId" field mapping to "parent_id" column
o "Name" field mapping to "name" column
o "ObjectId" field mapping to "object_id" column
4. Define a form with Class = "EasyFormTree". EasyFormTree is an Openbiz core
form class. 2 more attributes for such class.
79
Openbiz 2.4 Manual
o RootSearchRule. It tells the root node search rule. E.g. "[PId] is null"
o TreeDepth. It tells how many levels of the initial tree.
5. Set form template engine as "PHP", and use tree_php.tpl
o PHP template allow more control of the rendering logic. Rendering tree
needs to use recursive function call which is hard in smarty (needs custom
plugin)
o tree_php.tpl prepare the jstree and other necessary functions
To see the sample of the tree structure, please check
baseapp/modules/easy/f_tree_structure_list.xml. The test url is
http://host/baseapp/bin/controller.php?view=easy.v_tree_structure.
Multi-selection (multi-delete) support
Selecting multiple records on a data grid is a common function in many applications. To
add a checkbox in the first column of a grid, the following line needs to be added.
<Element Name="row_selections" FieldName="Id" Class="RowCheckbox" …/>
The example is baseapp/modules/easy/v_EventList.xml.
80
Openbiz 2.4 Manual
Application tabs and sub tabs support
Tabs are very popularly used in both business web applications and consumer web sites.
In many business applications, subtabs are common widgets to organize the
parent-children relationship between UI components in a page. Openbiz supports tabs
and subtabs with combination of enhanced HTMLTab class.
The sample metadata xml file of HTMLTab class.
demo/Tabs.xml
<?xml version="1.0" standalone="no"?>
<Tabs Name="Tabs" Class="HTMLTabs" TemplateFile="tabs.tpl">
<TabViews>
<View Name="home" URL="./home.php" Caption="Home"/>
<View Name="event" View="demo.EventView"Caption="Events"/>
<View Name="regist" View="demo.RegistView" Caption="Registration"/>
<View Name="attendee" View="demo.AttendeeView" Caption="Attendees"/>
<View Name="reports" URL="./report.php" Caption="Reports"/>
<View Name="test" View="demo.FieldDepTestView" Caption="Test 2.1 Features"/>
</TabViews>
</Tabs>
81
Openbiz 2.4 Manual
demo/EventTabs.xml
<?xml version="1.0" standalone="no"?>
<Tabs Name="EventTabs" Class="HTMLTabs" TemplateFile="subtabs.tpl">
<TabViews>
<View Name="EventAttendee" View="demo.EventView" Target="" Caption="Attendees"
/>
<View Name="EventRegist" View="demo.EventRegistView" Target=""
Caption="Registration"/>
</TabViews>
</Tabs>
Other Navigation widgets
Menu configuration in Openbiz. Please see the sample below. The xml should be
self-explained.
<?xml version="1.0" standalone="no"?>
<Tree Name="Tree" Class="HTMLTree">
<Node URL="http://www.yahoo.com" Target="" Caption="yahoo">
<Node URL="http://mail.yahoo.com" Target="" Caption="yahoo email"/>
<Node URL="http://finance.yahoo.com" Target="" Caption="yahoo finance">
<Node URL="http://finance.yahoo.com/mt?u" Target="" Caption="Today's
market"/>
<Node URL="http://biz.yahoo.com/top.html" Target="" Caption="News"/>
</Node>
</Node>
</Tree>
Tree configuration in Openbiz. Please see the sample below. The xml should be
82
Openbiz 2.4 Manual
self-explained.
<?xml version="1.0" standalone="no"?>
<Menu Name="Menus" Class="HTMLMenus">
<MenuItem URL="http://www.yahoo.com" Target="" Caption="Yahoo"
Icon="yahoo.gif">
<MenuItem URL="http://mail.yahoo.com" Target="" Caption="Yahoo email"
Icon="yahoo.gif"/>
<MenuItem URL="http://finance.yahoo.com" Target="" Caption="Yahoo
finance ..." Icon="yahoo.gif">
<MenuItem URL="http://finance.yahoo.com/mt?u" Target="_blank"
Caption="Today's market"/>
<MenuItem URL="http://biz.yahoo.com/top.html" Target="_blank"
Caption="News"/>
</MenuItem>
</MenuItem>
</Menu>
Use Theme
Use theme in openbiz application
From Openbiz 2.4 beta, theme is added to provide more flexibility of managing application
style.
New application structure with theme
baseapp/ (baseapp web pages)
---bin/ (baseapp php source)
---files/ (baseapp files)
---js/ (baseapp javascript files)
---pages/ (baseapp HTML files)
---log/ (baseapp logs)
83
Openbiz 2.4 Manual
---medata/ (baseapp metadata files)
---modules (baseapp modules files)
---session (baseapp session files)
---themes/ (baseapp themes)
---default/ (baseapp default theme)
---css/ (baseapp theme css files)
---images/ (baseapp theme images files)
---templates/ (baseapp theme template files)
Custom theme will be like
---themes/ (baseapp themes) ---my_theme/ (baseapp custom theme) ---css/ (baseapp theme css files) ---images/ (baseapp theme images files) ---templates/ (baseapp theme template files)
Theme settings
The following needs to be done to set a theme:
1. In your_app/bin/app.inc, change the definitions properly.
/* define themes const */
define('USE_THEME', 1); // if USE_THEME is set to 0, openbiz will locate css under
/css, image files under /images, template files under /templates
define('THEME_URL',"../themes"); // relative to /baseapp/bin/, or it can be absolution url
define('THEME_PATH',APP_HOME."/themes"); // absolution path the themes
define('THEME_NAME',"default"); // name of the theme. theme files are under
themes/theme_name
/* define javascript path */
define('JS_URL', "../js"); // relative to /baseapp/bin/, or it can be absolution url
2. Add /themes/your_theme/templates/cfg/tpl.conf.
This file is smarty config file that defines the images and css url (absolute or relative to
84
Openbiz 2.4 Manual
your_app/bin).
# global variables
images = "../themes/default/images"
css = "../themes/default/css"
3. Change template files with config file variables
For css file, change from "../css" to "{#css#}"
For image file, change from "../images" to "{#images#}"
Upgrade old version application with theme
Developers have 2 options of using theme on the older application.
1. Ignore theme
For application built on older version, it can keep the existing source structure where css,
images, templates folders are under your_app/. In your app.inc, set
define('USE_THEME', 0);
2. Use theme
Please follow the steps mentioned in "Theme settings" section.
Theme and template file
Openbiz uses template in both view and form. It is recommended that
move only view templates under theme/templates. Theme contains the overall
application style and page layout that is defined in view template file.
keep form templates under its own module directories. Form template is special
layout in the form block. It won't change in different theme.
85
Openbiz 2.4 Manual
Openbiz Development Guide
View access url
Manage your code
Use BizDataObj functions
User Form functions
Data validation
Extend Openbiz
Implement plug-in services
Implement authentication and access control
Use DataObject event trigger
Control look and feel
Enable multi-lanuage
Debugging
View access url
Openbiz view can be configured as static view and dynamic view
Static view is a view that has fixed forms configured in the view metadata.
Dynamic view is a view with Class as "DynaView" that has empty forms in it metadata.
This view can accept any form (given in url) to render.
For view with 3 or more forms (like dashboard page), static view is recommended to avoid
complex url.
Openbiz view can be accessed by url like
With view name (Static view)
http://host/app_path/bin/controller.php?view=viewname
Sample http://localhost/ob24/baseapp/bin/controller.php?view=easy.v_EventList
86
Openbiz 2.4 Manual
With view name and field name/value (Static view)
http://host/app_path/bin/controller.php?view=viewname&fld:fldname=fldvalue
fldname and fldvalue are used as the search rule of the first form in the view.
Sample http://localhost/ob24/baseapp/bin/controller.php?view=easy.v_EventDetail&fld:Id=EVT_4
With view name and form name (Dynamic view)
http://host/app_path/bin/controller.php?view=viewname&form=formname
Sample http://localhost/ob24/baseapp/bin/controller.php?view=easy.v_Regist&form=easy.f_Regist
List
With view name, form name and field name/value (Dynamic view)
http://host/app_path/bin/controller.php?view=viewname&form=formname&fld:fldname=fld
value
fldname and fldvalue are used as the search rule of the form in the view.
Sample http://localhost/ob24/baseapp/bin/controller.php?view=easy.v_Regist&form=easy.f_Regist
Detail&fld:Id=REG_103
With view name, form name and child form name (Dynamic view)
http://host/app_path/bin/controller.php?view=viewname&form=formname&cform=child_fo
rmname
Sample http://localhost/ob24/baseapp/bin/controller.php?view=easy.v_Attendee&form=easy.f_Att
endeeList&cform=common.f_AttachList
With view name, form name and child form name and field name/value
(Dynamic view)
http://host/app_path/bin/controller.php?view=viewname&form=formname&cform=child_fo
87
Openbiz 2.4 Manual
rmname&fld:fldname=fldvalue
fldname and fldvalue are used as the search rule of the parent form in the view.
Sample http://localhost/ob24/baseapp/bin/controller.php?view=easy.v_Attendee&form=easy.f_Att
endeeDetail&cform=common.f_AttachList&fld:Id=ATD_1
Manage your code
Developers are recommended to write their module and put source files under
app/modules/your_module/ directory.
The following source files are normally considered in the module development.
Metadata files
There are several ways to store your metadata files
1. metada files in single module directory. (ok for small module)
Example /modules/trac/ includes all data, form and view files.
2. separate files by functions.
Example /modules/trac/admin/ includes data, form and view files.
/modules/trac/ticket/ includes data, form and view files
3. separate files by data, form, view
Example /modules/trac/ includes only view metadata files
/modules/trac/data/ includes only data metadata files
/modules/trac/form/ includes only form metadata files
4. separate files by functions and data, form, view (good for big module)
Example /modules/trac/ticket/ includes only ticket view metadata files
/modules/trac/ticket/data/ includes only ticket data metadata files
/modules/trac/ticket/form/ includes only ticket form metadata files
88
Openbiz 2.4 Manual
Custom php class files
PHP custom class file should be in the sample directory of the metadata
Template files
Template files can be stored in the /templates directory of the metadata file.
For general template, it can be stored in yourapp/modules/common/templates/ or
yourapp/templates/ directory.
Openbiz locates the templates in package/templates/ first, then in common/templates,
then in /templates/.
Image files
Image files are in yourapp/images/. You can set sub directory in image/
css files css files are in yourapp/css/. You can set sub directory in css/
javascript files
Javascript files are in yourapp/js/. You can set sub directory in js/
Language files
msg files should be in the sample directory of the metadata
Use BizDataObj functions
Only basic usage of BizDataObj is listed below. Please refer to the API doc for details.
Query and get results:
/* Fetches SQL result rows as a sequential array according the query rules set
before.
* sample code:
89
Openbiz 2.4 Manual
*/
$do->ResetRules();
$do->SetSearchRule($search_rule1);
$do->SetSearchRule($search_rule2);
$do->SetSortRule($sort_rule);
$do->SetOtherRule($groupby);
$total = $do->Count();
$do->SetLimit($count, $offset=0);
$recordSet = $do->Fetch();
/* Fetches SQL result rows as a sequential array without using query rules set
before.
* sample code:
*/
// fetch all record with firstname starting with Mike
$do->DirectFetch("[FirstName] LIKE 'Mike%'");
// fetch first 10 records with firstname starting with Mike
$do->DirectFetch("[FirstName] LIKE 'Mike%'", 10);
// fetch 20th-30th records with firstname starting with Mike
$do->DirectFetch("[FirstName] LIKE 'Mike%'", 10, 20);
/* Do the search query and return results set as PDOStatement
* sample code:
*/
$do->ResetRules();
90
Openbiz 2.4 Manual
$do->SetSearchRule($search_rule1);
$do->SetSearchRule($search_rule2);
$do->SetSortRule($sort_rule);
$do->SetOtherRule($groupby);
$total = $do->Count();
$do->SetLimit($count, $offset=0);
$resultSet = $do->Find();
$do->GetDBConnection()->setFetchMode(PDO::FETCH_ASSOC);
while ($record = $resultSet->fetch())
{
print_r($record);
}
Insert, Update and Delete a record
/* Insert a record
* sample code:
*/
$dataRec = new DataRecord(null, $dataobj);
$dataRec->first_name = 'Steve';
$dataRec->last_name = 'Jobs';
$dataRec->save( );
/* Note: the following code works too. */
$dataRec['first_name'] = 'Steve';
$dataRec['last_name'] = 'Jobs';
$dataRec->save( );
91
Openbiz 2.4 Manual
/* Update a record
* sample code: $recordArray is the old record
*/
$dataRec = new DataRecord($recordArray, $dataobj);
$dataRec->first_name = 'Steve';
$dataRec->last_name = 'Jobs';
$dataRec->save( );
/* Note: the following code works too. */
$dataRec['first_name'] = 'Steve';
$dataRec['last_name'] = 'Jobs';
$dataRec->save( );
/* Delete a record
* sample code: $recordArray is the record to be deleted
*/
$dataRec = new DataRecord($recordArray, $dataobj);
$dataRec->delete( );
Use Form functions
User can configure function in BizForm metadata file to invoke appropriate action on
server side. The commonly used BizForm methods are listed below. Please refer to the
API doc for details.
Query and show results
RunSearch - Issue the query and rerender the form
92
Openbiz 2.4 Manual
Insert a new record
NewRecord - show the new record page
SaveRecord - save current edited record
Update a record
EditRecord - show the edit record page on current focus record
SaveRecord - save current edited record with user input
Delete a record
DeleteRecord - delete the current focus record
Sort records
SortRecord - sort record list on given column and rerender the form
Page Navigation
GotoPage - render the given page
User input validation
According the topic at http://www.boringguys.com/?p=30, there are 3 different types of
data validation checks one can do:
Syntactic validation - check data syntax
Semantic validation - check one piece of data makes sense in regards to other
incoming data
Domain or model validation - check data against another source of acceptable values
Syntactic and semantic validation can be implemented on client side and service side.
Domain validation involves query data source, it is usually done in service code that
connects to database.
Client side form validation
Openbiz does input validation using excellent yav library (http://yav.sourceforge.com). To
configure a validation rules for an Openbiz Element, developers can set event handler of
93
Openbiz 2.4 Manual
the Element. The event handler will invoke yav validation rules and display validation error
message at proper location.
In baseapp/modules/easy/f_EventEdit.php, you can find
<Element Name="fld_loc" Class="InputText" FieldName="Location" Label="Location"
Width="400">
<EventHandler Name="fld_loc_onblur" Event="onblur"
Function="js:validate(this,'required,minlength|3')"/>
</Element>
This is to validate location input must not be empty and must have more than 2 characters.
The error message will be displayed at the "span" element with id = "errorsDiv_fld_loc".
The error message is displayed as:
Server side input validation
Openbiz supports validation on BizDataObj and Form. In BizField, Required and Validator
attributes are used for such purpose.
Developers can use customer class to override DataObj::ValidateInput() method or
Field::Validate() method achieve their own validation rules.
BizForm has an empty ValidateForm method which may be overridden by customer
classes to implment special validation logic.
Custom validation logic can be implemented in BizDataObj and Form.
Developer can override DataObj's ValidateInput() method or Field's Validate()
method achieve their own validation rules.
Developer can override Form's ValidateForm() method or Element's Validate()
method achieve their own validation rules..
94
Openbiz 2.4 Manual
Validation rules can be set in metadata files. This will invoke corresponding method call in
validation service.
<BizField Name="Email" Column="EMAIL" Validator="{@validate:email('[Email]')}"/>
<BizField Name="Phone" Column="PHONE"
Validator="{@validate:phone('[Phone]')}"/>
Openbiz uses validation service containing several standard validations along with the
ability to extend the service for your own purposes. The validation service is accessed
via the "Validator" attribute of a BizField or Element metadata. Call the validate service in
a manner similar to other services...
Sample validation of DataObject can be found at baseapp/modules/easy/d_Event.xml
<BizField Name="Name" Column="NAME" OnAudit="Y" Required="Y"/>
Sample validation of Form can be found at baseapp/modules/easy/f_AttendeeEdit.xml
<Element Name="fld_email" Class="InputText" FieldName="Email" Label="Email"
Width="200" Validator="{@validate:email('[Email]')}"/>
Error message display
Error messages are usually displayed in the following ways:
displayed on dedicated error message box
inline error message near individual element
In the form template, 2 elements are needed to display error messages. (Sample at
baseapp/modules/easy/templates/details.tpl)
<div id='errorsDiv' class='innerError'> on top of the form
and <span id="errorsDiv_elementName"></span> at the right hand of each element.
95
Openbiz 2.4 Manual
Extend OpenBiz classes
OpenBiz provides many functionality to build complicated web applications. But different
application has different requirement, so you may extend OpenBiz packages to implement
custom logic.
Extend server side classes
Because OpenBiz packages are based on object-oriented design, you can easily build up
your own object by extending these packages and inherit all useful functions provided by
them.
Extended classes are automatically loaded on demand. Extended class must be included
in a file with format as ClassName.php.
Use can specify class name for BizDataObj, BizField, EasyView, EasyForm, Element and
PluginService by filling the "Class" attribute of in metadata file
Example: Extend BizDataObj and EasyForm
/**
* class BOUser is the BizDataObj class to implement USER logic object
*/
class BOUser extends BizDataObj
96
Openbiz 2.4 Manual
{
function my_special_function() {...} // new function
function UpdateRecord() {...} // override existing function
}
/**
* class FMUser is the EasyForm class to implement USER UI object
*/
class FMUser extends EasyForm
{
function my_special_function() {...} // new function
function ValidateForm() {...} // override ValidateForm fucntion
}
Extend client side classes
EasyForm is the main server side presentation class, it has its counterpart class on client
browser side. In the EasyForm metadata, users can specify client side class in jsClass
attribute. For example.
<EasyForm Name="f_Event" ... Class="EasyForm" jsClass="jbForm"...>
Openbiz provides two client side classes AjaxForm and jbForm that is a subclass of
AjaxForm.
AjaxForm methods:
CallFunction(method, params_array) - convert function to request and send it to
server. A server side BizForm method is invoked by this method if there's no specific
method implemented in the client class. For example, a BizForm, whose
97
Openbiz 2.4 Manual
jsClass=jbForm, has a method named "SelectRecord". Openbiz will check if
"SelectRecord" method is defined in jbForm class. If yes, it calls jbForm's
SelectRecord(params_array), otherwise it calls CallFunction(method, params_array).
CallbackFunction(retContent) - Ajax callback function. It passes the returned content
to Show().
CollectFormData() - collect form data into a message in Ajax call
Show(retContent) - called by callback function to show Ajax returned content in the
form
jbForm methods:
CollectFormData() - overriding AjaxForm CollectFromData(), add additional "selected
row" in the form data
SelectRecord(params_array) - special logic on select record call
SortRecord(params_array) - special logic on sort record call
DeleteRecord(params_array) - special logic on delete record call
To implement UI logic on client side, developers need to create their own client side class
like jbForm and give the class name to jsClass attribute of BizForm element. If you need
special logic in some methods, add these methods in the client class, which can be
subclass of either AjaxForm or jbForm. These methods can be pure client code or it can
this.CallFunction(...) to send the request to server.
An example:
Form metadata file is like:
<EasyForm ... Class="MyForm" jsClass="MyjbForm"...>
...
<Element Name="mybutton" ...>
<EventHandler Name="onclick" Event="onclick"
Function="server_MyButtonClick"/>
<EventHandler Name="onblur" Event="onblur" Function="js_MyButtonBlur"/>
...
98
Openbiz 2.4 Manual
</EasyForm>
In server side MyForm class, server_MyButtonClick() needs to be defined.
In client side MyjbForm class, js_MyButtonBlur() needs to be defined. Of course, if
server_MyButtonClick() is defined in client class, server_MyButtonClick() needs to call
this.CallFunction("server_MyButtonClick", params_array) at the end of the method to
send the request to server MyForm server_MyButtonClick() method. The client side code
will be like:
function MyjbForm(name) {}
MyjbForm.inheritsFrom(jbForm); //set inheritance
MyjbForm.prototype.js_MyButtonBlur = function (params_array)
{
// put client logic here
...
}
MyjbForm.prototype.server_MyButtonClick= function (params_array)
{
// put client logic here
...
// send request to server side at the end
this.CallFunction("server_MyButtonClick", params_array);
}
Implement Plug-in Service
Openbiz customer can write their special logic by implementing Plug-in Service. Plugin
services are also metadata-driven objects. Service code is under bin/service and
99
Openbiz 2.4 Manual
metadata is under /metadata/service. The plugin service metadata only gives the service
name and implementing class. Any xml elements can be child of the root PluginService
element. This is because different services may have different metadata configuration.
Please refer to the Appendix to see the DTD of plugin service metadata xml file.
Openbiz core services
Openbiz core library includes services under openbiz/bin/service/ and their metadata files
under openbiz/metadata/service/.
excelService.php - excel serivce can output to CSV files from a form and import from
CSV file to a form.
authService.php - authentication service, please refer to next chapter for usage
accessService.php - view access control service, please refer to next chapter for
usage
profileService.php - user profile service, please refer to next chapter for usage
logService.php - log service that write log mesage to file or other storage
emailService.php - integrated with Zend_Mail to send emails through smtp mail
server.
doTriggerService - BizDataObj trigger service that can trigger other actions on
database operations
auditService - audit trail service to trace data change
genIdService - table primary key column (Id) generation service.
Configure a service
In the application, you can specify your own plugin service implementation with following
methods.
1. Change the service metadata content under your_app/metadata/service/, still use the
core service. For example, you can write different accessService.xml to control the
view access rule, but the implementing class is accessService.php in core library. The
accessService.xml is like
<PluginService Name="accessService" Package="service" Class="accessService">
application specific view access definition
100
Openbiz 2.4 Manual
</PluginService>
2. Specify the service implementing class. For example, different applications have
different profile service. The profileService.xml is like
<PluginService Name="profileService" Package="service"
Class="your_own_service_class">
</PluginService>
3. Combine the above 2 methods.
Write a service
Implement the class and method in the ClassName.php and store the file under
/bin/service/. Its metadata file should be under /metadata/service/. The input arguments of
the method are the caller's object name (a BizForm name) and the input data string (a
collection of form values from client browser). The method implements the user-specific
business logic and returns void. See the following code snippet.
class pdfService
{
function pdfService() {}
function renderView($viewName)
{
// get the view object and render the view to a html string
$viewobj = BizSystem::ObjectFactory()->GetObject($viewName);
$sHTML = $viewobj->Render();
// convert HTML to PDF
// ... customer code to do the convert
}
101
Openbiz 2.4 Manual
}
Call a service method
Call service in form. Define the caller function in BizForm metadata file <...
Function="CallService(ClassName,MethodName)"...> is to call a method
"MethodName" of the service "ClassName".
Call service with url. Use url like
bin/BizController.php?F=Invoke&P0=[servicename]&P1=[methodname]&P2=[param
eter1]...
An example is
bin/controller.php?F=Invoke&P0=[pdfService]&P1=[renderView]&P2=[demo.ReportVi
ew]
Call service in code.
global $g_BizSystem;
$svcobj = $g_BizSystem->GetService($class);
$svcobj->$method($this->m_Name);
Implement authentication and access control
User authentication
Openbiz uses authentication service (usrlib/authService.php) to authenticate username
and password
public function AuthenticateUser ($userid, $password) is called to authenticate user.
AuthenticateUser by default querys on "User Id" and "Password" fields defined in
metadata/shared/BOAuth.xml. If input user id and password is found in in BOAuth,
AuthenticateUser returns true. AuthenticateUser method is to be modified to fit
customer logic.
metadata/shared/SignupView.xml is the default login view. This view can be
102
Openbiz 2.4 Manual
configured for change the login look and feel.
Role-based view access control
View access control depended on the AccessControl attribute in view metadata file in
Openbiz implements role-based view access control in its new security architecture.
Openbiz uses profile service (usrlib/profileService.php) to get user profile that includes
"role". Then match this role to access service (usrlib/accessService.php) to determine the
users' accessibility to the view.
ProfileService GetProfile ($userid) method is called to get user profile array which is an
associated array with profile key and profile value pairs. Please note that customer must
replace the default GetProfile method in openbiz package, because the default GetProfile
method returns some randomly made array.
AccessService has a configuration file (accessService.xml) that defines the view access
permission. Please see an example below.
<?xml version="1.0" standalone="no"?>
<PluginService Name="accessService" Package="service" Class="accessService">
<access-constraint>
<view-collection>
<view name="shared.CalendarView">
<role name="admin"/>
<role name="member"/>
</view>
<view name="demo*"> <!-- can use regular expression in the view name -->
<role name="admin"/>
<role name="member"/>
</view>
103
Openbiz 2.4 Manual
</view-collection>
</access-constraint>
</PluginService>
The xml configuration file is easy to understand. Customer needs to put their own logic in
the accessService.xml.
Attribute-based data access control
Openbiz uses profile service (usrlib/profileService.php) to get user profile that includes
attributes. Then based on these attributes to determine browse/update/delete permission
of data record. The data access permissions are controlled in BizDataObj.
User can refer to attributes by @profile:attribute in BizDataObj metadata files. Profile
attributes are all from profileService. When user first login, profileService returns a profile
array that is saved in session. If an attribute is found in the profile array, the attribute value
is returned. If the profile array doesn't contain such attribute, profileService method
GetAttribute ($userid, $attr) is called to return the attribute value. Customer must
implement GetAttribute method with their own logic.
- Data browse permission. A typical access control requirement is to limit the
accessibility of table record to different users. This feature can be achieved by configuring
AccessRule in BizDataObj metadata file. We do the configuration with the following two
scenario.
Event can be only accessed by the owner (personal access control)
Configuration
<BizDataObj Name="Event" ... AccessRule="[OwnerId]='@profile:ORGID'" ...>
<BizField Name="OwnerId" Column="OWNER_ID"/>
104
Openbiz 2.4 Manual
Event can be accessed by all invited attendees (if the login user is one of the
attendees, he can access the event)
Configuration
<BizDataObj Name="Event" ... AccessRule="[AttendeeId]='@profile:USERID'" ...>
<BizField Name="AttendeeId" Column="ATTD_ID" Join="Attendee"/>
<Join Name="Attendee" Table="evts_attds" Column="EVT_ID" ColumnRef="SYSID"
JoinType="LEFT JOIN"/>
- Data update permission. UpdateCondition is to control the record update permission.
UpdateCondition expects true or false.
A sample is UpdateCondition = "[OrgId]=={@profile:ORGID}". {} is the evaluated as simple
expression.
- Data delete permission. DeleteCondition is to control the record delete permission.
DeleteCondition expects true or false.
A sample is DeleteCondition = "'admin'=={@profile:ROLEID}"
Implement dataobject events trigger
Upon dataobjects update/delete operations, openbiz allows triggering different alerts and
action requests based on boolean results from search criteria for specific object. Briefly it
is called DO Trigger which executes in a response to a change in the values stored in the
database. DO trigger has two parts - trigger events and trigger actions. These information
are defined in DOTrigger plugin service metadata files. At runtime when user
update/delete a BizDataObj record, openbiz searches for this dataobj's trigger by looking
for its trigger metadata file with name DataObjName_trigger.xml under the same directory.
For example, demo/BOEvent's dataobj trigger metadata file is demo/BOEvent_trigger.xml.
Define a dataobject trigger metadata
A syntax of the DO trigger metadata is listed below:
105
Openbiz 2.4 Manual
<PluginService Name="DataObjName_Trigger" Description="" Package="demo"
Class="service.doTriggerService" DataObjectName="DataObjName">
<DOTrigger TriggerType="UPDATE|DELETE"> *
<TriggerCondition Expression="" ExtraSearchRule="" />
<TriggerActions>
<TriggerAction Action="Method_Name" Immediate="Y|N" DelayMinutes=""
RepeatMinutes="">
<ActionArgument Name="" Value="" /> *
</TriggerAction>
</TriggerActions>
</DOTrigger>
</PluginService>
Trigger conditions
trigger type
Update or Delete record
Expression
any expression supported by openbiz
Sample {[Expense]}>100. Check if current record's Expense field > 100
extra search rule
search rule added on the current dataobj search rules
Sample {[AlertFlag]}='Y'. Check if there's at least one record whose AlertFlag is 'Y'
106
Openbiz 2.4 Manual
Trigger action methods
ExecuteSQL
ExecuteSQL method executes SQL statement
Parameters
Name="DBName" Value="Default"
Name="SQL" Value="select * from regist where EVENT_ID='{[Id]}'"
ExecuteShell
ExecuteShell method executes external application
Parameters
Name="Script" Value="dir"
Name="Inputs" Value=" > d:\temp\out.txt"
SendEmail
SenEmail method sends outbound emails. It calls emailService's sendEmail method
Parameters
Name="EmailService" Value="service.emailService"
Name="Account" Value="MyPhpopenbiz"
Name="TOs" Value="[email protected]; [email protected]"
Name="CCs" Value=""
Name="BCCs" Value=""
Name="Subject" Value="alert message"
Name="Body" Value="This is an alert message. \nPlease notice that the record with
{[Id]} was updated."
Name="Attachments" Value=""
107
Openbiz 2.4 Manual
AuditTrail
Trace record field change
It calls auditService Audit method
Parameters
Name="AuditService" Value="service.auditService"
Name="DataObjectName" Value="{@:Name}"
any method in doTriggerService
The method of doTriggerService is called
Parameters Parameters needed to the method
Use message and enable multi-language
Messages in Openbiz application
Openbiz developers will encounter messages at 2 different situation.
1. Use message in metadata file
2. Use message in source code
Messages widely appear in metadata file (especially in Form xml files). For example,
Element has "Label" attribute
Form has "Title" attribute
View has "Description" attribute
These messages will be eventually rendered on browser.
Messages can be used in source code. For example,
Error message
108
Openbiz 2.4 Manual
Define messages
For messages in metadata, no special definition is needed. You just need to use English
words or other default language in the string.
Openbiz defines a list of system messages in openbiz/messages/system.msg. The
definition uses php define function.
define('DATA_FIELD_REQUIRED', Field %s is required. Please enter a valid value.");
You can override the openbiz system messages by define a message in a message file and specify the message file in metadata MessageFile attribute. For example,
In easy/d_event.xml, we have
<BizDataObj Name="" ... MessageFile="event.msg">
In /messages/event.msg, we have
DATA_FIELD_REQUIRED = "@@@ Field %s is required. Please enter a valid value."
will override system DATA_FIELD_REQUIRED
To use message in source code, you need to set "MessageFile" attribute in Form or
Dataobj metadata file. The sample code of using message:
$errMsg = $this->GetMessage("DATA_FIELD_REQUIRED",array($fld));
$errMsg =
$this->GetMessage("DATA_FIELD_INVALID_INPUT",array($fld,$value,$bizFld->m_Valid
ator));
Support multi languages
If you want to support 2 languages in your application, what you should do is
109
Openbiz 2.4 Manual
No change on metadata files. In Smarty template files, include translatable
message into {t}{/t} pair. Example: {t}Name{/t}. Note, you need to copy
openbiz/bin/block.t.php to the plugin directory of your smarty installation.
Run 2mo.php (under yourapp/bin/languages/) to extract UI messages into language files. For example, English language file is yourapp/languages/en/LC_MESSAGES/lang.en.po and Spanish language file is yourapp/languages/es/LC_MESSAGES/lang.es.po
Edit *.po file with POEdit (downloadable from http://www.poedit.net). It auto-generates *.mo files that are compiled language files
To switch language on the same application, you can add lang parameter in the URL. For example, home.php?lang=es.
At run time, Zend_Translate is used to read in correct language messages.
Use Cache
From Openbiz 2.4 beta, cache is supported on
View. View can be cached according to the given URL
Form. Form can be cached by its name
DataObj. DataObj query (only "Select" query) can be cached per unique SQL
statement.
To enable cache on openbiz objects, you need to add "CacheLifeTime" attribute for the
metadata element. CachLifeTime has unit as "second".
<View Name="Misc" CacheLifeTime="60"> tells that the content of view "Misc" is cached
by the system for 60 seconds.
Openbiz counts on cache service to cache content. Zend_Cache is used by cache service.
Thanks for Zend_Cache, the cache service can support all cache backend including:
File cache
SqlLite cache
MemCache
110
Openbiz 2.4 Manual
APC
...
Cache service comes with a configuration file under
openbiz/metadata/service/cacheService.xml. In the configuration file, user can specify the
cache backend to use.
For file cache, openbiz saves the cache data under baseapp/files/cache/data/...
More security
More security is added in openbiz 2.4 beta. Security service is used to check the potential
attack from outside world. Security service allows user to set
Url filter. It will filter out bad urls
Domain filter. It can block certain domain address
IP filter. It can block given IPs
Agent filter. It can block requests with certain "User-agent" headers
Post filter. It can disable "POST" action for certain urls.
Get filter. It can disable "GET" action for certain urls.
Security service can be configured with its own configuration file at
openbiz/metadata/service/securityService.xml
Each filter has rules. Each rule can have format as
<Rule Name="ip_filter_1" Action="Deny" Match="210.72.214.*"
EffectiveTime="0000-2400" />\
Action can have "Allow" or "Deny".
Match is a regexp string matching
EffectiveTime has form at as starttime-endtime. That tells the effective time
interval.
Control the look and feel with css files
The openbiz look and feel is controlled by stylesheet css files. The main css file is
111
Openbiz 2.4 Manual
/css/openbiz.css
Control BizForm table style
In case of using Format="block" in the BizForm's displayMode, users can modify the
following section in css/openbiz.css file.
/* -------- table style -------- */
.tbl {...}
.tbl .head {...}
.tbl .rowodd {...}
.tbl .roweven {...}
.tbl .rowsel {...}
.tbl .cell {...}
Control tabs style
In order to give user specific tab styles, users can modify the following section in
css/openbiz.css file.
/* -------- tabs style -------- */
.tabmenu {...}
.tabmenu li {...}
.tabmenu a, a.active {...}
.tabmenu a.active {...}
.tabmenu a:hover {...}
.tabmenu a:visited {...}
.tabmenu a.active:hover {...}
112
Openbiz 2.4 Manual
Control menu style
In order to give user specific tab styles, users can modify the following section in
css/menu.css file.
Control tree style
In order to give user specific tree styles, users can modify the following section in
css/openbiz.css file.
/* ----- tree style ----- */
UL.expanded {...}
UL.collapsed {...}
LI.tree {...}
Control rich text editor (RTE) style
In order to give user specific RTE styles, users can modify the following section in
pages/rte/rte.css file.
Date and Datetime picker
The DHTML calendar is well documented at
http://www.dynarch.com/demos/jscalendar/doc/html/reference.html. The javascript file is
under demoapp/js/jscalendar.
Debug strategies
Logging
BizSystem::log() method can be called to log 4 priority levels LOG_EMERG, LOG_ERR,
LOG_WARNING and LOG_DEBUG. Also a subject can be specified to give log messages
different categories. The error is logged under /log/log_error.html, open it and you may
113
Openbiz 2.4 Manual
find out what's wrong.
Debugging
Developers can turn on other 2 debug flags.
Open the sysheader.inc under /bin, turn on debug log by changing define("DEBUG",
1); Then you'll see some debug information in /log/log_debug.html. This debug file
records mainly the database calls and other operations
Turn on RPC debug flag, each RPC response is printed in a separate window. Set
var RPC_DEBUG = true; in clientUtil.js.
114
Openbiz 2.4 Manual
Openbiz Design Tool Guide
Openbiz Tool Overview
Manage Openbiz Application
Metadata Wizard
Metadata Editor
Openbiz Tool Overview
Openbiz Design Tool is to help writing Openbiz metadata files. With the new web design
tool, users can
Manage Openbiz application source in your browser
Generate Openbiz metadata files with Metadata Wizard
Edit Openbiz metadata file with Metadata Editor
Manage user working directory and permissions. This function is available for
administrator.
Openbiz Tool is released with GPL license.
Openbiz Tool is built on top of Extplorer- a great open source file management application.
The version of Extplorer used by Openbiz Tool is 2.0.1.
Installation
Download the Openbiz Tool from Openbiz sourcegorge site. Unzip the file in a folder that
is the same level of other Openbiz applications. For example, you may have directories
like
- baseapp. The openbiz baseapp.
- obtool. The openbiz tool
- openbiz. The openbiz library
115
Openbiz 2.4 Manual
After unzip the files, load http://host/tool_path/ in your browser. You will be asked to login.
Enter admin/admin as username and password to login as admin. On Unix/Linux box, you
need to change the permission of the application directory. Please refer to Extplorer site
for details.
Set up the databases
After install the tool source, please edit the obtool/metadata/Config.xml to list all your
working database info. These database list will be used in Metadata Wizard and Editor.
Manage Openbiz application
With the help of Extplorer, users can manage the file system on browser. The Extplorer
has similar functionality and user interface as client file explorer.
To manage Openbiz application, it is recommended to
1. Add the application developer as a user.
2. Set the user's working directory to your application root directory.
3. Give the right permissions to the user.
When login as "admin", you can find a "Admin" button on the main toolbar. Click the button
to manage users.
Screen: Openbiz tool UI.
116
Openbiz 2.4 Manual
Metadata Wizard
Developers can use Metadata Wizard to quickly create Openbiz 2.4 metadata files. This
wizard will ask user to
1. Select a database instances which are declared in /metadata/Config.xml
2. Select a table from the database
3. Select columns of the table
4. Give a component name and generate metadata files
5. After the metadata files are generated, a link is presented to user to test the view
The following metadata files will be generated in the user defined path.
Data object file
View object files
Form object files - List form, Detail form, Edit form and New form
Step 1 screen: Metadata wizard can be triggered by clicking the "Metadata Wizard" button.
117
Openbiz 2.4 Manual
Step 2 screen:
118
Openbiz 2.4 Manual
Step 3 screen:
119
Openbiz 2.4 Manual
Step 4 & 5 screen:
Metadata Editor
Metadata editor is to help developers to smooth their metadata editing. It is an Openbiz
application and utilizes the jsTree javascript library.
On the Metadata Editor, users can
Navigate the metadata element tree
Create element
Delete element
Move up and down element
Edit the element attributes
Normal single-line and multi-line edit box for free text editing
Normal dropdown list for static value selection
Special dropdown lists
Dropdown list for databse selection
120
Openbiz 2.4 Manual
Dropdown list for table selection. This list depends on the database
selection
Dropdown list for column selection. This list depends on the database
and table selection
Dropdown list for join selection.
Dropdown list for BizField selection of a form element. This list depends
on the BizDataObj seleciton in the form.
Dropdown list for data and form object selection
Screen of Metadata Editor.
Under certain cases, you may want to edit the metadata source code directly. You can
always use normal "edit" button to edit the metadata xml source.
121
Openbiz 2.4 Manual
