Tabs deep dive: anatomy of a tab

Welcome back to the Tabs deep dive series, where I’m giving you all the information you need to customize your documents with tabs using the eSignature REST API! In my last post I explained the differences between some of the most common tab types. In this post, I'll dig deeper into the anatomy of tabs and show you how to set properties that control their behavior and appearance.

While each type of tab is a little bit different, they all share similar properties that you’ll want to understand before you start adding them to your documents. The JSON below shows the definition of two different types of tabs, each with different properties.

"tabs": {
  "signHereTabs": [
    {
      "anchorString": "**signature_1**",
      "anchorUnits": "pixels",
      "anchorXOffset": "20",
      "anchorYOffset": "10",
      "scaleValue": "1.5",
      "name": "signature",
      "optional": "true"
    },
  ],
  "textTabs"”: [
    {
      "xPosition": "100",
      "yPosition": "200",
      "width": "50",
      "height": "14",
      "name": "enterText",
      "documentId": "1",
      "pageNumber": "1",
      "required": "true"
    }
  ]
}

When creating custom tabs, developers frequently need to set a specific size for those tabs. The Text tab above includes width and height properties that determine the size of the tab in pixels. The size of Sign Here tabs, however, can’t be changed using width and height; instead, you need to use the scaleValue property, which takes a value between 0.5 (half the normal size) and 2 (twice the normal size).

The major difference between the two tabs above is that the Sign Here tab is placed using an anchor string, while the Text tab is placed with specific coordinates. I’ll explain more about how to place tabs in your documents in a later post. For now, it’s important to note that the documentId and pageNumber properties are only required if you are not placing your tabs with anchor strings. The Text tab above is placed at specific x and y coordinates, so you need to use the documentId property to specify the document and the pageNumber property to indicate in which page of that document the tab should appear. 

Another big difference between the Text tab and the Sign Here tab in the JSON above is that the Text tab is required, while the Sign Here tab is optional. This means that the signer needs to fill out the Text tab in order to finish signing the document, but they don’t need to complete the Sign Here tab. Even though the desired effect of the required and optional properties is the same, they are not interchangeable. Text and Number tabs use the required property, while Sign Here and Initial Here tabs use optional

Tabs also have properties that can be used to customize their style. The JSON below demonstrates how to create a Full Name tab with various properties that change the font and color of the text while also italicizing it. In addition to the italic property, you can set the bold or underline properties to “true” to format the text in your tab.

"fullNameTabs": [
  {
    "anchorString": "**full_name**",
    "anchorUnits": "pixels",
    "anchorXOffset": "20",
    "anchorYOffset": "10",
    "scaleValue": "1.5",
    "font": "Tahoma",
    "fontColor": "Purple",
    "italic": "true",
  },
],

These are just some of the properties you can use to customize your tabs. For even more, see the API reference. Check back next month for the next post in the Tabs deep dive series, in which I’ll be showing you the different ways you can place tabs in your documents.

Want to know more about this topic? Register for our inaugural DocuSign Developer Conference, coming October 26 & 27, where we'll have a dedicated session.

Additional resources

Paige Rossi
Author
Paige Rossi
Programmer Writer
Published
Related Topics