Survey Portlet

Quickstart Guide

This Quickstart Guide assumes its' reader has a basic level of competence with the Liferay portal. As such it will not cover Liferay management topics such as how to create pages or add or remove portlet applications to a page.

Installation

The My Survey portlet comes in the form of a Web Application Archive. It may be installed by copying to the <liferay-install-path>/deploy folder or via Control Panel > Plugins Installation > Install More Portlets > Upload File.

Creating your first Survey definition

  1. Add the My Survey portlet application to an empty page (it can be found under the MyOffice24x7 category).
  2. Click the "Preferences" icon ().
  3. Select the "Definition Management" tab.
  4. Type a name for your new Survey definition in the "New Type" field and click the "Add" button.
  5. In the Text Area which appears paste the following XML and click the "Save" button.
<definition>
<name>Contact Us</name>
<description>Online contact form</description>
<permanentMessage />
<startMessage>
<![CDATA[ <h2> To leave us a message, please click the
<span style='color:orange;font-weight:bolder'>Contact Us</span> button below. </h2> ]]>
</startMessage>
<startFromUploadMessage />
<resumeMessage />
<suspendMessage />
<finalizeMessage />
<completedMessage>
<![CDATA[ <h2>Thank you, your message has been submitted!</h2>]]>
</completedMessage>
<page id='1' name='Page #1'>
<title>Your Enquiry</title>
<field id='1' name='information_type'>
<question>
I am interested in obtaining further information regarding:
</question>
<checkGroupAnswerType>
<orientation>
<vertical />
</orientation>
<optionList>
<option>Products</option>
<option>Consultancy</option>
<option>Technical Support</option>
<option>Other</option>
</optionList>
<errorText>Please select at least one option</errorText>
</checkGroupAnswerType>
</field>
<field id='2' name='information_other'>
<validation>
<depends fieldName='information_type'>
<contains>Other</contains>
</depends>
</validation>
<question>
<![CDATA[If 'Other', what would you like to know about:]]>
</question>
<multiLineAnswerType>
<width>80</width>
<height>6</height>
<minimumLength>1</minimumLength>
<errorText> Please specify detailed information </errorText>
</multiLineAnswerType>
</field>
</page>
<page id='2' name='FINAL PAGE'>
<title>Your Contact Details</title>
<field id='1' name='firstname'>
<question />
<singleLineAnswerType>
<prefix width='150'>First Name:</prefix>
<width>20</width>
<minimumLength>1</minimumLength>
<errorText>First name is required</errorText>
</singleLineAnswerType>
</field>
<field id='2' name='lastname'>
<question />
<singleLineAnswerType>
<prefix width='150'>Last Name:</prefix>
<width>30</width>
<minimumLength>1</minimumLength>
<errorText>Last name is required</errorText>
</singleLineAnswerType>
</field>
<field id='3' name='orgname'>
<question />
<singleLineAnswerType>
<prefix width='150'>Organisation Name:</prefix>
<width>40</width>
<minimumLength>0</minimumLength>
<errorText />
</singleLineAnswerType>
</field>
<field id='4' name='website'>
<question />
<singleLineAnswerType>
<prefix width='150'>Organisation Website:</prefix>
<width>60</width>
<minimumLength>0</minimumLength>
<errorText />
</singleLineAnswerType>
</field>
<field id='5' name='country'>
<question />
<singleLineAnswerType>
<prefix width='150'>Country:</prefix>
<width>30</width>
<minimumLength>0</minimumLength>
<errorText />
</singleLineAnswerType>
<tool>
<dictionary dictionaryId='countries'>
<title>Select Country</title>
</dictionary>
</tool>
</field>
<field id='6' name='state'>
<question />
<singleLineAnswerType>
<prefix width='150'>State:</prefix>
<width>20</width>
<minimumLength>0</minimumLength>
<errorText />
</singleLineAnswerType>
<tool>
<dictionary dictionaryId='aus-states'>
<title>Australian States</title>
</dictionary>
</tool>
</field>
<field id='7' name='contact_by'>
<markupOnChange />
<question> I would like to be contacted by: </question>
<checkGroupAnswerType>
<orientation>
<horizontal />
</orientation>
<optionList>
<option>Phone</option>
<option>Email</option>
</optionList>
<errorText>Please select contact option</errorText>
</checkGroupAnswerType>
</field>
<field id='8' name='contact_phone'>
<validation>
<depends fieldName='contact_by'>
<contains>Phone</contains>
</depends>
</validation>
<question />
<singleLineAnswerType>
<prefix width='100'>Phone Number:</prefix>
<width>20</width>
<minimumLength>10</minimumLength>
<errorText>
Please specify contact phone number, including extension
</errorText>
<regex>
<expression>^([0-9\(\)\/\+ \-]*)$</expression>
<errorText>Phone number contains invalid characters</errorText>
</regex>
</singleLineAnswerType>
</field>
<field id='9' name='contact_email'>
<validation>
<depends fieldName='contact_by'>
<contains>Email</contains>
</depends>
</validation>
<question />
<singleLineAnswerType>
<prefix width='100'>Email Address:</prefix>
<width>40</width>
<minimumLength>10</minimumLength>
<errorText>Please specify contact email address</errorText>
<regex>
<expression>^([A-Za-z0-9\-\.\_]*@[A-Za-z0-9\-\.\_]*)$</expression>
<errorText>Email address is not valid</errorText>
</regex>
</singleLineAnswerType>
</field>
</page>
</definition>

Congratulations, you just created the definition for a "Contact Us" style Survey!

Deploying your first Survey instance/campaign

From the Definition Details page where you just created your first definition, click the "Back to List" tab, and then from the "Definition Management" page click the "Instance Management" tab. You should now see a drop down list containing name of the definition you created and labelled "New Campaign using". Press the "Create" button to instantiate a new Survey campaign based on the selected definition.

At this point there is a Survey campaign up and running but it has not yet been bound to any particular My Survey portlet. To bind this Survey campaign to the portlet you added to your blank page, press the "Deploy to Portlet" button. Note that the Survey instance is still listed as being in the ‘Definition' stage. If you were to go and view the portlet right now (via the "Return to Full Page" link in the top right corner), you would see a waring message stating "This application is currently running in TEST mode". To remove this warning message it is necessary to activate the Survey campaign, which can be achieved [unsurprisingly] by clicking the "Activate" button.

Congratulations, at this point you are ready to start collecting contact requests via the My Survey portlet! Have a look at the Survey as rendered by the My Survey portlet by pressing "Return to Full Page" and then the "START" button of your newly configured My Survey portlet (note how the startMessage specified in the above definition is now displayed in the portlet). However the message is wrong – there is no "Contact Us" button, only a "Start" button! We'll correct this later. For now, study the correlation between the XML code specified in the definition above and what you see. Pretty obvious isn't it!

Configuring the My Survey portlet

While looking at the Survey, you'll note that many of the buttons are a bit of overkill for a basic "Contact Us" form. By default, the My Survey portlets are pre-configured for more complex surveys consisting of many tens of pages and hundreds of fields and where more flexible user interaction man be beneficial. Also we have to correct the start button label so it corresponds with the startMessage defined above.

As usual, access the My Survey portlet preferences by clicking the icon. Choose the "Portlet Preferences" tab (4th from the left). You are now presented with a second level of tabs, the currently selected one being "Buttons" tab. This is perfect, as it contains the many of the preferences we wish to change. First, change the Start Button's label to read "Contact Us". Second, hide the buttons "Save Page" and "Next Page" by setting them to ‘False'. Finally, ensure the "Save and Resume Later" button is also hidden – this survey is hardly that long that users may wish to go away and come back later!

There are many more portlet preferences which may be altered – if you wish to know what these do please refer to the "Portlet Preferences" section of the My Survey manual.

Congratulations, your "Contact Us" survey is now ready to be released to the wild!

Collecting Survey Results

The information collected via a My Survey portlet is collated in a CSV format report. This report may be obtained by:

  1. Clicking the "Preferences" icon () on any My Survey portlet.
  2. Choosing the "Instance Management" tab and selecting the Survey Campaign in question from the list.
  3. Clicking the "Generate Report" button followed by opening the "View Report" link which appears when the page is refreshed.

Gotchas

From experience, one of the more challenging concepts for developers to grasp is the fact that the Survey definition, Survey campaign/instance and the My Survey portlet (as deployed on a page) are three distinct entities. A Survey definition may have multiple Survey campaigns/instances active at the one time, each in different stages. Also, multiple My Survey portlets may be bound to the same instance.

Another common gotcha is attemping to use/test a Survey whilst signed in. This sometimes works, sometimes not, when the error message "Portlet is not configured correctly, please contact your administrator" is displayed. Whether this occurs or not depends on the sequence of interactions with Liferay which have been performed prior to attemping to start the Survey. As a consequence, it is recommended that during Survey development the developer have two web browsers open simultaneously (eg. Internet Explorer & Firefox), one in which they are signed in and one where they are not. The former is to be used for updating Survey definitions, the latter used for testing the Survey.