You are on page 1of 122

Openbiz 2.

4 Manual
OpenBiz 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
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

1
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

2
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

3
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

4
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

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

6
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

7
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
support@phpopenbiz.org, 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.

8
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

9
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

10
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

11
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

12
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) -

13
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

14
Openbiz 2.4 Manual

Element
InputText Textarea Password File Button HTMLButton
Class
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
ResetButton SubmitButton RichText AutoSuggest InputDate
Class
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

15
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
InputDatetime InputPicker RowCheckbox Hidden Listbox
Class
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

16
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
Checkbox Radio LabelText ColumnText HTMLBlock
Class
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

17
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

18
Openbiz 2.4 Manual

2. Full function list page with child list page

3. Drilldown to Detail page

19
Openbiz 2.4 Manual

4. Edit page

5. New Page

20
Openbiz 2.4 Manual

6. New in-page picker popup

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

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

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

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

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

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

27
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 table-per-class, N table to 1 class
mapping Many to one, one to many, many to many, one to one
Query SQL like query language - support SQL functions and operators, support
facilities SQL aggregate functions, support group by, having and order by
Metadata XML metadata describe the mapping
facilities

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:

28
Openbiz 2.4 Manual

View access control flow:

Security
Openbiz implementation with plugin services
concept
User Openbiz uses authentication service (bin/service/authService.php) to
authentication authenticate username and password
Role-based view Openbiz uses profile service (bin/service/profileService.php) to get
access control 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 Openbiz uses profile service (bin/service/profileService.php) to get
data access user profile that includes attributes. Then based on these attributes

29
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)

30
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)

31
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

32
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

33
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:

34
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">

35
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

36
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

37
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:

38
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

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

40
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}"/>

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

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

43
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

44
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

45
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

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

47
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">

48
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)

49
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)

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

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

52
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"

53
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

54
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

55
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

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

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

58
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

59
Openbiz 2.4 Manual

Screen: Toggle form set by New button

60
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 Textarea
input
List box or Combo Listbox By default show comboBox. If
box 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

61
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 AutoSuggest
input
Input picking box InputPicker
Area with pure html HTMLBLock "<" and ">" used in HTML block have to be
code replaced by "&lt;" and "&gt;". Please refer to
http://www.w3schools.com/html/html_entities.asp
for more details.
Checkbox for row RowCheckbox
selection of a grid
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

62
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

63
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

64
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

65
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

66
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"/>

67
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&amp;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

68
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],

69
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

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

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

72
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 &gt;"


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"/>

73
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

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

75
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

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

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

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

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

80
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

81
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)

82
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

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

84
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

85
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

86
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

87
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:

88
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();

89
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( );

90
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

91
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

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

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

94
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

95
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

96
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"/>

...

97
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

98
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

99
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

100
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

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

102
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"/>

103
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:

104
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'

105
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="rockyswen@gmail.com; rockyswen@phpopenbiz.org"

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=""

106
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

107
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

108
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

109
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

110
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 {...}

111
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

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

113
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

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

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

116
Openbiz 2.4 Manual

Step 2 screen:

117
Openbiz 2.4 Manual

Step 3 screen:

118
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

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

120
Openbiz 2.4 Manual

121