sc-help-button

This document is a user guide for the sc-help-button component release version 7.1.23.

1 Purpose

The sc-help-button component places a Help button on a form:

sc-help-buttons, which when clicked, can be used to display Help text about:

• A form
• A panel on a form.
• A field on a form.

The Help text linked to a particular Help button is defined by the document and the field in which that Help text is stored. Formbird supports using either multiple documents or a single document with multiple fields to store items of Help text.

Clicking a Help button opens a modal Help pop-up displaying the required Help text.

The Help button can be defined such that the Help pop-up displays the Help text in either View only mode (as shown above) or in View/Edit mode (as shown below). In View/Edit mode, the Help pop-up provides a View/Edit switch allowing the Help text to be switched between View and Edit mode.

To close the Help pop-up, the user simply clicks the Help pop-up close button

The sc-help-button component definition provides fields for setting the properties of the Help button and is fully described below.

2 Definition

The sc-help-button component 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

2.2 Required Customizable Fields

2.3 Optional Customizable Fields

Field	Valid Values	Description
btnClass	btnRound	Default value. The Help button displays on the form as a round button with a question mark.
enabled		The "enabled" field or the "keyIds" field can be defined to display the Help text in either 'View Only' mode or in 'View/Edit' mode. Note: If both the "keyIds" and the "enabled" fields are defined then the "keyIds" field will override any value of the "enabled" field.
	false	The Help pop-up displays the Help text in 'View Only' mode preventing the user from editing the Help text. Example: "enabled": false
	true	Default value. The Help pop-up displays a View/Edit switch allowing the Help text to be switched between 'View Only' and 'Edit' mode.
fullWidth	true	The sc-help-button field displays full width and right justified of the form. Example: "fullWidth": true
	false	Default value. The sc-help-button field does not display full width on the form.
helpDisplayWidth	string containing a numeric %	Defines the width of the modal help pop-up, expressed as a percentage of the maximum width. Example: "helpDisplayWidth": "75%"
helpDocumentId		The location of the required Help text is defined by the document and the field in which it is stored i.e. by a helpDocumentId and a helpFieldName.
	A valid Document ID	The document ID of the document that stores required Help text. Example: "helpDocumentId": "f5594af0-9d38-11e9-a626-1b3f204c67d0"
helpFieldName		The location of the required Help text is defined by the document and the field in which it is stored i.e. by a helpDocumentId and a helpFieldName.
	A valid document field name	The name of the document field that stores the required Help text. Example: "helpFieldName": "helpField"
helpFormat		The format of the Help text stored in the help document's help field. Valid formats are HTML and MARKDOWN.
	MARKDOWN	When the Help pop-up is in View only mode, Markdown formatted Help text will be processed to HTML for viewing in the Help pop-up. When the Help pop-up is in Edit mode, the Help pop-up displays Help text in a sc-markdown-editor allowing the user to edit and save the Help text in Markdown format.
	HTML	Default value. When the Help pop-up is in edit mode, the Help pop-up displays Help text in a sc-rich-text editor allowing the user to edit and save the Help text in HTML format.
helpHeight	fitText	Default value. The height of the Help pop-up is determined by the amount of help information it has to display. For a very large amount of information the pop-up will span the height of the screen and if required provide the ability to scroll.
helpTemplateId	A valid templateId	The template ID of the help document. Example: "helpTemplateId": "cb1af5c0-95e2-11e9-8108-e9db4351ffae"
keyIds		The enabled field or the keyIds field can be defined so as the Help pop-up displays the Help text in either View only mode or in View/Edit mode Note: If sc-help-button definition has both the "keyIds" and the "enabled" fields defined then the "keyIds" field will override any value of the "enabled" field.
	Array of keyIds	An array of one or more keyIds used to control who can edit Help text displayed in the Help pop-up. A user account must have at least one of these keyIds in order to switch the Help pop-up from View mode to Edit mode and then edit the Help text. If a user account does not have at least one of these keyIds, then they will only be able to view the Help text. Example: "keyIds": [     "3e88afa0-5e50-11e8-baa9-a9d161e55a91",     "a4a16960-0525-11e7-b390-f561768f8b16",     "8b81b585-256e-adb3-4787-6a34cdf4d70b" ]
		Defaults to the view/edit mode as determined by the "enable" field value.
label	Any value	The name of the sc-help-button field on the form i.e. the field label. The field label displays as: Tooltip text on mouseover of the sc-help-button field. The title of the help text shown within the help pop-up Examples: "label": "Help for entering the Address Details" "label": "Typical Defn sc-help-button"
		Defaults to the sc-help-button field displays without a field label on the form. Hence: No tooltip text on mouseover of the sc-help-button field. Help text shown within the help pop-up displays without a title.
visible	false	The sc-help-button field is not visible on the form. Example: "visible": false
	true	Default value. The sc-help-button field is visible on the form.

3 Typical Definition

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

    {
        "componentName": "sc-help-button",
        "name": "typicalDefnScHelpButton",
        "btnClass": "btnRound",
        "enabled": false,
        "fullWidth": false,
        "helpDocumentId": "0a26ef30-405e-11ec-932a-ef90488cd889",
        "helpFieldName": "helpField",
        "helpFormat": "HTML",
        "helpHeight": "fitText",
        "helpTemplateId": "cb1af5c0-95e2-11e9-8108-e9db4351ffae",
        "label": "Typical Defn sc-help-button"
    }

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.

        "enabled":true,
        "fullWidth":true,
        "helpDisplayWidth": "75%"
        "keyIds": [
            "3e88afa0-5e50-11e8-baa9-a9d161e55a91",
            "a4a16960-0525-11e7-b390-f561768f8b16",
            "8b81b585-256e-adb3-4787-6a34cdf4d70b"
        ],
        "visible": false,

4 Examples

Example 1

sc-help-button defined with the typically needed fields.

    {
        "componentName": "sc-help-button",
        "name": "typicalDefnScHelpButton",
        "btnClass": "btnRound",
        "enabled": false,
        "fullWidth":false,
        "helpDocumentId": "0a26ef30-405e-11ec-932a-ef90488cd889",
        "helpFieldName": "helpField",
        "helpFormat": "HTML",
        "helpHeight": "fitText",
        "helpTemplateId": "cb1af5c0-95e2-11e9-8108-e9db4351ffae",
        "label": "Typical Defn sc-help-button"
    }

Resulting field on the form:

Resulting field on the form after clicking the help button

Clicking the help button will open a modal Help pop-up displaying the required Help text in View only mode.

To close the Help pop-up, click it's close button

Example 2

sc-help-button defined with the typically needed fields plus the "enabled": true field.

    {
        "componentName": "sc-help-button",
        "name": "typicalDefnScHelpButton",
        "btnClass": "btnRound",
        "enabled": true,
        "fullWidth":false,
        "helpDocumentId": "0a26ef30-405e-11ec-932a-ef90488cd889",
        "helpFieldName": "helpField",
        "helpFormat": "HTML",
        "helpHeight": "fitText",
        "helpTemplateId": "cb1af5c0-95e2-11e9-8108-e9db4351ffae",
        "label": "Typical Defn sc-help-button"
    }

Resulting field on the form:

Resulting field on the form after clicking the help button:

Clicking the Help button will open a modal Help pop-up displaying the required Help text in View mode. A View/Edit Switch allows the user to switch to Edit mode.

To close the Help pop-up, click it's close button

Resulting field on the form after switching the View/Edit switch to Edit mode.

Switching the View/Edit switch to Edit mode displays the Help Text in the Rich Text Editor.

Resulting field on the form after editing the Help text.

Editing the Help text will trigger the Save button to display

Clicking the Save button will save the edited Help text and close the Help pop-up.

Closing the Help pop-up without saving the edited Help text will display a Warning pop-up allowing the user to either Cancel, Discard or Save the changes.