Email Integration

Form submissions can be emailed to a recipient when the user clicks the submit button. To configure the form to send an email upon submission, open the form designer and click the [[V4_Designing_Forms#Form_.26_Doc_Action_Wizards | Doc Action button in the toolbar]]. This will launch the wizard selector. Choose the Email Data to Specified Address wizard.

Each time the form is submitted, Live Forms will send an email message with the form submission data, optionally an attachment snapshot of the form image, and optionally the data in XML format in an attachment named "form".

You can enter multiple comma separated addresses To, Cc, Bcc and a single Reply To address. The email address may either be a static address such as info@frevvo.com or a dynamic address by using template syntax such as {person}@frevvo.com if you want the name dynamic and the domain static or {emailAddress} to make the full email address dynamic.

We suggest you uncheck "Send Data" if you don't need the xml attachment. Also leave the "Send Snapshot" dropdown blank if you do not need the form image attachment. Both options have small performance and memory overheads. So don't select them if you're not going to use these attachments.

Here is an example using the dynamic template {emailAddress}. You must name one of your form controls emailAddress.

Step 1:First name one of your controls. You do this by entering a string into the control's Name property as shown below.

Step 2: Next, open the [[V4_Designing_Forms#Form_.26_Doc_Action_Wizards | Doc Action Email wizard]]. Replace jSmith@gmail.com with the template: {emailAddress}

Also you can specify an email address containing a template and static text such as: {customer}@frevvo.com. In this case the value in the form field named "customer" would replace {customer}. If the user enters "Joe" into the customer form field the submission would be emailed to Joe@frevvo.com.

The form image snapshot attachment can be Pdf, Png, Jpeg or Tiff. Live Forms In-house customers must install the Tiff generator in order to see the Tiff option.

Step 3: The email wizard lets you set your own email subject and message. The message body can contain html and css giving you the ability to generate very nicely formatted emails. Form data values can be added to the message subject and body using control template names. Two dropdowns in the wizard make it easy to add control templates. Or for customers preferring the Pdf attachment, the email message body can contain a very simple text message, which is the default.

Here is a sample of formatted message body. Note the use of html.

Dear {FirstName} {LastName} 
<p> Your loan request in the amount of <b>{LoanAmount}</b> has been received. 
</p> 
Sincerly,<br/> 
<i>The Mortgage Team</i>

 Here is the resulting email message:

Print View

All Live Forms forms are printable. By selecting a form's [[V4_Designing_Forms#Printable_2 | printable checkbox]] a print [[Image:printer.gif]] icon will be displayed at the top of your form. When the form is used and the printer icon is clicked the form is rendered in a new browser tab in an HTML printable format.

See also [[V4_Using_Forms#Printing_Forms | Printing Forms]].

PDF Integration 

Forms submission can be converted to PDF documents. The PDF document can be saved in Live Forms's Submission Repository, sent as an attachment to a submission email, or as an attachment to a POST to a back-end system such as a document management system.

The [[V4_Designing_Forms#Form_.26_Doc_Action_Wizards | Form and Doc action wizards]] for email and post submission control whether or not the form is converted to a PDF document and attached to the submission. You can control which form fields are added to the PDF via the [[V4_Designing_Forms#Printable | printable property]] on each field in your form.

Document Service

Live Forms's built-in document service can be used for processing your form data prior to submission.

The document service is accessed via the Url /service. It supports the following parameters:

• method=POST -- required and should be left POST
• target=[url] -- [url] is the path to your servlet

The target will be passed name/value pairs of all of the controls in your form with their current values. The target will also be passed the collection of xml documents comprising the form's current data. The collection will include at least one document in the namespace 'form' which contains all the data in controls added to the form from palette. The collection will also include one xml document for each data source added to the form.

Custom Print View

One example use of Live Forms's document service is to provide a print preview different from Live Forms's default print view.

All forms by default are printable. To make a form printable edit the form and check the [[V4_Designing_Forms#Printable_2 | printable property]]. Sometimes form designer required a highly customized print view. By calling Live Forms's document service you can pass all the form's xml documents to another target servlet that transforms the data into exactly the format you need and then returns html to another browser window.

To do this:

• Add a message control to your form
• Add the following html to your message control

<center> 
<a href="javascript:void(0);" onClick="window.open(document.location.toString().split('?')[0] + 
'/service?_method=POST&amp;target=http://[myhost]:[myport]/Myservices/service/print/myForm')">Print</a> 
</center>

Your transformation service should return html to the browser window. You can style the message control as a button by adding a border, background color and even dragging into a panel to size the "button".

Integrating with REST applications

From the point of view of the user interface, most web applications can be thought of simply as CRUD (Create, Retrieve, Update & Delete) operations on documents. In the diagram below, the form is being used to initially display a Customer and Order and then to update them. If you think in REST terms, the form is a View Resource that composes multiple Entity Resources (in this case a Customer Resource and an Order Resource), displays their current state and allows you to update them.

Live Forms provides a very flexible and powerful mechanism for interacting with documents (and the web in general). You can [http://www.frevvo.com/bucket/restlet/RestletCustomerExample.zip download source code and forms] for the discussion below. We strongly recommend that you download the example, [[#Customer_Example|study it]] and use it as a template for integrating with your own web applications.

Document URIs

For each [[V4_Designing_Forms#From_Schema|Document Type]] that you add to your form, Live Forms permits you to assign

• a document [http://bitworking.org/projects/URI-Templates/ URI Template] resolved either using query parameters or form fields.
• a Read method and
• a Write method.

This is best described using several examples. Consider the example above. Here are the interactions a Customer Resource supports:

Updating a document

Consider the case where a form is used to update a particular customer. To create the form: 

1. Upload your customer schema to the designer, add the customer element to the document types for the form and add the customer to the form (which automatically generates controls). See the section on [[V4_Designing_Forms#From_Schema|Adding Controls from Schema]] for further details.
2. Drag/drop, change labels etc. directly in the browser
3. Specify URI template .../customers/{customer}, choose Read Method GET and Write Method PUT
4. Specify a Form Action URI if desired (we'll get to this later).

That's it. As usual, you [[V4_Using_Forms#Sharing_Forms |access the form using its URI]]. When the form is used (instantiated), you may specify one or more query parameters along with the URI. For this example, we might use a URI and query parameter: .../form/1234?customer=02. Live Forms will resolve the URI template above to: .../customers/02, GET the customer, and display the initialized form. When the form is submitted, Live Forms will automatically PUT the customer document to the same URI thereby updating the customer. The diagram below shows the interactions.

Here's [http://www.frevvo.com/frevvo/web/user/gallery/app/_73zHwep_EduZgK0BUzi1Ug/formtype/__AKE4PgqEdusGKt5_HoCDw?_method=POST&embed=true&customer=02 an example form] that uses the Customer entity described above. In the example:

1. We instantiate the form with a parameter customer=02. This causes the form to resolve the URI template and GET the customer data from: http://[server]/customers/02. The resulting XML document provides the initial state of the Customer and is used to initialize the form.
2. Modify a value and click Submit. The form will automatically PUT to the correct resource and update the customer information.
3. Finally, Live Forms will store the generated document set and assign it a unique URI. The document set and the documents therein can be [[V4_Using_Forms#Documents|accessed at this URI]].

Creating a new document

Consider the case where a form is used to create a new customer. Follow the same steps above, except use the appropriate URI template .../customers and change the Read method to POST. That's it. As usual, you [[V4_Using_Forms#Sharing_Forms | access the form using its URI]]. When the form is used (instantiated), Live Forms will perform the POST and create the customer. It will then follow the server redirect (to the URI of the newly customer) and display the form. When the user enters customer information and submits the form, Live Forms will automatically PUT the resulting XML document to the URI of the newly created customer resource thereby updating it. The diagram below shows the interactions:

Here is [http://www.frevvo.com/frevvo/web/user/gallery/app/_73zHwep_EduZgK0BUzi1Ug/formtype/_1zmI4PsCEduLxOM9M8PJlQ?_method=POST&embed=true an example form] that creates a new customer using this method.

Dynamic documents

A document URI template can also be linked to a form control. To do this, use the [[V4_Designing_Forms#Name |Control Name]]. Consider the [[#Updating_a_document|Updating a document]] example above and the [http://www.frevvo.com/frevvo/web/user/gallery/app/_73zHwep_EduZgK0BUzi1Ug/formtype/__AKE4PgqEdusGKt5_HoCDw?_method=POST&embed=true&customer=02 sample form] therein.

The form has a Customer document and we have specified URI template .../customers/{customer} and Read method GET. In this form, there is a control which has Type ID 'customer' as shown in the figure below.

If you enter a value in this control, frevvo will automatically resolve the URI template using the new value and attempt to GET a new document. If it succeeds, the form will be initialized with the new document and all relevant control values will automatically update. In the example above, try changing the value to 03 or 04. Notice how the customer information fields change to reflect the new document that is being edited by the form.

If you enter an ID that does not exist, the GET will fail (return an empty document or a 404 HTTP status code). In this case, frevvo will automatically revert back to the default document with [[V4_Designing_Forms#Setting_a_Default_Value_for_a_Control |default values]] as specified by the designer.

In either case, if you modify/fill in fields and submit the form, it will PUT (since we chose PUT as the Write Method, the form will send an HTTP PUT) the resulting XML document to the resolved URI.

For example, if you enter ID 03, Live Forms will GET .../customers/03, display the form with fields initialized from the returned XML document and PUT the modified XML document to the same URI when the form is submitted. This PUT will update the customer with ID 03.

If you enter ID 99 (which does not exist), Live Forms will GET .../customers/99, which returns an empty document. The form will be displayed with default values (as entered originally by the designer). When submitted, the resulting XML document will be PUT to .../customers/99. This PUT will create a new customer with ID 99 (the behaviour depends on the implementation on the server - in our example, the PUT creates the customer).

Example

This example is a good way to understand Live Forms's handling of document URIs and the powerful capabilities of composing multiple document resources into view resources. You can download the entire example including source code and forms [http://www.frevvo.com/bucket/restlet/RestletCustomerExample.zip by clicking here].

This example follows the principles of REST and uses the [http://www.restlet.org Restlet framework] but you can use any framework or server-side model that you like. As mentioned earlier, Live Forms forms can be thought of as View Resources that compose one or more Entity Resources (documents). In this example we have entities Customer and List of Customers. Reproduced here are the methods that they support.

This is implemented in the two classes: com.frevvo.restlet.customer.CustomersResource and com.frevvo.restlet.customer.CustomerResource. These simply provide implementations of the above methods returning the desired representation of the resource for a GET, creating a new customer for a POST and updating an existing customer for a PUT. In general, the representation that is returned depends on content negotiation via the Accept headers.

Select Customer

There are three forms. The first one is the Select Customer form. This form allows you to search for a specific customer. It uses the first GET method from the table above, and populates a drop down with the list of customers returned according to the search criteria. This is done using a rule. Edit the form, click on the Rules tab and open the Get Customer List rule.

if (S.value.length > 0) { 
eval('x=' + http.get('http://<hostname>/customers/?pattern=' + S.value));
C.options = x.customers; 
ID.options = x.ids; 
} 

This rule populates the dropdown Customers based on the list of customers returned by the GET method that is invoked by the rule. When a rule invokes http.get(), it also sets the Accept header in the request to 'application/json'. This causes the implementation to provide the JSON representation of the customer list. In this example, we return two JSON arrays: an array of names and an array of IDs. These arrays are used to populate the two dropdowns in the example - the Customer Names dropdown and the hidden Customer IDs dropdown. Try typing a search string (e.g. A). This will return the list of customers whose names start with A. Select a customer from the list. The second rule in this form ensures that the hidden Customer ID field is in sync with the selected customer.

The Form action for this form is set to the URI template: http://<hostname>/frevvo/web/user/gallery/app/_73zHwep_EduZgK0BUzi1Ug/formtype/__AKE4PgqEdusGKt5_HoCDw?_method=POST&customer={ID}. As described in the [[#Multi_page_forms|Multi Page Forms]] section above, when the user clicks submit, the URI template above will be resolved based on the selected customer ID and the browser will be redirected to the resulting URI, which is simply that of the next form with a query parameter (customer=02, for example). This form is described below.

Customer Information

This form is described in the [[#Updating_a_document|Updating a document]] section above. It GETs the XML representation for a specific customer using the third method in the table above, initializes the form with that information and displays it to the user. When submitted, the updated customer information is automaticlly PUT to the same [resolved] URI using the fourth method in the table above.

Create Customer

This form is described in the [[#Creating_a_new_document|Creating a new document]] section above. When instantiated, it does a POST to the Read URI using the second method in the table above. This causes the server to create a new customer and return the URI of that customer. Live Forms will automatically follow this URI, GET the representation of the customer and display the form (presumably with empty values). When the user enters all required fields and submits the form, Live Forms will automatically PUT the resulting XML document to the URI for the newly created customer thereby updating the customer.

In this manner, the combination of URI templates, read/write methods and form parameters provides a very powerful and flexible way to interact with the web.

You can find further discussion of this example on the Live Forms blog. The relevant articles are: [http://www.frevvo.com/blog/?p=26 Part 1] and [http://www.frevvo.com/blog/?p=32 Part 2]. Other articles that may be of interest are [http://www.frevvo.com/blog/?p=23 How do I use my brand new WOA?] and [http://www.frevvo.com/blog/?p=35 Ajax+REST: the next killer app?].

PaperVision® / ImageSilo® Connector

Live Forms supports direct connectivity with Digitech Systems' PaperVision® and ImageSilo® document management products. This Connector allows you to save submissions to the PaperVision® and ImageSilo® document management repository as PDF, TIFF, .JPG and .GIF format.

Installation Instructions

If you are using Live Forms Online there is nothing to install. If you are using Live Forms In-house:

1. copy <frevvo install dir>\frevvo\ext\connectors\pve.war to <frevvo install dir>\frevvo\tomcat\webapps
2. If your are sending your form submissions to ImageSilo https://login.imagesilo.com then the connector requires no further configuration
3. If you are submitting to a local installation of PaperVision then edit the connector's web.xml to configure the local URL path. Replace login.imagesilo.com with the host:port of your PaperVison installation.

Edit <frevvo installdir>/frevvo/webapps/pve/WEB-INF/web.xml

<context-param>         
        <param-name>frevvo.pve.login.url</param-name> <param-value>https://login.imagesilo.com/HTTPInterface.asp</param-value> </context-param>

In your browser, go to: http://<server-name>[:port]/pve/test. You should see a message "Your PVE Connector request was successfully handled." This means the connector is properly installed.

Live Forms V4

A Doc Action Wizard steps you thru the process of connecting your form to PaperVision.

1. Enter your PaperVision/ImageSilo entity, username and password and click the login button
2. The wizard connects to your account and now displays a dropdown with all your PaperVision/ImageSilo projects
3. Select the project where you want to save the form submission
4. Select the image type: PDF, TIFF, JPG, or PNG. # Select if you want to store the xml data document in addition to the form image document
5. Click Next

For Live Forms In-house users, if the TIFF option doesn't appear you have not yet installed the TIFF software into your Live Forms installation.

1. The wizard connects to your selected project and retrieves the list of key index fields from PaperVision/ImageSilo
2. Map each PaperVision/ImageSilo key index field to a field on your Live Forms form. The dropdown contains a list of all the form fields listed by field name (not field label).
3. Click Finish

Your form is now connected to PaperVision/ImageSilo. When you use your form and click the submit button the form image, any attachments and the xml document (if you selected that in the doc action wizard) will be saved into your PaperVision/ImageSilo project.

Google Connector

frevvo Live Forms supports direct connectivity with Google Documents and Spreadsheets. The Google Connector allows you to:

1. Save submissions to Google Spreadsheets
2. Read data from Google Spreadsheets
3. Update data in a Google Spreadsheet (v4.1.5)
4. Store form submissions directly into your Google Apps account.
5. Format emails or confirmation receipts using an online Google Document; and store form submissions directly into your Google Apps account.

See [[V4 Connecting to Google | Connecting to Google]] for details.

Integrating with your database 

Live Forms provides a simple connector that integrates forms with your database. The connector is freely available for download and is licensed under an open source model. The documentation can be found at [[V4_Database_Connector|Connecting with your database]].

Integrating with HTTP Servers (including handling attachments)

Live Forms can POST form or workflow data to your web server for processing. There are two options available [[V4_Designing_Forms#Post_Data_then_Forward_to_Web_Page | Form Action POST]] and [[V4_Designing_Forms#Post_Data | Doc Action POST]]. The difference between the two is that the Form Action POST displays the response from the web server to the user whereas the Doc Action POST does not.

Processing form data POSTed to your web server is [[Process_Submissions_Tutorial#POST_to_your_web_server | detailed in this Tutorial]].

Initializing forms with XML documents

Forms can be initialized by an XML document. This is most commonly done when the form is created from an XSD data source but can also be used with forms create from Live Forms's palette controls. The most common method is to connect the XML document to the form via the form's doc action manually set [[V4_Designing_Forms#Doc_URI_Wizards | document URIs wizard]].

XML document from Doc URI

The form designer ensure the XML document used to initialize the form conforms is valid for the XSD schema used to create the form. If the XML document is invalid your form will fail to initialize and will display the message "There were problems initializing form".

One example of an invalid XML document is when the XSD contains a repeating element. If minOccurs=3 and the XML document contains only 2 elements then the document is invalid and your form will display the standard error message.

XML document from Post payload

In addition chaining multipe forms together via the Form Action Post with common data sources from XSD as described above, it is also possible to write a servlet or other web code that does a Post request with a form Url to the Live Forms Form Server. This request can also be coded to contain an XML document. If the XML document conforms to and is in the same namespace as one of the form's documents (either from-scratch palette controls or from XSD schema datasource), then the Form Server will use that XML document to initialize the form's fields.

Custom JavaScript

It is possible to associate a custom JavaScript handler to any form control. You can provide this JavaScript as part of a custom theme in a file called custom.js. If it is present, this file will be automatically loaded for any form that uses the theme in question and all JavaScript handlers in the file will be available to the form.  The custom.js file for forms will contain JavaScript code that looks something like:

var CustomEventHandlers = {    
    setup: function (el) {      
        if (CustomView.hasClass(el, 's-submit'))        
            FEvent.observe(el, 'click', this.submitClicked.bindAsObserver(this,el));
        else if (CustomView.hasClass(el, 'my-class'))        
            FEvent.observe(el, 'change', this.myHandler.bindAsObserver(this,el));    
    },    
    submitClicked: function (evt, el) {      
        alert ('Submit button was clicked');    
    },    
    myHandler: function (evt, el) {      
        alert ('My Class change handler called');    
    },    
    onSaveSuccess: function (submissionId) {       
        alert ("Save complete. New submission id is: " + submissionId);    
    },    
    onSaveFailure: function () {       
        alert ("Save failed");    
    } 
}

Let's look in a little more detail

1. You must have a class called CustomEventHandlers declared. Note that it is case-sensitive.
2. It must have a method called setup() which takes a single argument (called el above). When the form is loaded, Live Forms will call this setup() method for each control in the form and will pass in the control as the argument.
3. For each control we are interested in, the CustomEventHandlers class has a handler method. All handlers are functions that take two arguments: the event that triggered the handler and the control itself.
4. The example above uses a custom CSS class on the control in question to figure out if it's the control we are interested in. You can [[V4_Designing_Forms#CSS_Class | set a custom CSS class for any control]] in the Form Designer.
5. We're interested in two controls: the Submit button which already has a CSS class s-submit and a user-defined input control with custom CSS class my-class. For each control, we've associated a handler as described above. To associate a handler, call FEvent.observe (el, EVENT_NAME, handler) using the syntax above. The EVENT_NAME can be any standard event fired by your browser e.g. click (also called onClick) or change (also called onChange).
6. When the event is question is fired by the control in question, your handler will be called.
7. In addition to the event handlers, you can also provide methods that are called when the form is Saved using [[V4_Using_Forms#Save.2FLoad | the Save/Load feature]].
8. The onSaveSuccess() method is called when a submission is saved and the resulting submission ID is passed in.
9. The onSaveFailure() method is called when the save fails.

What can you do in a handler

You can call any JavaScript code in a handler; you can access the DOM of the page (note that you only have access to the DOM of the iframe in which the Live Forms form is rendered assuming you're using a standard embedding) or call external code. In addition, you have access to the following methods:

1. CustomView.$frevvoControl(el) returns the HTML element corresponding to the Live Forms control that triggered the handler. This is typically a DIV HTML element and typically has CSS class 'f-control'
2. CustomView.getState (el) returns the state of the control as a JavaScript object. The state contains things like the label, value, hint, help etc. Use a tool such as Firebug or a different JavaScript debugger to view it in detail.
3. CustomView.getExtId (el) returns [[V4_Designing_Forms#Name | the name of the control]] as set in the Form Designer.
4. CustomView.getIndex (el) returns the index of the control in its enclosing repeat control if the control is repeating. If the control is not repeating, it returns -1.
5. CustomView.hasClass (el, className) returns true if the control has the indicated CSS class, false otherwise.

More Examples

You can add different event handling to your JavaScript code. This example handles click, mouseover and mouseout events to the Submit button:

 /*  
  * Custom Javascript here.  
  */   
   var CustomEventHandlers = {     
    setup: function (el) {       
        if (CustomView.hasClass(el, 's-submit'))       
        {  
            alert('setting up s-submit events');         
            FEvent.observe(el, 'click', this.submitClicked.bindAsObserver(this,el));         
            FEvent.observe(el, 'mouseover', this.submitMouseOver.bindAsObserver(this,el));         
            FEvent.observe(el, 'mouseout', this.submitMouseOut.bindAsObserver(this,el));       
        }     
    },     
    submitClicked: function (evt, el) {       
        alert ('Submit button was clicked');     
    },     
    submitMouseOver: function (event, element) {       
        alert ('Submit mouse over');     
    },     
    submitMouseOut: function (event, element) {       
        alert ('Submit mouse out');     
    } 
}

Extensions for flows

In addition to the above, flows also support a few other methods.

var CustomFlowEventHandlers = {     
    onNextClicked: function (name, id) {       
        alert ("Next button clicked for activity: " + name);     
    },     
    onNavClicked: function (name, id) {       
        alert ("Nav button clicked for activity: " + name);     
    },     
    onSaveSuccess: function (submissionId) {       
        alert ("Save complete. New submission id is: " + submissionId);     
    },     
    onSaveFailure: function () {       
        alert ("Save failed");     
    }   
}

 As the method names indicate

1. onNextClicked() is called when the Continue button is clicked: this button might be labeled Continue or Finish or might have a custom label assigned by you. The parameters are the name and id of the current activity (step) in the flow.
2. onNavClicked() is called when the user clicks on a link in the Navigation toolbar if it is displayed. The parameters are the name and id of the activity (step) in the flow that is clicked.
3. Finally, onSaveSuccess() and onSaveFailure() for flows must be defined in the CustomFlowEventHandlers class.

It's not currently possible to directly fire a custom.js handler from a business rule. You can write a form.load rule that sets the value of a hidden control and set a change handler for that control in your custom.js Custom Handlers.