Stefan Cameron on Forms
Building intelligent forms using Adobe LiveCycle Designer

Using URL Requests in PDF Forms

Here’s a sample in response to Ernest’s question on passing values to PDF forms via URL. His intent is to use it to provide a key to a PDF form such that it can be used to filter records from an ODBC Data Connection in order to pre-populate the form with data.

I love these kinds of questions because they challenge me to find answers!

Of course, this is quite specific but there are many other uses for this. In fact, you could have a whole lot of fun with it too! You could even use this to alter the appearance of your form: Say you had one form that you were using for multiple departments in your company and every department had its own header. You could place each header in a subform, make them all hidden and then, based on the URL request which would include a department code, decide which one to show — no XML Data file, database connection or web service needed!

Beware, however, that URL request strings are not secure because they get posted in plain text for anyone to read so be careful of the information you pass-in to your form this way.

This sample form looks for a “message” and a “color” key in the URL request in order to show a message in a text field and change the text field content area’s color (an RGB value). For example:

Download Sample [pdf]

Minimum Requirements: Designer 7.0, Acrobat 7.0.

The trick to all this is obtaining the URL that was used to access the PDF form. This can easily be achieved by accessing the Acrobat Document Object associated with the form and then obtaining the value of its URL property. This is done in JavaScript via the “Message” text field’s Initialize event:

event.target.URL

This property will give you the following string (from the second sample URL I provided earlier):

//URLRequests.pdf?message=Think%20of%20the%20possibilities...&color=0%2C255%2C0 

From there, it’s just simple JavaScript code to extract the request

?message=Think%20of%20the%20possibilities...&color=0%2C255%2C0

and then parse the key/value pairs

message=Think%20of%20the%20possibilities...
color=0%2C255%2C0

Finally, since we’re passing-in a string that may contain spaces which will have been URI-encoded (that’s use of “%20” instead of spaces and “%2C” instead of commas in the request string), we need to decode it back to a normal string using JavaScript’s built-in “decodeURI” and “decodeURIComponent” functions:

decodeURI(decodeURIComponent(string))

If you want to have fun submitting different strings to show in the message box, I found a little tool online which converts regular strings into URI-encoded strings.


Posted by Stefan Cameron on October 20th, 2006
Filed under AcroForm Objects,Scripting,Tutorials
Both comments and pings are currently closed.

36 Responses to “Using URL Requests in PDF Forms”

  1. Ernest on October 24th, 2006

    Thanks for the info, it works great in populating box(es) on a form.

    One additional question. I am able to send, retrieve “RecordID”, and populate a textbox on the form with said “RecordID”. I have a data connection to SQL Server 2005, and would like to filter for a specific record OnOpen, with the sql query …”WHERE RecordID = ????. How do I get the the value retrieved from the URL, and placed in textbox “RecordID”, to populate the sql “Where” clause.

    Thanks

    Ernest

  2. Stefan Cameron on October 26th, 2006

    Ernest,

    I recently posted an article about doing just that: Selecting Specific Database Records.

    Please have a look at that sample. It should answer your questions.

  3. Dave P Nottingham on November 18th, 2006

    Stefan

    Your work on this was a real breakthough! The issue, and one that you address, is that of security! It seems that you can’t run a ‘POST’ against a pdf form – before moving to the .NET platform I used to use APToolkit in asp to move data into the respective fields, but that is very time consuming coding! Running the whole thing in a SLL window without address bar seemed an idea, but the URL is carried forward if no HTTP Title tag is formed as the title. Is there a way of including a title within the XML page to show at the top of the browser? I’ve had a look though:-
    http://partners.adobe.com/public/developer/en/xml/xdp_2.0.pdf
    but not been able to find an answer!

  4. Stefan Cameron on November 21st, 2006

    Dave,

    I understand what you’re getting at but unfortunately there’s nothing in the XDP spec that I know of which would let you specify the title.

    Ultimately, when you’re viewing a PDF in a browser, it’s the Acrobat plug-in (Mozilla) or ActiveX control (IE) that controls what you see in the title bar. My best guess at this point would’ve been to specify title metadata in the PDF itself (via “File | Properties”) but when the PDF contains an XFA Form, you can’t set that metadata.

  5. Pete Elmgreen on January 23rd, 2007

    Hello,
    I’m investigating options for a new project and came across sample URLRequests.pdf
    Unfortunately the file is damaged and cannot be openend w. Acrobat Prof 7.0.
    Please check the file and post a working file

    Thanks
    Pete

  6. Stefan Cameron on January 24th, 2007

    Pete,

    Thanks for bringing this to my attention.

    What happened is I saved the form as an Acrobat 7.0.5 Dynamic PDF form instead of an Acrobat 7.0 Dynamic PDF form which explains why you weren’t able to open it in something less than Acrobat 7.0.5.

    I’ve uploaded a new version of the file. Please let me know if you still have problems opening it.

  7. josh on March 12th, 2007

    What is the specific javascript code you are using in the PDF to populate the feilds?

    I downloaded the sample PDF, but the security of the document is not letting me view the javascript code to get the URL Request code.

    I’m trying to populate a form by URL request and couldn’t find any other good info on the web except for this page.

    Thanks,
    Josh

  8. Greg on March 15th, 2007

    Great info, but one question – I need this to run on the server. When we are populating the form with data, it All needs to happen on the server, as we don’t want anything but the web server to access to the database (the pdf form is actually being displayed inside of a .net web site).

    Is there any way to run a server script and pass some kind of value to it, like shown here?

    Thanks!
    -Greg

  9. Stefan Cameron on March 16th, 2007

    Josh,

    The sample I posted is an XFA form saved as an Acrobat 7.0 Dynamic PDF file.

    You should be able to use Designer 7.0 or later to open it and see the script on the “Message” text field using the Script Editor palette.

    What kind of security problems are you experiencing when you’re attempting to find the script?

  10. Stefan Cameron on March 19th, 2007

    Greg,

    Obviously, the URL Request information is being obtained from the host which is running on the client and therefore isn’t available to you on the server.

    Unfortunately, I don’t know enough about the way your web site works in order to think of a solution. Nothing “generic” is coming to me at the moment. How does a user request a particular form which is then served from the server application? What kind of information is it that you need to pass into the form?

    There must be some user interaction at some point during the process of selecting the form which will be served. This point of interaction may be a good opportunity to gather some information from the user and submit it to the server…

  11. Willie on March 28th, 2007

    Is there some other property similar to event.target.url to obtain the the url from a web browser when the user has entered a file id such as: file://c:\mypath\MyPdf.pdf?param1=Value1

    event.target.url gives the file and path, but apparently not any parameters. Maybe the ?Param=Value syntax is only valid for http urls, if true, is there another syntax that I should be using to pass the parameter value in?

    My goal is to be able to pass parameters into an adobe pdf form, without using IIS.

    Thanks,
    Willie

  12. Stefan Cameron on March 30th, 2007

    Willie,

    You should be able to get the parameters across if you use a URI to a file in your browser.

    For example, the following should work

    file:///C|/Forms/URLRequests.pdf?message=Some%20text

    for a file located here:

    C:\Forms\URLRequests.pdf

    I understand you were saying that it’s not working for you but my file URI syntax is slightly different from yours…

    Also, beware that certain URI-encoded characters might give you some grief when using a URI to a local file. I don’t really know why but here’s an example: Including “%85″ in my message for an exclamation mark produced an exception in one of the “decode” functions used in my sample form to convert the URI-encoded characters into regular characters.

  13. willie on April 3rd, 2007

    Still not working for me.

    Here is something that I did notice as being different…maybe it means something, maybe not:

    If I enter into my IE the URL
    file://c:\mypath\myfile.pdf
    it gets translated into
    c:\mypath\myfile.pdf
    and the event.target.URL returns
    file:///c|/mypath/myfile.pdf
    which is fine.

    If I start with
    file:///c|/mypath/myfile.pdf
    I again get the same results as above.

    However, if my starting URL that I enter into IE 6 is
    file://c:\mypath\myfile.pdf?param=value
    the translated URL in the IE bar becomes
    file:///c:/mypath/myfile.pdf?param=value
    Note that the file:// did not get stripped this time vs initially.

    The event.target.URL returns
    file:///c|/mypath/myfile.pdf
    without any parameters.

    And lastly, if I enter into IE
    file:///c|/mypath/myfile.pdf?param=value
    the IE URL changes only slightly from the entered value to
    file:///c:/mypath/myfile.pdf?param=value
    and the return value from event.target.URL is
    file:///c|/mypath/myfile.pdf
    again without any parameters.

    Aside from not getting my parameters out, I thought it odd that the IE URL would strip the file:// notation whenever I did not try to include any parameters, but was kept when I did enter parameters.

    To be complete, if I place myfile.pdf inside the default IIS website path (c:\inetpub\wwwroot) and then enter into the IE URL
    http://localhost/myfile.pdf
    the IE URL returns the identical value, as well as the event.target.URL.

    If I enter into IE URL
    http://localhost/myfile.pdf?param=value
    both the IE URL and event.target.path return the identical value as input (including the ?param=value).

    Right now, this is an academic question for me to understand why I cant get it to work. As a matter of practical solution, I was able to embed the values of the parameters into the filename, and then parse them out.

  14. Stefan Cameron on April 6th, 2007

    Willie,

    When I tested it myself, I was using FireFox 2.0.0.3.

    I think what’s happening is that depending on the browser and the syntax specified in the URI pointing to the file, the browser may treat the path either as a command to open a file (at which point the parameters after the “?” get passed to the application) or to browse to a file (which results in the parameters after the “?” being treated as an HTML Request).

    That’s the best answer I can come-up with. Thankfully, you were able to work around it.

  15. eDesign4Less on June 18th, 2007

    Hi Stefan,

    First I have to say awesome work! You are really touching on some points that are important. I wanted to see the example, but I am not able to download… is it me, or could you provide another download?

    Thanks,
    Stephanie

  16. Stefan Cameron on June 18th, 2007

    Stephanie (eDesign4Less),

    Thank you very much for your encouragement. I’m happy to hear that you find my articles useful.

    As far as I can tell, you should be able to download the sample PDF form here: http://forms.stefcameron.com/samples/URLRequests.pdf

    If the link still doesn’t work for you, let me know and I’ll email you the form.

  17. Murray Greig on April 7th, 2008

    Hello _ i must say that this simple script is super…
    thank you – im interested in the ways you assign properties to fields ie “rawValue”
    is there a list of these?
    for example – I am trying to specify the URL of the image field how would i go about this? rawDesc ? or if a wanted to Specify the position of a text field?
    im looking about but there is not much on images? any ideas?

  18. Stefan Cameron on April 9th, 2008

    Murray Greig,

    The Adobe XML Form Object Model Reference is always a good place to look for this kind of information.

    Unfortunately, I believe there are security issues that prevent you from programmatically setting the URL of an image field so what I’m going to outline likely won’t work in Acrobat/Reader:

    Setting the URL for an image field at runtime isn’t as straight-forward as setting the field’s value since the value, in this case, is either empty when the image is referenced or is the Base64-encoded form of the image when the image is embedded. The XFA specification says that the <image> node has an “href” property which specifies a link to external content as well as a “contentType” property which specifies the MIME type for the reference or embedded content.

    If the image is referenced, you would theoretically set the URL like this:

    MyImageField.value.image.contentType = "image/jpg"; // specify a JPEG
    MyImageField.value.image.href = "http://...";

    If the image is embedded, then you wouldn’t use the “href” property. Instead, you would get the Base64-encoded version of the image and you would set that as the image’s rawValue:

    MyImageField.value.image.contentType = "image/jpg"; // specify a JPEG
    MyImageField.rawValue = "iVBORw0KGgoAAA...";
  19. Nolan Smith on May 7th, 2008

    HI,

    I love this tutorial but I was wondering if you could help me a little. I am trying to get the parameter from this URL and pass it to my SQL query in the DataConnection in the LiveCycle Designer.

    Thanks,

    Nolan

  20. Stefan Cameron on May 14th, 2008

    Nolan Smith,

    Have a look at my tutorial on selecting specific database records. Rather than using a drop down list to select the movie category, you could replace that with an Initialize script that retrieves the movie category from the URL Request.

  21. Jaymes on May 16th, 2008

    Stefan,

    I’m working with a form using event.target.URL to determine (from the first four characters of that value) if the file is local (“file”) or from a website (“http”). The problem, which exists in your document also, is that when opened locally, there is a security dialog prompt to “allow access to the file”. Any idea how to get this information (whether local or hosted) without the security prompt? It may be important to note this is with Reader 8 and up. Thanks for any input you have!

    Jaymes

  22. Stefan Cameron on May 26th, 2008

    Jaymes,

    Unfortunately, I don’t know of a way to do that. Acrobat/Reader has security measures in place to give the user the opportunity to control access to the file path which could contain sensitive information (such as their username).

  23. Sunshine on June 16th, 2008

    Hi Stefan! You mentioned “Acrobat/Reader has security measures in place to give the user the opportunity to control access to the file path which could contain sensitive information.” When users open these forms all day long, they get very weary of continually “allowing” the security prompt each time. This didn’t happen in v8.0, the issue just appeared as I’ve been testing v8.1.2. Is there any setting on the user’s computer which can eliminate those security warnings?? I tried Trust Manager (allow all web sites), but that didn’t help. If there is no such solution, then is there something I as the developer can change in my form code? is it the xfa references that is triggering the security warnings? I’m hoping there is relief/solution somewhere?!! Thx in advance for your expertise!

  24. Sunshine on June 16th, 2008

    ah-ha! I’ve subsequently discovered it was the event.target.URL section of my code that was triggering the security warnings. I removed that part of my Javascript, and voila, no more security warnings. So ignore my previous post. Thx!

  25. James on September 3rd, 2008

    Hi Stefan.

    Firstly, this is a fantastic resource for LiveCycle and Designer and is the first place I search for solutions, so please keep up the good work.

    I have the same issue as Jaymes where I have created a form, which uses the event.target.URL. The form is called from a company website and it parses the URL (through which we pass various parameters) to pre populate information in the form, and to specify the default email address that is assigned to ‘mailto’: behind the submit button.

    My problem seems to be from your responses to previous, that Adobe is controlling the security in relation to URL access very tightly. Even using event.target.URL is considered by Reader as accessing a website and the security prompt “This document has accessed more than one site and may be trying to share information…” comes up.

    We don’t want to have this message appear at all. From what you have said, there is no way to disable it, but is there another way to code the form that wouldn’t cause this prompt to be fired?

    Thanks
    James

  26. Stefan Cameron on September 9th, 2008

    James,

    Thanks for the encouragement. I’m glad you find my blog useful!

    The ways in which you can import data into a form using the free Reader are quite limited outside of using additional LiveCycle technology. Short of an XML data file, a database connection or a web service, the URL is the only way I see and unfortunately, it may contain some sensitive information which is why you get the security dialog.

  27. Dan on October 14th, 2008

    I love your post, but I’m having a ton of trouble with implementation. I tried editing your pdf in Acrobat 8, but I can’t modify the layout or look at the field parameters. Could you please publish a version that I can open and edit? I’m new to javascript and PDF’s so maybe what I need is a codeblock that I can tie to an action or set in the defaults for the field. Really, I don’t even know where to begin. Thanks for any input you can provide. Getting this going will solve a major problem we’re having.

    Best,
    Dan

  28. Stefan Cameron on October 19th, 2008

    Dan,

    I’m glad you liked my post. You’ll need Adobe LiveCycle Designer to open this form and look at the code inside. You can get a trial version of Designer by downloading the trial version of Acrobat Pro.

  29. James H. on November 3rd, 2009

    Hey Stefan,

    Can you save a document with data that is imported via the URL? I woud like the users to get 1/2 of the data via the URL, enter the other 1/2 and be able to save their PDF locally.

    I took your sample PDF document and commented out the two lines of code that clear the values:
    this.ui.oneOfChild.border.fill.presence = “hidden”;
    this.rawValue = null;

    But, after I save the document and re-open it, the values are gone.

    Thanks,

    James H.

  30. James H. on November 4th, 2009

    I think I found the issue with my above post. After you open the form, you need to manually type something into one of the other fields before saving.

    James H.

  31. Melissa on December 9th, 2009

    what i really need for the completion of your tutorial on the pass var via url to pdf field is the parsing code that goes in the pdf itself. I’ve tried to access it via the URLRequest.pdf but since its an older version I cant get the appropriat javascript from that doc. if you can send the code it would really help with a project i am on.

  32. Stefan Cameron on December 14th, 2009

    Melissa,

    My sample PDF is an XFA form. The only way you wouldn’t be able to open it to see the script is if you aren’t using Designer…

    In any case, here’s the parsing code. I hope it helps!

    // Requests:
    // message >> The message to display, URI-encoded
    // color >> RGB value "R,G,B" to set on the message
    
    // start by clearing the values first
    this.ui.oneOfChild.border.fill.presence = "hidden";
    this.rawValue = null;
    
    var sURL = event.target.URL; // URL used to access this PDF form
    var nRequestStart = sURL.indexOf("?");
    
    // show the URL
    URL.rawValue = sURL;
    
    if (nRequestStart > 0) // must be larger than zero or else this is a weird URL!
    {
        var sRequest = sURL.substr(nRequestStart + 1);
    
        // show the request
        Request.rawValue = sRequest;
    
        var aRequests = sRequest.split("&"); // 1 request per array element
    
        for (var i = 0; i < aRequests.length; i++)
        {
            var aNameValue = aRequests[i].split("="); // name=value
            var sName = aNameValue[0];
            var sValue = "";
    
            try
            {
                // attempt to decode the various URI encodings (regular and component)
                sValue = decodeURI(decodeURIComponent(aNameValue[1]));
            }
            catch (e)
            {
                // invalid URI encoding found -- skip
                continue;
            }
    
            if (sName == "message")
            {
                // show message value in text field
                this.rawValue = sValue;
            }
            else if (sName == "color")
            {
                // expecting RGB value: "R,G,B"
                this.ui.oneOfChild.border.fill.color.value = sValue;
                this.ui.oneOfChild.border.fill.presence = "visible";
            }
        }
    }
  33. Ken on February 21st, 2010

    Regarding the security popup caused by event.target.URL.

    Is there a way to find out if the PDF is opened from a website or on someone’s computer?

    Or maybe find out if the PDF has been saved?

    Basically what I was thinking was finding a way to only execute the javascript code IF the PDF is viewed online and not yet saved.

    So that we would only use the event.target.URL only if the PDF is viewed online and not local, if it’s viewed locally don’t run the code.

    Any ideas?

  34. Stefan Cameron on March 2nd, 2010

    Ken,

    I believe event.target.URL will return a URL that begins with “file:///” if the PDF is locally.

    Perhaps simply checking the URL for “file:” instead of “http:” would give you the information you need.

  35. Gerald Clerc on August 27th, 2010

    Hi Stefan

    I tried your sample, but nRequestStart = sURL.indexOf(“?”)
    returns -1.
    Is there a problem when the PDF is opened on Web?
    Thanks for help
    Gerald

  36. Stefan Cameron on September 10th, 2010

    @Gerald Clerc,

    Opening the PDF in a browser is the only way this feature will work. What URL are you using?