Webster+ Object

Methods

Below is a list of Webster+ methods in alphabetical order. When referencing the method, it would normally be prefixed with %Webster'.

Method

Description

AddRow(gridname$, row)

This function can be used to add a row to a grid. It will use the current values for the variables defined in the IOList attached to the grid memory file as defined in the variable names in gridname$. If the specified row already exists in the grid, a new row will be inserted.

An Error 11 will occur when an invalid row is specified.

(The AddRow method was added in PxPlus 2022.)

ChgRow(gridname$, row)

This function can be used to update an existing row in a grid. It will use the current values for the variables defined in the IOList attached to the grid memory file as defined in the variable names in gridname$.

If the specified row does not exist in the grid, an Error 11 will occur.

(The ChgRow method was added in PxPlus 2022.)

ClrUserField(variable$)

This function is used to clear/remove the specified user variable from the current user's profile.

Console.Error( )

Console.Log( )

Console.Warn( )

These functions provide a means to output to the browser log.

     %Webster'Console.xxx(text$)

Where:

xxx

Identifies the type of console output. Value options are Log, Warn and Error.

text$

Contains the text to display on the browser console.

The console output can be viewed by the user by pressing F12 on most browsers. The three types of output are displayed in different colors based on the severity with Error generally being on a Red background, Warn on a Yellow background and Log being on White.

DelRow(gridname$, row)

This function can be used to delete an existing row in a grid.

If the specified row does not exist in the grid, an Error 11 will occur.

(The DelRow method was added in PxPlus 2022.)

Download(filename$)

This function initiates a file download to the workstation.

Where:

filename$

Contains the pathname of the file you want sent to the workstation.

This function will initiate a browser download of the specified file. The file will be placed in the standard download location based on the workstation or device settings.

Enable(id$, state)

This function can be used to enable/disable a button on the page.

Where:

id$

Contains the ID of the button as specified on the targeted [button] short code using id=xxx.

state

If non-zero, will enable the button; zero will disable it.

Event(eventname$)

This function is used to force an event to be generated by a Webster+ page.

Where:

eventname$

Name of the event you want the Webster+ page to submit after being updated.

Note:
This function switches Webster+ from a full screen refresh to an Ajax style update.

Focus(element$ [ ,grid$, line ] [, radiobtnval$ ] )

This function is used to set focus to the specified element on the page.

element$

A string that contains the name of the element (variable name) on the Webster+ generated page that focus will be sent to.

grid$

Optional parameter that contains the grid name when selecting a field in a grid.

line

Optional parameter that contains the line number when selecting a field in a grid.

radiobtnval$

Optional parameter used when the target element is a radio button. This parameter should contain the value of the radio button desired.

Note:
When setting focus to a tree view, you must use the associated string variable name, not the numeric variable name defined in the short code.

Example:

For [tree MyTree…], you would use %Webster'Focus("MyTree$").

GetFileUrl$(filename$)

This function returns a URL that can be used to retrieve any file on the system from a browser.

This function is typically used to provide access to images or other files (PDF, Documents, etc.). The URL returned includes an encrypted key that Webster+ will use to access the file. The key is based on the user currently signed on; thus, the URL itself is only of use to that user.

Where:

filename$

Contains the pathname to the file for which you want to get a URL.

Note:
The URL returned can only be used within Webster+. It cannot be used in an email or other such communication as it will only work from a browser session on which the current user is signed on.

GetiNomadsEmbedURL$(URLToEmbed$)

This function returns a URL that will display the given iNomads URL embedded in a Webster+ page.

Where:

URLToEmbed$

iNomads URL to display embedded in Webster+.

(The GetiNomadsEmbedURL$ method was added in PxPlus 2024.)

GetTempFile$(filename$)

This function returns the pathname to a temporary file based on the filename provided. These temporary files should be deleted when no longer needed; however, the system will delete any temporary file over one day old.

Where:

filename$

Contains a desired filename upon which the temporary filename will be derived.

The path returned will point to a file in the system temporary file directory (as defined in Webster+ setup) with the filename provided altered to include a unique timestamp sequence number inserted before the file suffix.

Hide(name$, state [,leavespace])

This function can be used to hide/show a control on the page.

Where:

id$

Contains the name or ID of the control targeted.

state

If non-zero, will hide the control; zero will show it.

leavespace

(Optional) If non-zero and the control is hidden, the space on the screen occupied by the control will remain.

If zero (or omitted), the page layout will be adjusted to appear as the control has been removed.

Lock(name$, state)

This function can be used to lock a control such as an input field or list.

Where:

name$

Contains the name or ID of the variable associated with the control to be locked.

state

If non-zero, will lock the control; zero will unlock it.

Message(messageid$ WITH variable$=value$, variable=value…)

This function will return the message identified by messageid$ from the system message library.

Where:

messageid$

Contains the key of the message stored in the system message library.

variable$

Contains the name of a variable that will appear in the message and is to be replaced.

value$

Value that replaces the variable.

This method provides enhanced replacement capabilities over the standard MSG( ) function; however, instead of replacing parameters by ordinal numbers (%1, %2, %3, etc.), it replaces values by variable name.

Example:

Using Message Library Maintenance, the following message could be defined:

     Message Key:      OnHold
     Message Text:     The client %Acct$ is on hold.

You could then use this method to convert this, passing the message key and the values to be substituted as follows:

     Text$ = %Webster'Message$("OnHold" with Acct$=AccountNo$)

This would replace the string %Acct$ with the value currently in AccountNo$.

Numeric variables can also be used; however, no formatting of the value will be done; that is, the parameter in the text will be replaced with a simple STR( ) of the variable's value.

Note:
The %Acct$ in the sample message text above should not be confused with a global variable. The leading % simply identifies the variable to be replaced and is designed to be consistent with the numbered parameters %1, $2, %3, etc.

MsgBox(message$, title$, options$ [ , eventprefix$ ] )

This function provides the ability to generate and display a message box on the page when it is returned to the browser. The buttons on the message box can be used to signal events to your page for further processing.

Where:

message$

Contains the message text you want to display on the browser. You can use SEP or $0A$ (LF) to separate lines of text and $09$ (TAB) to insert four spaces.

title$

Contains the title to be displayed on the top of the message box.

options$

Used to define the icon and buttons in the message box. See PxPlus MSGBOX directive for valid options.

eventprefix$

Optional prefix to be applied to the events associated with the buttons in the message box. If omitted, the default of "msgbox" will be applied.

Note:
The suffix and the event will be separated by an _ (underscore).

When the user selects a button from the message box, Webster+ will generate an event, causing the page contents and event to be returned to the program specified on the [form] short code.

The event name will be lowercase text value from the button. For example, the "Yes" button by default will return an event of "msgbox_yes". The "OK" button (when no eventprefix$ is defined) and the "Cancel" button (in all cases) are exceptions and will simply close the message box without generating an event.

Optionally, if you manually define button text using BTN1=xxx, etc., you can include a :Event following the text to appear on the button, and that will be used instead. For example, if you included the option "BTN1=Authorize:auth", the first button would contain the text "Authorize" and, when pressed, would generate an "auth" event.

Example:

Suppose you want a message box to ask for confirmation to delete a record. This could be done using the following:

%Webster'MsgBox("Do you want to delete this record","Please confirm","?,YESNO","delete")

This would display a message box and, if the user clicked the "Yes" button, your program would receive an event of "delete_yes". If the user selects "No", you will receive "delete_no". If the user simply closes the message box, you will receive nothing.

If you do not want or need a "delete_no" event, you can add "btn2=No:" to the option string. This will override the default behavior for the "No" button and simply cause the message box to close with no event generated.

OptionBox(boxname$, msg$, event$, opt1$, opt2$, … ,opt5$)

This method can be used to update a named infobox (a [show] short code with the class of infobox) with message text followed by up to five options from which the user can select.

Where:

boxname$

Name of the infobox on the page. Must be the name of a string variable.

msg$

Message text to display in the message box.

event$

Name of an event to trigger once any option is selected. Must be the name of a valid numeric variable, or if null (""), the boxname (less the trailing $) will be used.

opt1$ through opt5$

Options to be displayed to the user (two to five options are supported).

Once the user selects one of the options, the specified event will be generated with the corresponding variable (same as event name) loaded with the number of the option selected.

Example:

%webster'OptionBox("payinfo$","iNo outstanding invoices to pay",
                    "",
                    "I don't care",
                    "Really I don't",
                    "I'm not kidding")

… would generate an infobox like this:

    

Since the event$ parameter specified is "", once the user selects one of the options, the event "payinfo" (name of the infobox) will be generated, and the variable "payinfo" will be set to the selected option number.

(The OptionBox method was added in PxPlus 2022.)

PopInput(message$, title$, options$, variable$ [ , inputoptions$ ] )

This function provides an enhanced MsgBox that will prompt for input. The value entered by the user will be returned in a variable named by the variable$ parameter.

Where:

message$

Contains the message text you want to display on the browser. You can use SEP or $0A$ (LF) to separate lines of text and $09$ (TAB) to insert four spaces.

title$

Contains the title to be displayed on the top of the message box.

options$

Used to define the icon and buttons in the message box. See PxPlus MSGBOX directive for valid options.

variable$

A string whose value defines the name of the string variable to receive the response entered by the user; e.g. "response$".

inputoptions$

Optional string that contains [input] short code options. Only the following options are allowed: align, class, format, len, size (width only), tip and uppercase. Multiple options are separated by a space.

(The PopInput method was added in PxPlus 2022.)

SetErrorMsg( [ variable$, message$ [ ,grid$, line ] ] )

This function is used to force an input field to be flagged as invalid and to set the error message to be displayed.

Where:

variable$

A string that contains the name of the variable on the Webster+ generated page that is to be marked invalid.

message$

Contains the error message to be displayed.

grid$

Optional parameter that contains the grid name if specifying a field in a grid.

line

Optional parameter that contains the line number if specifying a field in a grid.

Once an error has been set on a field, you must either replace the whole page or specify an empty ("") error message. If there are any fields with errors, a button with a 'validate' specification will not issue its associated event when pressed. Instead, the system will set focus on the first invalid field on the screen and redisplay its associated error message.

SetUserField(variable$, value$)

This function is used to define user variables that will be loaded into %usr.variable$ and made accessible to the application.

Where:

variable$

Name of the string variable that will be prefixed with "%usr." whose value will be saved and loaded.

value$

Contains the value that will be saved and loaded.

This routine will allow values to be saved to the profile information for the current user.

Example:

     %Webster'SetUserField("CellPhone","4165551212")

This would result in the value %usr.CellPhone$ being set to "4165551212" on subsequent requests for the current user.

A maximum of 2K worth of data values may be saved.

ShowFile(pathname$[,newtab])

This function is used to show a file, such as an image file or PDF, to the user (if newtab=1, force new tab).

SignalChange(pathname$)

This function signals a change in the specified pathname$ that can be watched (using the WatchChange method) by another tab in the browser. It is used by the Webster+ program and HTML page editors to signal that a file has changed in order to have other tabs, such as a directory listing or program view, update their display.

(The SignalChange method was added in PxPlus 2021 Update 1.)

Update(channelNumber)

This function is used to update the contents of a tree view by passing the channel number that contains the tree view contents. When updated (like when initially displayed), the tree view will only show the top level of the tree.

To expand/expose lower levels, you need to update the tree view using the %Webster'Update(tree_name$, value$) method.

The %Webster'Update(channelNumber) method can also be used to directly update the contents of a grid.

(The Update(channelNumber) method was added in PxPlus 2023.)

Update(listboxname$)

This function is used to update a list box. It is a more consistent way of running %Webster'Bind'Reload(listboxname$). See %Webster'Bind'Reload.

Where:

listboxname$

Contains the name of the list box.

(The Update(listboxname$) method was added in PxPlus 2023.)

Update( [ variable$, value$ [ ,grid$, line ] ] )

This function is used to update the contents of a variable on a Webster+ generated HTML page.

Where:

variable$

A string that contains the name of the variable on the Webster+ generated page that is to be updated with the value specified.

value$

Contains the new value the field is to contain.

grid$

Optional parameter that contains the grid name when updating a field in a grid.

line

Optional parameter that contains the line number when updating a field in a grid.

You can call this routine with no parameters to force Webster+ to flip to Ajax style updates.

This can be useful if you have nothing to update on the screen (i.e. you only processed the event and do not change anything).

It can also be used in conjunction with %Webster'SetErrorMsg("control", "message") to set a validation error message on a control or if all you want to do is respond with a message box using the method %Webster'MsgBox("message", "title", "options").

If you do not call 'Update( ) to flip to Ajax mode, your response will be sent as part of a full screen retransmission.

UpdateFMDisplay( )

This function is used in conjunction with File Maintenance generated Webster+ pages to force a full update of all fields on the page as if a new record has been retrieved.

Note:
This function switches Webster+ from a full screen refresh to an Ajax style update.

UpdateFMShowVars( )

This function is used in conjunction with File Maintenance generated Webster+ pages to force an update of any SHOW.xxxx values on the current page. For information on SHOW.xxxx descriptive fields, see Extended Class Validation and Display.

Note:
This function switches Webster+ from a full screen refresh to an Ajax style update.

UpdateIOL(iolist$, values$ [ ,grid$, line ] )

This function is used to update the contents of multiple variables on a Webster+ generated HTML page.

Where:

iolist$

Contains an IOList of the variables to be updated.

values$

Contains the new values for the fields identified in the iolist$. This string will be parsed using the iolist$ provided to extract the individual field values.

grid$

Optional parameter that contains the grid name when updating fields in a grid.

line

Optional parameter that contains the line number when updating fields in a grid.

Note:
This function switches Webster+ from a full screen refresh to an Ajax style update.

WatchChange(pathname$ buttonid$)

This function initiates a background monitor for changes made by another tab in the same browser to the specified pathname$. When a change is signaled (using the SignalChange method), the button whose ID is specified in buttonid$ will be logically clicked, allowing an event to be sent to the host for processing.

To monitor a directory for any changes in subordinate files, append /* to the directory name.

(The WatchChange method was added in PxPlus 2021 Update 1.)

See Also

Properties