Rule Files

Web extension rule files define screen integration elements for specific web pages.  Any number of rule files can be configured, each listed in uf101d.ini in a [webrulefiles] section.  This section is composed of lines in the format: rulefile=URL-pattern.  For example, if you want a rule file named "classic-erp.rul" to be used whenever visiting the site "https://classic-erp.com/sdsi", use a line like this:

classic-erp.rul=https://classic-erp.com/sdsi

Note that the URL pattern is treated as a regular expression, enabling complex pattern matching in cases where there might be specific URL parameters or fragments to should apply.

Once a matching site is viewed in the browser, the configured rule file is applied to pages and frames the user navigates to.  Frames are very common in browser-based applications, and each frame is treated as a unique page for integration purposes.

Detection

The standard UnForm detect statement is used to determine which rule set, if any, to apply to any given page or frame.  The detection is evaluated in the following way:

detect x,y,"match value"

0,0 title + " " + url

0,1 title

0,2 url

0,3 host+path

0,4 query string (without the ?)

0,5 selector existence  (selectors are jQuery/CSS selectors, used to check for ERP-specific input elements)

The match value for options 0 to 4 should be a full case-insensitive text match, but can begin with a prefix:

 != matches text not equal to the match value

 ~ treats the match value as a regular expression, and matches text that matches the expression

 !~ treats the match value as a regular expression, and matches text that does not match the expression

The match value for option 5 is a jQuery/CSS selector.  If a match is found, the detection pattern passes.

All detects must pass for the rule set to be applied to the page.

For any page or frame that is detected, a webaction button and form are created based on the below commands.  The button can be clicked to show the form.

Action Buttons

An action button is presented as a small UnForm icon or specified html somewhere on the browser screen, within the frame it is associated with.  The default location of this button is the upper right corner, but the position and size can be adjusted with CSS style tags, and it can also be anchored to a selected element, to allow buttons to appear alongside specific page content.  An action button is specified with the webaction command.  There can be more than one button in a rule set, and all are presented on the page or frame.  The button last clicked is the one submitted with the web form data.

webaction "name" [,style "button CSS styles"] [,beforebegin|afterbegin|beforeend|afterend "selector"] [,tip "tooltip" ] [,autorun] [, html "<tag... @ufaction>...</tag>"

If no html option is present, an UnForm icon image is used.  If html is provided, it must be a valid tag or tag set, such as "<button @ufaction>Click Here</button>".  The string "@ufaction" should be present and is replaced by the extension at runtime with attributes required for identification and event handling.  The code can otherwise by any html fragment, including nested tags.

Form Specification

A combination of fields and items are presented in a web form, either as a single page or with a tab-style interface.  The elements of the form are defined with three commands:

Fields are text items that extract information from the current web page or frame.  A jQuery/CSS selector is used to identify which field or screen element to read.  If the element has a "value" attribute, such as an input element, that is used.  If not, the innerHTML property is used, for example to get a table cell or span element's contents.

The specified attributes are added to the input tag, so should be a space-delimited list of HTML <input> attribute names and values.

webfield "name","selector"[,attributes]

If a selector is not found, then the field is not added to the form.  Note if the selector needed contains a period (.), it should be escaped (\.) to avoid conflict with selector class lookups.

Items are addition input fields the user can interact with.  An input widget is created of the type specified (input, textarea, radio, checkbox, select, button), with optional attributes to apply.  Certain types support a list of options (radio, checkbox, select), which is a simple semi-colon delimited string.  A button option submits all the fields to the same rule file and rule set, which can access the form data via the cgi.data$ structure, or in individual fields as cgi.field_name$. The name of the button pressed is sent as cgi.button$.

The specified attributes are added to the associated tag, so should be a space-delimited list of HTML <input> attribute names and values.

webitem "name", input|textarea|radio|checkbox|select|button|file ["list"] [, attributes]

The file type of webitem allows the user to upload a local file to the UnForm server, for handling by the rule set associated with the current browser screen.

Panels add tabs to the form interrface.  Each webpanel command creates a new tab for the fields and items that follow it in the rule set.

webpanel "title"

Form Submission

When a web item of type "button" is pressed, or if the web action button contains an 'autorun' option, the form is submitted to the UnForm server, to process the active rule set.  The rule set is explicitly specified via -f and -r arguments to an UnForm command line on the server. Code blocks, such as prejob, will execute with specific variables defined with form content, and the result can be either a PDF file generated by normal rule file processing, or the content of a cgiresponse$ variable, which can contain any HTML text, messages, or script code.

More details are in the code block response page.

Notes

UnForm code block expressions are not supported in any of the commands.  However, global and rule set constants (global, local, const commands) are supported, enabling parameterization of command elements, like style or attribute tags.

Due to parsing methods, quotes in the above commands are part of the syntax and must be double quotes (").  Portions passed to HTML can use single or double quotes, such as in attribute lists.

The extension loads all configured rule files from the UnForm sites when loaded, to limit the overhead imposed by the load process.  If you are maintaining a rule file and need it reloaded, you can use the "Reload Site Rules" button on the extension options window.

CSS Selectors

CSS/jQuery selectors are used in detection, webaction, and webfield commands.  A selector is used to  locate a particular element in a web page's document object. Standard CSS selectors are well documented in many sites on the Internet, such as:

https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors

https://www.w3schools.com/cssref/css_selectors.asp

https://en.wikipedia.org/wiki/Cascading_Style_Sheets#Selector

jQuery is the actual engine used by the Web Extension when identifying elements with selectors.  jQuery supports standard CSS syntax along with a few extensions.  You can find its selector documentation here:

http://api.jquery.com/category/selectors/

Special Selector Prefixes

The default context for a selector is the current window.document object.  This is often the document of a frame of a larger web page.  If you need to access another document object within the larger web page, such as the top level or a sibling frame, you can use one of these prefixes to the selector:

•parent:selector

•top:selector

•opener:selector

•$(value):selector

The first three formats use the document object associated with the named window object.  If the $(value) syntax is used, a jQuery selector function is executed and the first matching returned jQuery object is used as the selector context.