Versions Compared

Old Version 32

changes.mady.by.user Mercedes Rothwell

Saved on

compared with

New Version 33

changes.mady.by.user Mercedes Rothwell

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Click on Images to Expand Them

The contents of the Docupace Start wizard pages are created by placing fields of different types on each page. Term “field” in this case refers to any type of element placed on a page. To the end-user, it may look like a text field, a checkbox, a drop-down list, a button, an image, a section, a group of fields, or any of a number of elements. Currently, Docupace Start supports 20 types of fields, as described in the Field Types reference section.

Each field has settings that control its contents, its functionality, and its visualization. Some of these settings are common to almost all field types. These are addressed in this description and also in the Field Settings (common) reference section. For settings specific to each Field Type, see respective chapters of this guide.

In some instances (for fields labels and for rich-text fields) you can edit text directly in the Designer panel. When using this method, any text pasted will retain its original formatting.

Related Sections:

Table of Contents
absoluteUrltrue
excludeRelated Sections

To place a new field on a page proceed as follows:

Step 1: Add a Single Text Field.

1.1. Click on the page in the page tree pane on the left side of the Docupace Start screen. It is opened for editing in the Designer panel.

New empty page of the wizard

1.2. Open Add Field panel.

1.3. Click the Single Text button to add it as the first field for this page.

Adding a Single Text field

1.4. Select the Single Text field and open Field Settings.

1.5. Enter the following values for this field:

Field Settings for a Single Text field

Expand
titleField Values

Field

Value

Field Label

Owner Last Name
This is the name of the field that is visible to the user and is displayed above or next to the field, or on top of an Action button.

Use label as placeholder

Deselected

Placeholder

Type the owner's last name.
Text that will be visible to the user inside the field as a tip.

Meta Field Name

Owner1.LastName
This is the unique name for the data held within the field as it is referenced by code and in the database. It will be mapped to a specific field in a PDF form. Notation for Meta Field Names is described in How to Choose a Meta Field Name.

Warning

Warning! This is a mandatory setting. If left empty for any of the fields, the wizard will not function properly.

Warning

Warning! Meta Field Name must start with a letter. It may contain letters, numbers and underscores ("_"). Other characters are not permitted and will prevent the wizard from functioning properly.

On value change

JS code that will be performed, when the value in this field has been changed.

Initial value

A JavaScript expression that provides a specific value that is used as default value for this field. It is shown and selected as the first value for this field, when the user opens the page. E.g., a choice in a drop-down, that is initially selected, or a sting in a text field that is already filled in. To enter a string or a value from choices, use quotes, e.g. "Yes" The JS expression's execution context has only 2 variables:

  • field - field configuration

  • application - same as $scope.widgetApp

Validations

Validations are described in-depth in a separate chapter of this guide.
Validations that will be performed for this field. This setting overrides the default validations defined in the Wizard settings.
To create several blocks of validations, click +Add in the bottom of this section.

Column Span

1
The page of the wizard is divided into two invisible columns. Column span 1 means that the field uses space of one column on the page (or less, if the Size by content option is selected).

Enabled condition

startingPointData['Owner1.Type'] == 'Person'
If the result of this expression evaluates to TRUE or if this setting is left empty, the field will be available for editing to the user, visible and enabled.

Visibility Condition

startingPointData['Owner1.Type'] != 'Entity'
If the result of this expression evaluates to TRUE or if this setting is left empty, the field will be visible to the user.

Read-Only Condition

scope.api.getCurrentWorkItemId() != null
If the result of this expression evaluates to TRUE, the field will be visible to the user, but as a read-only value. The condition can be used, for example, to lock the form after a Work item is created and the user just wants to review the data on the page.

Default Value

Leave this field empty.
This setting provides a "hard-coded" value for this field. It will be used as the value for this field even if the user tries to change it.

Required

Selected
If selected, the user will be required to fill in this field. This is a built-in validation. An asterisk will be displayed next to the field label.

New Line

Deselected
If selected, the field will start on a new line on the page.

Size by content

Selected
If the option is selected, the size of the field will change (stretch) to match the content in it. The Column Span setting will be ignored.

CSS class names

Leave empty, to keep the default styling.
The field allows to enter several space-separated CSS class names defined in CSS/LESS or Global CSS/LESS tab, to override the default Docupace styling.

Step 2: Apply the Changes.

2.1. Click Apply button in the bottom of the screen to close the Widget Design Screen and apply changes.

2.2. Click Save button in the top of the Widget Details Screen to save these changes. Click on the Widget configuration cogwheel icon to open Docupace Start and proceed adding fields to pages.

Image RemovedImage Added
Note

Note: Repeat these two steps, when you have made several changes to the wizard and need to save them. If you leave your work for a time and your session times out, changes will not be saved.

How to Choose a Meta Field Name

Meta Field Name is the unique name for the data held within the field as it is referenced by code and in the database. 

The Meta Field Name is a mandatory setting for all field types that may carry data to the system. If left empty for any of the fields, the wizard will not function properly. This issue is logged in the console. When a wizard doesn't load (a blank screen appears to the user), please check the console for this type of configuration error.

There are predefined field names in the PDF forms (client documents). Within the Docupace system most of these PDF names are mapped (cross-referenced) to a Meta Field Name in the BASE namespace. 

If the data from your wizard must be mapped to a specific field in a PDF form, use the predefined values from the Quick Field Names Table.  You may use either the name from the BASE namespace or the name used directly in the PDF form. If the mapping is working correctly, both cases should work.

A PDF form with field names visible

One way to find out what meta field names and corresponding values to use, so that they map correctly to a PDF form, is to open a relevant document from a Client subfolder. Turn on Admin Mode, by clicking the cogwheel icon . Meta field names and their values can be seen by floating the mouse cursor over a field. They can be copied by right-clicking on the field.

The usual notation is objectName.propertyName.

Most of the objects and their properties are self-explanatory.

Info

Examples:

Applicant1.IncomeRange
Guardian1.FirstName
Guardian1.LastName
Dependent1.Age
Spouse1.PrimaryPhoneType
Beneficiary1.PictureID
Rep1.RIANumber
Rep1.BranchPhone1 

Meta Field Names and Values on a PDF form in Admin Mode


If the data is only used for the purposes of this wizard, e.g. as a selector for further transitions, then you may create any name for it. It can be a stand-alone field name, or it can be a property of an object defined within the wizard (e.g. defined in the onLoad actions in Wizard Settings).

Warning

Warning! Unless the name comes from the Quick field list, the Meta Field Name must start with a letter. It may contain letters, numbers and underscores ("_"). Other characters are not permitted and will prevent the wizard from functioning properly.

Info

Examples:

WizardChoice.MoreFilesAttached

myField1

nextPageNumber.

How to Access Meta Field Values

Most of the Docupace wizard flexibility and functionality relies on getting current values from the Meta Fields. Meta Field values are used in a number of settings: enabled condition, visibility condition, read-only condition, on value change actions, custom validations, transition actions, for displaying dynamic text in Rich Text fields, for setting initial value, and many more.

When writing JS expressions or code, you can access Meta Field values in several ways.

Syntax

Description

Example

startingPointData['Meta Field Name']

The recommended way how to access Meta Fields values. Prefix with $scope, when using in onEnter JavaScript code.

In visibility conditions, transition conditions, and similar, use this format:

Code Block
startingPointData['Owner1.FirstName']

In onEnter JavaScript use this format:

Code Block
$scope.startingPointData['Owner1.FirstName'] = 'John'

model.parent.value["Local Meta Field Name"]

Use   this syntax if you need to read the value of a field in a repeating group. Used in visibility, read-only and required conditions.

Note

Note: Currently this syntax does not work for Rich Text Fields. It is not possible to set a visibility condition based on a value of a field in a repeating group.

For example, if you have a repeating group of phone numbers, which has a Phone Type, a Phone Number and an Extension, and you need to accommodate a business rule which says that Extension must be shown only if Phone Type is Business. In this case, the current number’s Type be accessed, which may be Phone1.Type, Phone2.Type, Phone3.Type, etc., depending on how many phones the repeating group has. The startingPointData object will not provide the correct Type. Use the following format:

Code Block
model.parent.value["Type"]

widgetApp.wizard.getCurrentPageName()

Get the current page name, in which this Java Script function is run.

Code Block
widgetApp.wizard.getCurrentPageName()

$scope.wizardState

 

Another way how to access Meta Fields values.

Note

Note:  Don't use $scope prefix in Visibility Conditions, leave only wizardState .

Code Block
$scope.wizardState.Owner4 == true

How to Track Changes to Meta Fields

To configure actions within a wizard that are based on changes made to a Meta Field, use these methods.

Description

Example

Use $watch method of the $scope object to observe changes to any Meta Field values.
 

Code Block
$scope.$watch('startingPointData["Owner1.FirstName"]', 
  function (newName) {
  console.log(newName)
})

To track changes made to any field in an object, pass 'true' as a third parameter into the $watch method.
 

Code Block
$scope.$watch('startingPointData', 
  function (updatedStartingPointData) {
  console.log(updatedStartingPointData)
  }, 
  true))