# Advanced usage

The definition tags can be used to handle long text tags. When text tags contain many directives, they may become very long, making it difficult to specify fields with small bounds on the document. To solve this, the definition is introduced.

Following is the list of definitions that can be added to the tags with descriptions.

{% nestedtable %}

- {% arguments name="DefinitionId" /%}{% batch datatype="string" /%}{% required /%} 
- The ID will be used to match the text tag definition provided in the document.

---

- {% arguments name="Type" /%}{% batch datatype="string" /%}{% required /%} 
- The form field type.

---

- {% arguments name="SignerIndex" /%}{% batch datatype="integer" /%}{% required /%} 
- Index of the signer to which the field needs to be assigned.

---

- {% arguments name="IsRequired" /%}{% batch datatype="boolean" /%}
- Indicates whether the field is required or not.

---

- {% arguments name="IsMasked" /%}{% batch datatype="Nullable boolean" /%}
- Decides whether this form field should be masked so that its value is hidden from other signers present in the document.

---

- {% arguments name="FieldId" /%}{% batch datatype="string" /%}
- Unique field Ids are to be set for all the individual fields.

---

- {% arguments name="Size" /%}{% batch datatype="json" /%} 
- Indicates the size of the text tag.

---

- {% arguments name="Font" /%}{% batch datatype="json" /%}
- Font to be set for the form field.

---

- {% arguments name="Validation" /%}{% batch datatype="json" /%}
- Validation for the content present in the textbox field type.

---

- {% arguments name="Placeholder" /%}{% batch datatype="string" /%}
- Placeholder to be displayed in the textbox field.

---

- {% arguments name="DateFormat" /%}{% batch datatype="string" /%}
- Date format to be set in the date time field.

---

- {% arguments name="RadioGroupName" /%}{% batch datatype="string" /%}
- Group name to be set in the radio button fields.

---

- {% arguments name="GroupName" /%}{% batch datatype="string" /%}
- Assign a group name for the form field to be used with form groups.

---

- {% arguments name="TabIndex" /%}{% batch datatype="Nullable int" /%}
- Assign tab index to control the flow of field focus while using `TAB` key navigation. Default to `null`, which denotes it will follow regular flow. The accepted range starts from `-1` to a valid `integer`.
---
- {% arguments name="Label" /%}{% batch datatype="string" /%}
- The label used to represent the value for a radio button. Also, can be used to prefill a radio button.
---

- {% arguments name="PageNumber " /%}{% batch datatype="integer" /%}
- Page number in which the form field should be placed.

---

  - {% arguments name="Offset" /%}{% batch datatype="object" /%}
  - Specifies the offset positioning for the text tag, allowing adjustments to its location relative to the computed position. The computed value after value must remain within the page dimensions.
    {% nestedtable %}

    - {% arguments name="OffsetX" /%}{% batch datatype="double" /%}
    -  Adjusts the text tag's position horizontally (left or right).

    ---

    - {% arguments name="OffsetY" /%}{% batch datatype="double" /%}
    - Adjusts the text tag's position vertically (top or bottom).

    {% /nestedtable %}


---

- {% arguments name="resizeOption" /%}{% batch datatype="enum" /%}
- Defines how the Textbox form field resizes based on the entered text. The available values are `GrowHorizontally`, `GrowVertically`, `GrowBoth`, `FixedSize`, and `AutoResizeFont`.

---

  - {% arguments name="DataSyncTag" /%}{% batch datatype="string" /%} 
  - The value that can be specified on two or more textbox fields to sync them.

  ---

  - {% arguments name="TextAlign" /%}{% batch datatype="string" /%} 
  - Determines the horizontal alignment of text for the textbox and label form fields, and can be set to `Left`, `Center` or `Right`. The default of alignment of text is `Left`.

  ---

  - {% arguments name="TextDirection" /%}{% batch datatype="string" /%} 
  - Determines the text direction of text for the textbox and label form fields, and can be set to `LTR` or `RTL`. The default text direction is `LTR`.

  ---

  - {% arguments name="CharacterSpacing" /%}{% batch datatype="float" /%} 
  - Determines the character spacing of text for the textbox and label form fields. It can be set as a floating-point value.

  ---

  - {% arguments name="CharacterLimit" /%}{% batch datatype="integer" /%} 
  - Limits the number of characters in the text. The character limit value must be greater than zero.

{% /nestedtable %}

## Usage syntax

Tag usage starts with @ and proceeds with the definition Id from TextTagDefinitions provided in the send request.

The sample for the definition Id set as `tag1` is given below:

```json
{{@tag1}} 
```

**Note:** If the definition Id provided in the document is not present in TextTagDefinitions, then the document will not be sent, and the reason for this will be sent to the webhook endpoint configured.

## Substitution and override

 When there is a use for different field labels and field ids with the same set of tags, the definition values can be overridden in the text tags with label and field ID.

```json
{{@tag1:Please enter your first name|firstName}}
```

## Size

The size of the field can be configured using the `Size` property in definition tags. This will override the size of the definition tag, which is set in the document.

```json
{
    "width": 0,
    "height": 0
}
```

## Offset

The offset of the field can be configured using the `Offset` property in definition tags. This will override the offset of the definition tag, which is set in the document.

`OffsetX` - Adjust the textTag postion left or right.

`OffsetY` - Adjust the textTag postion top or bottom.

**Note:** If offset value out of bounds according to its page size then the document will not be sent, and the reason for this will be sent to the webhook endpoint configured.

```json
{
    "offsetX": 0,
    "offsetY": 0
}
```

## Font

Different aspects of fonts, like the font name, font size, and font style, can be configured in the definition tags. This provides further customization to the fields, and this helps in differentiating different fields when filling.

Supported fonts are given as follows:

- Helvetica
- Courier
- TimesRoman

 Following are the supported font styles.

- Regular
- Bold
- Italic
- Underline

These font styles can be achieved using `IsBoldFont`, `IsItalicFont` and `IsUnderLineFont`

```json
{
    "name": "Helvetica",
    "color": "string",
    "size": 0,
    "lineHeight": 0,
    "isBoldFont":"boolean",
    "isItalicFont":"boolean",
    "isUnderLineFont":"boolean"
  }
```

**Note:** Helvetica is the default font type for all the fields.

## Validation

Even though the textbox field accepts any value, you can control and define what values are accepted by using validations. The textbox fields support a number of built-in form validations as well as your own custom Regex validation to allow only certain characters or only uppercase, etc. Validation can take one of five types:

1. NumberOnly
2. Email
3. Currency
4. CustomRegex
5. None

```json
{
    "type": "NumberOnly",
    "regex": "string",
    "regexMessage":"string"
}
```

## Sample document

The sample document with text tags can be downloaded {% customlink href="https://www.syncfusion.com/downloads/support/directtrac/general/pd/BoldSign_TextTags1560747096.pdf" text="here" /%}. Kindly note that the tags will not be visible since they are added in the same color as the background (white-on-white).

Sample document with hidden text tags:

![BoldSign invisible tags](/static/images/text-tags/boldsign-in-visible-tags.webp)

Sample document with visible text tags:

![BoldSign visible tags](/static/images/text-tags/boldsign-visible-tags.webp)

A sample send document API request with the `UseTextTags` property enabled and TextTagDefinitions is shown below.

Request Body - containing definition tags

{% codetab %}

cURL

```shell 
curl -X POST 'https://api.boldsign.com/v1/document/send' \
      -H 'X-API-KEY: {your-api-key}' \
      -F 'Title=Sent from API Curl' \
      -F 'Message=This is document message sent from API Curl' \
      -F 'EnableSigningOrder=false' \
      -F 'Signers[0][Name]=Signer Name 1' \
      -F 'Signers[0][EmailAddress]=luthercooper@cubeflakes.com' \
      -F 'Signers[0][SignerOrder]=1' \
      -F 'Signers[0][SignerType]=Signer' \
      -F 'Signers[0][authenticationCode]=123' \
       F 'Signers[0][PrivateMessage]=This is private message for signer' \
      -F 'CC[0][emailAddress]=stacywilson@cubeflakes.com' \
      -F 'UseTextTags=true' \
      -F 'TextTagDefinitions[0][DefinitionId]=tag1' \
      -F 'TextTagDefinitions[0][Type]=TextBox' \
      -F 'TextTagDefinitions[0][SignerIndex]=1' \
      -F 'TextTagDefinitions[0][IsRequired]=true' \
      -F 'TextTagDefinitions[0][FieldLabel]=Email field' \
      -F 'TextTagDefinitions[0][FieldId]=axq12367' \
      -F 'TextTagDefinitions[0][Size][Width]=500' \
      -F 'TextTagDefinitions[0][Size][Height]=50' \
      -F 'TextTagDefinitions[0][Placeholder]=Enter your email here' \
      -F 'TextTagDefinitions[0][PageNumber]=1' \
      -F 'TextTagDefinitions[0][Font][Name]=Helvetica' \
      -F 'TextTagDefinitions[0][Font][Size]=20' \
      -F 'TextTagDefinitions[0][Font][Style]=Italic' \
      -F 'TextTagDefinitions[0][Validation][Type]=Email' \
      -F 'TextTagDefinitions[0][Offset][OffsetX]=0' \
      -F 'TextTagDefinitions[0][Offset][OffsetY]=0' \
      -F 'Files=@NDA.pdf;type=application/pdf'
```

C#

```csharp
ApiClient apiClient = new ApiClient("https://api.boldsign.com", "Your_API_Key");

DocumentClient documentClient = new DocumentClient(apiClient);

List<FormField> formField = new List<FormField>
{
    new FormField(
        id: "Signature",
        type: FieldType.Signature,
        pageNumber: 1,
        bounds: new Rectangle(x: 50, y: 50, width: 200, height: 30))
};

var documentDetails = new SendForSign
{
    Title = "Agreement",
    Signers = new List<DocumentSigner>
    {
        new DocumentSigner(
            signerName: "David",
            signerType: SignerType.Signer,
            signerEmail: "david@cubeflakes.com",
            formFields: formField)
    },
    Files = new List<IDocumentFile>
    {
        new DocumentFilePath
        {
            ContentType = "application/pdf",
            FilePath = "YOUR_FILE_PATH",
        }
    },
    TextTagDefinitions = new List<TextTagDefinition>
    {
        new TextTagDefinition(
            definitionId: "tag1",
            type: FieldType.TextBox,
            signerIndex: 1,
            isRequired: true)
    }
};

var documentCreated = documentClient.SendDocument(documentDetails);
```

Python

```python
import boldsign

configuration = boldsign.Configuration(host = "https://api.boldsign.com", api_key="YOUR_API_KEY")

with boldsign.ApiClient(configuration) as api_client:

    document_api = boldsign.DocumentApi(api_client)
	
    form_field = boldsign.FormField(
		fieldType="Signature",
		pageNumber=1,
		bounds=boldsign.Rectangle(x=50, y=50, width=200, height=25))

    document_signer = boldsign.DocumentSigner(
        name="David",
        emailAddress="david@cubeflakes.com",
        signerType="Signer",
        formFields=[form_field])

    send_for_sign = boldsign.SendForSign(
        files=["YOUR_FILE_PATH"],
        signers=[document_signer],
        title="Document SDK API",
        textTagDefinitions= [
            boldsign.TextTagDefinition(
                definitionId="tag1",
                type="TextBox",
                signerIndex=1)
        ]
    )

    document_created = document_api.send_document(send_for_sign)
```

PHP

```php
<?php require_once "vendor/autoload.php";

use BoldSign\Configuration;
use BoldSign\Api\DocumentApi;
use BoldSign\Model\{FormField, Rectangle, DocumentSigner, SendForSign, FileInfo, TextTagDefinition};

$config = new Configuration();
$config->setHost('https://api.boldsign.com');
$config->setApiKey('YOUR_API_KEY');

$document_api = new DocumentApi($config);

$form_field = new FormField();
$form_field->setFieldType('Signature');
$form_field->setPageNumber(1);
$bounds = new Rectangle([100, 100, 100, 50]);
$form_field->setBounds($bounds);

$document_signer = new DocumentSigner();
$document_signer->setName("David");
$document_signer->setEmailAddress("david@cubeflakes.com");
$document_signer->setSignerType("Signer");
$document_signer->setFormFields([$form_field]);

$send_for_sign = new SendForSign();
$files = new FileInfo();
$files = 'YOUR_FILE_PATH';
$send_for_sign->setFiles([$files]);
$send_for_sign->setSigners([$document_signer]);
$send_for_sign->setTitle('Document SDK API');

$textTagDefinitions = new TextTagDefinition();
$textTagDefinitions->setDefinitionId('tag1');
$textTagDefinitions->setType('TextBox');
$textTagDefinitions->setSignerIndex(1);
$send_for_sign->setTextTagDefinitions([$textTagDefinitions]);

$document_created = $document_api->sendDocument($send_for_sign);
```

Java

```java
ApiClient client = Configuration.getDefaultApiClient();
client.setBasePath("https://api.boldsign.com");
client.setApiKey("YOUR_API_KEY");
        
DocumentApi documentApi = new DocumentApi(client);

FormField signatureField = new FormField();
signatureField.setFieldType(FormField.FieldTypeEnum.SIGNATURE);
signatureField.setPageNumber(1);
Rectangle bounds = new Rectangle().x(100f).y(100f).width(100f).height(50f);
signatureField.setBounds(bounds);

DocumentSigner signer = new DocumentSigner();
signer.setName("David");
signer.setEmailAddress("david@cubeflakes.com");
signer.setSignerType(DocumentSigner.SignerTypeEnum.SIGNER);
signer.setFormFields(Arrays.asList(signatureField));

SendForSign sendForSign = new SendForSign();
File file = new File("YOUR_FILE_PATH");  
sendForSign.setFiles(Arrays.asList(file));
sendForSign.setSigners(Arrays.asList(signer));
sendForSign.setTitle("Document SDK API");

TextTagDefinition textTagDefinition = new TextTagDefinition();
textTagDefinition.setDefinitionId("tag1");
textTagDefinition.setType(TextTagDefinition.TypeEnum.TEXT_BOX);
textTagDefinition.setSignerIndex(1);
sendForSign.setTextTagDefinitions(Arrays.asList(textTagDefinition));

DocumentCreated documentCreated = documentApi.sendDocument(sendForSign);
```

NodeJS

```js
import { DocumentApi, DocumentSigner, FormField, Rectangle, SendForSign, TextTagDefinition } from "boldsign";
import * as fs from 'fs';

const documentApi = new DocumentApi("https://api.boldsign.com");
documentApi.setApiKey("YOUR_API_KEY");

const bounds = new Rectangle();
bounds.x = 100;
bounds.y = 50;
bounds.width = 100;
bounds.height = 100;

const formField = new FormField();
formField.fieldType = FormField.FieldTypeEnum.Signature;
formField.pageNumber = 1;
formField.bounds = bounds;

const documentSigner = new DocumentSigner();
documentSigner.name = "David";
documentSigner.emailAddress = "david@cubeflakes.com";
documentSigner.signerType = DocumentSigner.SignerTypeEnum.Signer;
documentSigner.formFields = [formField];

const textTagDefinition = new TextTagDefinition();
textTagDefinition.definitionId = "tag1";
textTagDefinition.type = TextTagDefinition.TypeEnum.TextBox;
textTagDefinition.signerIndex =1;

const files = fs.createReadStream("YOUR_FILE_PATH");

const sendForSign = new SendForSign();
sendForSign.title = "Agreement";
sendForSign.signers = [documentSigner];
sendForSign.textTagDefinitions = [textTagDefinition];
sendForSign.files = [files];

const documentCreated = documentApi.sendDocument(sendForSign);
```

{% /codetab %}