BizView and BizForm Configuration

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

BizView Configuration

BizView metadata DTD file can be found in Appendix B

BizView is the physical web page that contains multiple BizForms and other HTML elements. Its layout is based on the smarty template enginee. A BizView defines the layout of BizForms as well as relationship between BizForms. Below is a sample BizView, notice how you can control which smarty template is used for a BizView via the Template attribute. Developers can also override the default BizView by specifiying their own derived class by changing the Class attribute. All BizForms, Tabs and Menu elements are specified in the ControlList. Finally, underlying relationships between BizForms can be configured here via the SubCtrls attribute.

Use SubCtrls to map relationship amont BizForms

Many times a page displays two BizForms that are related, usually in a Parent->Child relationship. OB provides a way where clicking on a record in the parent BizForm filters the Child BizForm to only show related records. These relationships are configured in a parent BizForms BizDataObj and can be enabled on the BizView via SubCtrls. In the example below, shared.FMAttachement will only shows records related to its parent form, FMAttendee.

...
<Control Name="fm_attd" Form="FMAttendee" SubCtrls="shared.FMAttachment"/>
<Control Name="fm_attach" Form="shared.FMAttachment" SubCtrls=""/>
...

The underlying PARENT BizDataObjs spells out how these two BizForms are connnected. In the example FieldRef points to the Parent's Primary Key while Column points to the Child's related Foreign Key. It is important to use the child's BizDataObj in the Name Attribute and also specify the type of relationship being used.

Multiple SubCtrls can be specifed using the following syntax

SubCtrls="childform1_name;childform2_name;...".

Let's take a look at expressing a more complex example where the underlying tables are expressed as a Many to Many relationship.

BOEvent and BOAttendee have just such a relationship where the event form and attendee form will take the M-M as their relationship. In the case of a M-M relationship, a third object is incorporated to connect the two indirectly related tables.

The chain of related fields is:

FieldRef="ID" -> XColumn1="EVENT_ID" (Same Table) -> XColumn2="ATTENDEE_ID" -> Column="SYSID"

- Sample Event View:

EventView (Event-Attendee as M-M)

FMEvent as BizForm
|-- BOEvent as BizDataObj

FMAttendeeChild as BizForm
|-- BOAttendee as BizDataObj

BizForm Configuration

BizForm metadata DTD file can be found in Appendix B

Basic Layout: Data, Toolbar and Navigation bar

Openbiz BizForm is composed with three parts - 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 standard or custom commands on the BizForm.
Navigation bar is a set of controls that controls data navigation or paging.

Here's a sample layout of a BizForm:

Toolbar Navigation bar

Data part Row 1

Data part Row 2

Present BizDataObj by BizForm

BizForm represents data configured in a BizDataObj right down to the column level. But should a column be rendered as a ListBox or a Radio button. Better still, should the data be hidding in one display mode but not in another? To answer these questions a BizForm contains BizCtrls to map to BizFields in a BizDataObj. These BizCtrols contain information on how OB is to render the control. Here's an example.

Present data with various HTML elements

HTMLControl or BizCtrl can present its data with various HTML elements by specifying element type and attributes. HTML elements are displayed in edit/query modes

Attributes of BizCtrl element in BizForm
Type	Width	Height	HTMLAttr*	Style**	SeclectFrom	Caption	Image	Comments
Text	x	x	x Limit the input length	x				Single line text input. Default type
Textarea	x	x	x	x				Multi-line Text input
RichText	x	x	x	x				Rich text editor edit HTML source
ListBox	x	x	x Show ListBox or ComboBox	x	x Set list of values			ListBox or ComboBox
CheckBox	x	x	x	x	x Set True value			CheckBox
Radio	x Arrange radio list	x	x	x	x Set list of values			Radio buttons
HTMLButton	x	x	x	x		x		Standard HTML Button
SubmitButton	x	x	x	x		x		Standard HTML Submit Button
ResetButton	x	x	x	x		x		Standard HTML Reset Button
Password	x	x	x	x				HTML password
Button	x	x	x	x		x	x	OpenBiz image button
Date	x	x	x	x				Textbox with date picker icon
Datetime	x	x	x	x				Textbox with datetime picker icon
HTMLBlock	x	x		x		x Special Characters		Caption is treated as HTML block
File	x	x	x	x				File control to upload file
AutoSuggest	x	x	x Limit the input length	x				Hybrid Text/Listbox

* HTMLAttr field can contain any valid additional HTML attribute applied on the HTML element type

** Style field can contain any valid style properties (css)

Limit the input length:

HTMLAttr="maxlength=N" to limit the maximum number of characters that the user can enter in a text control.

Show ListBox or ComboBox:

By default show comboBox. If HTMLAttr="size=N", show N-row listbox.

Set list of values:

SelectFrom="XmlFile(Key)" means this field control is a listbox or radio buttons whose data is from the "Key" elements in XmlFile.

Set True value:

SelectFrom="Value" means this checkbox returns the Value when user check the checkbox.

Arrange radio list:

By default the radion buttons are arranged horiztionally. If Width="1", you can force them arranged vertically.

Special characters:

"<" and ">" used in HTML block have to be replaced by "<" and ">". Please refer to http://www.w3schools.com/html/html_entities.asp for more details.

Rich text editor

Openbiz rich text editor primarily uses the code (LGPL license) from Kevin Rothhttp://www.kevinroth.com/rte/demo.htm. Thanks Kevin for his excellent work. It supports IE5.5+ and Firfox 1.x. Below is a screenshot.

Date/Datetime picker

Openbiz 2.1 uses the open source DHTML calendar 1.0 (LGPL license) provided by dynarch.com. The DHTML calendar is well documented at http://www.dynarch.com/demos/jscalendar/doc/html/reference.html. Many thanks to Nik Chankov for his help on integrating openbiz with DHTML calendar. Openbiz by default uses system style for the calenar.

Auto suggestion text input

Thanks for the effort and Jim and Rocky, Auto Suggestion text input is available in release 2.2.2 beta2. To configure an auto suggestion input, simply set the "Type" of a HTMLControl or FieldCtrl as "AutoSuggest", then set the suggestion list in SelectFrom attribute. For example, to add a control that suggests the first name of attendees,

The demo can be found at the "UI Components" tab in the demoapp. Its metadata is at demoapp/metadata/demo/FMFieldDepTest.xml.

Additional attributes of BizCtrl

FieldName - the BizField name of BizForm's BizDataObj
DisplayName - the label of the control, it is the column head in table format
Link - the hyperlink of the control under READ display mode. An example: <BizCtrl Name="LName" FieldName="LastName" Link="a valid relative or absolute url"/>. Users will see on the UI the last name (i.e. Wilson) hyperlink (the link is the url).
DrilldownLink - refer to "Configure drilldown link to another view"
Sortable - indicates if the field is sortable column in table format
Order - the sequence of BizCtrls
ValuePicker - refer to "Configure a BizCtrl to show popup"

Event handling in BizForms

As a html element can trigger events like onclick and onblur, each html Control or BizCtrl may have event handling functions associating to events. Event handling is defined in following syntax.

More than event handlers can be associated with a control. Function and FunctionType attributes are moved from a Control Element to an EventHandler element under a Control 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. Usually developers create their own methods in a customer class derived from BizForm. When the request hits BizController, it is routed to the BizForm method. If the method doesn't exist, an error is returned. Consider the following example:

<EventHandler ... Function="objectName.methodName(arg1, arg2...)" .../>.

If the objectName is empty, OB looks for the method in the current BizForm. For example, <EventHandler ... Function="SaveRecord()" .../>. Users can only invoke methods of objects who have metadata files. These objects include BizForm, BizDataObj, BizView and PluginService. BizForm methods and PluginService methods are callable from the client side in this way.

- FunctionType can be either RPC or Page or Form or Popup.

FunctionType	Explanation	Example
RPC	the function is invoked on server side by HTTPRequest (AJAX). RPC is default value	New record button: <Control Name="btn_new" Function="NewRecord()" FunctionType="RPC"/>
Page	the function is invoked on server side with page reload, form data is not passed to server	Export button to bring up a file save dialog in the page <Control Name="btn_export" Function="CallService(ioService,exportXML)" FunctionType="Page"/>
Form	the function is invoked on server side by form submission	Save button when there's file to upload in the form: <Control Name="btn_save" Function="SaveRecord()" FunctionType="Form"/>
Popup	the function is invoked on server side targeting to a new popup window	Excel output button to show excel format in a popup: <Control Name="btn_excel" Function="CallService(excelService,renderHTML)" FunctionType="Popup"/>

- ShortcutKey associates a shortcut key to the function. It is explained in "Keyboard navigation on BizForm".

- PostAction is the redirected page/view after an action is taken. It is explained in "Controlling page navigation".

Keyboard navigation on BizForm

BizForms can support user defined keyboard shortcuts. This is another example of porting the rich client experience to the browser. Shortcuts are defined in the BizForm and allow users to specify a wide variety of combinations that map to existing toolbar or navbar buttons such as Next Page, Last Page, Edit, New, Delete etc. A control's EventHandler stor the shortcut definition as shown in the example provided.

A BizForm 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
Up arrow key	Left
Down arrow key	Down
Insert key	Insert
Delete key	Delete

Developers can configure a 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. Please refer to http://www.mozilla.org/support/firefox/keyboard for shortcut keys for different browsers.

See shortcut key sample in demoapp/metadata/demo/FMEvent.xml. This BizForm supports following shortcut keys:

Shortcut key	Command to execute
Ctrl+Shift+Right	go to next page
Ctrl+Shift+Left	go to previous page
Ctrl+Shift+Down	go to next record
Ctrl+Shift+Up	go to previous record
Ctrl+Shift+N	create a new record
Ctrl+Shift+E	edit the selected record
Delete	delete the selected record
Ctrl+Shift+Q	switch to search record mode
Enter	run search, or save record
Escape	cancel search or cancel editing
Ctrl+Shift+C	copy the selected record
Ctrl+Shift+R	refresh form with default query

Form controls dependency

In a complex form, there are usually some controls depending on the values of other controls. When the parent control changes, child controls change accordingly. This is so called form controls dependency. With the help of OB's expression language, a controls relationships can specified in BizForm metadata files. With the help of event handlers, events on the parent control will cause changes to specified child controls on the fly.

A sample form is delivered under demoapp/metadata/demo/FMFieldDepTest.xml

The first combobox is the parent 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)

Configuration of record-selecting popup BizForm

Users may need to pick records from a different form in 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 BizDataObj, BizForm, BizView) 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 a html control to show popup

To configure a html control to show popup form, users can set "ShowPopup($popupFormName)" in the control Function attribute and set FunctionTarget="Popup". This configuration can be used in picking a child record (M-1 or M-M) in the child form.

<Control Name="btn_new" Caption="Add" Type="Button" Function="ShowPopup(demo.FMAttendeePopup)" FunctionTarget="Popup"/>

On the popup form, add a button to call AddToParent() to add the currently selected record to the parent form (the form trigger the popup).

Configure a BizCtrl to show popup

To configure a BizCtrl to show a popup from a user ValuePicker attribute.

<BizCtrl Name="reg_attdln" FieldName="AttdLName" DisplayName="Last Name" ValuePicker="FMAttendeePopup"/>

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

Configure an automatic value picker for a BizCtrl

You can use a ValuePicker attribute to allow users to click the icon to show the picker popup window. Users may want to type in the value in the control and the system will automatically pick the right record according to the user input. Openbiz supports this feature by BizForm's AutoPickValue($ctrlname) method. To configure auto picker.

<BizCtrl Name="reg_attdln" FieldName="AttdLName" DisplayName="Last Name" ValuePicker="FMAttendeePopup">
<EventHandler Name="onchange" Event="onchange" Function="AutoPickValue(reg_attdln)" />
</BizCtrl>

According to the user input, the behavior is described in the following table:

Case User input Behavior

1 empty delete all related controls values

2 not empty query the DataObj of valuepicker BizForm with searchRule as [field] LIKE 'input_value%'. Based on the query results:

if single record returned, auto fill all related controls values with returned value

if no record returned, show value picker popup with no searchRule

if multiple records returned, show value picker popup with the searchRule

Configure drilldown link to another view

You can configure a BizCtrl to render with a hyperlink that will navigate to another view and display the record that clicked. In this way users can "drilldown" to a different view of a give record. For example an application may display high level records with drilldown links to a detail view.

In a BizForm, set a DillDownLink attribute of a BizCtrl. The syntax is

DrillDownLink="OtherView,OtherBizForm.OtherBizCtrl=MyBizCtrl".
OtherView - a view name the link takes to;
OtherBizForm - an independent BizForm, which is not a subforml of any other BizForm, in OtherView;
OtherBizCtrl - a BizCtrl of OtherBizForm
MyBizCtrl - a BizCtrl in current BizForm

Here's an example: <BizCtrl Name="reg_attdln" FieldName="AttdLName" DisplayName="Last Name" ValuePicker="FMAttendeePopup" DrillDownLink="AttendeeView,FMAttendee.attd_id=reg_attdid"/>.

Select field data from comboBox or ListBox

- Bind static list to comboBox

In your BizForm, you assign SelectFrom="Selection(Fee)" for a BizCtrl, which means this field control is a comboBox whose data is from the "Fee" elements in Selection.xml file. Please see example in demo FMRegist.xml where BizCtrl reg_fee is defined as a comboBox.
<Selection>
<Fee Value=""/>
<Fee Value="15"/>
<Fee Value="20"/>
</Selection>

Also, you can give both value and text. If only give value, openbiz uses the value as the display text.
<Selection>
   <ChartOption Value="AAA" Text="BarLine Chart"/>
   <ChartOption Value="BBB" Text="Pie Chart"/>
   <ChartOption Value="CCC" Text="GroupBar Chart"/>
</Selection>
You can make up your own xml file that has list of values for selection.

- Bind dynamic list (Table column) to comboBox

In your BizForm, you assign SelectFrom="BizDataObjName[BizFieldName]" for a BizCtrl, which means this field control is a comboBox whose data is from the table column mapping to the BizFieldName of the BizObjName. To avoid same values appear in the comboBox, you need to make sure the BizObj query returns an unique list.

Format SelectFrom="BizDataObjName[BizFieldName4Text:BizFieldName4Value]" is supported too. So users can show BizFieldName4Text field in comboBox and set BizFieldName4Value for value.

A SearchRule can be applied on the SelectFrom with syntax as SelectFrom="BizDataObjName[BizFieldName4Text:BizFieldName4Value], SearchRule_of_the_BizDataObj". For example, <BizCtrl Name="" ... SelectFrom="BOEvent[Name], [Name] LIKE '%Soc%'"/>.

Controlling page navigation

Openbiz has an unique concept of display mode. BizForm can have more than one display modes. Basically each display mode is a rendering mode of the BizForm. A Bizform presents a BizDataObj data to UI, the same data set can be rendered in different modes which is called "display modes".

- Display modes in a BizForm

Display modes are specified in the <DisplayModes> section of a BizForm metadata file. You can associate a smarty template with each mode. For details please refer to build view and form web templates.

Usually a BizForm can have READ, NEW, EDIT, QUERY display modes. But developers can specify their own modes for the BizForm. An example is under /demoapp/metadata/shared/FMCalendar.xml. It has display modes such as "LIST", "DAY", "WEEK", "MONTH".

Switching between display modes in a BizForm is done in code by calling BizForm method SetDisplayMode($mode). Code may be applied to each display mode to implement special logic.

Each control or BizCtrl has a DisplayMode attribute specifying which modes will show that BizCtr. By default leaving this attribute empty means the BizCtrl will be shown in all displaymodes. You can set one or more modes using DisplayMode = "MODE1|MODE2|...". For example,
<BizCtrl Name="LastName" ... DisplayMode="EDIT|NEW"/>
means that LastName will only show on EDIT and NEW modes.

- Page redirection after an action is finished

It's very common that users click on a button to trigger an action on server side and after the action is finished the page is redirected to another page. Page redirection can be specified as a post action in BizForm metadata file. The syntax is

<EventHandler Name="..." Function="..." PostAction="url|view"/> PostAction can accept url:url_string or view:view_name.

An example is the login form demoapp/metadata/shared/FMAuth.xml

- Error page and error message

If an action errors out, OB should return an error page or error popup to the users browser.

TODO FILL THIS IN

Import and export from BizForm

Data import and export support is and important feature for off-line users. Off-line users usually run the application (web application also can be run in local box) locally on their laptops and take the work back to synchronize with server database. Openbiz provides import and export support in the following ways:

Data export - implemented in exportXML method of ioService. The exported xml file has format as

Data import - implemented in importXML method of ioService. The xml file to import has the same format as described above.

Example import and export buttons are configured in the FMAttendee form. Pressing the export button invokes ioService's exportXML method directly, while the ixport button brings up a popup window to ask for the file to be imported. Please refer to the demoapp/metadata/demo/FMAttendee.xml for details.

It would be possible to add more export/import methods in ioService to support other file types.

Upload file from BizForm

A File upload feature is supported in OB's shared package. Check out the example metadata file in the demoapp at demoapp/metadata/shared/FMAttachment.xml and in the class file is at demoapp/bin/shared/FMAttachment.php.

To upload a file, developers needs to configure a BizCtrl with type as "File". It maps to a BizField with type as "Blob".

To download the file, users needs to configure a BizCtrl with Function as Download($record_id). Download method is implemented in FMAttachment class.

Please refer to the FMAttachement class and metadata for details.

Printer-friendly version
Login to post comments

OpenBiz & Cubi

DHTML Navigation