Field scripting in eDocBuilder allows you to change styling, colors, fonts, text and images on the field level in your eDocBuilder Forms templates. There are two types of field scripting: HTML scripting and VB scripting. HTML script is used for basic styling, and does support removing data for fields that are empty. VB scripting allows for more complex conditionals and functions to be applied to the field input. HTML script formatting can be used within VB scripting statements.
As a simple example, if you have a third phone number to be input, then that field reference, as well as styling tags around it, can automatically be removed from the field if the user does not enter a third phone number. VB script supports creating statements for more complex conditional situations such as if the user does not enter a third phone number and does not enter a second phone number, then the result of the script can change depending on if both of those fields do not have any values.
IMPORTANT: Field scripting is only supported for standard Forms templates. It is not supported in Interactive Designer templates. To be precise, scripted changes will be applied to production files created from an Interactive Designer template session. But scripted changes on an Interactive Designer template will not be visible to the customer when they are customizing that template. On a Forms template, the scripted changes are visible to the user when customizing the template, as well as in the production file generated from the session the user customized.
Turning on Field Scripting
Field Scripting is enabled for individual fields in a template. Go to the Field Setup area on your template, choose a field to enable field scripting on, and indicate if the field will have Text or Image content under "What type of field will this be?" Then under "Data for this field will come from," choose Field Scripting or Static Text. Then under the Field Scripting tab choose None, HTML Markup or VB Script.
When working in the Field Scripting tab, there are a couple of settings and helper drop-down menus for filling in the scripting area. The Fields drop-down menu lets you choose fields in the current template to insert at the cursor position in the text area below. There are also drop-down menus for inserting some common formatting tags and symbols.
The fields dropdown menu in HTML Markup mode:
The common formatting tags dropdown menu in HTML Markup mode:
The common symbols dropdown menu in HTML Markup Mode:
The Fields dropdown menu in VB Script mode:
The Functions dropdown menu in VB Script mode:
In HTML Markup mode there is a Convert To VB button that shows below the text area where the script is edited. Clicking that button will convert your HTML markup scripting to VB scripting. The functionality does the basic work of converting the scripting, but may need to be edited to clean it up a bit. Please see the Convert to VB section below for more information. The setting Suppress Blank Lines will need to be turned on if the result of the script could contain blank lines that you want to have automatically removed when the field is populated with input data.
Note that when adding the field names to be used in the script, the field names in HTML Markup mode will be surrounded by @ symbols. In VB Script mode, only the name of the field is used. The fields will populate this way when using the Fields dropdown menu to build your script.
HTML Markup mode:
VB Script mode:
Considerations and Caveats
- VB Script can use HTML markup scripting, but HTML markup scripting cannot use VB script.
- When using HTML markup within a VB script statement, it is best to use single quotes for any tag attributes, as double-quote marks define the literal text in the VB script statement.
- A field set to produce a scripted result can only use the results from input fields on the template, it cannot use another field set for field scripting or static text as an input.
- A field set to use VB scripting cannot use lines or goto statements; a single statement must be used. It can be multiple statements joined by ampersand characters, however, but it must be one statement.
- VB script statements can be nested within VB script statements.
- If HTML markup or VB script is used on image fields, the result of the script must be the name of a single image, or the url address to a publicly-available image.
- Field scripting is fully supported only on Forms templates. Fields set for scripting on Interactive Designer templates will only produce results on the production file generated from the template.
Basic Business Card HTML Markup Scripting Example
In the basic business card HTML Markup scripting example, a number of fields are being used for input, and are composited into a single field using HTML markup scripting. The example PDF file can be downloaded here if you wish to follow the points below in a template you create in your own account.
In the HTML markup scripting example below, several fields have been combined within the contact information field. This concatenation permits the exclusion of information that does not apply, or applying different formatting styles within the same field. More importantly, scripting provides the option of building a more intuitive interface for your customer.
The contact information (Address, Telephone, Fax and email) were originally entered into one text field. This did not allow for flexibility of providing the address in a drop down, or ensuring that the customer used specific formatting (notice the periods between the digits in the phone and fax field), or kept the look of the card consistent with corporate policies. With field scripting we can create a separate form field for each of the different items that are included in that contact block and set very specific rules for each.
Instead of one field called "ContactInfo", the eDoc user interface for this business card now has additional fields added: phAddress, phPhone, phTelephoneExt, phFax, and phEmail. These fields will be composited using simple HTML scripting and then displayed in the ContactInfo field.
The first step in construction of this card is the addition of five new fields in the master PDF. The fields will be added to the original template in Adobe Acrobat, using the Edit Forms tool. These fields will not display on the final PDF, so their position is not critical, they will be set to accept input but will be hidden as these inputs will be shown as the result of the scripting in the ContactInfo field.
The six new fields that have been added use a naming convention to distinguish them during the development process. The prefix "ph" indicates that these fields are "placeholder" fields, used for data input but not displayed on the PDF (phAddress, phPhone, phEmail, etc). The practice of using a naming convention of this type can reduce much of the guesswork in making future revisions to your templates, as it helps to make clear the purpose of those fields.
Upload the revised PDF, replacing any existing Master PDF in the assets area. Then you must commit changes by clicking the commit changes button in the Field Setup area.
The field setup automatically displays the five new fields within its list. Drag the fields into the order you would like them to be presented to the end user – ContactInfo, as a scripted field, will not be presented to the user in the input area. It will appear in the preview area combining all of the elements of the field script (our ph fields).
Expand the phAddress Field by clicking the downward facing arrow at the end of the field. Click on the Field Type tab. Define the field type as "Text" coming from "User Entry". Use these selections for all of the new fields that we will be creating.
In this example, we want the address to come from a drop down field so the customer can just choose their office without having to type in the information. To do this, on the Data Capture tab, User Control Type should be set for Drop Down List. The user must select an address, so the Required check box is active. Note the address selections in the List Options field. As in the previous sample, a pipe character separates the city label, and hard returns are applied with a backslash n or "\n".
On the Format tab, the Field Usage setting will be set to "Hide Field" for this field and the others being used in our field script. The other settings on this tab are not important. We want to hide the form field from being seen by the customer on the template because it will be part of the field script which is part of the ContactInfo field we will be using. Always remember to click the Save button after applying field settings.
For both the PHPhone and PHFax fields, these will be set to be text coming from user entry on the "Field Type" tab.
On the "Data Capture" tab, set the "User Control Type" to "Text Box."
On the "Format" tab select the "Text Reformat" drop down selector and pick the format style that you prefer for telephone numbers.
Again, Field Usage (at the bottom of the screen) will be set to "Hide Field".
Click the Save tab to save your work after each field.
The phEmail field should be set as text coming from user entry on the "Field Type" tab. On the "Data Capture" tab, set the "User Control Type" to "Text Box." A default field value may be entered. The advantage of this example, providing the @ symbol and a specific domain name, is that it lets the user enter their name before the default.
On the "Format" tab, Field Usage (at the bottom of the screen) will be set to "Hide Field". Set the Text Reformat dropdown to Email. Remember to click the Save button after changing the settings on the field.
Expand the"phTelephoneExt". Again, on the "Field Type" tab set the field to "Text" and "User Entry". On the "Data Capture" tab set the "User Control Type" to "Text Box." Set the prompt text under the Data Capture tab. The field usage on the "Format tab" should specify Hide Field.
The next step will be to expand the ContactInfo field. The five place holder fields will now be combined, using HTML scripting within this field. Under the Field Type for ContactInfo, specify "Text" and "Static Text or Field Scripting" for the data source. The Data Capture tab is not required for the ContactInfo field because of the scripting that we will be using to capture the information.
Open the Format tab, specify your font preferences. The font preferences you set here will override any font preferences set on the "Format" tabs of the individual place holder fields. In this example field usage is set for both proof and production files.
When you first click on the Field Scripting tab, three selections will appear with radio buttons. The first selection is the default, None. The other two are HTML Markup and VB Script. Select the HTML Markup radio button. The screen will expand to display the HTML text editor. Note that this editor is not WYSIWYG. If you wish to have format changes here, you must type HTML tags like <B> or <font>. See "HTML Field Scripting Reference – Syntax" for reference.
* Be careful not to use empty tags in your html script otherwise you will get unexpected behavior.
On the right side of the toolbar is a field picker (dropdown). The information being used in our ContactInfo field will be brought in from the fields selected. The illustration displays the fields surrounded on both ends by the @ character which is automatically placed before and after the field. This is the markup language that pulls the data from each of the fields.
Note the static text labels Phone, Cell, and Fax are typed into the appropriate position.
Double curly brackets have been added, surrounding the field names and labels of fields that may not be used. By doing this, the field and its label will not print on the document if no data has been entered into the field.
The hard line returns (created by hitting "Enter" on your keyboard) have been removed and replaced with the HTML code for a line break "<br/>". (The line break can be added using the "Insert Code Snippet" dropdown.) Activate the check box "Suppress Blank Lines". This will insure that no blank lines appear within the block of copy. If the customer does not want the fax number to display, you don't want a blank space between the phone and email.
Click the Save tab to save your settings. You also must click the "Commit Changes" button at the top of the page.
Convert to VB
If you need to use a VB script you can start in HTML Markup and use the Convert to VB button at the bottom of the field to automatically change the HTML into VB Script. VB scripting can become very complex depending on what you are trying to accomplish. The Related Articles section below contains a number of examples of using VB script to accomplish different results. It is good to keep in mind that eDocBuilder VB Scripting is like Visual Basic in terms of its formatting and syntax, but is not a full implementation of Visual Basic script itself. The functions and available commands are shown in the article Ch. 035 vbScript Field Scripting for your reference. The two screenshot examples below show the same statement in HTML markup and VB script.
HTML Markup example
VB Script example
Note that when converting to VB Script, the conversion will add a double-quote mark to existing double-quotes where formatting tag values exist, resulting in double double-quotes. You will have to manually edit the script to change to a single quote after converting. Converting the double quotes to single quotes makes the script more readable. Double-quote marks are used to enclose any literal text in the VB script, any text outside of the double-quote marks is part of the VB script statement itself.
Any HTML markup tags within the literal text of the script should use single quotes around attribute values. Meaning that if you have a statement like ifs(phTelephone<>"", "<font face='Arimo'>" & phTelephone & "</font>","") then the text outside of the double-quote marks is VB script. The text within the double-quote marks contains HTML markup tags, so <font face='Arimo'> is written with single-quote marks around the tag attribute, the name of the font. Using double-quotes would work, as in <font face=""Arimo""> but makes the entire statement harder to read for most users.
When more complicated formatting of the combined field area is necessary, scripting can get rather intricate. See the related articles section below for more details and examples of both types of scripting. If you are having trouble with scripting in your eDocBuilder template, please open an ticket to our support department at support.aleyant.com. We will try to answer any questions about scripting in eDocBuilder templates, but please keep in mind that our support staff will try to help and give general answers to scripting questions, but cannot build out custom scripts to your specifications on request.