sc-thumbnail

This document is a user guide for the sc-thumbnail component release version 7.1.14.

1 Purpose

The sc-thumbnail component places a thumbnail field on a form such that:

It provides the ability to locate documents and display them as thumbnails on a form.
Each thumbnail reflects the content of the document it represents, making it easier for the user to quickly navigate to the required document.
It includes a slider field allowing the user to increase/decrease the thumbnail size.
Clicking the thumbnail will open the document it represents in a modal pop-up. For pdf documents, the modal pop-up displays the first page of a pdf document and provide the ability to navigate page by page througn its other pages (if any). For image documents, the modal pop-up displays the image.

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

2 Definition

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

Required system fields
Required customizable fields
Optional customizable fields

Note:

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-thumbnail	The component name. Example: `"componentName": "sc-thumbnail"`

2.2 Required Customizable Fields

Field	Valid Values	Description
name	Any value written in camel case.	Defines the name of the sc-thumbnail field in the document and database. Examples: `"name": "typicalDefnScThumbnail"`
documentLocations	Array of document location definitions	An array of one or more document location definitions, each identifying the location of a document to be displayed as a thumbnail on the form. See Section 2.4 documentLocations Field for detailed description of the documentLocation field.

2.3 Optional Customizable Fields

Field	Valid Values	Description
enabled	true	The sc-thumbnail field on the form is greyed out. A Stop icon appears on mouseover of the sc-thumbnail field. The 'Display Width' slider field cannot be used to increase/decrease the thumbnail size. Clicking a thumbnail will not open the file it represents. Example: `"enabled": false`
	false	The sc-thumbnail field on the form is not greyed out. A Stop icon does not appear on mouseover of the sc-thumbnail field. The 'Display Width' slider field can be used to increase/ decrease the thumbnail size. Clicking a thumbnail will open the file it represents.
filter	elastic search query	An elasticsearch query to locate the documents to display as thumbnails on the current document. Example: `"filter": "{'query':{'bool':{'should':[{'term':{'systemHeader.templateId':'81633d5e-3e3e-450d-b702-a2edf5b7c076'}}]}}}"`
		Defaults to no elasticsearch query search is performed.
fullWidth	true	The sc-thumbnail field displays full width and right justified of the form. Example: `"fullWidth": true` `"fullWidth": true` is recommended when displaying a sc-thumbnail field on a form.
	false	Default value. The sc-thumbnail field does not display full width on the form.
initialImageSize	Integer value between 3 and 12	Sets the initial position of the thumbnail slider field. An integer value less than or equal to 3 sets the slider to its leftmost position (i.e. the smallest thumbnail size). An integer value greater than or equal to 12 sets the slider to its rightmost position (i.e. the largest thumbnail size). Example: `"initialImageSize": 3`
	8	Default value.
label	Any value	Defines the name of the sc-thumbnail field on the form i.e. the field label. Example: `"label": "Typical Defn sc-thumbnail"`
		Defaults to the sc-thumbnail field displays without a field label on the form.
visible	false	The sc-thumbnail field is not visible on the form. Example: `"visible": false`
	true	Default value. The sc-thumbnail field is visible on the form.

2.4 documentLocations field

The documentLocations field listed in Section 2.3 Optional Customizable Fields is an array of one or more document location definitions, each providing fields to define the location of a document to be displayed as a thumbnail on the form.

This section lists and describes the fields for defining the location of a document.

2.4.1 Required Customizable Fields

Field	Valid Values	Description
fieldName		The name of the field to use in the current document or in a result document returned by the optional `filter` field query. To specify a field in the current document, prefix its field name with "document.". To specify a field in a result document returned by the optional `filter` field query, prefix its field name with "result.". Although not recommended, if the fieldName value is not prefixed, then the default prefix is "result." Examples: `"fieldName": "document.fileAttach"` `"fieldName": "result.fileAttach"`
fieldType		The type of field so that data can be interpreted.
	docId	The documentId of a document in the Formbird database. Example: `"fieldType": docId`
	sc-uploader	Indicates documents created by the sc-uploader component. Example: `"fieldType": "sc-uploader"`
	url	A url that can be used to access the item. Example: `"fieldType": url`
itemType		An array of one or more item types to display, thus providing the ability to filter the items to display by item type. Examples: `"itemType": ["image"]` `"itemType": ["image","pdf"]`
	image	Documents with an image file format e.g. png, jpg/jpeg, gif Example: `"itemType": ["image"]`
	pdf	Documents with a pdf file format. Example: `"itemType": ["pdf"]`
		Defaults to no items, hence thumbnails, are displayed.

2.4.2 Optional Customizable Fields

Field	Valid Values	Description
title	handlebars expression	A handlebars expression used to set the title of for each thumbnail. Example: `"title": "{{{result.responseAttach.fileName}}}"`

updateWatchFields	Array of field names in the current document	Specifies one or more fields in the current document to watch and to rerun the `filter` field query when any of these fields change. If the optional `filter` field has not been defined then items defined by the `documentlocations` field will refresh, generating new thumbnails and thumbnail titles. Example: `"updateWatchFields": [` `"document.status"` `]` Example: `"updateWatchFields": [` `"document.firstName",` `"document.lastName"` `]`
		Defaults to no fields in the current document are being watched for a change in value.

3 Typical Definition

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

        {
            "componentName": "sc-thumbnail",
            "name": "typicalDefnScThumbnailWithFilter",
            "fullWidth": true,
            "initialImageSize": 3,
            "filter": "{'query':{'bool':{'should':[{'term':{'systemHeader.templateId':'81633d5e-3e3e-450d-b702-a2edf5b7c076'}}]}}}",
            "documentLocations": [
                {
                    "fieldName": "typicalDefnScUploader",
                    "fieldType": "sc-uploader",
                    "itemType": [
                        "image",
                        "pdf"
                    ],
                    "title": "DocId : {{results.documentId}}"
                }
            ],
            "label": "Typical Defn sc-thumbnail with Filter"
        }

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":false,
        "fullWidth":false,
        "updateWatchFields": [
            "document.firstName",
            "document.lastName"
        ],
        "visible": false,

4 Examples

Example 1

sc-thumbnails defined with the typically needed fields.

        {
            "componentName": "sc-thumbnail",
            "name": "typicalDefnScThumbnailWithFilter",
            "fullWidth": true,
            "initialImageSize": 3,
            "filter": "{'query':{'bool':{'should':[{'term':{'systemHeader.templateId':'81633d5e-3e3e-450d-b702-a2edf5b7c076'}}]}}}",
            "documentLocations": [
                {
                    "fieldName": "typicalDefnScUploader",
                    "fieldType": "sc-uploader",
                    "itemType": [
                        "image",
                        "pdf"
                    ],
                    "title": "DocId : {{results.documentId}}"
                }
            ],
            "label": "Typical Defn sc-thumbnail with Filter"
        }

Resulting field on the form:

The leftmost thumbnail is for a pdf document, the rightmost thumbnail is for a png image document.

Resulting field on the form after moving the slider button to the right to enlarge thumbnails:

Clicking the thumbnail for the pdf document opens the pdf document in a modal pop-up:

The modal pop-up displays the first page of an eleven page pdf document and provides the ability to navigate page by page througn its other pages. To close the modal pop-up, click the red "Close" button.

Clicking the thumbnail for the png image document opens the png document in a modal pop-up:

To close the modal pop-up, click the red "Close" button.