Skip to content

sc-related-document

This document is a user guide for the sc-related-document component release version 7.1.25.

go-to-typical-definition

sc-related-document-field-Example-1-Image-3

1 Purpose

sc-related-document places a related document field on a form, allowing the user to search for, select and save an existing document as a related document to the document displayed on the form. Related documents are represented by their documentId and summaryName.

The sc-related-document definition provides fields for setting the properties of a related document field and is fully described below.

2 Definition

sc-related-document is defined by a set of name/value pair fields consisting of:

  • Required system fields
  • Required customizable fields
  • Optional customizable fields

Note:

  1. Default values for fields described in the tables below are shown in bold text.

2.1 Required System Fields

Field Valid Values Description
componentName sc-related-document The component name.

Example:
"componentName": "sc-related-document"

2.2 Required Customizable Fields

Field Valid Values Description
filter Elastic search query The filter query used to search for existing documents.

Example:
"filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.systemType': 'document'}},{'term':{'appTags':'testDataSc-related-document'}}]"

Note:
The filter can also be set/changed using the "setFilter" Ruleset function as described in the setFilter Ruleset Function Guide.
name Any value written in camel case. Defines the name of the related document field in the document and database.

Example:
"name": "testScRelatedDocument"

2.3 Optional Customizable Fields

Field Valid Values Description
disableLink true Disables the hyperlinks on the related document field values.

Example:
"disableLink": true
false Default value.
Enables the hyperlinks on the related document field values. Clicking a related document hyperlink will open the related document.
disableSave true Changing the sc-related-document field value (i.e. selecting, deselecting or selecting different related document) does not trigger the Save icon to flash.
Exiting the form without saving changes to the sc-related-document field value does not trigger a warning message to display.
In the Angular version of the sc-related-document component, clicking the Save icon will not save the sc-related-document field value to the document.
In the AngularJS version of the sc-related-document component, clicking the Save icon will save the sc-related-document field value to the document.

Example:
"disableSave": true
false Default value.
Changing the sc-related-document field value (i.e. selecting, deselecting or selecting different related document) does trigger the Save icon to flash.
Exiting the form without saving changes to the sc-related-document field value does trigger a warning message to display.
In both the Angular and AngularJS versions of the sc-related-document component, clicking the Save icon will save the sc-related-document field value to the document.
enabled false The related document field is greyed out.
A Stop icon appears on mouseover.
A document cannot be entered in the related document field.

Example:
"enabled": false
true Default value.
A document can be entered in the related document field.
fieldDefault A set of field mappings A set of one or more field mappings, each mapping a destination field to a source field.
Each mapping is written as:
"destination field name": "source field name".
The destination field is a field on the form.
The source field is a field on the related document.
Each mapping is used to pass a value from a source field to a destination field, thus setting a default value for a destination field.

Example:
"fieldDefault": {
    "state": "australianState",
    "city": "capitalCity",
    "cityPopulation": "capitalCityPopulation"
}

In this example, the default value for:
  • The "state" field on the form is the value of the related document field "australianState".
  • The "city" field on the form is the value of the related document field "capitalCity" field.
  • The "cityPopulation" field on the form is the value of the related document field "capitalCityPopulation".

On saving, the resulting document will save:
  • The related document "documentId" & "name" as elements of a relatedDocument field.
  • The "state", "city" & "cityPopulation" in dedicated root level fields fields.
fullWidth true The related document field displays full width on the form.

Example:
"fullWidth": true
false Default value.
The related document field does not display full width on the form.
label Any value Defines the name of the related document field on the form i.e. the field label.
Example:
"label": " Test sc-related-document"
Defaults to the related document field displays without a field label on the form.
labelStyleText CSS string Formbird applies a default set of display properties when displaying field labels on a Form.

The labelStyleText field provides the ablity to define an alternative set of display properties for displaying the sc-related-documentfield label on a Form.

Example:
"labelStyleText": "color: #000; font-size: 20px;background-color: yellow;font-weight: bold"

In this example, the sc-related-document field label will display as:

sc-related-document-labelStyleText
Defaults to the Formbird default set of display properties for displaying the sc-related-documentfield label on a Form.

The sc-related-document` field label will display as:

sc-related-document-no-labelStyleText
mandatory true The related document field displays as mandatory (i.e. label in red text with an asterisk).
Saving without a value, a message prompts the user to enter a value for the related document field.

Example:
"mandatory": true
false Default value.
The field displays as optional (i.e. label in black text).
newTemplate Template documentId The documentId of a template which can be used to create new documents.
A button is displayed beside the related document field:
sc-related-document-field-new-template-button
Mouse over the button will show a tooltip text (a concatenation of "Add" and the related document field label) e.g. "Add Test sc-related-document"
Clicking the button will open the template allowing the creation a new document.
Example:
"newTemplate": "41b84b40-ba91-11e6-943f-8deecc4f8938"
Defaults to no button is displayed beside the related document field.
relatedFields A set of field mappings A set of one or more field mappings, each mapping a destination field to a source field.
Each mapping is written as:
"destination field name": "source field name".
The destination field is an element of a related document field on the form.
The source field is a field on a related document.
Each mapping is used to pass a value from the source field to the destination field.
Example:
"relatedFields": {
    "city": "capitalCity",
    "cityPopulation": "capitalCityPopulation"
}

In this example:
  • The "city" element of the related document field on the form will be set to the related document "capitalCity" field value.
  • The "cityPopulation" element of the related document field on the form will be set to the related document "capitalCityPopulation" field value.

On saving the form, the resulting document will save:
  • The related document "documentId" & "name" as elements of a relatedDocument field.
  • The "city" & "cityPopulation" also as elements of a relatedDocument field.
showDropDown true Clicking the related document field will list all documents returned by the filter query in a dropdown, each identified by its "summaryName" value.
A document selected from the dropdown will display in the related document field.
On save, the related document field will display "summaryName" of a selected document. If the `"disableLink": false (the default setting), then the sumaryName will display as a hyperlink. Clicking the hyperlink will open the related document.

Example:
"showDropDown": true
false Default value.
Clicking the related document field will not list all documents returned by the filter query in a dropdown.
singleSelection true Only one document can be added to the related document field.

Example:
"singleSelection": true
false Default value.
Multiple documents can be added to the related document field.
trigger The "trigger" field value is a set of name/value pair fields shown below:

"trigger": {
    "postSave": false,
    "data": null
}

Used to watch when the document is saved from dialog. The value will be set to true in documentSaveService.performPostSave function when document is saved.
uniqueSelection true The related document field does not allow a document to be selected more than once.
Selected documents are removed from subsequent dropdown list selections and searches.

Example:
"uniqueSelection":true
false Default value.
The related document field does allow a document to be selected more than once.
Selected documents are not removed from subsequent dropdown list selections and searches.
urlOpenIn newWindow A related document hyperlink opens the related document in a new browser window or tab (the browser determines whether its new tab or window).

Example:
"urlOpenIn": "newWindow"
popup A related document hyperlink opens the related document in a browser pop-up.
Example:
"urlOpenIn": "popup"
overlay A related document hyperlink uses a popup window to overlay the related document over the current page

Example:
"urlOpenIn": "overlay"`
currentWindow Default value.
A related document hyperlink opens the related document in the current browser window or tab (the browser determines whether its new tab or window).

Example:
"urlOpenIn": "currentWindow"
visible false The related document field is not visible on the form.

Example:
"visible": false
true Default value.
The related document field is visible on the form.

3 Typical Definition

Below is a typical sc-related-document definition, defined with its required fields plus any optional field whose value is typically other than its default value.

{
    "componentName": "sc-related-document",
    "label": "Test sc-related-document",
    "name": "testScRelatedDocument",
    "filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.systemType': 'document'}},{'term':{'appTags':'testDatasc-related-document'}}]}}}",
    "showDropDown":true
}

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

    "disableLink":true,
    "disableSave":true,
    "enabled":false,
    "fieldDefault": {
        "state": "australianState",
        "city": "capitalCity",
        "cityPopulation": "capitalCityPopulation"
    },
    "fullWidth": true,
    "labelStyleText": "color: #000; font-size: 20px;background-color: yellow;font-weight: bold"
    "mandatory": true,
    "newTemplate":"41b84b40-ba91-11e6-943f-8deecc4f8938",
    "relatedfields": {
        "city": "capitalCity",
        "cityPopulation": "capitalCityPopulation"
    },
    "singleSelection":true,
    "trigger": {
        "postSave": false,
        "data": null
    },
    "uniqueSelection":true,
    "urlOpenIn": "newWindow",
    "visible":false,

4 Examples

Example 1

sc-related-document defined with the typically needed fields.

        {
            "componentName": "sc-related-document",
            "label": "Test sc-related-document",
            "name": "testGblRelatedDocument",
            "filter": "{'query':{'bool':{'filter':[{'term':{'systemHeader.systemType': 'document'}},{'term':{'appTags':'testDatasc-related-document'}}]}}}",
            "showDropDown": true
        }

Resulting field on the form:

sc-related-document-field-Example-1-Image-1

Resulting field on the form after clicking in the related document field:

sc-related-document-field-Example-1-Image-2

Resulting field on form after selecting a value:

sc-related-document-field-Example-1-Image-3

Resulting field in the document and database after saving:

    "testScRelatedDocument": [
        {
            "documentId": "eb60bd00-baa3-11e6-943f-8deecc4f8938",
            "name": "Test Document - QLD"
        }