Configuration of BizDataObj

Submitted by jim on Mon, 02/25/2008 - 17:44.

The DTD file of the BizDataObj xml is listed in Appendix A.1

Map BizDataObj to Tables

Openbiz maps database tables to objects with BizDataObj. This section introduces the concept of mapping one or more tables with BizDataObj, the next section has full details describing how OB tackles Object Relation Mapping. At its most basic, a BizDataObj contains parts such as table name and mapping between BizDataObj fields and table fields of SQL Functions.

Specify the base table:
<BizDataObj Name="BizDataObjName" Table="TableName" ...>
Map a Column to a BizField:
<BizField Name="FieldName" Column="ColumnName"....>
One of BizFields must have name as "Id". This is required. This Id field usually maps to the primary key column of a table.
Map SQL Function to BizField:
Users can assign a BizField a SQL function provided by the database engine. The syntax is <BizField Name="FieldName" Column="" SQLExpr="FUNC([FieldName1]...[FieldName2]...)">. Make sure that the Column attribute is empty or the SQL function will not work. For example: <BizField Name="FullName" Column="" SQLExpr="CONCAT([FirstName],' ',[LastName])"...>
Note the example SQLExpr contains query related attributes like [FirstName] and [LastName] A [FieldName] is not evaluated to field value. [FieldName] is the syntax of query lanaguage and will instead reference the Column attribute of that BizField.
Specify a default value:
<BizField Name="FieldName" Column="ColumnName" DefaultValue="default_value">. Use DefaultValue attribute to give default values to the BizField when a dataobject creates a new record.

Query Language in BizDataObj

Openbiz users won't worry about composing complicated SQL statements since BizDataObjs support a 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, OB converts [FieldName] to the column name and generates a SQL statement. OB also supports including table relationships in generated query statements.

Specify the default query in SearchRule
<BizObj Name="BOCalendar" Description="Calendar BizObj" Package="shared" Class="MyClass" Table="calevts" SearchRule="[Start]>'1999-10-20'" ...>
Specify the default sort in SortRule
<BizObj Name="BOCalendar" Description="Calendar BizObj" Package="shared" Class="MyClass" Table="calevts" SortRule="[Start] ASC" ...>
Specify additional SQL statement in OtherSQLRule
<BizObj Name="BOCalendar" Description="Calendar BizObj" Package="shared" Class="MyClass" Table="calevts" OtherSQLRule = "GROUP BY [EvtId] HAVING [Fee]>10" ...>

Data type and format of BizFields

BizFields support following data types and formats in their Type and Format attributes.

Type	Format	Syntax	Format Example
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	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		*123 4567890 is treated as international number
Blob/Clob	none	<BizField ... Type="Blob" ...> <BizField ... Type="Clob" ...>

Data validations

Validation Type	Example
Required - indicates the field can not be empty	<BizField Name="Name" Required="Y" Column="NAME"/>
Validator - simple expression language	<BizField Name="Fee" Type="Currency" Format="Currency" Validator="{[Fee]>=15}" Column="FEE">
Validation Service - Use pre-made validation rules or create your own	<BizField Name="Email" Column="EMAIL" Validator="{@validate:email('[Email]')}"/> <BizField Name="Phone" Column="PHONE" Validator="{@validate:phone('[Phone]')}"/>

The latest 2.2.2 RC 2 demo contains several working examples. Check out demoapp/metadata/demo/BOAttendee.xml

Object Relational (O/R) Mapping

o support 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, users only need to configure the BizFieldList part in the metadata.

Primary key (Id) generation

IdGeneration	how id (Primary Key column) is generated	Supported database types
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. 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

In Openbiz 2.1, BizDataObj supports composite key. 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="" Package="" Class="" ... IdGeneration="None">
<BizField Name="fpk1" Column="PK1"/>
<BizField Name="fpk2" Column="PK2"/>
<BizField Name="Id" Column="PK1,PK2" />
...

Map multiple tables to a BizdataObj

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

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.

Many to one relationship between BizDataObjs

Many to one relationship between two tables means 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.

Object Attribute	Description
Name	The name of the referred BizDataObj
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
FieldRef	The field mapping to the foreign key column in base table

To get the referred dataobj (child dataobj), call GetRefObject($objame) method from parent dataobj. The referred dataobj instance will have the restriction according to the parent dataobj.

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.

Object Attribute	Description
Name	The name of the referred BizDataObj
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.

To get the referred dataobj (child dataobj), call GetRefObject($objame) method from parent dataobj. The referred dataobj instance will have the restriction according to the parent dataobj.

- One to one relationship between BizDataObjs

One to one relationship is a special case of many to one or one to many relationship.

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.

Object Attribute	Description
Name	The name of the referred BizDataObj
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.

To get the referred dataobj (child dataobj), call GetRefObject($objame) method from parent dataobj. The referred dataobj instance will have the restriction according to the parent dataobj.

BizView and BizForm Configuration

BizView metadata DTD file can be found in Appendix A.2.

BizForm metadata DTD file can be found in Appendix A.3.

BizView - the HTML page container

BizView is the physical web page that contains multiple BizForms and other HTML elements. Its layout is based on smarty template enginee. BizView defines the layout of BizForms as well as the relationship between BizForms.

- Map BizDataObj relationship of BizForms

If more than one BizForm is placed in a BizView and they are linked by specifying Parent-Child relationship in BizView, the BizForms will have the relationship of their underline BizDataObj.

SubCtrls attribute has syntax like SubCtrls="childform1_name;childform2_name;...". It tells children forms name of the parent form, which means children form data may change along the change of the parent form.

Because BOEvent and BOAttendee have many to many relationship, the event form and attendee form will take the M-M as their relationship. They present the data relationship on user interface.

- Sample Event View:

EventView (Event-Attendee as M-M)

FMEvent as BizForm
|-- BOEvent as BizDataObj

FMAttendeeChild as BizForm
|-- BOAttendee as BizDataObj

Basic BizForm layout: Data, Toolbar and Navigation bar

Openbiz BizForm is composed with three part - data part, toolbar and navigation bar.

Data part is the area showing the data. It can be shown as list, table, form, tree and so on.
Toolbar is a list of controls where users can invoke command on the BizForm.
Navigation bar is a set of controls that controls data navigation such as paging, scrolling.

Here's a sample layout of a BizForm:

Toolbar Navigation bar

Data part

Present BizDataObj by BizForm

BizForm represents data from BizDataObj. BizForm defines the mapping between BizCtrls in the BizForm and the BizFields in BizDataObj. Here's an example.

Printer-friendly version
Login to post comments

OpenBiz & Cubi

DHTML Navigation