Auto-Place (Anchor Tagging) Tabs
Auto-Place (Anchor Tagging) Tabs
Anchor tagging enables you to place tabs at every location where a specified text string, also known as an anchor, is found in a document. When tabs are added with anchor tagging, Docusign searches the document for instances of an anchorString property that you provide. For each found instance, it places a tab of the specified type for the designated recipient. Tab positions in relation to the string instances can be set by providing x and y offsets. These properties are part of the tabs object.
Anchor tagging is especially useful for documents that do not have a fixed layout or format. In these documents, you might not know the absolute location of the tabs because they must move with text.
For example, you might have a document that contains the text Please Sign Here. If you want to place a signature tab by each instance where this string is found in the document or, better yet, place a signature tab one inch to the right of the string to make sure the signature does not overwrite it, you could use the following tab definition:
Because you set the anchorString property to the value Please Sign Here, a Sign Here tab will be placed wherever that string is found in the document, and because anchorXOffset is set to 1 and anchorUnits is set to inches, the signature tabs will be placed one inch to the right of each location. Note that with anchorIgnoreIfNotPresent set to false, an error will be returned if the text Please Sign Here is not found anywhere in the document.
Note: When you add anchor tabs as part of a composite template and your account has set document Data Population Scope (meaning your anchor tabs are only applied to chosen documents, rather than all documents in an envelope), your composite template is limited to containing one server and one inline template. Note that the Data Population Scope settings can only be updated by DocuSign support.
Setting tab offsets from anchor strings
By default, an anchor tab is placed starting at the first character of its anchor string. You can customize this placement by:
- Setting values for the tab’s
anchorXOffsetandanchorYOffsetproperties (offsets default to pixels, but you can also choose to use inches, mms, or cms by setting the anchorUnits property) - Setting a value of right or left for the
anchorHorizontalAlignmentproperty, which controls whether the offset is at the left or right edge of the anchor string
Anchor strings with custom tabs
You can also use AutoPlace to place Docusign custom tabs in the same way as any other tab. Just as for predefined tabs, to set a custom tab to use AutoPlace, specify an anchor string in your custom tab definition that matches the anchor string in your document where the tab(s) will be placed.
- Set the
anchorStringproperty in the tab to the value of the anchor string in your document. - Ensure that the document contains an instance of the anchor string in each location where you want to place your tab.
- Send the envelope as normal.
Best practices
One common approach to anchor tagging is to use special strings that don’t appear anywhere else in the document as the anchorString property for anchor tagging, and then setting the color of these strings to match the document background, making them invisible to recipients. This enables you to easily attach tabs to many places in your documents without disrupting the signing experience for your recipients.
For example, the string *\s1* could be used to indicate where signature tabs for the first recipient should be placed, and *\i2* could be used to indicate where initial tabs for the second recipient go. By setting their font color to the same color as the background, you can hide these strings so that the recipients will only see the tabs at those locations, eliminating the need to set an offset.
Next steps
The following examples, all of which are available in 8 programming languages, demonstrate how to add tabs to a document via anchor tagging.