O4W Mobile APIs (Functions/Subroutines/Programs,Web)
Created at 20 SEP 2013 01:28PM
O4W Mobile APIs
O4WSetMobile(bMobileFlag)
Used to inform O4W that this page will be generated for the mobile browser (if bMobileFlag parameter is “1”) or the desktop browser (if bMobileFlag parameter is “0”). Make this call before O4WForm() to properly configure O4W.
O4WGetMobile()
Returns “1” if the currently generating page has been set for the mobile browser, or “0” if the page is for the desktop browser. This routine will check for the presence of the “mobile flag”; if a prior page was set to mobile mode, O4WGetMobile() will return “1”. For example:
* are we being called while in a mobile environment bIsMobile = O4WGetMobile()
if bIsMobile = “1” then
* yes; generate this page in mobile mode as well O4WSetMobile(“1”)
End O4WForm()
O4WMobileOptions(roleName, themeCode)
O4WMobileOptions defines the “role” that an element (typically a section) plays in layout on the mobile browser page. Available options for roleName include “page”, “header”, “footer”,
“navbar”, “content”, “listview” (when applied to O4WListStart), and “fieldcontain”. O4W will use the role information to determine appropriate layout and styling of the element and its children on the mobild browser. Themecode may also be specified to designate which “theme swatch” colors should be applied to this element and its children; available codes are “a” through “z”.
Example:
O4WSectionStart(“ourPage”, O4WMobileOptions(“page”, “e”)) O4WSectionStart(“ourHeader”, O4WMobileOptions(“header”)) O4WHeader(“Sample Page”, 3)
O4WSectionEnd(“ourHeader”)
O4WSectionStart(“ourBody”, O4WMobileOptions(“content”)) O4WText(“Mobile content goes here!”) O4WSectionEnd(“ourBody”)
O4WSectionEnd(“ourPage”)
O4WMobilePageOptions(bDoInitEvent, bDoShowEvent, {mobilePageAndTheme})
O4WMobilePageOptions is applied to the O4WSectionStart call when in O4W mobile mode and controls whether the mobile browser will send an event when this page section is first loaded (bDoInitEvent = “1”), and/or whenever this page section is displayed (bDoShowEvent = “1”).
If the mobilePageAndTheme parameter is not null, this call will also set the O4WMobileOptions(“page”), passing in this parameter as the theme code (“a” through “z”), thus eliminating the need to call O4WMobileOptions in addition to this call.
Example:
O4WSectionStart("Main page", O4WMobilePageOptions(“1”, “1”, “c”))
O4WMobileButtonOptions(transitionType, iconName, {mobileButtonAndTheme})
O4WMobileButtonOptions is applied to O4WLink or O4WButton elements when in O4W mobile mode and controls what transition effect is used when the button is pressed, and what icon should be displayed with that button (note that O4W will automatically convert links into buttons when in mobile mode). Available options for transitionType include “pop”, “slide”, “slideup”, “slidedown”, “flip”, and “fade”. Available icons include “delete”, “arrow-l”, “arrow- r”, “arrow-u”, “arrow-d”, “plus”, “minus”, “check”, “gear”, “refresh”, “forward”, “back”, “grid”, “star”, “alert”, “info”, “home”, and “search”.
If the mobileButtonAndTheme parameter is not null, this call will also set the O4WMobileOptions(“button”), passing in this parameter as the theme code (“a” through “z”), thus eliminating the need to call O4WMobileOptions in addition to this call.
Example:
O4WLink("Second page", O4W_LINKTYPE_LOCAL$, "subsection1", “”, “”, O4WMobileButtonOptions(“fade”, “forward”))
Mobile Device Orientation
O4W Mobile is also able to customize which styles get applied to different browser elements based on the orientation of your mobile device. It does this by applying either the "landscape" or "portrait" style names to the generated page as appropriate. You can build styles that are applied only in the right circumstance by using O4WMOBILE_STYLE_PORTRAIT$ and O4WMOBILE_STYLE_LANDSCAPE$ equates in your various O4WxxxSTYLE API calls.
Simply include the proper equate instead of, or in addition to, the "style name" parameter, and that style definition will only apply in that instance.
For example, to use a red background color when in portrait mode, but a yellow background color when in landscape mode, for a header, you could have the following code:
O4WHeader("This is the header", 1, "", O4WColorStyle(O4WMOBILE_STYLE_PORTRAIT$, "red"):O4WColorStyle(O4WMOBILE_STYLE_LANDSCAPE$, "yellow"))
Like all O4WxxxSTYLE calls, these can also be assigned to a variable and used repeatedly:
portraitColor = O4WColorStyle(O4WMOBILE_STYLE_PORTRAIT$, "red") landscapeColor = O4WColorStyle(O4WMOBILE_STYLE_LANDSCAPE$, "yellow") O4WHeader("This is the header", 1, "", portraitColor:landscapeColor)
If you wish to use "named" styles, you can apply the O4WMOBILE_STYLE_PORTRAIT$ and O4WMOBILE_STYLE_LANDSCAPE$ equates as the "suffix":
O4WColorStyle("headerColor":O4WMOBILE_STYLE_PORTRAIT$, "red") O4WColorStyle("headerColor":O4WMOBILE_STYLE_LANDSCAPE$, "yellow") O4WHeader("This is the header", 1, "", "headerColor")
Enhancing User Interface Elements
O4W supports the same user interface elements in mobile mode as in normal desktop mode; however, for added functionality, you may need to apply some additional styles or options. Note that there is no drawback to adding these styles and options to all your O4W routines – including any desktop O4W stored procedures; as newer browsers become available that support HTML5, these additional styles and options will enhance the user experience on the desktop as well.
Grouping Elements Together
Apply the "fieldcontain" role to a section (using the O4WMobileOptions API call) to style associated labels and input controls together. O4W will attempt to draw the elements that are in that section side-by-side, rather than using a 100% width for the elements as it might otherwise do.
Apply the "controlgroup" role to a section (using the O4WMobileOptions API call) to group related elements in your form. For example, the radio buttons in a radio button set, the checkboxes in a checkbox set, or multiple buttons that should appear side-by-side can be grouped in a controlgroup.
Example:
O4WSectionStart("questionOneSection", O4WMobileOptions("fieldcontain")) O4WText("Enter your name")
O4WTextbox("", "", "", "name", "q1name") O4WSectionEnd("questionOneSection") O4WSectionStart("buttonSection", O4WMobileOptions("controlgroup")) O4WButton("Cancel", "BTN_CANCEL")
O4WButton("OK", "BTN_OK")
O4WSectionEnd("buttonSection")
By default, buttons will be grouped vertically. To group horizontally, apply the "horizontal" option to the "data-group" O4WDataStyle.
Example:
O4WSectionStart("buttonSection", O4WMobileOptions("controlgroup"):O4WDataStyle("","data-type","horizontal")) O4WButton("Cancel", "BTN_CANCEL")
O4WButton("OK", "BTN_OK")
O4WSectionEnd("buttonSection")
Accessibility Enhancement
The O4WTextOptions allows you to associate a "label" with an input element, such as a textbox, radio button, etc. This allows the browser to identify which input element is described by the label, and this information can be rendered more appropriately (for example, the label and input control can be kept together even on the smaller mobile screen) or in more accessible ways (for example, if a screen reader is speaking the page aloud).
Example:
O4WSectionStart("questionOneSection", O4WMobileOptions("fieldcontain")) O4WText("Enter your name", "", O4WTextOptions("q1name")) O4WTextbox("", "", "", "name", "q1name") O4WSectionEnd("questionOneSection")
When using a radio button set or checkbox set, the labels that describe each radio button or checkbox are automatically associated with each radio button or checkbox; to set the overall label for the set (rather than for an individual element), O4WFieldsetOptions must be applied to the section that contains the set.
Example:
O4WSectionStart("questionTwoSection",O4WMobileOptions("fieldcontain")) O4WSectionStart("questionTwoSet", O4WFieldsetOptions("Agree to the terms")) O4WCheckbox("I agree", "1", "checkbox_1","checkbox_1") O4WSectionEnd("questionTwoSet")
O4WSectionEnd("questionTwoSection")
You can apply the O4WfieldSetOptions to a section, in conjunction with the "controlgroup" role, to identify (for accessibility purposes) that these related elements are grouped together in your form. For example, the radio buttons in a radio button set, the checkboxes in a checkbox set, or
multiple buttons that should appear side-by-side can be grouped in a fieldset with the controlgroup.
Example:
O4WSectionStart("questionTwoSection", O4WMobileOptions("fieldcontain"))
O4WSectionStart("qtwoFieldset", O4WFieldsetOptions("Agree to the terms"):O4WMobileOptions("controlgroup")) O4WCheckbox("I agree", "1", "checkbox_1","checkbox_1")
O4WSectionEnd("qtwoFieldset") O4WSectionEnd("questionTwoSection") O4WSectionStart("buttonSection", O4WMobileOptions("controlgroup")) O4WButton("Cancel", "BTN_CANCEL")
O4WButton("OK", "BTN_OK")
O4WSectionEnd("buttonSection")
Special Textbox Types
HTML5 compliant browsers (including newer mobile browsers) can enhance a textbox - for example, to limit the types of characters that can be typed, or by displaying a custom keyboard for the specific type of input – if the type of input can be specified. O4W provides some specific APIs that already change the "type" of the input (such as O4WPwdBox and O4WNumberBox); you can also use O4W’s O4WInputBoxOptions to specify any additional type of input (such as "email", "tel", "number", "search").
Example:
O4WSectionStart("questionThreeSection", O4WMobileOptions("fieldcontain")) O4WText("Enter your email: ", "", O4WTextOptions("emailAdd")) O4WTextbox("", "", "", "emailAdd", "emailAdd", O4WInputBoxOptions("email")) O4WSectionEnd("questionThreeSection") O4WSectionStart("questionFourSection", O4WMobileOptions("fieldcontain")) O4WText("Enter your age: ", "", O4WTextOptions("age"))
O4WNumberBox("", "", "", "0","120","","1","age","age")
O4WSectionEnd("questionFourSection")
Enhanced Listboxes
By applying the O4WMobileOptions API with "slider" specified, you can turn a listbox into a "slider", which is much easier for users to select manually. Note that a slider should contain ONLY two options.
Example:
O4WSectionStart("sliderSection", O4WMobileOptions("fieldcontain")) O4WText("Flip switch", "", O4WTextOptions("flipSelect")) O4WListboxStart("myslider", "flipSelect", O4WMobileOptions("slider")) O4WListbox("No", "N", "myslider", "", "flipSelect_N")
O4WListbox("Yes", "Y", "myslider", "", "flipSelect_Y") O4WListboxEnd()
O4WSectionEnd("sliderSection")
Enhanced Lists
Use the O4WMobileOptions "listview" parameter to turn normal O4W lists (controlled by O4WListStart, O4WListItem, and O4WListEnd API calls) into mobile-friendly output; both numbered and unnumbered lists will be converted, and nested lists will be displayed appropriately as well. By using additional mobile API call, it is possible to insert list dividers, counts, etc. into the list output.
Use the O4WMobileOptions API call with the "list-divider" parameter to turn a list item into a divider.
Example:
O4WListStart("0", "myList", O4WMobileOptions("listview")) O4WListItem("", O4WMobileOptions("list-divider")) O4WText("A")
O4WListItem()
O4WLink("Adam", O4W_LINKTYPE_LOCAL$, "#adam") O4WListItem()
O4WLink("Alan", O4W_LINKTYPE_LOCAL$, "#alan") O4WListItem("", O4WMobileOptions("list-divider")) O4WText("B")
O4WListItem()
O4WLink("Barry", O4W_LINKTYPE_LOCAL$, "#barry") O4WListItem()
O4WLink("Betty", O4W_LINKTYPE_LOCAL$,"#betty") O4WListEnd("myList")
A list can be made "searchable" by using the O4WDataStyle API with the "data-filter" set to "true"; a textbox will then automatically be added to the start of the list.
Example:
O4WListStart("0", "myList", O4WMobileOptions("listview"):O4WDataStyle("","data-filter","true")) O4WListItem("", O4WMobileOptions("list-divider"))
O4WText("A")
O4WListItem()
O4WLink("Adam", O4W_LINKTYPE_LOCAL$, "#adam") O4WListItem()
O4WLink("Alan", O4W_LINKTYPE_LOCAL$, "#alan") O4WListItem("", O4WMobileOptions("list-divider")) O4WText("B")
O4WListItem()
O4WLink("Barry", O4W_LINKTYPE_LOCAL$, "#barry") O4WListItem()
O4WLink("Betty", O4W_LINKTYPE_LOCAL$,"#betty") O4WListEnd("myList")
To add a "count bubble" to the list item, you need to apply the "ui-li-count" class to the number you want displayed. This is done via the O4WText call inside the list item.
Example:
O4WListStart("0", "myList", O4WMobileOptions("listview")) O4WListItem("", O4WMobileOptions("list-divider")) O4WText("A")
O4WText("2", "", "ui-li-count") O4WListItem()
O4WLink("Adam", O4W_LINKTYPE_LOCAL$, "#adam") O4WListItem()
O4WLink("Alan", O4W_LINKTYPE_LOCAL$, "#alan") O4WListItem("", O4WMobileOptions("list-divider")) O4WText("B")
O4WText("3", "", "ui-li-count") O4WListItem()
O4WLink("Barry", O4W_LINKTYPE_LOCAL$, "#barry") O4WListItem()
O4WLink("Betty", O4W_LINKTYPE_LOCAL$,"#betty") O4WListItem()
O4WLink("Bob", O4W_LINKTYPE_LOCAL$,"#bob")
O4WListEnd("myList")