New List Object Properties and Methods
Some of you may recall my tutorial on sorting lists at runtime which I posted last June. Oh how I wish I had waited until the release of Designer and Acrobat 8.0 in order to write it! With the new release of these two products comes a new API for list objects that would’ve significantly simplified things: Rather than having to know details about how list object items are represented in XFA (using an <items> node for item text values and an <items save="1"> node for item data values) and manipulating these nodes in script, I could’ve used methods such as getDisplayItem and getSaveItem.
New Properties
- length: Returns the number of items in the list object. This property is read-only.
- selectedIndex: Returns the zero-based index of the first-found item which is selected or -1 if the list has no selection. You may set this property in order to set a new selection in the list or set it to -1 in order to remove the selection entirely. Note that setting this property will first de-select any currently-selected items prior to applying the new selection.
New Methods
- bool getItemState(int index): Returns true (1 in FormCalc) if the list item specified by the zero-based index parameter is currently selected in the list.
- setItemState(int index, bool state): Add or remove a list item from the selection by specifying its zero-based index and true to select or false to de-select it (1 or 0, respectively, in FormCalc). Note that if the list object does not support multiple selection (drop down lists typically don’t), using this method will have the same effect as setting the selectedIndex property.
- string getDisplayItem(int index): Returns a list item’s text value (this pertains to the list’s <items> element in XFA) based on a zero-based index into the list.
- string getSaveItem(int index): Returns a list item’s data value (this pertains to the list’s <items save="1"> element in XFA) based on a zero-based index into the list.
- bool deleteItem(int index): Deletes the list item specified by a zero-based index and returns true (1 in FormCalc) to indicate that the item was effectively deleted.
Demo Form
In order to show-off this cool new API (available in both JavaScript and FormCalc), I designed a little form that uses all the new properties and methods. Play with it in Acrobat 8.0 and check out the script in Designer 8.0. I’m certain it’ll make your life a whole lot easier when it comes to scripting list boxes and drop down lists.
Minimum Requirements: Designer 8.0, Acrobat 8.0.
Note that you must click away from the "List Box" object after you’ve set a selection since the list is set to commit its selection on exit (as is recommended when supporting multiple selection). You can specify this by setting the "Commit On" property on the Object palette’s Field tab to "Exit".
Posted by Stefan Cameron on February 1st, 2007
Filed under Scripting,Tutorials
Both comments and pings are currently closed.
Thanks for posting those new commands. I spent an hour trying to figure out how to get a specific item from a dropdown list. I’m trying to fill my dropdownlist with the filenames from a folder. Is this possible in Javascript inside of Livecycle? It looks like there is no findfilefirst command
Scott Sheck,
You’re welcome! I’m glad you’re finding it useful.
Unfortunately, you can’t get file information from scripts running in XFA forms because the scripts run in a protected environment which doesn’t allow access to the file system.
That said, you could do it by writing a JavaScript script that you would place in Acrobat’s special script folder (//Program Files/Adobe/Acrobat 8.0/Acrobat/Javascripts, I believe). Scripts in that folder run with higher privileges. The down-side to this approach is that users of your form would have to manually install that script as a sign of trust which is why I don’t think that’s quite what you’re looking for.
That’s something I didn’t know. Here is what I’m trying to do. I spend over 10 hours trying to do the following (which included learning livecycle), and didn’t come up with a good solution.
On my form, I’m adding a toolbar which will have a LOAD DATA and SAVE DATA button, and a dropdownlist (which specifies the unique job number). The SAVE DATA simply calls exportData so export all data to an .XML file. I chose to export to an XML file rather than any other data source because I when I distribute the PDF, I don’t want the user to have to own any other software or setup much.
The LOAD DATA simply calls importData. Both LOAD and SAVE data buttons both read the dropdownlist.rawvalue to name the xml filename. It all works great, except for the dropdownlist. I need the dropdownlist to be populated with *.xml filenames for this to work.
I can’t think of any alternative way of doing this. I thought of just saving the dropdownlist somewhere and keep it running list of entered jobnumbers each time the user clicks the SAVE DATA button, but I wasn’t able to get the code working to save/recall the dropdownlist data. I tried to use the dynamic data binding, but it only worked in livecycle, but not in Acrobat reader 8.
Any help would be greatly appreciated.
Scott Sheck,
Two things come to mind in order to make this work in an XFA form without having to mess with Acrobat’s special scripts folder:
First, you could simply pre-populate the drop down list used to choose the XML data file for import with the existing XML data file names. You could use the file name as an item’s text data and the full path as an item’s value data (assuming you don’t need this list to be dynamically-generated and you don’t mind updating it manually when the set of available XML data files changes). Using the drop down list’s Change event and
(in JavaScript), you could determine the full path of the XML data file selected by the user and call
to import the data they selected.
Second, keep in mind that the Adobe Reader can’t import XML data by default. You’ll need to use Acrobat Pro to extend your form (saved as a PDF file) in order to enable data import in Reader (use the “Enable Usage Rights in Adobe Reader” command under the top-level “Advanced” menu in Acrobat 8.0).
If you enable Reader to import data, then the “Dynamic Binding” feature will function correctly (if you need to use it).
In Acrobat Pro 8 reader, I was not able to get the importDATA command to work by using ‘Enable Usage rights’. It only worked when I chose Advanced, Sign and Certify, then Certify without visible signature. Would you know why?
Also, when you suggest populating the dropdownlist, the problem is not populating it since it is not a fixed list. That is, since my Save data command can save more XML files to disk, the dropdown will need to read the disk on the fly to determine the latest XML filenames out there that can be imported. If I can’t read the disk, then I’m wondering if there is a way I can maintain this list of filenames. It would have to stay up to date everytime a user created more XML files with the SAVE button.
I appreciate your help.
Also, can the importData have a path location in the parameter such as xfa.host.importData(“.\temp\test.xml”). If it does, I can’t seem to get it to work, not even importData(“c:\test.xml”). It only works with just a filename even though the documentation says you can specify a location along with the filename.
Scott Sheck,
I’m very sorry about misleading you with respect to xfa.host.importData. After your comment on May 5th saying that you couldn’t get it to work, I inquired about the problem to my colleagues and they informed me that it isn’t possible to enable the use of xfa.host.importData in the Adobe Reader simply by using Acrobat Pro’s “Enable Usage Rights in Reader”. I was convinced it was possible but you’ll unfortunately need to use LiveCycle Reader Extensions to achieve that level of functionality.
The confusion came from the fact that “Enable Usage Rights in Reader” enables a feature in Reader called “local save” which lets the user save their form along with any data they might’ve typed into it in order to resume filling the form at a later time. I was thinking an “import data” function was then used to re-open the form with the saved data merged-in but it turns-out the data isn’t saved in a separate file: It’s saved directly in the PDF form so the “importData” function isn’t required and therefore isn’t enabled.
If you’re deploying this form internally and find that Reader Extensions is too expensive, you should note that Acrobat Standard is able to import data like Acrobat Pro can and purchasing copies of Acrobat Standard might be less expensive than Reader Extensions. Just a thought.
As for maintaining the list of file names without having to read the disk (which you can’t do), you should be able to use the list object properties and methods I listed in this article in order to keep the list updated by adding/removing items. Without knowing more about your form, I can’t really speak to when you would call the methods but you should be able to do it.
My form actually will be used by my customer, not internally, so having my customer (and future customers) only need to own Reader would have been my first choice. Thanks for clarifying though, that’s too bad Adobe doesn’t allow the import/export as standard. It would get more use.
Now that I’ve learned that Adobe Reader with usage rights enabled will let you do only a few new things, will it at least allow you to use the dynamic binding for even a single field? I’d like to bind it to an XML file. I’m hoping I don’t also need Reader Extensions for this also, but I have a feeling that I do.
Scott Sheck,
I’m afraid the answer is that you need Reader Extensions to do it in Reader. Reader doesn’t let you import any kind of data without the form being extended and the “enable usage rights” isn’t enough. Dynamic Binding requires data import and therefore can’t be done unless the form is extended.
Actually, just be enabling usage rights alone, Adobe Reader 8 can import data using the importData() command. Unfortunately, it just can run the exportData() command.
This is a perfect example of how Adobe should have clearly explained what is enabled when ‘enabling usage rights’. They use the term “Save data” loosely, but people don’t realize that this means you can save data as a PDF file, but not as a data file or to a data source. Also, they don’t explain that you can import data. Unfortunately, so many people are spending hours to figure this out by trial and error.
I have a form with a listbox and corresopnding “add item” and “delete item” buttons. I coded the delete with the new commands and it worked great for me while I had Acrobat 8 professional installed. However, after I added Reader extensions and made the form available for my business clients to test user Reader 7, the delete button wouldn’t work. I guess I’m now forced to dig up script on how to delete items from a listbox the old way. Can you help me with the script on how to do this? I can’t find anything documented by Adobe! Thanks!
Mary Hoyt,
That’s correct: The new properties and methods I describe in this article are only valid when using Acrobat/Reader 8.0 or later.
Unfortunately, prior to Acrobat/Reader 8.0, the only methods there were for manipulating items in list boxes and drop down list were “addItem” and “clearItems” which won’t help you remove only specific items from the list.
There are two approaches you could take:
I’m totally new in LiveCycle and I need solution to export data from PDF form and append these data into XML file located on local disc. I hope so sombody has a simple solution.
Thanx in advance
Valkire,
You should be able to achieve that simply by placing an email submit button on your form. When the button is clicked, an email message will be created with an XML data file attached to it. This data file will contain the data that the user entered on the form. Once you’ve received data files from all your recipients, you can then use Acrobat’s tool to compile returned form data (in Acrobat Pro 8.1, it’s found in the “Forms > Compile Returned Forms” menu item). Using Acrobat Standard or Pro, you’ll also have the ability to load an XML data file into your form in order to create a filled copy of it for your records.
I have created a form, and am having a terrible time trying to compile them when I get it back. I have followed the directions in the manual about compiling. I get a message saying that adobe doesn’t recognize the file format or the message wasn’t encoded properly. If you could give me any insight to fixing this problem I would greatly appreciate it!
Glynda,
I don’t think I quite follow what you’re talking about. What do you mean by “directions in the manual about compiling”? When is it (what application are you running?) that you’re getting the message about not recognizing the file format?
This is not exactly an Adobe question. I am co-organizer of a group and have created registration forms for 2 upcoming events. We would like to compile this information into Excel spreadsheets. Unfortunately, I am the only one with access to Acrobat 8 Pro, but I am not the one who will be doing the compiling (will be out of town for a while). Do you know of any other (easy) options for compiling .xml info into an Excel file without having to open each file individually and cut and paste into a master file? Once I come back to town I can do it with Adobe, which I’m looking forward to.
Thanks in advance for any help you can give.
Shari
Shari,
The only alternative I can think of is to avoid submitting XML data files from the form. Instead, use an HTTP button to submit the data to a PHP/ASP/JSP/etc. page and insert the data directly into a database or parse it into a comma-delimited string and append it to a file which you can then import in a single step into your Excel spreadsheet. It’s not the simplest solution but it gets around the need to use Acrobat Pro for compiling the XML data files you get back.
Acrobat Reader doesn’t allow the xfa.host.exportData(“”, 0); script to export data in XML to the local file system, as I understand, due to some security considerations. Is there a way to change this? It doesn’t seem to make any sense anyway, since nothing prevents you from creating a Submit By Email button, through which you are able to submit user entered data in XML. Thanks in advance:
Martin
I’m new in LiveCycle and I need solution to export data from PDF form ,FILLED WITH A CONNECTION TO XML FILE, and append the data selected or filled into XML file located on local disc. I hope so sombody has a simple solution.I am only getting to export,with a submit button, the same xml file of the connectorion.Nothing field filled or combobox data selected appears in the xml exported by submit button.
Thanx in advance
NP_Martin,
Unfortunately, I wasn’t able to obtain a definite answer for you with regards to the restrictions on the use of xfa.host.exportData in Reader. It’s possible that its use is exclusive to Acrobat Standard or Pro for some reason.
Stefan, NP_Martin and Javier,
I too have been struggling with the xfa.host.exportData(“”,0) for several weeks. Per the LC Scripting Reference document a pdf document needs to be Certified for this to work. I get a security error in Reader 8.1 and 9.0 when attempting the exportData method. I have confirmed in Reader my certificate has trusts turned on for all features including High Priority Java Scripts.
Adobe support has not been able to reproduce the problem. It occurs for me on three separate systems. This seems to be a bug to me.
Javier,
As I mentioned in response to another one of your questions, you need to make sure those fields are bound to data nodes in your data connection.
i have and pdf file in it a comments i want to display these comments in a spreed sheet as excel in four separete columns in this columns the title of the comment and category of it and the description of the comments please i wana help in this query
i am a new software developer and have this assignment
i have and pdf file in it a comments i want to display these comments in a spreed sheet as excel in four separete columns in this columns the title of the comment and category of it and the description of the comments please i want help in this query
@merooo5,
Your question sounds like it’s out-of-scope for this blog (comments in a regular PDF, not XFA-related in some way). I suggest you ask over at acrobatusers.com.