PDF Form Field Scripting Basics

there are a few basic operations and concepts that pervade all formfield scripting in Acrobat JavaScript you will see and use these in every script that has to do with form fields in Acrobat JavaScript each individual form field is represented by its own form field object the form field object contains properties and functions that we can use to analyze and control the form field so to use a form field in a script we have to first acquire its associated form field object to do this we use the get field function but before getting into the details of this let's take one step back in our perspective form fields are elements on a PDF document in the PDF document also has an Associated object as discussed in an earlier video this is a pattern in any JavaScript environment every element of interest has an Associated object that provides us with properties and functions to analyze and control that element this slide is divided into two sections the left-hand side represents the Acrobat viewer and inside the viewer we see PDF documents and on those documents are PDF elements like form fields the right-hand side represents the JavaScript perspective the view from the scripting world since form fields are inside of a PDF document from the JavaScript perspective form field objects are inside of the document object and that's where we always start with the document object javascript in almost all situations we use the this keyword to get the document object this isn't always true in core JavaScript that this keyword represents the current object and of course there are situations where the current object is not the document but for the vast majority of scripting situations within the Acrobat JavaScript environment the this keyword is the document object let's examine this a bit more closely for scripts that are inside of a document the keyword this always refers to that document the document the script is inside of even if that document is not the document currently visible to the user so it's not the users current document but it is the scripts current document in scripts that are outside of the document like scripts that run from the console window or within automation scripts that run from a toolbar button or from a menu item the this keyword refers to the PDF document that is currently being viewed by the user so we have two situations scripts inside the PDF and scripts outside the PDF where the this keyword has a slightly different application but it means the same thing and of course there are other ways to get a document object various functions like the one for opening a PDF returns the document object but these are much more advanced topics and won't be discussed in this video series for our purposes here we can think of the this keyword as being the document object everything about the PDF is accessed through the document object now back to fields we acquire the field object from the get field function which is a member of the document object you'll see and use this syntax over and over this dot get field where this is a pointer to the document object in get field is the document object function for acquiring the field object the get field function has a single input which is the name of the form field to acquire a form field object we have to know the name of the field this is one reason why it's important to have a good naming convention for your fields so that you can remember the names and make sense out of them when you see the code at a later time once we have the field object we can analyze and manipulate it we'll get into that in just a little bit there is other information about fields that we can get from the document object for example we can find out how many fields there are on a document from the num fields property let's try it out in the console window I'll just paste in the code from the slide and press control enter to execute the code it returns three so there are three fields on this document you haven't seen them yet because there are on other pages and this is an important point that will be covered again in more detail later on fields belong to the entire document not to a particular page you'll notice that the get field function doesn't take a page input there is no function we can use to say get all the fields on page one when we get fields we get fields for the entire document in Acrobat fields are an abstract concept what you see on the page are the field appearances or what we call widgets we'll talk about this more later on we can find out the names of the fields on the document using this function the get nth field name function is very useful for doing more generic operations where we want to search through all the fields on a document to and choose the fields we want to work with like for example some fancy calculation or to find out which fields widgets are on a particular page we can search through all the fields on the document and find out which fields are on which page but mostly this function is used in automation scripts where we don't have any previous knowledge of what the field names are on a particular document automation won't be covered here and for the most part we don't use this function in document scripts once we have the field object there's all kinds of stuff we can do with it probably the most useful of course is getting and setting field values the fields value is accessed through the value property of the field object on the bottom of this page there is a text field a check box and a group of radio buttons even though these are very different kinds of fields in JavaScript getting and setting field values is exactly the same for all of them let's do some examples I'll bring up the JavaScript console again but this time I'll move it so that we can see all of the fields on the page and work with the code to manipulate them at the same time first I'll enter some text into the text field then in the console window I'll type in this get filled and acquire the text field I set up the name of this field to be my text when I created the document its value is accessed like I said previously through the value property I'll just hit control enter and it returns hello world which is exactly what we would expect next I'll change its value from this line of JavaScript code by assigning a new string to it when I hit control enter notice that the text in the text field changes instantaneously now let's clean up the workspace and I'll repeat the same process for the check box which is named my check right now the check box is turned off but when I run this code it returns the off value which just happens to be the word off this is the same value all checkboxes will have for the off value let's click on the checkbox to turn it on and now the value returns yes this is the default on value for all checkboxes but unlike the off value this can be changed from the options tab in the checkboxes properties dialog and again I can manipulate the value of the checkbox by assigning it a value in JavaScript let's just turn it off when I execute the line of code you'll see that the checkbox turns off if I assign it the value of yes the checkbox turns on let's try this process again with the radio buttons Acrobat treats a group of radio buttons as a single field I've called this group of radio buttons my choice and the current value of my choice is auth because none of the radio buttons are turned on if I select option 2 and execute this line of code again it returns ops 2 this is a string that I assigned is the on value for this particular radio button different radio buttons in the group have different values just like in the other cases I can manipulate the value of the radio button group by assigning it of value in JavaScript I'll assign it the value of opt 3 which will turn on the third radio button if I assign the value of off to the radio button group all of the radio buttons turn off that's how we use javascript to set and get field values course there is much much more to a form field than just its value each field object has a set of properties that control how it looks and how it behaves in fact nearly every property on the fields property dialog can be controlled with a script on the bottom of this line you'll see that I've added some form fields in fact the input field and the checkbox field that you see are exactly the same field that were on the previous slide they're just different instances of those fields and that's why they're showing the same values let's take a look at some of the properties that are set for these fields I'll select the Select object tool and double-click on the text field which displays the text fields properties dialog as discussed in the previous video the values on the general and the appearance tabs are common to all form fields for example the form field visibility property and the read-only property but of course each field type also has its own unique set of properties associated with that type and these are shown on the options tab for example a text field can be single or multi line but this particular property makes no sense for a checkbox as we can see here this particular text box is set for non multi-line or single line operation let's close the properties dialog and do an example I'll bring up the JavaScript console window we'll clean it up a bit and set the get filled operation to get the textfield object but instead of setting and getting the value we'll look at the multi-line operation when I execute this line of code it returns false which is exactly what we saw in the properties window but now I'll set it to true let's close the console window and go back and take a look at the properties dialog on the options tab we can see the multi-line checkbox is set to true most of the options that are available on the properties dialog we can also get and set through JavaScript let's go back to the JavaScript console window let's try getting the multi-line property from the check box which is named my check JavaScript through an exception it says invalid get error yet not possible invalid or unknown this response is pretty severe but it does tell us that the multi-line property is completely invalid for the checkbox the multi-line property is unique for text field and does not apply to any other field type each of the field types have properties that are like this they are unique only for their own field type let's look at a property that's common for all form field types the fill color the check box has a red fill or background color when I run this line of code it returns a color array I'm not going to get into the color formats here just suffice it to say that this represents the color red to change it to green we assign it a new value for this I'll use a predefined value in the color object when I execute the code you can see that the background color of the checkbox changes immediately let's do one more example showing and hiding fields the fields visibility is controlled through two different properties the hidden property and the display property both of these properties do exactly the same thing when fields were first added to Acrobat in version 3 they created the hidden property for showing and hiding the fields but by the time Acrobat 4 rolled around they'd rethought this property and decided that it should be called display instead of hidden so they created the display property and told us scripters hey don't use that hidden property use the display property but of course everybody was already using the hidden property and they've never been able to get rid of it since which doesn't mean that one day we'll all wake up and hidden won't exist anymore it could happen this is a pattern you'll see repeated with many of the properties and functions in Acrobat JavaScript before using a property always be sure to check it out in the Acrobat JavaScript reference first the reference will say whether or not this property has been deprecated which is just a fancy way of saying that they don't want you to use it anymore not that it's not there so let's give it a try for the demonstration I'll use the hidden property currently it's set to false which makes sense because we can see the checkbox but if I set it to true the checkbox immediately disappears set it back to false and the check box appears that's how you hide and Schofield's in Acrobat JavaScript more of the field properties will be covered in the following videos on using the specific form field types but the definitive reference is always the Acrobat JavaScript reference if you see a property in the fields property dialog that you want to use look it up in the Acrobat JavaScript reference to see if it's available for scripting and how it's used you

Channel: PDFScripting

Views: 66,747

Keywords: Acrobat, PDF, Forms, JavaScript, Paperless, Electronic Document

Id: wySx6rhK-E4

Length: 16min 28sec (988 seconds)

Published: Fri Dec 29 2017