Creating Form Rendering ASP.NET Applications

Transcription

1 Creating Form Rendering ASP.NET Applications You can create an ASP.NET application that is able to invoke the Forms service resulting in the ASP.NET application able to render interactive forms to client web browsers and handle form submissions. The Forms service is able to render different interactive form types, such as PDF, HTML, and Form guides (Flash-based forms). For the purpose of this discussion, it is assumed that the Forms service renders interactive PDF forms (interactive means that an end user will be able to enter data into the form s fields). The Forms service renders interactive PDF forms to client devices, typically web browsers, to collect information from users. After an interactive form is rendered, a user can enter data into form fields and click a submit button located on the form to send information back to the Forms service. Adobe Reader or Acrobat must be installed on the computer hosting the client web browser in order for an interactive PDF form to be visible. Note: Before you can render a form using the Forms service, you must create a form design. Typically, a form design is created in Designer ES and is saved as an XDP file in LiveCycle ES repository. (See LiveCycle Designer ES Help.) This document discusses how to create an ASP.NET application that is able to render interactive forms to loan applicants in order to collect information required to process a loan request. This application lets a user fill in a form with data required to secure a loan and then submits data to the ASP.NET application. The following diagram shows the ASP.NET loan application s logic flow.

2 The following table describes the steps in this diagram. Step Description 1 A user requests that the loan application be rendered to the web browser. 2 The ASP.NET application invokes the Forms ES service using a web service and renders an interactive form to the client web browser. 3 After the user fills the loan form and clicks the submit button, data is submitted back to the ASP.NET application. The ASP.NET application processes the form submission and retrieves form data (the data that the user entered into the form). 4 A confirmation form is rendered back to the web browser. Data such as the user s first and last name is merged with the form before it is rendered. This interactive loan form is rendered by the ASP.NET application to the user.

3 This confirmation form is rendered by the ASP.NET application to the user after the loan form is submitted. The ASP.NET application prepopulates this form with the user s first and last name as well as the loan amount. To prepopulate a form with data, ensure that you use an XML data source that contains XML elements that match the form fields. For example, the following XML data can prepopulate this form with data. <root> <FirstName>Tony/FirstName> <LastName>Blue</LastName> <Amount>1000</Amount>

4 </root> Summary of steps To create an ASP.NET application that is able to render an interactive PDF form and handle form submissions, perform the following steps: 1. Create a.net client assembly. 2. Create an ASP.NET application and reference the.net client assembly. 3. Reference the Microsoft XML library. 4. Create an ASP page that renders the loan form. 5. Create an ASP page that handles the form submission. 6. Execute your ASP.NET application. Note: The ASP page that handles the form submission also renders the confirmation form to the user. (See Creating an ASP page that handles the form submission.) Creating a.net client assembly You can create a proxy class that is used to create the.net client assembly by using a tool that accompanies Microsoft Visual Studio. The name of the tool is wsdl.exe and is located in the Microsoft Visual Studio installation folder. To create a proxy class, open the command prompt and navigate to the folder that contains the wsdl.exe file. Enter the following command at the command prompt: wsdl By default, this tool creates a CS file in the same folder that is based on the name of the WSDL. In this situation, it creates a CS file named FormsServiceService.cs. You use this CS file to create a proxy object that lets you invoke the Forms service. Amend the URL in the proxy class to use base64 encoding by specifying?blob=base64 to ensure that the BLOB object returns binary data. In the proxy class, locate the following line of code: " and change it to: " Note: For more information about the wsdl.exe tool, see MSDN Help. Create a new Visual Studio Class Library project that produces a.net client assembly. The CS file that you created using wsdl.exe can be imported into this project. This project produces a DLL file that you can use in other Visual Studio.NET projects to invoke a service. To develop the.net client assembly:

5 1. Start Microsoft Visual Studio.NET. 2. Create a new Class Library project and name it FormsService. 3. Import the CS file that you created using wsdl.exe. 4. In the Project menu, select Add Reference. 5. In the Add Reference dialog box, select System.Web.Services.dll. 6. Click Select and then click OK. 7. Compile and build the project. Note: This procedure creates a.net client assembly named FormsService.dll that you can use to send SOAP requests to the Forms ES service. This.NET client assembly will be used in the client ASP.NET application. Caution: Make sure that you add?blob=base64 to the URL in the proxy class that is used to create the.net client assembly. Otherwise, you cannot retrieve binary data from the BLOB object. (See Creating a.net client assembly.) Creating an ASP.NET web application Start a new Microsoft.NET C# ASP.NET Web application. The following illustration shows the contents of the ASP.NET project named WebSite3 created in this document. The ClassLibrary1.dll represents the.net client assembly that consumes the Forms service s native SOAP stack. The Interop.MSXML2.dll represents the Microsoft XML library that must be included in this project to work with submitted form data. (See Referencing the Microsoft XML library.) The Default.aspx page represents the ASP page that renders the loan form and Default2.aspx represents the ASP that handles the form submission and renders the confirmation form. To start a new Microsoft.NET project: 1. Start Microsoft.NET Visual Studio. 2. From the File menu, select New, Web Site. 3. In the Templates list, select ASP.NET Web Site.

6 4. In the Location box, select a location for your project. 5. In the Language box, select Visual C#. 6. Click OK. Referencing the.net client assembly Place your newly-created.net client assembly on the computer where you are developing your client ASP.NET application. After you place the.net client assembly in a directory, you can reference it from your ASP.NET project. You must also reference the System.Web.Services library from your project. If you do not reference this library, you cannot use the.net client assembly to invoke the Forms service. To reference the.net client assembly: 1. In the Project menu, select Add Reference. 2. Click the.net tab. 3. Click Browse and locate the FormsService.dll file. 4. Click Select and then click OK. Referencing the Microsoft XML library The code example that processes submitted form data uses XML data types, such as MSXML2.DOMDocument50Class, to handle the XML data. You must include this library into your ASP.NET project to compile and execute the code examples that are specified in this document. To reference the Microsoft XML library: 1. In the Project menu, select Add Reference. 2. Click the COM tab. 3. Select Microsoft XML, v5 and click OK. Creating an ASP page that renders a form Within the ASP.NET project that you created, add a web form (an ASPX file) that is responsible for rendering the loan form to the web user. The web form is actually a class that is derived from System.Web.UI.Page. The C# application logic that renders the form is located in the Page_Load method. You must specify URI values that are required by the Forms ES service to render a form. A form design that is stored in the LiveCycle ES repository can be referenced by using the content root URI value repository:///. When you specify a form design located in the LiveCycle ES repository, you must specify the full path. For example, consider the following form design named Loan.xdp located in the LiveCycle ES repository:

7 To access this form design, you must specify FormsFolder/Loan.xdp as the form name (the first parameter passed to the renderpdfform method) and repository:/// as the content root URI value. To render an interactive form, you must define URI values such as the target URL that specifies where form data is posted. The target URL can be defined in one of the following ways: On the Submit button while designing the form design in Designer ES By using the Forms service client API (this document uses this option) If these two values conflict, the URL in the form design overrides the value that is programmatically defined. However, if you have a form that contains a submit button and a calculate button (with a corresponding script that runs at the server), you can programmatically define the URL to where the form is sent to execute the script. To create an ASP page that renders an interactive form, perform the following tasks in the Page_Load method: 1. Create a.net client assembly that consumes the Forms service s native SOAP stack. (See Creating a.net client assembly.) 2. Reference the.net client assembly in your ASP.NET project. (See Referencing the.net client assembly.) 3. Using the Microsoft.NET client assembly, create a FormsServiceService object by invoking its default constructor. 4. Set the FormsServiceService object s Credentials data member with a System.Net.NetworkCredential value that specifies the user name and password values. 5. Create an URLSpec object that stores URI values by using its constructor. 6. Invoke the URLSpec object s setapplicationwebroot method and pass a string value that represents the application s web root. For example, if the name of your ASP.NET project is WebSite3, then the application s web root is 7. Invoke the URLSpec object s setcontentrooturi method and pass a string value that specifies the content root URI value. Ensure that the form design is located in the content root URI. If not, the Forms ES service throws an exception. To reference the LiveCycle ES repository, specify repository:///. 8. Invoke the URLSpec object s settargeturl method and pass a string value that specifies the target URL value to where form data is posted. If you define the target URL in the form design, then you can pass an empty string. When working with an ASP.NET application, specify another ASPX file that handles the form submission. For example, assuming the name of the ASPX file that handles the form submission is named Default2.aspx, specify 9. Invoke the FormsServiceService object s renderpdfform method and pass the following values:

8 A string value that specifies the form design name, including the file name extension. If you are referencing a form design that is saved in the LiveCycle ES repository, ensure that you specify the complete path, such as FormsFolder/Loan.xdp. A BLOB object that contains data to merge with the form. If you do not want to merge data, pass null. A PDFFormRenderSpec object that stores run-time options. This is an optional parameter and you can specify null if you do not want to specify run-time options. An URLSpec object that contains URI values that are required by the Forms service. A java.util.hashmap object that stores file attachments. This is an optional parameter and you can specify null if you do not want to attach files to the form. An empty com.adobe.idp.services.holders.blobholder object that is populated by the method. This is used to store the rendered PDF form. An empty javax.xml.rpc.holders.longholder object that is populated by the method. (This argument will store the number of pages in the form.) An empty javax.xml.rpc.holders.stringholder object that is populated by the method. (This argument will store the locale value.) An empty com.adobe.idp.services.holders.formsresultholder object that will contain the results of this operation. The renderpdfform method populates the com.adobe.idp.services.holders.formsresultholder object that is passed as the last argument value with a form data stream that must be written to the client web browser. 10. Create a FormResult object by getting the value of the com.adobe.idp.services.holders.formsresultholder object s value data member. 11. Create a BLOB object that contains form data by invoking the FormsResult object s getoutputcontent method. 12. Set the Response object s ContentType data member with the value of the BLOB object s ContentType data member. Example: Rendering a form using an ASP.NET page The following C# code example renders a form named Loan.xdp that is located in the LiveCycle repository. Notice that the code example is located in the n the Page_Load method. using System; using System.Data; using System.Configuration; using System.Web; using System.Web.Security; using System.Web.UI; using System.Web.UI.WebControls;

9 using System.Web.UI.WebControls.WebParts; using System.Web.UI.HtmlControls; using System.IO; public partial class _Default : System.Web.UI.Page protected void Page_Load(object sender, EventArgs e) try //This will render a form to a client web browser FormsServiceService forms = new FormsServiceService(); //Set authentication values forms.credentials = new System.Net.NetworkCredential("administrator", "password"); //Specify URI values used by the Forms service URLSpec urivalues = new URLSpec(); urivalues.applicationwebroot = " urivalues.contentrooturi = "repository:///"; urivalues.targeturl = " //Set out parameter values long pagecount = 1; String localvalue = "en_us"; FormsResult result = new FormsResult(); //Render an interactive PDF form forms.renderpdfform( "FormsFolder/Loan.xdp", null, new PDFFormRenderSpec(), urivalues, null, out pagecount, out localvalue, out result); //Write the data stream to the web browser BLOB outform = result.outputcontent; String contenttype = result.contenttype; Response.ContentType = contenttype; byte[] ccontent = outform.binarydata; Response.OutputStream.Write(cContent, 0, ccontent.length); catch (Exception ee) Console.WriteLine(ee.Message);

10 Creating an ASP page that handles the form submission Web-based applications that enable a user to fill in interactive forms require the data to be submitted back to the server. Using the Forms service, you can retrieve the data that the user entered into an interactive form. After you retrieve the data, you can process the data to meet your business requirements. For example, you can store the data in a database, send the data to another application, send the data to another service, merge the data in a form design, display the data in a web browser, and so on. Form data is submitted to the Forms service as either XML or PDF data, which is an option that is set in Designer ES. A form that is submitted as XML enables you to extract individual field data values. That is, you can extract the value of each form field that the user entered into the form. A form that is submitted as PDF data is binary data, not XML data. As a result, you cannot extract field values. However, you can save the form as a PDF file, or send the form to another LiveCycle ES service. When form data is submitted as XML, you can retrieve XML data that represents the submitted data. All form fields appear as nodes in an XML schema. The node values correspond to the values that the user filled in. Consider a loan form where each field in the form appears as a node within the XML data. When form data is submitted as XML, you can retrieve XML data that represents the submitted data. All form fields appear as nodes in an XML schema. The node values correspond to the values that the user filled in. Consider a loan form where each field in the form appears as a node within the XML data. Assume a user fills the loan form with data shown in the following form.

11 The following illustration shows corresponding XML data that is retrieved by using the Forms service API. Note: The form design must be configured correctly in Designer ES for data to be submitted as XML data. To properly configure the form design to submit XML data, ensure that the Submit button that is located on the form design is set to submit XML data. For information about setting

12 the Submit button to submit XML data, see LiveCycle Designer ES Help at Retrieve form data You must retrieve form data that was posted to the Forms service and determine its processing state. That is, when data is submitted to the Forms service, it does not necessarily mean that the Forms service is finished processing the data and the data is ready to be processed. For example, data can be submitted to the Forms service so that a calculation can be performed. When the calculation is complete, the form is rendered back to the user with the calculation results displayed. Before you process submitted data, it is recommended that you determine whether the Forms service is finished processing the data. The Forms service returns the following values to indicate whether it has finished processing the data: 0 (Submit): Submitted data is ready to be processed. 1 (Calculate): The Forms ES service performed a calculation operation on the data and the results must be rendered back to the user. 2 (Validate): The Forms ES service validated form data and the results must be rendered back to the user. 3 (Next): The current page has changed with results that must be written to the client application. 4 (Previous): The current page has changed with results that must be written to the client application. Determine the submitted data content type When data is submitted from a client web browser to the Forms service, it can be submitted as either XML or PDF data. To retrieve data that is entered into form fields, the data must be submitted as XML data. If data is submitted as PDF data, you cannot retrieve individual field values. The content type of data that is submitted as XML is application/vnd.adobe.xdp+xml. In contrast, the content type of data that is submitted as PDF data is application/pdf. Process the submitted data Depending on the content type of the submitted data, you can either extract individual form field values from the submitted XML data or save the submitted PDF data as a PDF file (or send it to another service). To extract individual form fields, convert submitted XML data to an XML data source and then retrieve XML data source. To create an ASP page that handles a form submission, perform the following tasks in the Page_Load method: 1. Reference the.net client assembly in your ASP.NET project. (See Referencing the.net client assembly.)

13 2. Using the Microsoft.NET client assembly, create a FormsServiceService object by invoking its default constructor. 3. Set the FormsServiceService object s Credentials data member with a System.Net.NetworkCredential value that specifies the user name and password values. 4. Get the posted form data s content length by retrieving the value of the HttpRequest.Page.Request object s ContentLength data member. 5. Create a byte array and populate it with form data by invoking the HttpRequest.Page.Request object s BinaryRead method and passing the content length. 6. Create a BLOB object by using its constructor. This BLOB object is used to store the posted form. 7. Assign the byte array content to the BLOB object s binarydata data member. 8. Invoke the FormsService object s processformsubmission method and pass the following values: The BLOB object that contains the form data. A string value that specifies environment variables included all relevant HTTP headers. For example, you can specify the following string value: HTTP_REFERER=referrer&HTTP_CONNECTION=keepalive&CONTENT_TYPE=application/xml. A string value that specifies the HTTP_USER_AGENT header value; for example, Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1;.NET CLR ). A string value that will contain the name of the last button clicked on the form (this is an out parameter value). An empty BLOB object that is populated by the method (this is an out parameter value). An empty BLOB object that is populated by the method (this is an out parameter value). A short value that is populated by the method (this is an out parameter value). An empty Object array that is populated by the method (this is an out parameter value). A FormResult object that is populate by this method (this is an out parameter value). This object is used to store form data that was posted to the ASP page. 9. Determine whether the Forms service is finished processing the form data by getting the value of the FormsResult object s action data member. If this value is 0, the form data is ready to be processed (meaning that the submit button was clicked on the form).

14 10. Determine the submitted data content type by getting the value of the FormsResult object s contenttype data member. This data member returns a string value that specifies the content type of the submitted form data. If XML data is submitted to the Forms service, as opposed to PDF data, this method returns application/vnd.adobe.xdp+xml. 11. If the data content type is application/vnd.adobe.xdp+xml or text/xml, create application logic to retrieve XML data values. Create a BLOB object by invoking the FormsResult object s outputcontent data member. Create a byte array that store form data by getting the value of the BLOB object s binarydata data member. Create a MSXML2.DOMDocument50Class object by using its constructor. Ensure that you referenced the Microsoft XML library. (See Referencing the Microsoft XML library.) Load the XML data by invoking the MSXML2.DOMDocument50Class object s load method and passing the byte array that contains form data. Retrieve the value of each node within the XML document. One way to accomplish this task is to create a custom method that accepts two parameters: the MSXML2.DOMDocument50Class object and the name of the node whose value you want to retrieve. This method returns a string value representing the value of the node. In the code example that follows this process, this custom method is called getnodetext. The body of this method is shown. Example: Handling a form submission using an ASP.NET page The following C# code example handles a submitted form. Notice that the code example is located in the n the Page_Load method. This example uses a MSXML2.DOMDocument50Class object to retrieve XML data from the submitted form. The value of each form field is retrieved. This code example also creates a new XML data source using an MSXML2.DOMDocument50Class object. Three form field values are specified in the new XML data source: first name, last name, and mortgage amount. The XML data source is used to prepopulate the confirmation form that is rendered back to the user. The confirmation form is based on a form design named Confirmation.xdp and is located in the LiveCycle ES repository. The user-defined method that contains application logic that renders the form in the following code example is named renderform. using System; using System.Runtime.Serialization.Formatters.Binary; using System.Data; using System.Configuration; using System.Collections; using System.Web; using System.Web.Security; using System.Web.UI; using System.Web.UI.WebControls; using System.Web.UI.WebControls.WebParts; using System.Web.UI.HtmlControls;

15 using System.IO; public partial class Default2 : System.Web.UI.Page protected void Page_Load(object sender, EventArgs e) try //Handles a form submission FormsServiceService forms = new FormsServiceService(); //Set authentication values forms.credentials = new System.Net.NetworkCredential("administrator", "password"); //Get the length of data passed to this URL int numread = Request.ContentLength; //Get Information from the Request object byte[] formdata= Request.BinaryRead(numRead); BLOB informdata = new BLOB(); informdata.binarydata = formdata; RenderOptionsSpec processspec = new RenderOptionsSpec(); processspec.locale = "en_us"; //Specify user agent values String agent = "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1;.NET CLR )"; //Specify env values String envvalues = "CONTENT_TYPE=application/pdf&CONTENT_TYPE=application/vnd.adobe.xdp+xm l"; //Set out parameter values BLOB outblob = new BLOB(); BLOB outblob2 = new BLOB(); short action ; Object[] allobs = null; FormsResult formresult = new FormsResult(); String buttonname; //Handle the Form submission forms.processformsubmission(informdata, envvalues, agent, processspec, out buttonname, out outblob, out outblob2, out action, out allobs, out formresult);

16 //Make sure that the Form is submitted short formaction = formresult.action; if (formaction == 0) //Determine the content type of the data String mycontenttype = formresult.contenttype; if (mycontenttype =="application/vnd.adobe.xdp+xml") //Create a BLOB object that stores XML data //submitted with the form BLOB outformdata = formresult.outputcontent; byte[] outbytearray = outformdata.binarydata; //Load the form data into a MSXML2.DOMDocument50Class instance MSXML2.DOMDocument50Class mydom = new MSXML2.DOMDocument50Class(); mydom.load(outbytearray); submitted mydom); //Get the value of each field of the form that was String mortageamount = getnodetext("mortgageamount", String lastname = getnodetext("lastname", mydom); String firstname= getnodetext("firstname", mydom); String SSN = getnodetext("ssn", mydom); String PositionTitle = getnodetext("positiontitle", mydom); String Address = getnodetext("address", mydom); String City = getnodetext("city", mydom); String StateProv = getnodetext("stateprov", mydom); String ZipCode = getnodetext("zipcode", mydom); String = getnodetext(" ", mydom); String PhoneNum = getnodetext("faxnum", mydom); String Description = getnodetext("description", mydom); //Create an XML file using field values MSXML2.DOMDocument50Class xmldata = createxmldata(firstname,lastname,mortageamount); //Save the XML data to a temp XML file. xmldata.save("c:\\adobe\\temp.xml"); //Render the confirmation form renderform(); catch (Exception ee) Console.WriteLine(ee.Message); //Returns the text value of the specified XML node

17 private String getnodetext(string nodename, MSXML2.DOMDocument50Class mydom) MSXML2.IXMLDOMNodeList olist = mydom.getelementsbytagname(nodename); MSXML2.IXMLDOMNode mynode = olist.nextnode(); MSXML2.IXMLDOMNodeList ochildnodes = mynode.childnodes; String stext = ""; for (int i = 0; i < ochildnodes.length; i++) //Get single node MSXML2.IXMLDOMNode mysinnode = ochildnodes.nextnode(); //Get the element if (mysinnode.nodetype == MSXML2.DOMNodeType.NODE_TEXT) stext = mysinnode.text; return stext; //Creates a new XML data source private MSXML2.DOMDocument50Class createxmldata(string FirstNameVal, String LastNameVal, String AmountVal) //This method creates a new XML data source MSXML2.DOMDocument50Class xmlsource = new MSXML2.DOMDocument50Class(); //Create a root element MSXML2.IXMLDOMElement root = (MSXML2.IXMLDOMElement)xmlSource.createElement("root"); xmlsource.appendchild(root); //Create the FirstName element MSXML2.IXMLDOMElement FirstName = (MSXML2.IXMLDOMElement)xmlSource.createElement("FirstName"); FirstName.appendChild(xmlSource.createTextNode(FirstNameVal)); root.appendchild(firstname); //Create the LastName element MSXML2.IXMLDOMElement LastName = (MSXML2.IXMLDOMElement)xmlSource.createElement("LastName"); LastName.appendChild(xmlSource.createTextNode(LastNameVal)); root.appendchild(lastname); //Create the Amount element MSXML2.IXMLDOMElement Amount = (MSXML2.IXMLDOMElement)xmlSource.createElement("Amount"); Amount.appendChild(xmlSource.createTextNode(AmountVal)); root.appendchild(amount); return xmlsource;

18 //Renders the Confirmation form to the user private void renderform() try //This will render a form to a client web browser FormsServiceService forms = new FormsServiceService(); //Create a BLOB object to store form data BLOB informdata = new BLOB(); //Specify the PDF document to encrypt with a password string path = "C:\\Adobe\\temp.xml"; FileStream fs = new FileStream(path, FileMode.Open); //Get the file stream length and create a byte array int len = (int)fs.length; byte[] ByteArray = new byte[len]; //Populate the byte array with the contents of the FileStream object fs.read(bytearray, 0, len); informdata.binarydata = ByteArray; //Set authentication values forms.credentials = new System.Net.NetworkCredential("administrator", "password"); //Specify URI values used by the Forms service URLSpec urivalues = new URLSpec(); urivalues.applicationwebroot = " urivalues.contentrooturi = "repository:///"; //Set out parameter values long pagecount = 1; String localvalue = "en_us"; FormsResult result = new FormsResult(); //Render an interactive PDF form forms.renderpdfform( "FormsFolder/Confirmation.xdp", informdata, new PDFFormRenderSpec(), urivalues, null, out pagecount, out localvalue, out result); //Write the data stream to the web browser BLOB outform = result.outputcontent; String contenttype = result.contenttype; Response.ContentType = contenttype; byte[] ccontent = outform.binarydata;

19 Response.OutputStream.Write(cContent, 0, ccontent.length); catch (Exception ee) Console.WriteLine(ee.Message); Running the ASP.NET application After you compile and deploy your ASP.NET application, you can execute it using a web browser. Assuming the name of the ASP.NET project is WebSite3 and the name of the Default ASP page is Default.aspx, then specify the following URL within a web browser: where localhost is the name of the web server hosting the ASP.NET project and 1629 is the port number. When you compile and build your ASP.NET application, Microsoft Visual Studio, automatically deploys it. About the author Scott Macdonald is a senior SDK technical writer at Adobe Systems with more than 10 years in the software industry working with Java, C/C++/C#, as well as other programming languages. Attributions For more information about creating applications that invoke the Forms service, see the LiveCycle ES SDK Help at