Chapter 6 - Form, view and UI

These ten commands connect the form to the page it runs in: read the parameters the form was opened with, form properties and environment variables, load your own CSS and JavaScript, switch views, control autocomplete and character limits, set FormsViewer options, ask the user a question, and accept several files in one drop. Most of them belong on QdabraRules > finishedLoading, so they run once when the form starts. Chapter 1 explains the command syntax, dynamic parameter values and where results go; this chapter assumes you know it.

The examples use this main data source:

my:myFields
  my:TemplateName
  my:SiteUrl
  my:Comments
  my:Status
  my:Attachments
    my:Attachment         (repeating)
      my:File             (file attachment)
      my:Description

6.1 GetInputParameter

Returns the value of a parameter in the address the form was opened with. Use it to make one template behave differently depending on how it was launched, for example by template name, list name or a record ID passed in a link.

Syntax

GetInputParameter /key=<parameter name>

Result: the parameter's value. Success is false if the parameter is missing or empty.

Examples

GetInputParameter /key=templateName
GetInputParameter /key=SPHostUrl /resultxpath=/my:myFields/my:SiteUrl

The first returns the name the template was opened as. The second writes the SharePoint site address straight into SiteUrl.

Prod and Dev from one template: upload the same template twice, once as ExpenseReport and once as ExpenseReport DEV. On finishedLoading, run GetInputParameter /key=templateName, copy the Result into TemplateName, and let the next rules pick the submit library with a condition such as TemplateName contains DEV. Nothing in the file changes between the two uploads; only the name it was opened as.

Notes

• A missing parameter and a parameter with an empty value are treated the same: the command fails with The requested key templateName was not specified in the input parameters (with your key in place of templateName), and Result is empty. The command description in the Command Builder says FAIL is returned; the behavior above is what the engine does. Check Success before using the Result.
• Run it on finishedLoading, before any rule that depends on the value (for example, before the rules that change connection URLs).

Related: GetFormProperty, GetEnvironmentVariable.

6.2 GetFormProperty

Returns one property of the running form: the browser's user agent, the page address, the SharePoint site or site collection, or when the template was last modified.

Syntax

GetFormProperty /key=CurrentUrl|LastModified|SharePointSiteCollectionUrl|SharePointSiteUrl|UserAgent

Result: the property value.

Examples

GetFormProperty /key=SharePointSiteUrl /resultxpath=/my:myFields/my:SiteUrl
GetFormProperty /key=LastModified

The first stores the site address for later use in links or connection URLs; the second returns, for example, 2026-10-05T14:32:07.

Notes

• CurrentUrl returns the address of the browser page, not the location of a saved XML document. The command description in the Command Builder says otherwise; the behavior above is what the engine does.
• SharePointSiteUrl gives the same value as GetInputParameter /key=SPHostUrl. If the form was not opened with SPHostUrl, it fails with The SharePoint Site Url is not currently available.
• Other errors: The User Agent is not available., The Current URI is not available., The Last Modified Date is not currently available, and for SharePointSiteCollectionUrl a message starting with The SharePoint Site Collection Url is not currently available.
• Any other key, including a key in the wrong case, fails with GetFormProperty: The specified key is invalid: key.

Related: GetInputParameter.

6.3 GetEnvironmentVariable

Returns the value of a FormsViewer environment variable. Use environment variables for values that differ between installations or environments (for example a DBXL address), so the template itself does not have to change.

Syntax

GetEnvironmentVariable /key=<variable name>

Result: the variable's value. A variable that exists but has no value returns an empty Result with Success true.

Example

GetEnvironmentVariable /key=DbxlUrl

Returns, for example, http://DBXL1/QdabraWebService.

Notes

• If no variable has that name (check the case), the command fails with The specified environment variable was not found.
• An environment variable is not a secret store. Its value comes back into the form's data, where anyone who can open the form can read it.

Related: GetInputParameter, UseOption.

6.4 LoadResource

Loads a CSS style sheet or a JavaScript file into the page, or removes one again. The usual source is a file stored in the template's Resource Files; with extra parameters it can also load a file from another address. A resource file does nothing until it is loaded, so put one LoadResource action per file on finishedLoading.

Syntax

LoadResource /name=<file name> [/type=script|style] [/unload=true]
LoadResource /name=<URL> /allowexternal=true [/useproxy=true] [/type=script|style]

Result: empty on success.

Examples

LoadResource /name=full_width.css
LoadResource /name=ToggleClass.js
LoadResource /name=https://contoso.sharepoint.com/sites/forms/SiteAssets/theme.css /allowexternal=true /useproxy=true
LoadResource /name=DebugSlider.css /unload=true

The first two load files from the template's Resource Files; the third loads a shared style sheet from a SharePoint library through the FormsViewer server; the last removes a style sheet that was loaded earlier.

Notes

• The type comes from the extension (.css is a style, .js a script, any case). If the name has another extension or none, add /type, or the command fails with Could not determine resource type based on name 'name'. Please use the /type parameter. A URL that ends in a query string or a # fragment (for example theme.css?v=2) also needs /type.
• An invalid /type fails with Invalid type: 'value'. Valid types are: style, script.
• A resource file name must not contain / or \. Without /allowexternal=true, such a name fails with Could not load resource. Invalid path in /name: name.
• With /allowexternal=true, a name without / is still loaded from the template's Resource Files.
• /useproxy=true without /allowexternal=true fails with /allowexternal must be true if /useproxy is true.
• If the browser cannot load the file, the command fails with a message starting Error occurred loading resource:.
• /unload with a name that is not loaded fails with Could not unload resource with name: name A resource with this name was not found in the page's DOM. Removing a script file does not undo what the script has already done, such as commands it registered.
• Loading a script can register new qRules commands, which the rest of the form then calls from ordinary rules. Load such scripts above any rule that uses their commands.

Related: SetDefaultView.

6.5 SetDefaultView

Switches the form to another view. Use it where the Switch views action is not available (for example in a rule on a field), or when the view name is decided at run time.

Syntax

SetDefaultView /view=<view name>

Result: empty on success.

Examples

SetDefaultView /view=Display
SetDefaultView /view-xpath=/my:myFields/my:Status

The first switches to the Display view. The second switches to the view whose name is stored in Status, using a dynamic parameter (see Chapter 1).

Notes

• Despite its name, the command switches the current view straight away; it does not just change which view opens next time.
• Use the view name exactly as it appears in the designer.

Related: LoadResource, SetCharacterLimit.

6.6 SetAutocomplete

Turns off the browser's typing suggestions and auto-fill for one control or for all controls. Use it for fields where remembered entries are unwanted, such as IDs, amounts or one-time values.

Syntax

SetAutocomplete /mode=disable [/ctrlid=<control ID>]

Result: empty on success.

Examples

SetAutocomplete /mode=disable
SetAutocomplete /mode=disable /ctrlid=CTRL5

The first disables autocomplete for the whole form; the second for one control only.

Notes

• Any other mode fails with Invalid autocomplete mode: value. The check is case-sensitive, so Disable also fails.
• Each call adds to the settings made before it: several calls with different /ctrlid values disable each of those controls.
• There is no mode that turns autocomplete back on.

Related: SetCharacterLimit, UseOption.

6.7 SetCharacterLimit

Limits how many characters the user can type into a text control, optionally moving the focus to the next control when the limit is reached. Identify the control either by the field it is bound to or by its control ID.

Syntax

SetCharacterLimit /maxlength=<n> /xpath=<XPath> [/dsname=<data source>] [/view=<view name>] [/movenext=true]
SetCharacterLimit /maxlength=<n> /ctrlid=<control ID> /view=<view name> [/movenext=true]

Result: empty on success.

Examples

SetCharacterLimit /xpath=/my:myFields/my:Comments /maxlength=500
SetCharacterLimit /ctrlid=CTRL12 /view=Mobile /maxlength=10 /movenext=true

The first limits Comments to 500 characters in every view; the second limits one control in the Mobile view and jumps to the next control after ten characters.

Notes

• Because filters are not allowed in /xpath, you cannot limit a single row of a repeating table by path; the path names the field, not a row.
• /maxlength is read as a whole number; a value that is not a number counts as 0.
• Errors: /xpath and /ctrlid cannot be specified at the same time., Must specify either /xpath or /ctrlid, Must specify /xpath if /dsname is specified., Must specify /xpath if /view is omitted., Invalid XPath. Please specify the full path to the field, including the leading slash, without //, [, ], ::, *, ., .., or |

Related: SetAutocomplete, SetValue.

6.8 UseOption

Sets a FormsViewer option that changes how the form behaves, such as the way SharePoint lists are queried. Run it on finishedLoading, before anything that depends on the option.

Syntax

UseOption /key=<option name> /value=<option value>

Result: the previous value and the new value, as previous -> new. When the option had no value before, the Result starts with a space, for example -> rest.

Examples

UseOption /key=listquerymode /value=rest
UseOption /key=accessibility.useenhancedtooltips /value=true

The first is the usual fix for "user cannot be found" errors in SharePoint list queries; the second turns on accessible Screentips.

Notes

• The key and value are not checked. A misspelled option name is stored without an error and simply has no effect, so compare the Result with what you expect.
• The Result shows the change, which makes a temporary Set a field value of the Result a quick way to confirm the option took effect while testing.

Related: GetEnvironmentVariable, SetAutocomplete.

6.9 Prompt

Shows a modal dialog with your text and buttons, waits for the user to click one, and returns which one was clicked. Use it to confirm an action (for example before submitting or deleting) or to show a message the user must acknowledge.

Syntax

Prompt [/title=<text>] [/text=<text>] [/type=yesno|yesnocancel|okcancel|ok] [/yestext=<text>] [/notext=<text>] [/oktext=<text>] [/canceltext=<text>]

Result: true for Yes or OK, false for No, and empty for Cancel. Success is true in all three cases.

Examples

Prompt /title=Submit /text=Submit this expense report now? /type=yesno
Prompt /title=Delete rows /text=Delete all rejected rows? /type=okcancel /oktext=Delete
Prompt /text=The report was saved. /type=ok

Notes

• The rule waits while the dialog is open. Put the follow-up actions in the next rule, with a condition such as QdabraRules Result is equal to true, because a rule's condition is checked before its own actions run.
• Cancel and No are different: Cancel returns an empty Result, No returns false. With yesnocancel, test for true and false explicitly.
• The dialog does not close with the Esc key; the user must click a button.
• An invalid /type fails with Invalid type value: value. Allowed values are: yesno, yesnocancel, okcancel ok. If not specified, defaults to yesno. The Command Builder lists ok as a choice although its description mentions only the other three.
• To put a value from the form into the message, build the text with a dynamic parameter, for example /text-xpath=/my:myFields/my:Status (see Chapter 1).

Related: UseOption.

6.10 RegisterMultiDrop

Enables dropping several files at once onto the file attachment controls of a repeating group or repeating field. Run it once on finishedLoading for each repeating group that should accept multiple files.

Syntax

RegisterMultiDrop /repeater=<XPath> [/attachment=<relative XPath>] [/xpathsrc=<XPath>]

Result: empty on success.

Examples

RegisterMultiDrop /repeater=/my:myFields/my:Attachments/my:Attachment /attachment=my:File
RegisterMultiDrop /repeater=/my:myFields/my:Files/my:File

The first enables multi-file drop on the Attachment rows, where each row has a File field. The second is for a repeating field that is itself the file attachment.

Notes

• There is no /dsname: file attachment controls are edited in the main data source, so the paths always refer to it.
• The command only registers the group; it reports success without checking the paths. If dropping several files does not work, check /repeater and /attachment against the data source, and add /xpathsrc if /repeater has a filter.

Related: Insert.

Back to the Command Index.