Posted by Kas Thomas JUL 09, 2010
Posted in crx, crx gems, development, javascript, microsling, sling and tutorials Comment 1
In prior blogs, I've given code for interacting via HTTP with Day's CRX repository from a Chrome/Greasemonkey script environment as well as from an OpenOffice macro. Such interactions are, as you know, made easy by CRX's (or should I say, Apache Sling's) REST API, which exposes a huge amount of functionality through plain old HTTP, obviating the need for such cumbersome things as RMI-over-IIOP, SOAP-RPC, complex content mappings on the back end, etc.
It turns out that precisely because of the ease with which you can interact with a Sling repository over HTTP, it's quite straightforward to set up interactions between Adobe Acrobat (and/or Portable Document Format files) and CRX.
There are two styles of what I'll call Acrobat-CRX integration, in terms of RESTful interactions. One style involves PDF forms. The other style involves the Adobe Acrobat runtime environment itself. In the former case, you'll typically write JavaScript snippets that attach to form fields and are triggered by form events. In the latter case, you write scripts for Acrobat itself, and from within those scripts you can hit the server in a variety of ways and do AJAX-like things behind the scenes. In this blog, we'll talk about the first case (which is easy); in a subsequent blog, we'll talk more about the second case (which is only slightly harder).
The easiest way to read or write the repository from PDF is to use a PDF form. Acrobat Professional comes with decent form-creation tools, allowing you to create all the standard sorts of controls (text fields, radio buttons, etc.) and attach scripts to them. The default behavior of the Submit button, in a PDF form, is to trigger a POST in which all field data gets sent to the server, either as Adobe FDF (Forms Data Format), XFDF, or HTML (depending on what you specified in the Acrobat UI when you created the Submit button). So if all you want to do is hit the server with a form POST and (in so doing) push content into a new node in CRX, you simply need to create a PDF form with a Submit button and specify a Sling-legal target URL per the Sling cheat sheet. No JavaScript required.
Most of the time, though, you'll probably want to exercise finer control over the form's behavior. You might want to issue a ":redirect" directive to the Sling servlet, for example, so that your user is taken to a particular page after the POST. Or you might want to use the ":nameHint" directive to force the repository to create a node with a specific name. Perhaps there are fields whose values you want to include or exclude at POST time. To handle these and other special situations, you'll want to write a bit of JavaScript.
First, though, create the Submit button using Acrobat Professional's form-design tools. In the configuration dialog for the button, select the Actions tab, then use the Selection Actions picker to select "Run a JavaScript." (Normally, you'd choose "Submit a Form." Instead, we're going to do the Submit programmatically.) See the screenshot below.
Use the "Add..." button to add a script to the button, then select "Run a JavaScript" in the Actions pane and you'll see an Edit button become enabled.
Click the Edit button. In the dialog that appears, cut and paste the following code:
params.cURL = "http://localhost:7402/content/myapp/";
params.cSubmitAs = "HTML";
params.cCharset = "utf-8";
params.bGet = false;
this.submitForm( params );
What's going on here is that we're simply creating a parameter block that tells Acrobat what we want done at POST time, then we're passing that parameter block as an argument to the Acrobat JavaScript API method submitForm().
As you can see, we've specified in cURL the CRX target location (the node under which to create a new item). Note that the path ends with a forward-slash.
In the cSubmitAs parameter, we tell Acrobat to submit the form as HTML, while in the cCharset parameter we specify UTF-8 encoding. (We could also specify UTF-16, Shift-JIS, BigFive, GBK, or UHC.) We set bGet to false to force a POST rather than GET. Acrobat's JavaScript API allows you to adjust a variety of other settings, as well, but this is all we really need to do in this example.
A sample form that contains two text fields (one for an e-mail address and another for a Comment) and a Submit button with this script already attached to it is available via the download link at the end of this blog. Note that the form actually contains four text fields, two of which are hidden. We've created a hidden text field named ":redirect" with a value of "http://localhost:7402/content/acrobat/thankyou.pdf," which tells Sling to serve the specified file (thankyou.pdf, a small file containing just the words "Thank you for your feedback") after the POST finishes. If we don't do this (if we don't include ":redirect"), Acrobat will serve up a PDF representation of the Sling servlet's default response (i.e., a wire dump), which is probably not what you want your user to see.
There is also a hidden field named ":nameHint," set to a default value of "myform." This tells Sling (or CRX) to create a new node named myform at the path given earlier. If myform already exists, a new node called myform_0 will be created. If that exists, myform_1 will be created. And so forth.
That's really about all there is to creating new content in CRX with a PDF form POST.
Next time, we'll look at what it takes to push and pull content to and from the repository asynchronously, which is to say in more of an AJAX-flavored manner, using Acrobat JavaScript. So stay tuned. It gets pretty interesting!
