URL encoding strings in Acrobat

Learn how to correctly format a URL that contains complex information.

By Thom Parker – March 24, 2008

 

For sending e-mail and launching web pages from a PDF

JavaScript Corner Tip – URL Encoding
Scope: All Acrobat versions
Skill Level: Beginner
Prerequisites: Familiarity with the Acrobat JavaScript Console

URLs (or URIs, Universal Resource Identifiers) can be very simple, or can contain complex information. If the URL does contain complex information, it is absolutely necessary it be formatted correctly. For example, a URL cannot contain white space or special characters. In Acrobat, this is particularly important for two functions-—the doc.submitForm() and the app.launchURL() functions.

The problem comes when parameters are added to a URL. For example, the following line of code opens up one of my blog entries to the comments section. Run it from the JavaScript Console.

app.launchURL("http://windjack.com/?p=18#comments"); 

The standard part of the URL, “http://windjack.com/?p=18#comments” looks just like most URLs. But the last part is a bit cryptic, “?p=18#comment.” This is called the query string and it’s for passing information to the server. The “p=18” part means the server should return page 18, the 18th blog entry. The “#comments” part is a navigation instruction for the Web browser, not the server. It tells the browser to scroll down to the “comments” tag on the page returned from the server.

I’m not going to explain the ins and outs of writing URLs. The example above is presented to make two important points. First, there are some characters that have a special purpose in a URL. In the example, these are the “?,” “=” and “#” symbols. These characters can be problematic when used in the data parts of the URL, so if we want to include them or any other special characters or white space, we must have an alternate method for representing this information. The second point is that URLs are not static. They can be used to transmit dynamic information. In fact, to make a PDF more dynamic and user-friendly, it may be necessary for us to build our URLs and/or the associated query strings on the fly from arbitrary information.

The people who developed the Internet standards devised a method for handling these cases where a special character needs to be included in the URL (URI specification). The gist of it is replacing the special character with its character code. For example, the string “Hello World,” converts to “Hello%20World.” The percent symbol is another special character that indicates the following two numbers are the character code, i.e., in ASCII, the character code for a space is 20 in hexidecimal notation, or 32 in the regular base-10 world.

The good news is we don’t have to worry about any of these details because Core JavaScript provides a solution-- the encodeURI() function. This is not an Acrobat function, but something that’s built into JavaScript itself.

Let’s look at a practical Acrobat example. We have a form and want the user to e-mail the form data back to us. For processing the data, we’d like it to be in a custom-XML format; and for the convenience of the person handling the incoming e-mail, we want to include a special message in the main body of the e-mail, such as:

From:
Location:

I’m not going to cover creating a custom XML for submission. The only thing we need to know for this example is that in order get the features we want, submitting a custom XML, we have to use the doc.submitForm() function. When using this function, e-mail fields like the subject and body are placed in a query string appended to the e-mail address, so we have to worry how this information is formatted.

To begin, we need a form, and we need to place a button on that form for sending the e-mail. Here is an example file that demonstrates the code used in the article, plus a little more, URLEncodingExample.pdf.

If you want to utilize this sample from your own form, be aware that the following code uses specific form-field names, and a custom function for creating the XML for submission. You will need to either change the form-field names in the example code to match your own form-field names, or change names on your form to match the names in the code.

For demonstration purposes, the MakeMyXML() function and the oMyXML variable can be removed entirely.

Our initial inclination when writing the submission script is to use something like the code below, which is entered into the Run a JavaScript action for the submit button’s MouseUp event.

var oMyXML = MakeMyXML();
// This function creates our xml and
// is outside the scope of the article
// Build the subject and body parts of the email message
var strSubject = "Form A Data Returned"; var strMsg = "From: " + this.getField("ApplicantName").value; strMsg += "\nLocation: " + this.getField("ApplicantCountry").value;
// Build the URL used for the submitForm function
var strURL = "mailto:[email protected]?subject=" + strSubject; strURL += "&body=" + strMsg;
// call the submitForm function
this.submitForm({cURL:strURL, cSubmitAs: "XML", oXML: oMyXML});

The first line of code calls the MakeMyXML() function. Again, if you are trying this out on your own form, you can leave this function out and remove the oXML argument from the submitForm() function. For this article, we’re only interested in the rest of the code, which builds the e-mail URL.

To build the URL, we simply concatenate a set of strings onto the strURL variable. The mailto: prefix tells Acrobat to e-mail the data rather than post it to a website. The prefix is followed by the e-mail address, which is followed by the query string containing the subject and message body of the e-mail. This is where the problems start.

The subject and body contain illegal URL characters, spaces and new-line characters. We have no idea what the user is going to enter into the form fields, so we don’t know what other kinds of illegal characters may be placed in the URL, but we have an easy fix. We use the encodeURI()JavaScript function to fix the URL in the last line of the script.

// call the submitForm function
var strEncodURL = encodeURI(strURL);
this.submitForm({cURL:strEncodURL, cSubmitAs: "XML", oXML: oMyXML});

That’s all that needs to be done. We can use the encodeURI() function any time we need to use a URL in Acrobat JavaScript. If you’ve been following along using the example document, you’ll see it contains both the working code and non-working code, where the working code is commented out. Simply change the comments around to see the difference in operation.

If for any reason we need to decode an URL-- for example with the doc.URL property-- there is another built-in Core JavaScript function, the decodeURI() function. It works in a similar way.

For more information on the encodeURI() and decodeURI(), consult any standard JavaScript reference. Below is the official core JavaScript Web reference:

http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference

For information on the doc.submitForm() function, see the Acrobat JavaScript Reference at:
http://www.adobe.com/devnet/acrobat/javascript.html