OpenInsight For Web Development Toolkit
The OpenInsight for Web development toolkit (O4W) makes it possible for OI programmers with limited or no HTML/XML/javascript experience to develop feature rich web pages. O4W is designed to work the way OpenInsight developers think, taking advantage of the skills and knowledge they already have. While users with more web development experience can use O4W's advanced features, all developers can create modern web applications (using javaScript, XHTML, and AJAX) through O4W's APIs.
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 [*IMAGE/DETAILS LATER*]. 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:
SUBROUTINE O4W_MYROUTINE(CtlID, Event, Request)
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, stylesheets, 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
Subroutine O4W_MYROUTINE(CtlEntId, Event, Request)
$Insert O4WEquates
Check for the 'create' event, and verify that we have all the information needed to run this routine; if not, return an error
Begin Case
Case Event _eqc "CREATE"
* Initial form creation
ReportName = Inet_QueryParam(Request, "REPORTID")
If ReportName = "" Then
O4WError("No report specified")
Return
End
Read ReportDef From O4WReportFile%, ReportName else
O4WError("Report '":ReportName:"' not on file")
Return
End
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
O4WForm(ReportDef<TEMPLATE_NAME$>, O4WColors("", ReportDef<BGCOLOR$>, ReportDef<TEXTCOLOR$>, ReportDef<BGIMAGE$>):@FM:O4WTextStyle("","","","",ReportDef<Align$>+0))
O4WLinkStyle(ReportDef<LINKCOLOR$>, ReportDef<VISITEDCOLOR$> )
Set the "title" of the web page (which is displayed in the browser window)
O4WTitle(ReportDef<TITLE$>)
Define a style, called "RPTALIGN", that we will re-use with various other elements (including the "headline" of the web page)
O4WTextStyle("RPTALIGN", "", "", "", ReportDef<Align$>+0)
O4WHeader(ReportDef<BANNER$>, 1, "BANNER", "RPTALIGN")
Define a section that will contain our results (presented as a table). Note that the section uses the "RPTALIGN" style defined earlier
O4WSectionStart("DATATABLE", "RPTALIGN")
bBorder = 0
bWidth = ReportDef<TableBorder$> + 0
If ReportDef<TableBorder$> <> "0" And ReportDef<TableBorder$> <> "" Then bBorder = 1
Start the table, named RESULTS, and set its style
O4WTableStart("RESULTS", O4WTableStyle("", bBorder, bWidth, ReportDef<Align$>+0))
For each column in the table, define a "column header" with the desired color and text style
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, "",
O4WColors("",colBGColor, colColor):@FM:
O4WTextStyle("", "", colBold, colItalic, colAlign))
Define the styles for the columns themselves, saving them as the style named "RESULTS_<colnumber>"
valColor = ReportDef<ValueColor$, each.field>
valBGColor = ReportDef<ValueBGColor$, each.field>
valAlign = ReportDef<ValueAlign$, each.field>
O4WColors("RESULTS_":each.field, valBGColor, valColor)
O4WTextStyle("RESULTS_":each.field, "", "", "", valAlign)
O4WTableStyle("RESULTS_":each.field, bBorder, bWidth)
Next each.field
Build some results (ommitted from the sample code) and populate the table with the data. Note the use of the style "RESULTS_<colno>" defined for each column (above)
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
The RESULTS table is now complete
O4WTableEnd("RESULTS")
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
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']")
Put a "break" between the table, and add two buttons. Add events for these buttons when they are "clicked"
O4WBreak()
O4WButton("Download As CSV", "BTNCSV")
O4WButton("Download As PDF", "BTNPDF")
O4WQualifyEvent("BTNCSV", "CLICK")
O4WQualifyEvent("BTNPDF", "CLICK")
The DATATABLE section is now complete
O4WSectionEnd("DATATABLE")
Add a "link" at the bottom of the page, another break, and a "footer"
O4WLink("Home Page", "", "http://www.revelation.com")
O4WBreak()
O4WFooter(ReportDef<FOOTER$>, 3, "FOOTER")
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
Case event _eqc "CLICK"
Gosub GenerateTable
Finish up the commuter code logic
End case
Return
O4W Toolkit Style functions
O4WSTYLESHEET(<urltostylesheet>)
Allows you to define an external "style sheet" that you wish to put on the current web page.
O4WCOLORSTYLE(<stylename>, <bgcolor>, <fgcolor>, <bgimage>)
O4WCOLORS(<stylename>, <bgcolor>, <fgcolor>, <bgimage>)
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). 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>)
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.
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>)
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.
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>)
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.
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.
O4WRESPONSESTYLE(<stylename>, <textOnly>, <styleOnly>)
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.
O4WMARKEDSTYLE(<stylename>, <bIsMarked>)
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.
O4WVALIDATESTYLE(<stylename>, <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.
O4W Toolkit Display Element functions
O4WFORM(<templateID>, <style>)
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.
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
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.
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), an "embedded" url (O4W_LINKTYPE_EMBED$, or 6), "O4W report" (O4W_LINKTYPE_REPORT$, or 7), "local" (O4W_LINKTYPE_LOCAL$, or 8), and "OI" (O4W_LINKTYPE_OI$, or 9) (useful only when O4W screen is invoked in O4W_STANDALONE_FORM or O4W_CHILD_FORM).
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.
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. 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:
O4WFooter("(c) 2009 Revelation Software", 3)
will appear left-flush. To center:
O4WFooter("(c) 2009 Revelation Software", 3, "", O4WTextStyle("","","","","1"))
or (if centering will be used more than once)
O4WTextStyle("CENTERSTYLE","","","","1")
O4WFooter("(c) 2009 Revelation Software", 3, "", "CENTERSTYLE")
O4WTableStart/O4WTableEnd/O4WTableHeader/O4WSetCell/O4WTableModify
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 O4WCellStyle 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 O4WCellStyle 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.
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.
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
[*NOT YET IMPLEMENTED*]
O4WTABS(<tabSectionID>, <tabDetailIDS>, <tabTitles>, <tabRequiresData?>, <tabOptions>)
Creates a tabbed pane, named <tabSectionID>, containing tabs with titles from <tabTitles>. The content of the tabs must be contained in O4W sections, defined in <tabDetailIDS>. Alternatively, 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>).
O4WLISTSTART(<type>, <ID>, <style>)
O4WLISTEND(<ID>)
O4WLISTITEM(<style>)
Builds a sorted or unsorted list. 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; therefor, 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 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. Either may contain the code "F", 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), or the code "D" (to specify that this is a date series on the axis), and/or the code "M" followed by a number (to specify the minimum value to show on that axis), and/or the code "X" followed by a number (to specify the maximum value to show on that axis). The <graphOptions>, if specified, may contain the code "B" (to suppress the border ("B0") or change the border width "B"<number>") around the graph), and/or "Z" (to disable "zooming" on the graph data), and/or "L" (to explicitly enable ("L1") or disable ("L0") the display of legends), and/or "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).
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.
O4W Toolkit Input Control functions
O4WSTORE(<text>, <name>, <id>)
Creates a "hidden" text box 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 O4WInputStyle "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>)
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").
O4WTEXTBOX(<text>, <size>, <maxlen>, <name>, <id>, <style>)
O4WPWDBOX(<text>, <size>, <maxlen>, <name>, <id>, <style>)
Both the O4WTextBox and O4WPwdBox create an input "text box" 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 text box on the web page; if <maxlen> is specified, it defines the maximum number of characters the text box will accept. <Name> specifies the name of the text box, which is used when setting or querying it. This text box can also be addressed through style sheets individually by <ID>; if <style> is specified, the style is applied to the text box 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>)
Createa 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.
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 O4WInputStyle "checked" flag is set, then that specific <text> will be selected.
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 O4WInputStyle "checked" flag to check (when set to "1") or uncheck (when set to "0") the checkbox and radiobutton as desired.
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).
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>, <passedValues>, <addlParams>)
Sets an "event" on the specified <id>. When the event occurs, the specified action will be taken and/or the stored procedure will be called from the browser page. <event> includes "CLICK", "VALIDATE", "RESET", "LOSTFOCUS", "TOGGLE", "SUBMIT", "CHANGE", "TABNEXT", "TABBACK","DELETEROW", "INSERTROW", "COPYROW", "ADDTOTABLE", "DELETEFROMTABLE", "SHOW", "HIDE", "MOVE", "COPY", "REMOVE", "SELECT", "SHOWWHENSELECTED", and "SHOWWHENNOTSELECTED". For example:
O4WQualifyEvent("BTNOK", "CLICK")
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:
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']")
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 (@FM 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 O4WResponseStyle should be specified.
O4WPopup(<id>, <popupType>, <popupSrc>, <popupArgs>, <target>, <styleInfo>)
This routine generates a "popup" dialog box, with the unique identifier <id>. 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 O4W Commuter Module will be called when the popup return value is ready; the CtlEntId will be whatever was specified in the <target> parameter of this call, the event will be "RETURNVALUE", the value returned by the popup will be returned in the "o4wValue" variable, and an additional value (identifying the name of the dialog box) will be returned in the "o4wPopup" variable. For example:
Case event _eqc "RETURNVALUE"
O4WResponse()
popup = O4WGetValue('o4wPopup')
* dismiss the popup
O4WDialog(popup)
* get the return value
rtnValue = O4WGetValue('o4wValue')
* update the target with the returned value
O4WUpdate(ctlentid, O4WGetValue("o4wValue"), O4WResponseStyle('','1'))
<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), and O4W_LINKTYPE_POPUP$ (for an OI popup). 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. <StyleInfo>, in all cases, identifies style properties that can be applied to the popup dialog (for example, O4WSizeStyle). For example:
O4WPopup('mypopup', 'Test Popup', O4W_LINKTYPE_REPORT$, 'CUSTOMER', '@ID', 'targetTextBox', O4WSizeStyle('','600px','600px'))
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.
O4WFOCUS(<id>)
Sets focus to specified ID.
O4WMenu(<menuName>, <errmsg>)
Builds a menu on the current page with the menu definition <menuName>. If an error is encountered, returns an error string in <errmsg>. If %MENU%, %MENU-H%, or %MENU-V% is specified in your template, the menu will be placed at that location in the template; otherwise, the menu will be placed at the current location. If %MENU% (or no menu tag) is specified, the direction of the menu is controlled by the O4WConfig record "MENUDIR" - a 1 in field 2 indicates a horizontal menu, while a 0 in field 2 indicates a vertical 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.
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(<id>, <status>, <request>)
Looks through the specified string (using the passed-in query string if <request> is null) for the specified <id>. If found, returns the value associated with the <id>, 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>)
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.
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:
If O4WCache("READ", "REPORT*1234", LastDate, LastTime) Then Return
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 "".
O4WERROR(<errmsg>)
Generates an error message with text <errmsg>. Your procedure should RETURN immediately after calling O4WError.
O4WGENERATEID(<prefix>)
Generates and returns a unique ID in the O4W work file. It also removes any temporary records with the same prefix that are more than 2 days old [*TO DO*]
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'. 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).
[*STILL TO IMPLEMENT*]
comobobox
divider (hr?)
"Activating" table (turning it to input mode, allowing add/remove of rows)
defining 'actions' that can go along with the events
meta tags