eSign Field Tags

Introduction

eSign field tags are text elements that can be inserted anywhere within a document, which will be replaced by actual form fields on that particular location.
By using these tags we can add fields like: signatures, text inputs and checkboxes, as well as specifying rules for each of these.

When a eSign receives a document, it will look for these tags and replace them with the corresponding fields and information. With these tags we can enrich a document with business logic in a simple way.

Tag Structure

A field tag starts and ends with double brackets {{ }}.
The content within the tags may vary according to the desired purpose for that tag.

Below are some simple examples:

Example Description

{{t:sig|n:Signature1}}

Creates a signature names 'Signature1' to the document at the location of the tag, and with same are as the tag.

{{t:chk|m:!|n:ReadAndAccept}}

Creates a checkbox name 'ReadAndAccept' that is mandatory

{{t:txt|m:*|n:Company|v:Celfocus}}

Creates a read-only input field containing the value Celfocus.

Field Area

By default the size of the created fields will match the length of the tag, this means that if we want the field to be bigger than the actual tag we can simply add white spaces at the end.
Example: {{t:sig|n:Signature1|…​…​…​…​…​…​.}}

Of course if we want to be more precise regarding the dimensions of a field we can add the exact intended size to the field tag:

Example Description

{{t:sig|n:Signature1|w:200|h:50}}

Creates a signature names 'Signature1' with 200px of width and 50px of height.

Additionally there may be times where we want the generate field to be slightly offseted from the position of the tag. For such scenarios we can user the offset properties of the tag:

Example Description

{{t:sig|n:Signature1|offx:10|offy:20}}

Creates a signature names 'Signature1' 10px to the left of the tag and 20px above the tag.
Remember that in PDF documents all measures are performed counting from the bottom

Ownership

Unless explicitly specified, the field originated from a tag can be used by anyone who accesses the document.
To ensure that only a specific user or role can use a field we must add ownership to the tag.

Example Description

{{t:sig|n:Signature1|own:USER:sam}}

Creates a signature names 'Signature1' the can only be signed by the user Sam.

{{t:sig|n:Signature1|own:ROLE:operator,administrator}}

Creates a signature names 'Signature1' the can only be signed by a user with either the role 'operator' or 'administrator'

Placeholders

There may be times when we want the tags to contain information that may vary between each use of the document template.
For these cases the value of any tag may contain a block $\{<varname>\} where varname is the name of a property to be replaced during the document creation.

When we send a document to eSign, we can specify a set of properties (name-value pairs). eSign will inspect these properties and replace $\{<varname>\} with the value of the property named varname.

Example Description

{{t:txt|m:*|n:Company|v:${company_name}}}

Creates a read-only input field containing the value of the company_name property that was sent along with the creation of the document.

Add Properties

Fields created in eSign may have their own properties. This meta-information can later be used for several eSign features.
See the complete in the Field Variables section.

Properties of the fields are stored as url encoded query parameters.
Example Description

{{n:Signature1|vars:name1%3Dvalue1%26name2%3Dvalue2}}

Creates a signature field with properties name1=value1 and name2=value2

Properties are separated by the 'and' sign (&) and each property is a name-value pair separated be 'equals' sign (=).
To allow storing all types of characters within the tag, the properties need to be url-encoded.

Example:

When Storing two properties pairs name1-value1 and name2-value2 in the tag, the structure should be:

  • name1=value1&name2=value2

And then the entire block needs to be url-encoded into:

  • name1%3Dvalue1%26name2%3Dvalue2

Font Properties

When creating a text field we can optionally specify the font size and/or font family.

A font property may contain the font size and the font family separated by a colon (:).

Example Description

{{t:txt|n:TextField1|font:10}}

Creates a text field with font size 10

{{t:txt|n:TextField1|font:10:Verdana}}

Creates a text field with font Verdana and size 10

{{t:txt|n:TextField1|font::Verdana}}

Creates a text field with font Verdana (note that a colon (:) needs to preceed the font family to inform that no font size is being specified.

Attributes

The field tags are composed of a list of attributes separates by a vertical bar (|), and each attribute is a name-value pair separated by a colon (:).

Example: {{<name1>:<value1>|<name2:value2>|…​}}

Below is a list of all the tag attributes supported by eSign:

Attribute Purpose Type Description

t

Field Type

String

Specifies the type of field to be created. Possible values:
SIG - signature field
TXT - text input field
CHK - checkbox field
(default: SIG).

n

Field Id

String

Unique identifier of the field to be created.

v

Value of the field

Enum

Only applicable to field types TXT and CHK.
TXT - sets the value of the input field
CHK - If 'true' the checkbox is checked by default, otherwise is unchecked.
(default: <empty>)

m

Modifiers of the field

Enum

Supported modifiers are:
! - The created field is set as mandatory
* - The created field is set as read-only

lbl

Field label

String

Specifies the tooltip and label of the field to be created
(default: <empty>)

stp

Field step

Numeric

Specifies the step of the document to which the field belongs to.
(default: 1)

seq

Field sequence

Numeric

Specifies the sequence order of the field in the document.
Fields with a sequence number only become enabled after all other fields with a lower sequence number are filled.
(default: 0 - Field can be edited at any time)

own

Field Ownership

Enum

Determines who can use the field:
USER:<username1,username2,…​> - Specifies the list of users that can use the field
ROLE:<role1,role2,…​> - Specifies the list of roles that can use the field

vars

Field properties

Url-encoded text

Properties to associate to the field to be created.
See: Properties.

w

Field width

Numeric

Determines the width (in pixels) of the field to be created.
If not specified, the field width match the width of the field tag.

h

Field height

Numeric

Determines the height (in pixels) of the field to be created.
If not specified, the field height match the width of the field tag.

offx

Field horizontal offset

Numeric

Determines the horizontal offset (in pixels) of the field to be created, based on the field tag position.
(default: 0)

offy

Field vertical offset

Numeric

Determines the vertical offset (in pixels) of the field to be created, based on the field tag position.
(default: 0)

font

Font information of the text field to be created

String

Determines the font size and family of a text field.
Only applicable over TXT fields.