Archive for November, 2008

Executing web service calls in a form guide

LiveCycle ES Designer makes it easy to set up a connection to a WSDL in order to execute some web service call.  This functionality can also be extended to your form guide with a few simple steps.

A data connection to a web service will first need to be defined on your form.  These steps are the same regardless of what your ultimate form rendering will be.

  • Create your data connection in LiveCycle Designer.
  • Set up required data bindings.
  • Add the web service invoke button to your form.

At this point if you were to preview your form and click the invoke button a client-side web service call would be invoked by the PDF based on your data bindings.  A form guide however must execute its web service calls on the server which means a few extra steps are required.

Now let’s make the required changes to have this web service executed by a form guide.

  • Change the execution options of the invoke button to Run At Server.  If you also want the PDF to execute web service calls on the client you will need to add two invoke buttons and hide the one that will be used by the form guide.

As a minimum this is all that needs to be done.  Adding this button you your form guide will allow it to execute the desired web service and display the result based on your data bindings.  I am now going to dig a little deeper however to see how we can improve the experience on the form guide.

  • Add a hidden field to hold the status of asynchronous calls (eg. asyncCallActive).  This field will indicate to the guide if a server-side web service call is currently active.
  • Add another hidden button (eg. executeWS) whose click event is set to run at server.
  • Add the following script to the button’s click event (invokeBtn is the name of your web service execute button).
invokeBtn.execEvent("click");
asyncCallActive.rawValue = "false";

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

At this point we have all the server-side pieces in place for the form guide to be able to execute a web service.  All that still needs to be done is add the ability on the client to actually invoke this web service.  This step for the most part depends on your particular form design.  Typical usage includes invoking the web service on exit of some field or just by clicking a button.  Let’s look at the on exit case.

Let’s assume we have a web service that looks up the weather for a given zip code.  In this case it would make sense to invoke the web service on the exit event of a zip code field.

  • Add the following client-side script to the field’s exit event.
asyncCallActive.rawValue = "true";
executeWS.execEvent("click");

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

In the form guide whenever this field is executed the click event of the executeWS button will be executed on the server.  The result of the web service call will be merged back into the form guide based on what ever field bindings you had defined.

We’re almost done but not quite. You may have noticed that I have been setting the rawValue of the asyncCallActive field but not doing anything with it.  Add the following client-side script to this field’s change event.

if (xfa.host.name == "Flash" && this.rawValue)
{
    import mx.managers.CursorManager;
if (this.rawValue == "true")
CursorManager.setBusyCursor();
else
CursorManager.removeBusyCursor();
}

This script is a form guide trick that allows you to add ActionScript to your form that will only be executed in the form guide.  The check that xfa.host.name is Flash ensures this script will not execute on the PDF.  As a result we are able to set the Flex busy cursor state based on the value of the asyncCallActive field.  This helps your form provide feedback to the user that some back-end processing is being done.

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

Download XDP

Share on Facebook