====== O4W Application Program Interface (API) ======

 

=== Design Flow ===

 

Developers who wish to create their own O4W applications create a routine whose name begins O4W_ and register it through the O4W Security module. This routine is similar in design to an OpenInsight "commuter module"; it will be called by different "events" involved in the web development cycle.  The subroutine must take 3 parameters:

<code>
   SUBROUTINE O4W_MYROUTINE(CtlID, Event, Request)
</code>
 

All web applications will receive the "CREATE" event when they are first invoked.  Unlike a traditional OpenInsight form, the layout of your O4W web page will be created dynamically in this stored procedure. The stored procedure should build the web application during the CREATE event, optionally specifying other "events" that it wishes to be notified of; it will then be invoked by these other events (for example, button clicks), at which time it can dynamically generate new content or take any other action that is appropriate.

 

When building the web page with O4W, there are several functions that must be performed.  These include:

 

  * creating "styles" to control the look of the page;

  * creating the display elements of the page;

  * creating any "input controls" on the page;

  * specifying the actions that the page may generate

 

Styles are the heart of modern web development.  Styles control the look of the different pieces of the web page, including fonts, colors, alignment, and more.  Groups of styles can be bundled together into "style sheets", which may be added to your O4W application.  O4W toolkit functions also allow you to create style information "on the fly", and either use it for a single display element (for example, a particular block of text) or for groups of elements (for example, for all text).

 

When first creating your web page, you will normally specify a 'template' containing HTML code that defines the general layout of your web page.  This template can contain other scripts, style sheets, etc., which will all be included in your final output.  Any web design tool (or even notepad) can be used to create this template.  O4W requires the placement of 3 special "tags" within the template, along with one optional "tag", so that it can accurately place your programmatically-generated output.  The required tags include %HEAD% (located in the header section), %BODY% (located in the main body), and %FOOTER% (where you wish any footer banners to appear).  You can optionally also specify a location, and type, for any menu you wish to create - specify %MENU-H% for a horizontal menu, %MENU-V% for a vertical menu, or %MENU% (for a menu with the default orientation, controlled by the O4WCONFIG "MENUDIR" record), wherever you wish such a menu to appear (generated by a call to O4WMenu).

Display elements are the actual items to show on the web page.  This includes plain text, headers, tables, links, images, and anything else that the user will see on the page.  For each of these, it is possible to associate a style.

 

A particular type of display element is the "input control."  An input control (for example, a textbox) allows the user to enter information on the web page.  Input controls can have actions associated with them so that your program (or special functions built into the web page itself) can react to the users input.

== Sample Code ==

 

Below is annotated sample code illustrating the use of the O4W toolkit.  Specific information for each O4W API call is later in the document; however, this sample code illustrates the "flow" of the O4W design.

 

Define the name of the stored procedure (with the O4W_ prefix), and include the insert item that defines the O4W toolkit routines

 
<code>
   Subroutine O4W_MYROUTINE(CtlEntId, Event, Request)

   $Insert O4WEquates
</code>
 

Check for the 'create' event, and verify that we have all the information needed to run this routine; if not, return an error

 
<code>
   Begin Case

            Case Event _eqc "CREATE"

                        * Initial form creation

                        ReportName = O4WGetValue("REPORTID")

                        If ReportName = "" Then

                                    O4WError("No report specified")

                                    Return

                        End

                        Read ReportDef From O4WReportFile%, ReportName else

                                    O4WError("Report '":ReportName:"' not on file")

                                    Return

                        End
</code>
 

Load the HTML "template" that will serve as the basis for our form, and set some default style information for the form (colors, images, and alignment) and for any "links" on the page

<code>
                        O4WForm(ReportDef<TEMPLATE_NAME$>, O4WColorStyle("", ReportDef<BGCOLOR$>, ReportDef<TEXTCOLOR$>, ReportDef<BGIMAGE$>):@FM:O4WTextStyle("","","","",ReportDef<Align$>+0))

                        O4WLinkStyle(ReportDef<LINKCOLOR$>, ReportDef<VISITEDCOLOR$> )
</code>
 

Set the "title" of the web page (which is displayed in the browser window)

 
<code>
                        O4WTitle(ReportDef<TITLE$>)
</code>
 

Define a style, called "RPTALIGN", that we will re-use with various other elements (including the "headline" of the web page)

 
<code>
                        O4WTextStyle("RPTALIGN", "", "", "", ReportDef<Align$>+0)

                        O4WHeader(ReportDef<BANNER$>, 1, "BANNER", "RPTALIGN")
</code>
 

Define a section that will contain our results (presented as a table).  Note that the section uses the "RPTALIGN" style defined earlier

 
<code>
                        O4WSectionStart("DATATABLE", "RPTALIGN")

                        bBorder = 0

                        bWidth = ReportDef<TableBorder$> + 0

                        If ReportDef<TableBorder$> <> "0" And ReportDef<TableBorder$> <> "" Then bBorder = 1
</code>
 

Start the table, named RESULTS, and set its style

 
<code>
                        O4WTableStart("RESULTS", O4WTableStyle("", bBorder, bWidth, ReportDef<Align$>+0))
</code>
 

For each column in the table, define a "column header" with the desired color and text style

 
<code>
                        NUM.FIELDS = DCOUNT(ReportDef<DisplayField$>, @VM)

                        For each.field = 1 To num.fields

                                    colColor = ReportDef<ColumnColor$, each.field>

                                    colBGColor = ReportDef<ColumnBGColor$, each.field>

                                    colBold = ReportDef<ColumnBold$, each.field>

                                    colAlign = ReportDef<columnalign$, each.field>

                                    colItalic = ReportDef<columnItalic$, each.field>

                                    O4WTableHeader(ReportDef<ColumnName$, each.field>, each.field, "",

                                                O4WColorStyle("",colBGColor, colColor):@FM:

                                                O4WTextStyle("", "", colBold, colItalic, colAlign))
</code>
 

Define the styles for the columns themselves, saving them as the style named "RESULTS_<colnumber>"


<code>
                                    valColor = ReportDef<ValueColor$, each.field>

                                    valBGColor = ReportDef<ValueBGColor$, each.field>

                                    valAlign = ReportDef<ValueAlign$, each.field>

                                    O4WColorStyle("RESULTS_":each.field, valBGColor, valColor)

                                    O4WAlignStyle("RESULTS_":each.field, valAlign)

                                    O4WTableStyle("RESULTS_":each.field, bBorder, bWidth)

                        Next each.field
</code>
 

Build some results (omitted from the sample code) and populate the table with the data. Note the use of the style "RESULTS_<colno>" defined for each column (above)

 
<code>
                        for Cntr = 1 to Num.ROWS

                                    For EACH.FIELD = 1 To NUM.FIELDS

                                                O4WSetCell(CNTR, Each.field,'' , 'RESULTS_':EACH.FIELD)

                                                RSLT = ResultData<CNTR, Each.Field>

                                                O4WText(RSLT)

                                    Next each.field

                        Next Cntr
</code>
 

The RESULTS table is now complete

 
<code>
                        O4WTableEnd("RESULTS")
</code>
 

                        As an illustration of advanced functionality, convert the table using a "tablesorter" plugin.  This requires some scripts and stylesheets to be added, before the plugin is "attached" to the RESULTS table

 
<code>
                        O4WScript("/weboi/O4W/jquery.tablesorter.min.js")

                        O4WScript("/weboi/O4W/jquery.tablesorter.pager.js")

                        O4WStyleSheet("/weboi/O4W/style.css")

                        O4WPlugIn("RESULTS", "tablesorter", "{widthFixed: true, widgets: ['zebra']}" )
</code>


Put a "break" between the table, and add two buttons.  Add events for these buttons when they are "clicked"

 
<code>
                        O4WBreak()

                        O4WButton("Download As CSV", "BTNCSV")

                        O4WButton("Download As PDF", "BTNPDF")

                        O4WQualifyEvent("BTNCSV", "CLICK")

                        O4WQualifyEvent("BTNPDF", "CLICK")
</code>
 

The DATATABLE section is now complete

 
<code>
                        O4WSectionEnd("DATATABLE")
</code>
 

Add a "link" at the bottom of the page, another break, and a "footer"

 
<code>
                        O4WLink("Home Page", "", "http://www.revelation.com")

                        O4WBreak()

                        O4WFooter(ReportDef<FOOTER$>, 3, "FOOTER")
</code>
 

The CREATE event is now complete.  The following section will be called when one of the buttons is clicked, and the "CLICK" event is passed back to the O4W commuter module

                       
<code>
            Case event _eqc "CLICK"

                        Gosub GenerateTable
</code>
                       

Finish up the commuter code logic

                       
<code>
   End case

   Return
</code>


=== O4W Toolkit Style and Option functions ===

 

== O4WSTYLESHEET(<urltostylesheet>) ==

Allows you to define an external "style sheet" that you wish to put on the current web page.

 

== O4WALIGNSTYLE(<stylename>, <horizAlign>, <vertAlign>) ==

Creates a "style" for element alignment. If <horizAlign> specified, the element is horizontally aligned according to its value (this can be any valid CSS "text-align" value, and O4W recognizes 0, 1, and 2 as "shortcuts" for left, center, and right).  If <vertAlign> specified, the element is vertically aligned according to its value (this can be any valid CSS "vertical-align" value, and O4W recognizes 0, 1, and 2 as "shortcuts" for top, middle, and bottom). Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.

== O4WCOLORSTYLE(<stylename>, <bgcolor>, <fgcolor>, <bgimage>) ==

== O4WCOLORS(<stylename>, <bgcolor>, <fgcolor>, <bgimage>) Deprecated – Use O4WColorStyle ==

Creates a "style" based on the specified background color, foreground color, and background image.  Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.

 

== O4WLINKSTYLE(<stylename>, <normalcolor>, <visitedcolor>) ==

Defines the colors to use for links when they are first displayed, and after they have been visited.  If <stylename> is null, this applies to all links on the page.


== O4WTABLESTYLE(<stylename>, <border>, <borderwidth>, <align>) ==

Creates a "style" based on the specified border flag (0=no border,1=solid border), border width (with no units specified; pixels will be used), and alignment (0=left;1=center;2=right).  Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.

 

== O4WCELLSTYLE(<stylename>, <#cols>, <#rows>, <align>, <vertalign>,<headerFlag>) Deprecated – See O4WTableCellOptions and O4WAlignStyle ==

Creates a "style" for table contents.  If <#cols> specified, the current table 'cell' will expand across that number of columns; if <#rows> specified, the current table 'cell' will expand across that number of rows. If <align> specified, the text in the cell is horizontally aligned according to its value (this can be any valid CSS "text-align" value, and O4W recognizes 0,1, and 2 as "shortcuts" for left, center, and right).  If <vertalign> specified, the text in the cell is vertically aligned according to its value (this can be any valid CSS "vertical-align" value, and O4W recognizes 0,1, and 2 as "shortcuts" for top, middle, and bottom).  If <headerFlag> is set to "1", the cell is styled as a table header ("th") instead of the default table detail ("td"). Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.

 

== O4WTABLEADVANCEDOPTIONS(<DNDFlag>, <cornersFlag>, <zebraFlag>) ==

Specifies additional options for table display.  If <DNDFlag> is set to “1”, the table will automatically include the O4W plugin to allow “drag and drop” between the table rows. If <cornersFlag> is set to “1”, the table will automatically include the O4W plugin for rounded corners.  If <zebraFlag> is set to “1”, the contents of the table will be “zebra-striped”.  Returns the option information to use immediately with a display element or input control.

 

== O4WTABLEPAGEROPTIONS(<pagerLocn>, <rowsPerPage>, <sortCols>, <maxRows>,<currPage>,<addlOptions>,<overridePager>) ==

Specifies pagination and sorting options for table contents.  When specified, the default pagination subroutine will be applied to the current table (unless <overridePager> is set to the name of a different pagination subroutine to use).  The <pagerLocn> parameter should be set to “0” to have the pagination display appear above the table, and “1” to appear below the table.  Set <rowsPerPage> to the number of rows/page that should initially be displayed.  <SortCols> contains a @VM-delimited list of the column numbers where sorting should be allowed (the first column of the table is “1”, the second column is “2”, etc.).  If known, <maxRows> should be set to the total number of rows to be displayed in the table.  The <currPage> parameter should be set to the current page number (“1” initially, and then as appropriate after any callbacks for pagination/sorting have been handled).  Any additional options needed by the pagination routine should be passed with the <addlOptions> parameter.  Returns the option information to use immediately with a display element or input control.

== O4WTABLECELLOPTIONS(<#cols>, <#rows>, <headerFlag>) ==

Specifies additional options for table contents.  If <#cols> specified, the current table 'cell' will expand across that number of columns; if <#rows> specified, the current table 'cell' will expand across that number of rows.  If <headerFlag> is set to "1", the cell is styled as a table header ("th") instead of the default table detail ("td"). Returns the option information to use immediately with a display element or input control.

 

== O4WTEXTSTYLE(<stylename>, <fontname>, <bold>, <italic>, <align>, <size>) ==

Creates a "style" based on the specified font, bold flag (0=normal,1=bold), italic flag (0=normal, 1=italic), alignment (0=left;1=center;2=right;-1=justify), and font size.  Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.

 

== O4WLISTBOXSTYLE(<stylename>,<multipleflag>,<size>,<width>,<selectAllFlag>) Deprecated – See O4WListBoxOptions ==

Creates a 'style' based on the specified multiple flag (1=multiple selections allowed) and the specified <size> (number of rows to display) and <width> (width of rows).  If <selectAllFlag> is specified with <multipleFlag>, then the entire contents of the select box (instead of only 'selected' items) will be returned. Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.

 

== O4WLISTBOXOPTIONS(<multipleflag>,<size>,<width>,<selectAllFlag>,<listID>,<comboFlag>) ==

Specifies additional options for a listbox control, including whether multiple selections are allowed (set <multipleFlag> parameter to “1”), and the specified <size> (number of rows to display) and <width> (width of rows).  If <selectAllFlag> is specified with <multipleFlag>, then the entire contents of the select box (instead of only 'selected' items) will be returned. If <listID> is specified, then the overall listbox (the HTML “select” element) will be assigned this ID; if not specified, the “select” element will automatically be given the ID “list<NAME>”, where <NAME> is the name of the select element. If <comboFlag> is specified then the control will be displayed as a combobox (including a modifiable textbox), rather than a listbox. Set <comboFlag> to “1” for a case-sensitive combobox, or “-1” for a case-insensitive combobox.  Returns the option information to use immediately with a display element or input control.

 

== O4WSIZESTYLE(<stylename>, <width>, <height>) ==

For those elements that allow for width and/or height (tables and images), specify a value followed by "px" (or nothing) for pixels, or "%" for percent.  Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.

== O4WPOSITIONSTYLE(<stylename>, <left>, <top>, <posnType>, <floattype>, <cleartype>) ==

For those elements that allow for positioning, you may specify a value for the left and top locations of the element.  If <posnType> is "absolute", this is an absolute position on the page; if this is "relative" (or null), the position is relative to the element's parent. You cam also specify a <floattype> in addition to, or instead of, other positioning parameters; specify 'left' or 'right' (or any valid 'float' style).  Since 'floating' the element will remove it from the normal layout, to preserve the sizing of any containing section, you may create a dummy element with <cleartype> specified (for example, 'both') to retain the proper element flow.  Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.

 

== O4WINPUTSTYLE(<stylename>, <enabled>, <readonly>, <align>, <selected>) Deprecated – See O4WInputOptions ==

Creates a "style" based on the specified enabled flag (0=disabled,1=enabled) and alignment (0=left;1=center;2=right;-1=justify).  If <selected> is set to '1', then the specified element will be "selected" (radio buttons and checkbox items will be checked, listbox items will be selected, and buttons will be marked as the 'default' button).  Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.

 

 

== O4WINPUTOPTIONS(<enabled>, <readonly>, <autocomplete>) ==

Defines additional input options based on the specified enabled flag (0=disabled,1=enabled) and <readOnly> flag (0=read/write, 1=read only).  If <autocomplete> is set to “0”, then the input control will not allow the browser to “auto fill in” the value.  Returns the option information to use immediately with a display element or input control.

 

== O4WRAWSTYLE(<stylename>, <style>, <value>) ==

For advanced users.  Creates a "style" based on the CSS style name and associated value (both <style> and <value> can be @FM delimited).  Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.

**//O4WATTRIBUTESTYLE//****//(<stylename>, <style>, <value>)//**

For advanced users.  Creates a "style" based on the attribute name and associated value (both <style> and <value> can be @FM delimited).  Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.

**//O4WHTMLOPTIONS//****//(<returnHTML>, <acceptHTML>)//**

For advanced users.  When used with certain functions, indicates that the 'text' parameter is HTML (acceptHTML=1), and/or that the O4W API being called should return HTML rather than just build the generated HTML into the O4W output (returnHTML = 1).  At this time, the following O4W routines recognize O4WHTMLOptions: O4WLink (both returnHTML and acceptHTML), O4WImage (returnHTML), O4WSectionStart (returnHTML), O4WHeader (acceptHTML), O4WFooter (acceptHTML), O4WCheckbox (acceptHTML), O4WRadioButton (acceptHTML), O4WTabs (acceptHTML).  Note that, although it is O4WSectionStart that has the O4WHtmlOption, the returned HTML is not generated or returned until the O4WSectionEnd call. Returns the option information to use immediately with a display element or input control.

**//O4WRESPONSESTYLE(<stylename>, <textOnly>, <styleOnly>, <triggerChange>) Deprecated – See O4WResponseOptions//**

Marks the control or element for change when in ‘response’ event mode.  If the <textOnly> flag is set to “1”, only the control or element’s “text” property is changed; if <styleOnly> is set to “1”,  only the style information passed to the control or element is changed.  If neither is set, the entire element or control is updated with the modified element or control information. [NOTE: the <triggerChange> parameter is only applicable when this style is applied to O4WUpdate; if <triggerChange> is set to ‘1’, then the ‘change’ event for the control will be triggered when the element is updated; if set to ‘-1’, the change event will be triggered ONLY if the current and new values are different.] 

== O4WRESPONSEOPTIONS(<textOnly>, <styleOnly>, <triggerChange>) ==

Marks the control or element for change when in ‘response’ event mode.  If the <textOnly> flag is set to “1”, only the control or element’s “text” property is changed; if <styleOnly> is set to “1”,  only the style information passed to the control or element is changed.  If neither is set, the entire element or control is updated with the modified element or control information. [NOTE: the <triggerChange> parameter is only applicable when this style is applied to O4WUpdate; if <triggerChange> is set to ‘1’, then the ‘change’ event for the control will be triggered when the element is updated; if set to ‘-1’, the change event will be triggered ONLY if the current and new values are different.]  Returns the option information to use immediately with a display element or input control.

== O4WMARKEDSTYLE(<stylename>, <bIsMarked>) Deprecated – See O4WMarkedOptions ==

Sets the "marked" flag for various controls.  When used for a button, if set to "1", the button is marked as a 'submit' button; if set to "0", the button is explicitly marked as a "non-submit" button.  When used for a section, if set to "1", the section is marked as containing a form for submission to the host; if set to "0", the section is explicitly marked as _not_ containing a form.  When used with a checkbox, select list, or radio button, if set to "1", the specified control is checked or selected.

== O4WMARKEDOPTIONS(<bIsMarked>, <currentValues>) ==

Sets the "marked" flag for various controls.  When used for a button, if set to "1", the button is marked as a 'submit' button; if set to "0", the button is explicitly marked as a "non-submit" button.  When used for a section, if set to "1", the section is marked as containing a form for submission to the host; if set to "0", the section is explicitly marked as _not_ containing a form.  When used with a checkbox, select list, or radio button, if set to "1", the specified control is checked or selected. Alternatively, <currentValues> can be set to the value (or @VM-delimited values) that the checkbox, listbox, and radio button set should use as the currently selected value (note that the <currentValues> values should be the “code” values, rather than the display text, for the element).  Returns the option information to use immediately with a display element or input control.

 

== O4WVALIDATESTYLE(<stylename>, <validationtype>, <bRequired>, <errmsg>, <optParam1>, <optParam2>, <bServerOnly>) Deprecated – See O4WValidateOptions ==

Marks the control or element as requiring validation.  <Validationtype> is one of "date", "time", "ss", "cc", "zip", "phone", "num", "alpha", "alphanum", "state", "range", "length", "email" or  "daterange".  If set to "1", <bRequired> marks the field as required (no null allowed).  <Errmsg> indicates the (optional) message to display if validation fails.  <optParam1> and <optParam2> contain the minimum and maximum values, respectively, for the range, length, and daterange validations (note that <optParam1> and <optParam2> should be in internal format for daterange validation).  By default, validations will occur on both the client, and then again on the host (client-side validation should NEVER be used alone); if <bServerOnly> is set to "1", then the validation will occur only on the host.


== O4WVALIDATEOPTIONS(<validationtype>, <bRequired>, <errmsg>, <optParam1>, <optParam2>, <bServerOnly> ==

Marks the control or element as requiring validation.  <Validationtype> is one of "date", "time", "ss", "cc", "zip", "phone", "num", "alpha", "alphanum", "state", "range", "length", "email" or  "daterange".  If set to "1", <bRequired> marks the field as required (no null allowed).  <Errmsg> indicates the (optional) message to display if validation fails.  <optParam1> and <optParam2> contain the minimum and maximum values, respectively, for the range, length, and daterange validations (note that <optParam1> and <optParam2> should be in internal format for daterange validation).  By default, validations will occur on both the client, and then again on the host (client-side validation should NEVER be used alone); if <bServerOnly> is set to "1", then the validation will occur only on the host. Returns the option information to use immediately with a display element or input control.


=== O4W Toolkit Display Element functions ===

== O4WFORM(<templateID>, <style>) ==

For example, to select a template located in the templates folder you can state O4WForm(“O4W\templates\o4wtreetmpl.htm”)

== O4WRESPONSE(<contentType>) ==

Either the O4WForm or O4WResponse call MUST be called before specifying any other controls or style information in your O4W project.  O4WForm is used to generate a full web page of information; <templateID> specifies the location of the HTML record that all the other O4W controls will be placed into.  If <templateID> contains a space, it is considered to be an OI table and record name (<table> <record>); if there are no spaces, it is considered to be an OS file.  If <style> is specified, the style is applied to the main body of the web page that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions. O4WResponse is used to generate a partial response (of the desired type), typically in response to an event on a form originally generated with O4WForm.  Note that O4WForm also generates a value (accessible via O4WGetValue(“O4WUniqueID”)) that can uniquely identify the form during subsequent processing.

== O4WMetaTag(<tagName>,<tagContent>) ==

 The O4WMetaTag API call is used to set a “meta” tag in the header of the generated form.  Note that it //must// be applied in the CREATE event, after the O4WForm() call.  Specify the name of the meta tag to set in the tagName parameter, and the contents of the meta tag in the tagContent parameter. Example:


<code>
* make sure jQuery Mobile tag is applied to maximize our screen usage
O4WMetaTag(“viewport”, “width=device-width, initial-scale=1”)
</code>

== O4WTITLE(<text>) ==

Makes the specified <text> the "title" of the web page (as seen in the browser).

== O4WSectionStart/O4WSectionEnd ==

You may group areas of your web page into different "sections."  These sections can perform different behaviours (for example, they can be individually refreshed).

O4WSectionStart(<sectionname>, <style>): creates a new section named <sectionname>. If <style> is specified, the style is applied to the section of the web page that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.

O4WSectionEnd(<sectionName>) : ends the current section.  If the O4WHtmlOptions option to return HTML was specified for the O4WSectionStart call, then O4WSectionEnd returns the generated HTML.

== O4WTEXT(<text>, <id>, <style>) ==

== O4WFIXEDTEXT(<text>,<id>,<style>) ==

Displays the specified text at the current location on the browser page.  Multiple lines of text can be displayed (each @VM delimited value is a new line of text). If <ID> is specified, this text can be addressed through style sheets individually; if <style> is specified, the style is applied to the text that is generated.  Note that <style> may be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.  If the <style> parameter includes the O4WHtmlOptions option to return HTML, then O4WText will return the generated HTML rather than display it on the current form.

== O4WLINK(<text>, <linktype>, <linkto>, <target>, <id>, <style>) ==

Displays a "link" to the location specified in <linkto>. <text> is displayed for the user to click. If <target> is specified, that is used as the 'target name' of the link. If <ID> is specified, this link can be addressed through style sheets individually; if <style> is specified, the style is applied to the link that is generated.  Note that <style> may be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions. <linktype> choices currently include:

  - "normal" (O4W_LINKTYPE_NORMAL$, or 0);

  - "webOI form" (O4W_LINKTYPE_WEBOI$, or 1);

  - "o4w procedure" (O4W_LINKTYPE_PROGRAM$, or 2);

  - "o4w inquiry screen"  (passing in, optionally, the record key) (O4W_LINKTYPE_FORM$, or 3), "email" (O4W_LINKTYPE_EMAIL$, or 4);

  - "o4w inquiry screen" (passing in, optionally, search parameters) (O4W_LINKTYPE_FORM_SEARCH$, or 5);

  - embedded" url (O4W_LINKTYPE_EMBED$, or 6);

  - "O4W report" (O4W_LINKTYPE_REPORT$, or 7);

  - "local" (O4W_LINKTYPE_LOCAL$, or 8);

  - "OI" (O4W_LINKTYPE_OI$, or 9) (useful only when O4W screen is invoked in O4W_STANDALONE_FORM or O4W_CHILD_FORM);

  - “O4W Popup” (O4W_LINKTYPE_POPUP$, or 10);

  - “O4W Index Lookup” (O4W_LINKTYPE_INDEXLOOKUP$, or 11);

  - “O4W Dashboard” (O4W_LINKTYPE_GRAPH$, or 12);

 

If the O4WHTMLOptions option is passed into O4WLink, this call may return HTML rather than actually creating a link on the form, and it can accept HTML as the <text> parameter value.

== O4WIMAGE(<text>,<url>,<linktype>,<linkto>,<target>,<id>,<style>) ==

Displays the image specified in <url> at the current location, using <text> as the 'alternate text'.  If <linkTo> is non-null, the image is also a link the specified location, with <linktype> specifying the type of link and <target> specifying the 'target' browser window (see O4WLINK for a list of valid <linktype> values).  If <ID> is specified, this image can be addressed through style sheets individually; if <style> is specified, the style is applied to the image that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.  If O4WHTMLOptions is specified as one of the style options, this call may return HTML rather than actually embedding the image on the form.

== O4WBREAK(<id>,<style>) ==

Generates a "break" (new line/new paragraph) in the output on the web page.  If <ID> is specified, this break can be addressed through style sheets individually; if <style> is specified, the style is applied to the break that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.

== O4WHEADER(<text>, <size>, <id>, <style>) ==

== O4WFOOTER(<text>, <size>, <id>, <style>) ==

Generates a "headline" of the specified size with the specified text.  If <ID> is specified, this line can be addressed through style sheets individually; if <style> is specified, the style is applied to the headline that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions. If the O4WHTMLOptions style is applied, then the <text> parameter may contain HTML instead of plain text. NOTE: if you wish to center align the headline, you must pass in the appropriate style information; this does not center by default.  For example:

 
<code>
   O4WFooter("(c) 2010 Revelation Software", 3)
</code>
 

will appear left-flush.  To center:

 
<code>
   O4WFooter("(c) 2010 Revelation Software", 3, "", O4WAlignStyle("","1"))
</code>
 

or (if centering will be used more than once)

 
<code>
   O4WAlignStyle("CENTERSTYLE","1")

   O4WFooter("(c) 2010 Revelation Software", 3, "", "CENTERSTYLE")
</code>
 

== O4WTableStart/O4WTableEnd/O4WTableHeader/O4WSetCell/O4WTableModify/ ==

**//O4WTableAddRow/O4WTableAddCol/O4WTableDelRow/O4WTableDelCol//**

Tables are used to graphically organize both data and input controls.  Note that, with style sheets, it is not necessary to use tables (as you can now explicitly locate display and control elements via their IDs), but tables are still a simple and convenient way to generate columnar layouts.

 

O4WTABLESTART(<id>, <style>)

Starts a table named <ID>, applying style <style> to the table. This table can be addressed by <id> through style sheets individually; if <style> is specified, the style is applied to the table that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.

 

O4WTABLEHEADER(<Text>, <colno>, <ID>, <Style>)

Creates a "column header" in the current table with the label <text> at column <colno>.  If <colno> is not specified, the next column number in sequence will be automatically used (NOTE: if any of the headers in the table are styled with "column spanning" via the O4WTableCellOptions call, you should NOT use the 'implicit' colno functionality, as the cell position will not be correct).  If <ID> is specified, this column header can be addressed through style sheets individually; if <style> is specified, the style is applied to the column header that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.

 

O4WSETCELL(<rownum>, <colno>, <ID>, <Style>)

Sets the "active cell" in the table to row <rownum>, column <colno> (data rows start at 1; row 0 can be used to refer to the column headers).  If <colnum> and <rownum> are not specified, the next column in the current row will automatically be selected; if only <rownum> is specified, the first column in that row will be selected (NOTE: if any of the cells in the table are styled with "column spanning" or "row spanning" via the O4WTableCellOptions call, you should NOT use the 'implicit' rownum/colno functionality, as the cell position will not be correct). Any other O4W display or input controls can now be specified, and will be placed in the table at the specified location.  If <ID> is specified, this cell can be addressed through style sheets individually; if <style> is specified, the style is applied to the table cell that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.  Row and column number parameters also allow the use  of relative changes; that is “+<x>” or “-<x>” (ie, “+1” or “-1”) to increment or decrement the current row or column.  For example, O4WSetCell(“+1”) will move to the next row.

 

O4WTABLEMODIFY(<row>,<id>,<style>)

Allows for the identification and styling of individual rows in a table.  Specify the row number in <row>, and you can specify an <id> and style info.

 

** ** **//O4WTableAddRow//****//(<tableName>, <rowNumber>, <uniqueID>)//**

**//  O4WTableAddCol//****//(<tableName>, <colNumber>, <uniqueID>)//**

These routines programmatically add a new row (O4WTableAddRow) or column (O4WTableAddCol) to an existing O4W table.  You must specify the name of the table you are modifying in the “tableName” parameter.  The rowNumber or colNumber is the row or column number you wish to insert; use “0” to add a new first row or column, and “-1” to add a new last row or column.  All controls, sections, styles, etc. will be copied into the new row or column.  Any named controls, sections, etc. will be renamed using the value provided in “uniqueID”; the new IDs will be formed from the ID of the copied control, with “_o4wid_”:uniqueID concatenated to the end.

 

Example:

Assume there is a previously created table named “testTable" which contains 3 columns and 2 rows.  The columns each contain textboxes, and in row 2 the IDs for these textboxes are “tbrow2col1”, “tbrow2col2”, and “tbrow2col3”.  After the call:

 
<code>
O4WTableAddRow(“testTable", “-1”, “extraRow”)
</code>

The table “testTable" will contain 3 columns and //3// rows.  In the 3<sup>rd</sup> row, there will be 3 textboxes, and the IDs for these textboxes will be “tbrow2col1_o4wid_extraRow”, “tbrow2col2_o4wid_extraRow”, and “tbrow2col3_o4wid_extraRow”.

 

**// //** **//O4WTableDelRow//****//(<tableName>, <rowNumber>)//**

**//  O4WTableDelCol//****//(<tableName>, <colNumber>)//**

These routines programmatically remove a row (O4WTableDelRow) or column (O4WTableDelCol) from an existing O4W table.  You must specify the name of the table you are modifying in the “tableName” parameter.  The rowNumber or colNumber is the row or column number you wish to remove; use “-1” to remove the last row or column.   Note that if there is only 1 row remaining in the table, O4WTableDelRow will not delete it; if there is only 1 column remaining in the table, O4WTableDelCol will not delete it.  Under certain circumstances, if O4W cannot determine whether the first column in a table is a “header” column, neither first nor second columns can be deleted.

 

O4WTABLEEND(<id>)

Wraps up the current table.  If this table was contained within another table ("nested" in another table's cell), the prior table is re-activated.  If no prior table was being built, normal (non-table) output is resumed.

== O4WSPACE(<numspaces>) ==

Generates the specified number of "non-breakable" spaces (to force the browser to respect, and not trim, these spaces)

== O4WDIVIDER(ID,<styleInfo>) ==

Generates a line at the current location in the html output.  If the optional ID is specified, this ID can be used to directly reference this element through other O4W calls.  If any optional styleInfo settings are supplied, the named classes or dynamically generated styles are applied to the line.

== O4WTABS(<tabSectionID>, <tabDetailIDS>, <tabTitles>, <tabRequiresData?>, <tabOptions>, <styleInfo>) ==

Creates a tabbed pane, named <tabSectionID>, containing tabs with titles (@VM delimited) from <tabTitles>.  The content of the tabs must be contained in O4W sections, as named in the associated @VM-delimited <tabDetailIDS> parameter.  If the associated field in <tabRequiresData?> is set to "1", an ajax-style request is sent to the commuter module (event = 'TAB', ctlentid = the specific <tabDetailID>).  The <styleInfo> parameter contains, in field 1, the associated @VM-delimited list of style information for each tab, and in field 2, any style information that is specific to the overall tabbed pane.  If the O4WHTMLOptions style is passed in the <styleInfo> parameter, the associated <tabTitles> parameter may contain HTML instead of plain text. Since the O4WTabs call creates an overall tab section using the <tabSectionID> (via an internal call to O4WSectionStart(<tabSectionID>)), be sure to use O4WSectionEnd(<tabSectionID>) to close the overall tab section.

== O4WLISTSTART(<type>, <ID>, <style>) ==

== O4WLISTEND(<ID>) ==

== O4WLISTITEM(<ID>, <style>) ==

Builds a sorted or unsorted list.  The first parameter to the list item is an optional ID.  Call O4WListStart to create a sorted (<type>=1) or unsorted (<type>=0) list.  Call O4WListItem for each new item.  Call O4WListEnd to finish the list.

 

== O4WGraphStart(<ID>,<title>,<type>,<seriesName>,<xOptions>,<yOptions>,<graphOptions>,<styleInfo>) ==

== O4WGraphData(<ID>,<seriesName>,<xValue>,<yValue>) ==

== O4WGraphEnd(<ID>) ==

Generates a graph. Call O4WGraphStart to begin the graph definition process; <ID> is the name of a previously-defined section (created using O4WSectionStart/O4WSectionEnd, or defined in the style sheet). Note that the section should be specified with an actual pixel size using the O4WSizeStyle (ie, O4WSizeStyle(%%''%%,'600px','400px')) or through a stylesheet; failure to define the section with a pixel size will cause the graph to fail (Note that, if the graph is to be displayed on a multi-tab form, and the graph is not on the first tab, the size _cannot_ be determined from the section; therefore, the tab where the graph is to be drawn should be 'activated', otherwise the sizing of the graph will not be correct). <Title>, if specified, is displayed as the graph title.  <Type> is one or more of the following graph types: O4W_GRAPH_LINE$, O4W_GRAPH_POINT$, O4W_GRAPH_BAR$, O4W_GRAPH_PIE$, O4W_GRAPH_HORIZONTAL_BAR$, O4W_STACKED_LINE$, O4W_STACKED_BAR$, or O4W_STACKED_HORIZONTAL_BAR$. If you have included the Google Visualizations graphing library in your configuration file, you can also specify O4W_GRAPH_PIE_3D$, O4W_GRAPH_GAUGE$, O4W_GRAPH_MAP$, O4W_GRAPH_INTENSITY_MAP$, O4W_GRAPH_TABLE$, O4W_GRAPH_AREA$, O4W_GV_GRAPH_STACKED_AREA$, or O4W_GV_GRAPH_COMBO$  If more than one "series" of data points is to be used for this graph, you may specify a graph type for each series (@FM delimited).  <SeriesName> identifies, on this graph, the 'series' that the data points belong to; if multiple series are to be used on the graph, multiple series names should be specified (@FM delimited), and the series names will be used to identify each series in a 'legend' on the graph.  <XOptions> and <YOptions> control additional options (@FM-delimited) for the x and y axis, respectively.  These options may include:

-          D, to specify that this is a date series on the axis (JQPLOT ONLY);

-          F, to format the axis.  For graphs generated by the jqPlot library, the F must be optionally followed by a prefix character, and then the number of decimal values to display (for example, "F3" to show 3 decimals; "F0" to show no decimals; "F$2" to show a dollar-sign prefix and 2 decimals).  For graphs generated by the Google Visualizations library, the F must be followed by one of the following: none, decimal, scientific, currency, percent, short, or long;

-          L to indicate that the values for this axis should be treated as literals (strings).  Only applicable to x options;

-          M, followed by a number, to specify the minimum value to show on that axis;

-          T, followed by text, to specify the text for that specific axis (GOOGLE VISUALIZATIONS ONLY);

-          X, followed by a number, to specify the maximum value to show on that axis;

-          !, followed by any axis options;

-          #, followed by any axis “renderer” options

The <graphOptions>, if specified, may include:

-          A, followed by the ID of the graph, to indicate that this graph should trigger a “GRAPH” event when clicked;

-          B, followed by 0 to suppress the border ("B0") or a number to change the border width (for example, "B3") around the graph;

-          C followed by a number to 'combine' smaller slices in a pie chart - the number (from 0-1) specifies the minimum percentage value to show as an individual slice (JQPLOT ONLY);

-          K to indicate that the previous contents of the section where the graph is being drawn should be kept (normally, the graphing library will clear the section where the graph is being rendered);

-          L, followed by 1 to explicitly enable ("L1") or 0 to disable ("L0") the display of legends;

-          N1, to specify that empty string values should be replaced with nulls (GOOGLE VISUALIZATIONS ONLY);

-          S, followed by any series options (GOOGLE VISUALIZATION ONLY);

-          U followed by any specific “user options” text you need to supply to the graphics library;

-          W0 to instruct O4W to suppress the warning message if no data is available for the graph;

-          Z, to disable "zooming" on the graph data (JQPLOT ONLY);

-          !, followed by any series-specific user options;

-          #, followed by any series-specific “renderer” options

 

To add data to the graph, call O4WGraphData one or more times.  Specify the <ID> of the graph this data belongs to, and the <Series> that the specific data points belong to.  <xValue> is an @VM-delimited list of the x-values, and <yValue> is an associated @VM-delimited list of y-values, to add to this series of the graph.  On some graphs, where xValues would just be an incremental counter (1,2,3,...), you may leave the <xValue> null and O4WGraph will automatically generate the sequential values.  You can send data for more than one series in a single O4WGraphData call; specify multiple <seriesName> values, @FM delimited, and multiple <xValue> and <yValue> sets, associated @FM delimited.

When all the data has been specified for the graph, calling O4WGraphEnd will generate the actual graph.

 

**//O4WHelpStyle//****//(<stylename>, <helptext>)//**

Creates a 'style' that, when applied to any input control or link, generates "bubble help" when the user hovers their mouse on that control.  The text of the "bubble help" is specified in the <helptext> parameter.  Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.

 

=== O4W Toolkit Input Control functions ===

 

== O4WSTORE(<text>, <name>, <id>) ==

Creates a "hidden" textbox on the web page, useful for storing information that you may wish to retrieve later, or use programmatically in scripting.

== O4WBUTTON(<text>, <id>, <style>) ==

== O4WIMAGEBUTTON(<text>, <url>, <id>, <style>) ==

Generates a pushbutton on the form at the current location, with the label <text>.  If this is an O4WImageButton, then the image located at <url> is used as the button image.  <ID> specifies the name of the button, which is used when setting or querying it.  This button can also be addressed through style sheets individually by <ID>; if <style> is specified, the style is applied to the button that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.  If the O4WMarkedOptions "checked" flag is set to "1" and passed into the O4WBUTTON or O4WIMAGEBUTTON, the button is turned into a "submit" button; if the "checked" flag is set to "0", then the button will not automatically generate a "form" for any input controls in the current section (as it otherwise would).

== O4WTIMER(<#seconds>,<bIsRepeating>,<extraParams>,<ID>,<updateFlag>) ==

Creates a timer that fires after the specified # of seconds (which may be fractional).  If <bIsRepeating> is set to '1', the timer will fire repeatedly at the specified interval.  When the timer fires, a "TIMER" event is sent back to the O4W commuter module (and, similar to an O4WBUTTON 'click' event, the values of input controls associated with the current section will be submitted to the O4W commuter module).  If <extraParams> are specified, they will be passed back to the O4W commuter module when the timer fires as well.  Specifying <ID> allows the programmer to give the timer a unique name; this name can also be used to cancel the timer (by passing <#seconds> set to "0").  To reset an existing timer (either to cancel the timer, or to change the timer interval), set the <updateFlag> parameter to “1”.

== O4WTEXTBOX(<text>, <size>, <maxlen>, <name>, <id>, <style>) ==

== O4WPWDBOX(<text>, <size>, <maxlen>, <name>, <id>, <style>) ==

Both the O4WTextBox and O4WPwdBox create an input "textbox" on the web page at the current location, using <text> as the default text.  When the user types into the O4WPwdBox, however, the characters are hidden.  If <size> is specified, it defines the size (in characters) of the textbox on the web page; if <maxlen> is specified, it defines the maximum number of characters the textbox will accept.  <Name> specifies the name of the textbox, which is used when setting or querying it.  This textbox can also be addressed through style sheets individually by <ID>; if <style> is specified, the style is applied to the textbox that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.

== O4WDATEPICKER(<text>, <size>, <euroFlag>, <delimChar>, <name>, <id>, <style>) ==

Creates an input "date picker" control on the web page at the current location, using <text> as the default date (in external format).  If <size> is specified, it defines the size (in characters) of the associated textbox on the web page.  If <euroFlag> is set to “1”, then dates are interpreted and displayed in European format.  If <euroFlag> is seto to “-1”, then dates are interpreted and displayed in YYYY-MM-DD format.  If <delimChar> is specified, it is the delimiter character to use between the month, day, and year segments of the date.  <Name> specifies the name of the date picker control, which is used when setting or querying it.  This control can also be addressed through style sheets individually by <ID>; if <style> is specified, the style is applied to the control that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.

== O4WTIMEPICKER(<text>, <size>, <24Flag>, <secondsFlag>, <name>, <id>, <style>) ==

Creates an input "time picker" control on the web page at the current location, using <text> as the default time (in external format).  If <size> is specified, it defines the size (in characters) of the associated textbox on the web page.  If <24Flag> is set to “1”, then times are interpreted and displayed in 24-hour (“military”) format.  If <secondsFlag> is set to “1”, then seconds are also displayed.  <Name> specifies the name of the time picker control, which is used when setting or querying it.  This control can also be addressed through style sheets individually by <ID>; if <style> is specified, the style is applied to the control that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.

== O4WCOLORPICKER(<text>, <size>, <name>, <id>, <style>) ==

Creates an input "color picker" control on the web page at the current location, using <text> as the default color value (as either a named color, or in HTML “hex format” with a leading “#” character).  If <size> is specified, it defines the size (in characters) of the associated textbox on the web page. <Name> specifies the name of the color picker control, which is used when setting or querying it.  This control can also be addressed through style sheets individually by <ID>; if <style> is specified, the style is applied to the control that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.

== O4WTEXTAREA(<text>, <cols>, <rows>, <wrap>, <name>, <id>, <style>) ==

Creates an input "text area" on the web page at the current location, using <text> as the default text.  If <cols> is not specified, it defaults to 20 characters; if <rows> is not specified, it defaults to 5 rows.  <Wrap> may be specified as "0" (no wrap) (the default), "1" (soft wrap), or "2" (hard wrap). <ID> specifies the name of the text area, which is used when setting or querying it.  This text area can also be addressed through style sheets individually by <ID>; if <style> is specified, the style is applied to the text area that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.

== O4WLISTBOXSTART(<name>,<ID>,<style>) ==

Call the O4WListBoxStart API when you with to begin building output into an O4W list box.  Using the O4WListBoxStart call, it is possible to provide the overall listbox with a unique identifier.  Specify the name of the listbox in the “Name” parameter, a unique identifier in the “ID” parameter, and any style information in the “StyleInfo” parameter. 

Example:

<code>
O4WListBoxStart(“state”, “thisState”)
O4WListBox(“Arizona”:@VM:”California”:@VM:”New Jersey”:@VM:”New York”, “AZ”:@VM:”CA”:@VM:”NJ”:@VM:”NY”, “state”)
O4WListBoxend()
</code>

== O4WLISTBOX(<text>, <value>, <name>, <group>, <ID>, <style>) ==

Creates an entry in the listbox named <name> which will return <value> when selected.  If <group> is specified, then <text> and <value> is grouped within <group>.  If the O4WMarkedOptions "checked" flag is set, then that specific <text> will be selected, or alternatively use the O4WMarkedOptions “currValue” parameter to specify one or more selected entries.

== O4WLISTBOXEND() ==

Completes the construction of the current list box.  Note that you must call O4WListBoxEnd() for each O4WListBoxStart().

== O4WCHECKBOX(<text>,<value>,<name>,<ID>,<style>) ==

== O4WRADIOBUTTON(<text>,<value>,<name>,<ID>,<style>) ==

Creates a radio button or check box which will return <value> when the button or box is selected.  <Text> is displayed as the label for this button.  <ID> is the unique ID for the radio button or checkbox, and <style> is the name of the style to apply.  Multiple radio buttons and check boxes can be created at one time by having multiple <text>, <value>, and <ID> fields (@VM delimited).  <Name> identifies the radio button or checkbox "group"; all buttons that should work together should have the same <name>.  Use the O4WMarkedOptions "checked" flag to check (when set to "1") or uncheck (when set to "0") the checkbox and radiobutton as desired, or the O4WMarkedOptions “currValue” parameter to explicitly enumerate which elements should be checked.  You may also use the O4WHTMLOptions style to specify that the <text> parameter contains HTML instead of plain text. 

== O4WUPLOADBOX(<default>, <destination>, <length>, <name>, <id>, <style>) ==

Creates a "file upload" textbox with a size <length>.  The uploaded file will be placed at the specified <destination>; if this is in the form <tablename><space><record>, it will be copied into OI.  If <destination> is empty, the contents of the file will be available through O4WGetValue.  If <destination> is not null, it can contain the "^" character (which will be replaced by the original file name) and the "$" character (which will be replaced by the original file extension). You can also retrieve additional file information by getting the values for <ID>.length (the file length), <ID>.contenttype, and <ID>.filename (the original uploaded file name and extension). If no file is uploaded, <default> will be returned as the value of the control. <ID> is the unique ID of the uploadbox, and <name> identifies the upload when the form is returned from the browser.  If <style> is specified, the style is applied to the textbox that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.

== O4WTABOX(<default>, <size>, <name>, <SourceType>, <Param1>, <Param2>, <Param3>, <Param4>, <param5>, <ID>, <STYLE>) ==

Creates a "type ahead list box", with the default value set to <default>.  The data for the list box can either be provided as explicit text (with <sourceType> "0"), via a "code file" (<sourceType> "1"), via a "code record" (<sourceType> "2"), via a subroutine (<sourceType> "3"), or via a standard codes record (<sourceType> "4").  If <sourceType> is "0" , <Param1> should contain an @VM delimited list of "display text", and <Param2> should contain an associated @VM delimited list of "codes".  For <sourceType> "1", <Param1> should contain the name of the table,  <Param2> should contain the field number in each record that contains the value to display, <Param3> contains an (optional) sort statement (if not specified, "SELECT <PARAM1> BY @ID" is used), <Param4> contains an (optional) select criteria (which will be AND'ed to any characters typed in), and <Param5> contains the specification of how to match the input string (see below).  If <SourceType> is "2", <Param1> contains the name of the table, <Param2> contains the name of the "code record", <param3> contains the field number where the "display text" can be found, <param4> contains the field number where the "codes" can be found, and <Param5> contains the specification of how to match the input string (see below).  For <sourceType> "3", <Param1> contains the name of the stored procedure.  For <sourceType> "4", <param1> contains the name of the standard code record to use, and <Param5> contains the specification of how to match the input string.  If <sourceType> is "1", "2", or "4", <param5> can be set to "" (to use a case-insensitive match, returning any codes and text that contain the input string), "0" (to use a case-sensitive match, returning any codes and text that contain the input string), "1" (to use a case-insensitive match, returning any codes and text that begin with the input string), or "-1" (to use a case-sensitive match, returning any codes and text that begin with the input string).

 

**//O4WIconButton//****//(buttonText, iconName, iconLocation, ID, styleInfo)//**

Creates a new button with the specified buttonText (if any), using the icon specified in iconName.  If IconLocation is the literal "right" or the value "2", then the icon is placed to the right of the text (otherwise, the icon is placed to the left of the text).  The ID specifies the ID of the button that is created.  Any additional style information can be passed in the StyleInfo parameter.

 

**//O4WLinkedIn//****//(action, param1, param2, param3, param4, styleInfo)//**

Provides various linkedIn functionality, including alternative access to the new linkedIn link types. Action can be "INIT" (the default), "COMPANY", "SHARE", and "PROFILE".  "INIT" loads the required linkedIn scripts.  "SHARE" generates a "share" icon for linkedIn; param1 contains the URL to share, param2, contains the optional title, param3 contains the optional linkedIn name of the person who is sharing the reference, and param4 contains the optional summary.  "PROFILE" shows the linkedIn profile; param1 contains the linkedIn username to show, param2 contains the optional text to display, and param3 controls the type of display ("0" or "" for popup (the default), "1" for inline).  "COMPANY" displays the linkedIn "Company Profiler"; param1 is the company name, param2 is the optional name of the O4W section where this information should be displayed (if not specified, a new section will be created at the current location), and param3 controls the type of display ("" (the default) for popup, "0" for a borderless in-line display, and "1" for a bordered in-line display)

 

**//O4WFacebook//****//(action, param1, param2, param3, param4, styleInfo)//**

Provides various Facebook functionality.  Action can be "INIT" (the default), "ACTIVITY", "LOGIN", "LIKE", "LIKEBOX", "LIVE_STREAM", "FACEPILE", "COMMENTS", and "RECOMMEND". "INIT" loads the required FaceBook scripts; param1 must contain the "appid" your application has received from FaceBook, and param2 contains the optional url to use for initialization (normally this would only be overridden if you wished to use a non-English interface).  "LOGIN" generates a Facebook login button on the page; param1 is a flag to indicate whether you wish to show the users face when they have logged in (pass "1" to set this flag), param2 optinally indicates the maximum number of rows the login should consume, and an optional width can be passed via the styleInfo parameter.  "LIKE" generates a Facebook "like" button; param1 is the optional URL to "like" (if not specified, the current page URL is used), param2 optionally controls the display of the like button ("0" for the standard display without faces; "1" (the default) for the standard display with faces; "2" to display as a button with a count; and "3" to display as a box with a count), param3 optionally controls the color scheme (set to "1" to use the alternative "dark" color scheme), and param4 is the optional keyword to use (set to "1" to use the alternative "recommend" instead of the default "like" keyword), and an optional width and font can be passed via StyleInfo.  "LIKEBOX" generates a Facebook "like box"; param1 is the URL to like, param2 optionally controls the display of the like box ("" (the default) to specify a normal like box; "0" to display without either a header or a stream; "1" to display with a header but no stream; and "2" to display with a stream but no header), param3 optionally contains the connections information, and an optional width can be specified via the StyleInfo.  "FACEPILE" generates a Facebook facepile; param1 optionally specifies the maximum number of rows to display, and an optional width can be passed via StyleInfo.  "LIVE_STREAM" displays the Facebook stream; param1 must contain the appid of the application whose stream you wish to display, param2 optionally contains a unique ID to associate with the stream, and an optional width and height can be specified via StyleInfo.  "COMMENTS" creates a Facebook comment box; param1 contains an optional unique ID, param2 contains an optional maximum number of posts to show, and an optional width can be specified via StyleInfo.  "ACTIVITY" displays Facebook activity information; param1 contains the optional domain to display information about, param2 otionally controls display of the information ("" (the default) for a normal display; "0" for a display without headers or recommendations; "1" for headers but no recommendations; "2" for recommendations but no headers), param3 optionally controls the color scheme (specify "1" to use the "dark" color scheme instead of the default light color scheme), param4 optionally specifies the border color, and optional width, height and font can be specified via StyleInfo.    "RECOMMEND" displays a Facebook recommend box; param1 contains the optional domain to recommend, param2 otionally controls display of the information ("" (the default) for a normal display; "0" for a display without headers), param3 optionally controls the color scheme (specify "1" to use the "dark" color scheme instead of the default light color scheme), param4 optionally specifies the border color, and optional width, height and font can be specified via StyleInfo.

 

**//O4WAddThis//****//(ID, userID, displayText, styleInfo)//**

Creates an "Add This" ([[http://www.addthis.com|www.addthis.com]]) link on the browser page allowing the user to share on Twitter, via email, print, FaceBook, etc.  ID contains the unique ID to use for the addthis link; userID is the optional sharethis user ID (used if tracking analytics information); displayText is the text to show (defaults to "Bookmark and Share"); styleInfo contains any O4W style information (specifically height and width) that might be applied to the addthis graphic.  Note that if the addthis link is not going to be displayed during the create event, users should still call O4WAddThis() with no parameters to initialize the control during the create event.


=== O4W Toolkit Action functions ===

== O4WSCRIPT(<scriptname>, <scriptsource>) ==

Attaches either a link to an external script file (if <scriptname> is specified), or adds in the explicit javascript (if <scriptsource> is specified)

== O4WQUALIFYEVENT(<id>, <event>, <param1>, <param2>,<param3>) ==

The O4WQualifyEvent API is a very powerful, multi-purpose call.  In general, it tells O4W to trigger, or watch for, the specified <event> on the named <id>.  O4WQualifyEvent can also be called as a function; it will return 0 if the requested event was invalid and not processed. Depending on the value of the <event> parameter, an event may be triggered in the O4W commuter module, or an action may be executed on the client (browser), or both.  Below are more details describing the various parameters and actions for each supported event. Currently supported <event> values include:

 

- "CLICK";

- "VALIDATE";

- "SUBMIT";

- "RESET";

- "LOSTFOCUS" (also known as “BLUR”, “ONBLUR”, and “POST_FIELD”);

- “GOTFOCUS” (also known as “FOCUS”, “ONFOCUS”  and “PRE_FIELD”);

- “CHANGED”

- "TOGGLE";

- "SHOW";

- "HIDE";

- "CHANGE";

- “TAB”;

- "TABNEXT";

- "TABBACK";

- "DELETEROW";

- "INSERTROW";

- “DELETECOL”;

- “INSERTCOL”;

- "COPYROW";

- “COPYCOL”;

- "ADDTOTABLE";

- "DELETEFROMTABLE";

- “ADDTOTABLECOL”;

- “DELETEFROMTABLECOL”;

- "MOVE";

- "COPY";

- "REMOVE";

- "SELECT";

- "SHOWWHENSELECTED";

- "SHOWWHENNOTSELECTED";

- “REDIRECT”;

- “CUSTOM_xxx” (for user-definable events)


==  Click/Change Events ==

**Event:** CLICK (synonym: TAB)

**Description:** Tells O4W to notify the commuter module when the specified control is pressed

**Generates event in O4W commuter module:** CLICK event

**ID:** ID of button (or other control) to watch for click

**Param1:** N/A

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WButton(“Press me!”, “BTN_GO”)

O4WQualifyEvent(“BTN_GO”,”CLICK”)
</code>
 

**Event:** MENUCLICK

**Description:** Activates a click event when a menu item is selected, where the click event “pretends” it comes from a button

**Generates event in O4W commuter module:** CLICK event

**ID:** ID of menu item

**Param1:** ID to pass in (normally, the ID of a button this menu item is pretending to be)

**Param2:** N/A

**Param3:** N/A

 

**Event:** TABNEXT

**Description:** Move to the next tab in the tab set

**Generates event in O4W commuter module:**  TAB event, with additional values O4WTab (new tab number) and O4WPrevTab (previous tab number) which can be retrieved with O4WGetValue

**ID:** ID of button (or other control) to watch for click event

**Param1:** (Optional) Any additional name/value pairs to pass down to the commuter module with the TAB notification (for example, “COMPANY=REVELATION&PRODUCT=OI”); these values can be retrieved using O4WGetValue

**Param2:** The ID of the tab section

**Param3:** (Optional) 1 = disable the previous tab after moving to the next tab

**Example:**

 
<code>
O4WTabs(“ourTabs”, “sectOne”:@VM:”sectTwo”,”First Tab”:@VM:”Second Tab”)

…

O4WButton("< Back", "BTNBACK")

O4WButton("Next >", "BTNNEXT")

O4WQualifyEvent("BTNBACK", "TABBACK",'',”ourTabs”)

O4WQualifyEvent("BTNNEXT", "TABNEXT",'',”ourTabs”)
</code>
 

**Event:** TABBACK

**Description:** Move to the previous tab in the tab set

**Generates event in O4W commuter module:**  TAB event, with additional values O4WTab (new tab number) and O4WPrevTab (previous tab number) which can be retrieved with O4WGetValue

**ID:** ID of button (or other control) to watch for click event

**Param1:** (Optional) Any additional name/value pairs to pass down to the commuter module with the TAB notification (for example, “COMPANY=REVELATION&PRODUCT=OI”); these values can be retrieved using O4WGetValue

**Param2:** The ID of the tab section

**Param3:** (Optional) 1 = disable the previous tab after moving to the previous tab

**Example:**

 
<code>
O4WTabs(“ourTabs”, “sectOne”:@VM:”sectTwo”,”First Tab”:@VM:”Second Tab”)

…

O4WButton("< Back", "BTNBACK")

O4WButton("Next >", "BTNNEXT")

O4WQualifyEvent("BTNBACK", "TABBACK",'',”ourTabs”)

O4WQualifyEvent("BTNNEXT", "TABNEXT",'',”ourTabs”)
</code>
 

**Event:** CHANGE

**Description:** Generate CHANGE event when the value of the specified element changes

**Generates event in O4W commuter module:** CHANGE event, with additional values O4WChangeID (ID of element that changed) and O4WChangeValue (new value of element that changed) which can be retrieved with O4WGetValue

**ID:** ID of element to watch, or NAME of element to watch

**Param1:** Type of control specified in ID parameter (values are “listbox”, “radio”, “checkbox”, or “textbox”)

**Param2:** (Optional) Any additional name/value pairs to pass down to the commuter module with the CHANGE notification (for example, “COMPANY=REVELATION&PRODUCT=OI”); these values can be retrieved using O4WGetValue

**Param3:** N/A

**Example:**

 
<code>
O4WTextbox(“”, “”, “”, “CONTACT”)

O4WQualifyEvent(“CONTACT”, “CHANGE”, “TEXTBOX”)
</code>
 

== Client-side UI/Animation Events ==

**Event:** TOGGLE

**Description:** Alternately hides and shows the specified element

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for a click, or “” to have the toggle event happen as soon as the form is loaded, or “.<classname>” to watch for any element of the specified class

**Param1:** ID of element (normally section) to alternately hide and show

**Param2:** (Optional) speed of animation

**Param3:** N/A

**Example:**

 
<code>
O4WSectionStart(“helpSection”)

O4WText(“Here is some help text”)

O4WSectionEnd(“helpSection”)

O4WButton(“Toggle help section”, “BTN_TOGGLE”)

O4WQualifyEvent(“BTN_TOGGLE”, “TOGGLE”)
</code>
 

**Event:** HIDE

**Description:** Hides the specified element

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for a click, or “” to have the hide event happen as soon as the form is loaded, or “.<classname>” to watch for any element of the specified class

**Param1:** ID of element (normally section) to hide

**Param2:** (Optional) speed of animation

**Param3:** N/A

**Example:**

 
<code>
O4WSectionStart(“helpSection”)

O4WText(“Here is some help text”)

O4WSectionEnd(“helpSection”)

O4WButton(“Hide help section”, “BTN_HIDE”)

O4WButton(“Show help section”, “BTN_SHOW”)

O4WQualifyEvent(“BTN_HIDE”, “HIDE”)

O4WQualifyEvent(“BTN_SHOW”, “SHOW”)
</code>
 

**Event:** SHOW

**Description:** Shows (un-hides) the specified element

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for a click, or “” to have the show event happen as soon as the form is loaded, or “.<classname>” to watch for any element of the specified class

**Param1:** ID of element (normally section) to show

**Param2:** (Optional) speed of animation

**Param3:** N/A

**Example:**

 
<code>
O4WSectionStart(“helpSection”)

O4WText(“Here is some help text”)

O4WSectionEnd(“helpSection”)

O4WButton(“Hide help section”, “BTN_HIDE”)

O4WButton(“Show help section”, “BTN_SHOW”)

O4WQualifyEvent(“BTN_HIDE”, “HIDE”)

O4WQualifyEvent(“BTN_SHOW”, “SHOW”)
</code>
 

**Event:** SHOWWHENSELECTED

**Description:** Display (unhide) the specified element(s) when the specified watched elements are selected, and hides the specified element(s) when the specified watched elements are NOT selected

**Generates event in O4W commuter module:**  No – client side only

**ID:** ID(s) of elements to watch for selection (multiple IDs are separated by @VM)

**Param1:** Name of element to watch for selection (all IDs must share this name)

**Param2:** ID(s) of elements to show or hide (multiple IDs are separated by @VM)

**Param3:** N/A

**Example:**

 
<code>
O4WCheckBox("Change ALL selection label properties to match this?", "1", "dlgDOALL", "dlgDOALL_ID")

O4WSetCell(2,3, "DOALLCONFIRM1")

O4WText("This will change ALL selection label properties (colors and width)")

O4WQualifyEvent("", "hide", "DOALLCONFIRM1")

O4WQualifyEvent("dlgDOALL_ID", "showwhenselected", "dlgDOALL", "DOALLCONFIRM1")
</code>
 

**Event:** SHOWWHENNOTSELECTED

**Description:** Display (unhide) the specified element(s) when the specified watched elements are NOT selected, and hides the specified element(s) when the specified watched elements are selected

**Generates event in O4W commuter module:**  No – client side only

**ID:** ID(s) of elements to watch for selection (multiple IDs are separated by @VM)

**Param1:** Name of element to watch for selection (all IDs must share this name)

**Param2:** ID(s) of elements to show or hide (multiple IDs are separated by @VM)

**Param3:** N/A

**Example:**

 
<code>
O4WListBox("Plain text (not editable)", "<none>", 'dlgMOD','' , 'dlgMODNONE')

If isUserDef Then

   O4WListBox('Button', 'B', 'dlgMOD','' , 'dlgMODB')

end

O4WListBox('Textbox', 'T', 'dlgMOD','' , 'dlgMODT')

O4WListBox('Password', 'P', 'dlgMOD','' , 'dlgMODP')

…

O4WSectionStart("dlgProp1", O4WMarkedStyle('','0'))

O4WTableStart("dlgProp1Table", 'pct100')

O4WText("Default value (on new record entry): ")

O4WSetCell(1,2)

O4WListBox('Current date', '1', 'dlgDefault','' , 'dlgDefault1')

O4WListBox('Current time', '2', 'dlgDefault','' , 'dlgDefault2')

O4WTableEnd("dlgProp1Table")

O4WSectionEnd(“dlgProp1”)

…

O4WQualifyEvent("dlgMODB", "showwhennotselected", "dlgMOD", "dlgProp1Table")
</code>
 

== Other Client-Side Control Events ==

**Event:** MOVE

**Description:** Move the selected element(s) from the source control to the destination control

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class, or “” to trigger event as soon as the page is loaded

**Param1:** ID of the source element (normally listbox or textbox)

**Param2:** ID of the destination element (normally listbox or textbox)

**Param3:** N/A

**Example:**

 
<code>
O4WListbox(“”, “”, “MYDEST”, “”, “MYDEST”)

O4WListbox(“A”:@VM:”B”:@VM:”C”,”A”:@VM:”B”:@VM:”C”,”MYSOURCE”, “”, “MYSOURCE”)

O4WButton(“Move…”, “BTN_MOVE”)

O4WQualifyEvent(“BTN_MOVE”, “MOVE”, “MYSOURCE”, “MYDEST”)
</code>
 

**Event:** COPY

**Description:** Duplicate the selected element(s) from the source control to the destination control

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class, or “” to trigger event as soon as the page is loaded

**Param1:** ID of the source element (normally listbox or textbox)

**Param2:** ID of the destination element (normally listbox or textbox)

**Param3:** N/A

**Example:**

 
<code>
O4WListbox(“”, “”, “MYDEST”, “”, “MYDEST”)

O4WListbox(“A”:@VM:”B”:@VM:”C”,”A”:@VM:”B”:@VM:”C”,”MYSOURCE”, “”, “MYSOURCE”)

O4WButton(“Copy…”, “BTN_COPY”)

O4WQualifyEvent(“BTN_COPY”, “COPY”, “MYSOURCE”, “MYDEST”)
</code>
 

**Event:** REMOVE

**Description:** Delete the selected element(s) from the source control

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class, or “” to trigger event as soon as the page is loaded

**Param1:** ID of the source element (normally listbox or textbox)

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WListbox(“A”:@VM:”B”:@VM:”C”,”A”:@VM:”B”:@VM:”C”,”MYSOURCE”, “”, “MYSOURCE”)

O4WButton(“Delete…”, “BTN_DEL”)

O4WQualifyEvent(“BTN_DEL”, “REMOVE”, “MYSOURCE”)
</code>
 

**Event:** SELECT

**Description:** Select or deselect all elements in the source control

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class, or “” to trigger event as soon as the page is loaded

**Param1:** ID of the source element (a multi-select listbox)

**Param2:** 1 (select) or 0 (deselect)

**Param3:** N/A

**Example:**

 
<code>
O4WListbox(“A”:@VM:”B”:@VM:”C”,”A”:@VM:”B”:@VM:”C”,”MYSOURCE”, “”, “MYSOURCE”, O4WListboxOptions(‘1’))

O4WButton(“Select All…”, “BTN_SEL”)

O4WQualifyEvent(“BTN_SEL”, “SELECT”, “1”)
</code>
 

== Focus Events ==

**Event:** LOSTFOCUS (synonyms: BLUR, ONBLUR, and POST_FIELD)

**Description:** Generates an event when the specified control “loses focus”

**Generates event in O4W commuter module:** LOSTFOCUS event, or POST_FIELD event if POST_FIELD specified as event name

**ID:** ID of element to watch for lost focus event

**Param1:** (Optional) Any additional name/value pairs to pass down to the commuter module with the event notification (for example, “COMPANY=REVELATION&PRODUCT=OI”); these values can be retrieved using O4WGetValue

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WTextbox(“”, “”, “”, “CONTACTNO”, “CONTACTNO”)

O4WQualifyEvent(“CONTACTNO”, “LOSTFOCUS”)
</code>
 

**Event:** GOTFOCUS (synonyms: FOCUS, ONFOCUS, and PRE_FIELD)

**Description:** Generates an event when the specified control “gets focus”

**Generates event in O4W commuter module:** GOTFOCUS event, or PRE_FIELD event if PRE_FIELD specified as event name

**ID:** ID of element to watch for focus event

**Param1:** (Optional) Any additional name/value pairs to pass down to the commuter module with the event notification (for example, “COMPANY=REVELATION&PRODUCT=OI”); these values can be retrieved using O4WGetValue

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WTextbox(“”, “”, “”, “CONTACTNO”, “CONTACTNO”)

O4WQualifyEvent(“CONTACTNO”, “GOTFOCUS”)
</code>
 

**Event:** LOSTFOCUS-CHANGED (synonyms: CHANGED)

**Description:** Generates an event when the specified control has been modified.  Note that this event, unlike the CHANGE event, will only work with an explicit ID, and may not work properly with non-textbox controls

**Generates event in O4W commuter module:** LOSTFOCUS-CHANGED event or CHANGED event

**ID:** ID of element to watch for changed event

**Param1:** (Optional) Any additional name/value pairs to pass down to the commuter module with the event notification (for example, “COMPANY=REVELATION&PRODUCT=OI”); these values can be retrieved using O4WGetValue

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WTextbox(“”, “”, “”, “CONTACTNO”, “CONTACTNO”)

O4WQualifyEvent(“CONTACTNO”, “CHANGED”)
</code>
 

== Validation Events ==

**Event:** VALIDATE

**Description:** Perform any validations (set through O4WVALIDATEOPTIONS) and generate a VALIDATE event to the commuter module

**Generates event in O4W commuter module:** VALIDATE event

**ID:** ID of button (or other control) to watch for the click event

**Param1:** (Optional) Any additional name/value pairs to pass down to the commuter module with the event notification (for example, “COMPANY=REVELATION&PRODUCT=OI”); these values can be retrieved using O4WGetValue

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WTextbox(“”, “”, “”, “CC_NO”, “CC_NO”, O4WValidateOptions(O4W_VALIDATE_CC$))

O4WButton(“Validate”, “BTN_VALIDATE”)

O4WButton(“Reset Validations”, “BTN_RESET”)

O4WQualifyEvent(“BTN_VALIDATE”, “VALIDATE”)

O4WQualifyEvent(“BTN_RESET”, “RESET”)
</code>
 

**Event:** RESET

**Description:** Resets any failed validations (set through O4WVALIDATEOPTIONS) and generates a RESET event to the commuter module

**Generates event in O4W commuter module:** RESET event

**ID:** ID of button (or other control) to watch for the click event

**Param1:** (Optional) Any additional name/value pairs to pass down to the commuter module with the event notification (for example, “COMPANY=REVELATION&PRODUCT=OI”); these values can be retrieved using O4WGetValue

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WTextbox(“”, “”, “”, “CC_NO”, “CC_NO”, O4WValidateOptions(O4W_VALIDATE_CC$))

O4WButton(“Validate”, “BTN_VALIDATE”)

O4WButton(“Reset Validations”, “BTN_RESET”)

O4WQualifyEvent(“BTN_VALIDATE”, “VALIDATE”)

O4WQualifyEvent(“BTN_RESET”, “RESET”)
</code>
 

**Event:** SUBMIT

**Description:** Perform any validations (set through O4WVALIDATEOPTIONS) and SUBMIT all user input values to the commuter module (these values can all be retrieved with O4WGetValue). The SUBMIT event is normally the final event performed on a form; subsequent actions should take place after a new O4WForm() call

**Generates event in O4W commuter module:** SUBMIT event

**ID:** ID of button (or other control) to watch for the click event

**Param1:** (Optional) Any additional name/value pairs to pass down to the commuter module with the event notification (for example, “COMPANY=REVELATION&PRODUCT=OI”); these values can be retrieved using O4WGetValue

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WButton(“Submit”, “BTN_SUBMIT”)

O4WQualifyEvent(“BTN_SUBMIT”, “SUBMIT”)
</code>
 

== Table Management Events ==

**Event:** DELETEROW

**Description:** Remove row of table when specified button is pressed (note: button must be inside the table row that is to be deleted)

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class

**Param1:** N/A

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WTableStart(“sampleTable”)

O4WSetCell(1,1)

O4WButton(“Del”, “BTN_DEL_1”)

O4WButton(“Ins”, “BTN_INS_1”)

O4WSetCell()

O4WTextbox(“”, “”, “”, “NAME”)

O4WSetCell()

O4WTextbox(“”,””,””,”CONTACT_NO”)

O4WTableEnd(“sampleTable”)

O4WQualifyEvent(“BTN_DEL_1”, “DELETEROW”)

O4WQualifyEvent(“BTN_INS_1”, “INSERTROW”)
</code>
 

**Event:** INSERTROW

**Description:** Adds row to table when specified button is pressed (note: button must be inside the table row) – new row is inserted with all input controls blanked

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class

**Param1:** N/A

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WTableStart(“sampleTable”)

O4WSetCell(1,1)

O4WButton(“Del”, “BTN_DEL_1”)

O4WButton(“Ins”, “BTN_INS_1”)

O4WSetCell()

O4WTextbox(“”, “”, “”, “NAME”)

O4WSetCell()

O4WTextbox(“”,””,””,”CONTACT_NO”)

O4WTableEnd(“sampleTable”)

O4WQualifyEvent(“BTN_DEL_1”, “DELETEROW”)

O4WQualifyEvent(“BTN_INS_1”, “INSERTROW”)
</code>
 

**Event:** COPYROW

**Description:** Duplicates row of table when specified button is pressed (note: button must be inside the table row that is to be duplicated) – new row is inserted with all input control values copied from the current row

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class

**Param1:** N/A

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WTableStart(“sampleTable”)

O4WSetCell(1,1)

O4WButton(“Dup”, “BTN_DUP_1”, “dupbutton”)

O4WSetCell()

O4WTextbox(“”, “”, “”, “NAME”)

O4WSetCell()

O4WTextbox(“”,””,””,”CONTACT_NO”)

O4WTableEnd(“sampleTable”)

O4WQualifyEvent(“.dupbutton”, “COPYROW”)
</code>
 

**Event:** DELETECOL

**Description:** Remove column of table when specified button is pressed (note: button must be inside the table column that is to be deleted)

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class

**Param1:** N/A

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WTableStart(“sampleTable”)

O4WSetCell(1,1)

O4WButton(“Del”, “BTN_DEL_1”)

O4WButton(“Ins”, “BTN_INS_1”)

O4WSetCell(2)

O4WTextbox(“”, “”, “”, “NAME”)

O4WSetCell(3)

O4WTextbox(“”,””,””,”CONTACT_NO”)

O4WTableEnd(“sampleTable”)

O4WQualifyEvent(“BTN_DEL_1”, “DELETECOL)

O4WQualifyEvent(“BTN_INS_1”, “INSERTCOL”)
</code>
 

**Event:** INSERTCOL

**Description:** Adds column to table when specified button is pressed (note: button must be inside the table column) – new column is inserted with all input controls blanked

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class

**Param1:** N/A

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WTableStart(“sampleTable”)

O4WSetCell(1,1)

O4WButton(“Del”, “BTN_DEL_1”)

O4WButton(“Ins”, “BTN_INS_1”)

O4WSetCell(2,1)

O4WTextbox(“”, “”, “”, “NAME”)

O4WSetCell(3,1)

O4WTextbox(“”,””,””,”CONTACT_NO”)

O4WTableEnd(“sampleTable”)

O4WQualifyEvent(“BTN_DEL_1”, “DELETECOL”)

O4WQualifyEvent(“BTN_INS_1”, “INSERTCOL”)
</code>
 

**Event:** COPYCOL

**Description:** Duplicates column of table when specified button is pressed (note: button must be inside the table column that is to be duplicated) – new column is inserted with all input control values copied from the current column

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class

**Param1:** N/A

**Param2:** N/A

**Param3:** N/A

**Example:**

 
<code>
O4WTableStart(“sampleTable”)

O4WSetCell(1,1)

O4WButton(“Dup”, “BTN_DUP_1”, “dupbutton”)

O4WSetCell(2,1)

O4WTextbox(“”, “”, “”, “NAME”)

O4WSetCell(3,1)

O4WTextbox(“”,””,””,”CONTACT_NO”)

O4WTableEnd(“sampleTable”)

O4WQualifyEvent(“.dupbutton”, “COPYCOL”)
</code>
 

**Event:** ADDTOTABLE

**Description:** Add new row to table at the specified location

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class, or “” to trigger event as soon as the page is loaded

**Param1:** ID of the table

**Param2:** Location for the new row (0=top, -1=bottom)

**Param3:** N/A

**Example:**

 
<code>
O4WButton(“Add”, “BTN_ADD”)

O4WQualifyEvent(“BTN_ADD”, “ADDTOTABLE”, “sampleTable”)

O4WTableStart(“sampleTable”)

O4WTextbox(“”,””,””,”NAME”)

O4WSetCell()

O4WTextbox(“”,””,””,”CONTACT_NO”)

O4WTableEnd(“sampleTable”)
</code>
 

**Event:** DELETEFROMTABLE

**Description:** Delete row from table at the specified location

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class, or “” to trigger event as soon as the page is loaded

**Param1:** ID of the table

**Param2:** Location for the row to be deleted (0=top, -1=bottom)

**Param3:** N/A

**Example:**

 
<code>
O4WButton(“DEL”, “BTN_DEL”)

O4WQualifyEvent(“BTN_DEL”, “DELETEFROMTABLE”, “sampleTable”)

O4WTableStart(“sampleTable”)

O4WTextbox(“”,””,””,”NAME”)

O4WSetCell()

O4WTextbox(“”,””,””,”CONTACT_NO”)

O4WTableEnd(“sampleTable”)
</code>
 

**Event:** ADDTOTABLECOL

**Description:** Add new column to table at the specified location

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class, or “” to trigger event as soon as the page is loaded

**Param1:** ID of the table

**Param2:** Location for the new column (0=leftmost column, -1=rightmost column)

**Param3:** N/A

**Example:**

 
<code>
O4WButton(“Add”, “BTN_ADD”)

O4WQualifyEvent(“BTN_ADD”, “ADDTOTABLECOL”, “sampleTable”)

O4WTableStart(“sampleTable”)

O4WTextbox(“”,””,””,”NAME”)

O4WSetCell(2)

O4WTextbox(“”,””,””,”CONTACT_NO”)

O4WTableEnd(“sampleTable”)
</code>
 

**Event:** DELETEFROMTABLECOL

**Description:** Delete column from table at the specified location

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of button (or other control) to watch for click event, or “.<classname>” to watch for any element of the specified class, or “” to trigger event as soon as the page is loaded

**Param1:** ID of the table

**Param2:** Location for the column to be deleted (0=leftmost column, -1=rightmost column)

**Param3:** N/A

**Example:**

<code>
O4WButton(“DEL”, “BTN_DEL”)

O4WQualifyEvent(“BTN_DEL”, “DELETEFROMTABLECOL”, “sampleTable”)

O4WTableStart(“sampleTable”)

O4WTextbox(“”,””,””,”NAME”)

O4WSetCell(2)

O4WTextbox(“”,””,””,”CONTACT_NO”)

O4WTableEnd(“sampleTable”)
</code>
 

== Miscellaneous Events ==

**Event:** REDIRECT

**Description:** Redirect from the current page to the specified URL (similar to a link)

**Generates event in O4W commuter module:**  No – client side only

**ID:** ID of button (or other control) to watch for the click event, or “” to trigger event as soon as the page is loaded

**Param1:** Destination (URL, or special codes “<<close>>” to close the window or “<<back>>” to go back 1 page, or “<<back>>n” to go back “n” pages)

**Param2:** (Optional) Name of new tab/window to open

**Param3:** N/A

**Example:**

 
<code>
O4WButton(“Return to Revelation”, “BTN_REV”)

O4WQualifyEvent(“BTN_REV”, “REDIRECT”, “http://www.revelation.com”)
</code>
 

**Event:** ENCRYPT

**Description:** Encrypt the value in the specified control when it loses focus, using HMAC SHA1 encryption

**Generates event in O4W commuter module:** No – client side only

**ID:** ID of source control (typically a textbox)

**Param1:** ID of destination control (typically a hidden textbox)

**Param2:** ID of element containing the first hashing value (typically a hidden textbox)

**Param3:** (Optional) ID of element containing the second hashing value (typically a hidden textbox)

**Example:**

 
<code>
O4WPwdBox("",'' ,'' ,'' , "enteredPWD")

O4WStore("", "encryptPWD", "encryptPWD")

O4WStore(ourSalt, "ourSalt", "ourSalt")

O4WStore(DATE():'.':TIME(), "currTime", "currTime")

O4WQualifyEvent("enteredPWD", "ENCRYPT", "encryptPWD", "ourSalt", "currTime")
</code>
 

**Event:** CUSTOM_<userdefined>

**Description:** The CUSTOM event allows developers to specify any other event that’s natively supported by jQuery or their browser.  Specify CUSTOM_ followed by the name of the event.  Starting with release 10.2.2, the custom handler allows for additional parameters so that user scripts can be called before, or after, submitting the event to the host

**Generates event in O4W commuter module:** Defaults to <userdefined>, but can be overridden by parameter 2

**ID:** ID of element to watch for the specified event

**Param1:** (Optional) Any additional name/value pairs to pass down to the commuter module with the event notification (for example, “COMPANY=REVELATION&PRODUCT=OI”); these values can be retrieved using O4WGetValue

**Param2:** (Optional) Name of event to return to O4W commuter module instead of <userdefined> value

**Param3:** (Optional) In 10.2.2+, flag to specify that this is a "live" event and should persist even if this element is redrawn

**Param4:** (Optional) In 10.2.2+, script to invoke before sending the event to OI

**Param5:** (Optional) In 10.2.2+, script to invoke after sending the event to OI

**Example:**

 
<code>
O4WQualifyEvent(“txtDummy”, “CUSTOM_blur”)
</code>
 

== O4WPLUGIN(<id>, <functionname>, <options>) ==

The web framework O4W uses allows "plugins" to be specified for client-side functions.  <ID> specifies the name of the O4W control (display element or input control) which should be "attached" to the plugin; <functionname> is the name of the plugin function to invoke.  <Options> are any options that you wish to pass to the plugin.  Note that most plugins require an additional script to be added to your web page (see the O4WScript function), and possibly style sheets (see the O4WStyleSheet function). For example, to apply the jQuery "TableSorter" plugin to a table named RESULTS:

 
<code>
   O4WScript("/weboi/O4W/jquery.tablesorter.min.js")                        

   O4WScript("/weboi/O4W/jquery.tablesorter.pager.js")                      

   O4WStyleSheet("/weboi/O4W/style.css")                                    

   O4WPlugIn("RESULTS", "tablesorter", "{widthFixed: true, widgets: ['zebra']}" )
</code>

== O4WI_LOADPLUGINDATA(<id>) ==

This utility function will load the data associated with the specified plugin into the form.  This data may include stylesheet(s), javascript file(s), and explicit javascript command(s).  The control record for each plugin is stored in the O4WCODES table; currently defined control records include:

 

-          PLUGIN_COLORPICKER;

-          PLUGIN_COMBOBOX;

-          PLUGIN_DATEPICKER;

-          PLUGIN_HISTORY;

-          PLUGIN_HMENU;

-          PLUGIN_TABLESORTER;

-          PLUGIN_TIMEPICKER;

-          PLUGIN_TMENU

-          PLUGIN_VMENU

-           

For example, to load in the required data for the jQuery “tablesorter” plugin:

 
<code>
            O4WI_LoadPluginData(“PLUGIN_TABLESORTER”)
</code>

== O4WDIALOG(<id>, <title>, <buttonText>, <buttonID>, <options>, <clickIDS>, <className>) ==

Turns the specified element identified by <id> (normally a section) into a dialog.  <Title> is the title to show on the dialog and MUST be specified (calling O4WDialog with only <id> specified is the way to make the dialog disappear).  If you wish to have any buttons on the dialog, specify them (@VM delimited) in <buttonText>; <buttonID> is an associated list of the IDs to return to commuter module when the appropriate button has been clicked.  <Options> contains other options that you may wish to apply to the jQuery dialog function.  If <clickIDs> is specified, it contains the ID of a button or link to click on to activate the dialog in field 1, and the ID of a button or link to click on to hide the dialog in field 2.  If <className> is specified, the named style class will be applied to the dialog.

== O4WUPDATE(<id>, <text>, <style>) ==

This routine will update the specific selected routine with the specified style and/or text.  Note that the element named <id> must already exist, and that O4WResponseOptions should be specified.

== O4WPopup(<title>, <popupType>, <popupSrc>, <popupArgs>, <targetID>, <triggerID>, <triggerEvent>, <styleInfo>) ==

This routine generates a "popup" dialog box.  The source of the popup (as identified by the <popupType>, <popupSrc>, and <popupArgs> parameters) will be invoked (as though from the browser URL line), and is expected to return a value (in the case of the user-defined procedure, via the O4WPopupReturn call).  The invoking O4W Commuter Module will be called when the popup return value is ready; the CtlEntId will be whatever was specified in the <targetID> parameter of this call, the event will be "RETURNVALUE", and the value returned by the popup will be returned in the "o4wValue" variable.  If desired, you can also call O4WGetValue to return the name of the control that invoked the popup (found in the 'o4wPopupCtl' variable). For example:

 
<code>
            Case event _eqc "RETURNVALUE"

                        O4WResponse()

                        * get the return value

                        rtnValue = O4WGetValue('o4wValue')

                        * get the name of the control that invoked the popup

                        popupCtl = O4WGetValue('o4wPopupCtl')

                        * update the target with the returned value

                        O4WUpdate(ctlentid, rtnValue, O4WResponseOptions('1'))     

 <code>

<PopupType> specifies the type of source used for the popup - options include O4W_LINKTYPE_PROGRAM$ (for a user-defined O4W routine), O4W_LINKTYPE_REPORT$ (for an O4W_Report), O4W_LINKTYPE_POPUP$ (for an OI popup), or O4W_LINKTYPE_INDEXLOOKUP$ (for an OI IndexLookup).  If <PopupType> is O4W_LINKTYPE_PROGRAM$, <popupSrc> specifies the name of the routine to call, and <popupArgs> are passed as the value of the "o4wPopup" variable to the routine; if <PopupType> is O4W_LINKTYPE_REPORT$, <popupSrc> is the name of the O4W_REPORT to invoke, and <popupArgs> is the name of the field in the O4W_REPORT to use as the return value (if not specified, the @ID of any selected row is returned); if <popupType> is O4W_LINKTYPE_POPUP$, <popupSrc> is the name of the OI popup, and <popupArgs> is the "popup override" dynamic array.  If <popupType> is O4W_LINKTYPE_INDEXLOOKUP$, <popupSrc> is the (optional) name of the OI popup, and <popupArgs> contains 3 fields.  Field 1 is the table name to apply the index lookup to; field 2 is the list of fields to search (@VM delimited); and field 3 is the (optional) list of fields to display (@VM delimited).  If <triggerID> is specified, the popup will appear when the specified <triggerEvent> ("CLICK" (default), or "GOTFOCUS" or "LOSTFOCUS") occurs; if no <triggerID> is specified, the popup will appear when the form or response is sent back to the browser. <StyleInfo>, in all cases, identifies style properties that can be applied to the popup dialog (generally, the only applicable style is O4WSizeStyle).  For example:

 
<code>
                        O4WPopup('Test Popup', O4W_LINKTYPE_REPORT$, 'CUSTOMER', '@ID', 'targetTextBox', "", "", O4WSizeStyle('','600px','600px'))
</code>
 

O4WPopupReturn(<value>)

Returns the value specified in <value>, when called from within a popup.  This makes the value available to the calling routine.  When called from a non-popup environment, this call has no effect.


=== O4W Toolkit Utility functions ===

 

== O4WGOTOTAB(<tabSectionID>, <newTab>, <oldTab>) ==

Moves to the specified tab.  If <oldTab> is specified, it is disabled.

== O4WGOTOPAGE(<pageName>, <pageNumber>, <triggerID>, <addlParams>) ==

In mobile mode, moves to the mobile page specified in <pageName>; in desktop mode, “drops” the breadcrumb specified in <pageName>.  The value in <pageNumber> is passed back to the host in the PAGENO parameter (which can then be accessed via O4WGetValue). The <triggerID>, if specified, is the ID of the element whose “click” event we wish to emulate.  Any additional parameters (as specified in <addlParams>) are also passed back to the host.

== O4WFOCUS(<id>) ==

Sets focus to specified ID.

== O4WMenu(<menuName>, <errmsg>, <specificName>, <overrideType>, <styleInfo>) ==

The O4WMenu API call creates or updates a menu on the HTML page.  The location and type of the menu is determined by the location of special “tags” in the template.  These tags should be placed in the template wherever the menu should be displayed, along with an optional orientation to specify which type of menu should be used.  The standard tags are %MENU-H% (for a horizontal menu), %MENU-V% (for a vertical menu), %MENU-T% (for a tree menu), or %MENU% (to use the orientation specified in the configuration record).  A special tag, %MENU-NONE%, is used to indicate that no menu should be displayed.  Users can also create additional “named” menu tags for specific menus; these are accessed by specifying which named menu to use in the specificName parameter.  Specific menu tags can be placed in the template by using the format “%MENU.<specificname>{-<orientation>}%” (for example, “%MENU.leftside%” or “%MENU.top-H%”), where <orientation> can be “H” (for Horizontal), “V” (for vertical), “T” (for a tree menu), or “NONE” to indicate the menu should NOT be displayed.  If <orientation> is omitted, the default orientation specified in the configuration record is used.

If no menu tags are found for either the default or named menus, the menu is drawn at the current location in the “flow” of the web page output.

The “menuName” parameter contains either the name of a menu, created via the menu wizard, or the contents of a menu record if one is created dynamically.  The Errmsg parameter will be set if any errors occur during menu creation.  The SpecificName parameter is used to place the menu in a “named” menu location.  The overrideType parameter can be set to “0” to force a vertical menu, “1” to force a horizontal menu, or “2” to force a tree menu, to be displayed regardless of the orientation found in the tag.  StyleInfo contains any style settings that you wish to apply to the menu.

== O4WDownload(<filename>, <contentType>, <content>, <suggestedFilename>, <newWindowName>, <keepFile>) ==

Generates a file download with the contents contained in <content>, or (if not specified) from <filename>.  <filename> can be an os file, or an OI file (in the form <table>" "<itemID>).  <suggestedFileName> is the name to show as the "Save as..." on the download; if not specified, it is <filename>.  If <contentType> is not specified, it is determined from <suggestedFilename>/<filename>, if possible. If <newWindowName> is specified, and this is generated during an O4W "response", then a new browser window will be opened for the response.  If <keepFile> is set to "1", the file (if any) is not removed after this call (by default, O4WDownload will remove the file after downloading). O4W toolkit applications should return after the O4WDownload call, as no other content can be returned.  If suggestedFileName parameter is null (“”), then the downloaded item will attempt to be opened in the current browser page, and not as an attachment.

== O4WRedirect(<url>, <windowName>) ==

Instructs the browser to "redirect" to the specified URL. If <windowName> is specified, the contents will be displayed in the specified window; if <windowName> is null, the content is displayed in the current window.  O4WToolkit applications should return after the O4WRedirect call, as no other content can be returned.

== O4WGetValue(<name>, <status>, <request>) ==

Looks through the specified string (using the passed-in query string if <request> is null) for the specified <name>.  If found, returns the value associated with the <name>, and sets <status> to 1; if not found, returns null for the value, and sets <status> to 0.  Combines the functionality of inet_queryparam and cookie searching.

== O4WCookie(<id>,<value>,<expdate>,<exptime>,<path>,domain>,<httponly>,<secure>) ==

Sets or gets the cookie named <id>. If only <id> is passed, will return the value (if any) of the cookie; if <value> (and optionally other parameters) are set, then the cookie will be set for the outgoing response.  Note that expdate and exptime (the expiration date and time for the cookie) should be passed in internal format.  Set the <httponly> parameter to “1” to instruct the browser that the cookie should only be available to the host, and not non-HTTP APIs (such as javascript).  Set the <secure> parameter to “1” to instruct the browser this cookie should only be sent over secure (https://) protocol connections.

== O4WCACHE(<action>, <id>, <date>, <time>) ==

While O4W allows you to dynamically create your web output at the CREATE event, there are often times when a cached version of the web page might be sufficient.  O4WCache can retrieve a cached version of the web page if it is "current", allowing you to short-circuit the CREATE event.  <Action> should be "READ", and <id> should be the unique ID for this web page.  <Date> and <Time> is the "last modified" date and time (in internal format); if the cached version is more recent than the last modified information, O4WCache returns 1 and sets the O4W output to the cached HTML (your application should return at this point).  If there is no cached version, or if the cached version is out of date, O4WCache returns 0, and (at the end of your O4W CREATE event) caches the currently-generated version.  For example:

<code>
If O4WCache("READ", "REPORT*1234", LastDate, LastTime) Then Return
</code>

== O4WCHECKSECURITY(<ReqdPermissions>) ==

O4W security involves making user that users have "permissions" to run the desired O4W routines.  A users permission, and an applications required permissions, are numbers, where lower numbers indicate higher permissions.  Permission level "0" is the highest level; users with permission level 0 can run any O4W routine.  O4WCheckSecurity will validate the users permissions against the <reqdpermissions>, and return 1 if the user is authorised to run the routine; 0 if the user needs permissions but is not logged in; and -1 if the user is logged in, but has insufficient permissions to run the routine.  To allow all users to run a routine, without requiring them to log in, set the required permissions for the routine to "".

== O4WESCAPE(<value>,<type>) ==

O4W routine to 'encode' a string for a particular requirement.  Choices for the <type> parameter include O4W_ESCAPE_HTML$, O4W_ESCAPE_URL$, O4W_ESCAPE_URL_COMPONENT$, O4W_ESCAPE_ID$, and O4W_ESCAPE_JS$.  Note that O4W normally takes care of encoding strings as needed; however, it is up to the developer to use valid strings for "name" and "ID" parameters for the O4W calls, and calling O4WEscape with the O4W_ESCAPE_ID$ parameter is one way to ensure that a name or ID is valid.

== O4WERROR(<errorText> {,<dialogTitle> {,<redirectURL>}}) ==

O4WError displays a dialog box with the selected errorText.  If an optional dialogTitle is supplied, the dialog box uses the specified title; if no title is provided, “Alert” is used as the default title.   The O4WError dialog normally contains a single “OK” button which is used to dismiss the dialog; however, if the optional redirectURL is specified, then clicking on the “OK” button will redirect the user to the specified URL.

 

Examples:

 
<code>
O4WError(“You did not enter a valid user name”)
</code>
 

and

 
<code>
O4WError(“Please be sure to check your entries”, “Verify Information”)
</code>
 

and

 
<code>
O4WError(“Thank you for submitting your form!”, “Thank You”, “http:www.revelation.com”)
</code>

== O4WGENERATEID(<prefix>) ==

O4WGenerateID is a function that returns a guaranteed-unique identifier.  The “prefix” parameter is provided so that similar ids can be identified.  An advantage of using O4WGenerateID is that any records using the returned ID, if used in the O4W temporary work table (available through the named common variable O4WTempFile%), will automatically be “cleaned up” after two days.

== O4WRAW(<text>) ==

Attaches the <text> to the HTML that is generated by O4W at the current location.

== O4WBREADCRUMBS(<breadcrumbContainer>, <breadcrumbSections>, <breadcrumbNames>, <breadcrumbimages>, <breadcrumbflags>, <trackchanges>, <breadcrumbStyle>) ==

Sets up a section to track "breadcrumbs" (links to previously-visited sections) in the section <breadcrumbContainer>.  Each section that will be tracked (specified as an @VM-delimited list in <breadcrumbSections>, with optional "friendly names" specified in the associated <breadcrumbNames> parameter) will initially be hidden.  When the breadcrumbs are displayed, the style specified in <breadcrumbStyle> (if any) will be applied to the <breadcrumbContainer> section. If you wish the user to be alerted if they attempt to move out of a section (either via breadcrumbs or via manually changing the URL on the browser line) after they have made changes to a form, set the corresponding value in <trackchanges> to '1'.  Specify “-1” for the <breadcrumbflags> value if you want the breadcrumb to send a BCLICK_NOTIFY message to the host routine when clicked. To move to a section, and put its value into the 'breadcrumb' list, call O4WSetBreadcrumb.

== O4WSETBREADCRUMB(<breadcrumbSection>) ==

Shows the section specified in <breadcrumbSection>, hides any other breadcrumb sections that were previously visited, and updates the <breadcrumbContainer> section to show the current location (and the path that was taken to get to that point).

**//O4WSETHISTORY//****//(<ID>, <extraValues>, <title>)//**

Sets the 'browser history' to the specified ID/values/title combination.  When the user bookmarks this page and then returns to this bookmark, or pages forward or backward to this page, the user's commuter module will be called with the "HISTORY" event, passing in the specified ID as the control (ctlentid), along with any other string specified in the "extraValues" parameter (note that these should be specified as URL "name=value" pairs).  The title value, if specified, will be suffixed to the current page title (for example, if the browser title was originally set to "Customer Inquiry", and the title parameter was "Re-entry Point", the browser title will be changed to "Customer Inquiry  Re-Entry Point")

== O4WNumberBox(origValue, size, maxlen, minValue, maxValue, stepValue, blsRange, name, ID, StyleInfo) ==

O4WNumberBox is an enhanced (HTML5) text box used for numeric input.  On HTML5 enabled browsers (including many mobile browsers), it restricts input to valid entries (and may additionally provide other UI support for numeric input).  On non-HTML5 browsers, it will display and act as a normal textbox.

<origValue> is the default value.  If <size> is specified, it defines the size (in characters) of the numberbox on the web page; if <maxlen> is specified, it defines the maximum number of characters the numberBox will accept.  Specify the minimum allowed value (minValue), the maximum allowed value (maxValue), the incrementing step (stepValue), and a “1” if this should be displayed as a range input control (bIsRange), if available. <Name> specifies the name of the numberBox, which is used when setting or querying it.  This numberBox can also be addressed through style sheets individually by <ID>; if <style> is specified, the style is applied to the numberBox that is generated.  Note that <style> can be either the name of a style (as created by one of the O4W style functions, or as defined in an included style sheet), or it can be the returned value from one of the O4W style functions.

Example:

 
<code>
 O4WNumberBox(“10”, “”, “”, “0”, “100”, “2”, “1”, “NUMVALUE”, “NUMVALUE”)
</code>

== O4WInputBoxOptions(typeOption, minValue, maxValue, stepValue, placeholder, bRequiredFlag, bAutoFocusFlag) ==

O4WInputBoxOptions can be applied to an O4WTextBox, and adds support for enhanced (HTML5) input controls.  On HTML5 enabled browsers (including many mobile browsers), it restricts input to entries that are valid for the specific typeOption (and optional minValue and maxValue) (possibly including additional UI to make entry and selection easier), provides “placeholder” text (help text that is displayed inside the input control), marks a control as required (bRequiredFlag), and/or sets the focus to that control (bAutoFocusFlag).  On non-HTML5 browsers, it will have no effect.  Note that O4WNumberBox is a combination of O4WTextBox and O4WInputBoxOptions(“number”), and may be used as a shortcut for numeric input.

typeOption can be any valid HTML5 input type, currently including “email”, “url”, “number”, “range”, “search”, “date”, “month”, “week”, “time”, “datetime”, “datetime-local”, and “color”.

== O4WTextOptions(labelForID, labelForType,paragraphClass) ==

O4WTextOption can be applied to any O4WText, and indicates which input control this text is associated with, and whether this text should be treated as a paragraph; this information is used by the browser to help control layout or to provide additional “accessibility” support.  When using O4WText to generate a “label” for an input control, apply the O4WTextOptions, specifying the ID of the input control (labelForID) and the type of the input control (labelForType) – “textbox”, “radiobutton”, “checkbox”, or “listbox” (default is “textbox”).  The paragraphClass parameter is a flag that tells O4WText to display the text wrapped in “paragraph” (<p>) html tags (as opposed to its normal behavior of wrapping text in “span” (<span>) tags).  Set this to “1” to have O4WText generate “<p>” instead of “<span>” output.  ParagraphClass can also be set to the name of a class you wish to assign to your paragraph; if a non-null, non-“1” value is specified, O4WText will generate a “<p>” tag with the specified class, //in addition to// a span (which will be nested inside the “<p>” tag).

 

Example:

 
<code>
O4WText(“Customer Name: “, “”,O4WTextOptions(“CNAME”, “TEXTBOX”))

O4WTextBox(“”, “”, “”, “CNAME”, “CNAME”)
<code>
 

O4WText(“Now is the time for all good men to come to the aid of their country”, “”, O4WTextOptions(“”, “”, “main”));* this will treat this text as a paragraph, with the style class “main” applied to the generated html

== O4WDataStyle(ID, dataName, dataValue) ==

For advanced users.  Creates a "style" based on the attribute name and associated value (both <style> and <value> can be @FM delimited).  Returns the style information (to use immediately with a display element or input control), and (if <stylename> is not null) defines the style by the stylename for use with one or more elements and input controls.  Using this API, you can create your own HTML5 “data” attributes.  You can also specify values that are needed by pre-defined styles, such as those defined by jQuery.  The <id> is the identifier of the style.  The <dataName> is any HTML5 data attribute, for example data-name, data-location.  The <dataValue> is any allowed value for the specific data attribute.

== O4WSwitchMode(<source>) ==

Call O4WSwitchMode from a stored procedure, or run it from the system monitor, to change where the O4W libraries are loaded from.  Specify “LOCAL” if you do not have access to the internet, or if you prefer to use the local copies stored in the O4W folders; specify “GOOGLE” if you have internet access.