Actions and JavaScript

If you’ve checked out Steve’s post that introduces Actions and the Action Builder, you should have a basic idea of what Actions is about. In this post, I intend to dive a bit deeper into the guts of how Actions work “under the hood” as it were and explain what happens to your form when you use Actions.

I’ll start by expanding on Steve’s simple “When Button1 is clicked, go to a web page” example.

This is the simple button click example in the Action Builder dialog:

ActionsBtnClick.png

If you press the “OK” button and preview your form in Acrobat, when you press the button, a web browser will open to the website provided. It’s like magic!

And now I will sadly make the experience much less magical: I’m going to explain what’s really happening behind the curtain to get this to work.

When an Action is created, Designer is actually generating JavaScript code for you, under the hood. Given the conditions you provide and the results you want to achieve, we figure out what event should trigger the code to run, and what JavaScript needs to be placed in that event to achieve the result desired.

How It Really Works

What really happens is that Designer generates scripts and puts them in the right events of the form for you. Each Action generates one or more script blocks (which we call “script snippets” or just “snippets”.) A script block generated by Designer has a standard format:


[1] //+ The header ID line, which is also the "managed script" open line
[0-*] //+ Action parameter lines
[1-*] Lines of Javascript
[1] //- The managed script closing line

Everything between the first //+ and the //- line is a “managed script”, i.e. a script that Designer created, rather than one that was created manually by you, the form author. Designer keeps track of all the managed scripts through the header blocks (all the lines that start with //+).

After creating the simple “When Button1 is clicked…” Action, if you check the Script Editor, you will see that the Button1::click event contains some script:

ActionsBtnClkScript.png

At this point, there are two very important technical details about managed script that I would like to review:

The first point is that the header block is the important data of a managed script. The actual JavaScript is incidental, from Designer’s point of view. For Actions to work properly, all the information Designer needs is what is in the header block. In point of fact, the JavaScript between the //+ and the //- is routinely thrown away and regenerated by Designer.

The second point is that the Action Builder and Actions UI depend on the scripts that Designer generates not being tampered with to work correctly: if a managed script has been edited manually, it is an extremely difficult problem for Designer to figure out what has changed, and whether the changes are valid. Since it’s so difficult, we don’t even try: if any changes are made to a managed script, we un-manage that script. In essence, you lose your Action. This means that when the Script Editor next refreshes, the Action header block will be gone, and the script will look just like regular script you typed in manually. Also, if you open the Action Builder, the Action that was modified will no longer be there.

This isn’t as bad as it may seem. In fact, we designed this entire feature with the idea that people would eventually want to deliberately un-manage scripts: maybe you just want to use the Action Builder to get you started, but you want to do more complicated script on your own: so you create a “starter” Action and then go manually edit the action to make it do more complex things. So it’s not necessarily a bad thing to un-manage your Action – you should just be sure you know what you’re doing and don’t un-manage scripts accidentally.

I guess I’ll leave off here on the introduction to the innards of Actions. I have another post planned where I’ll explain the Action header block in more detail.