Screenshots •  Videos •  Demos •  Documentation •  Tutorials •  Articles •  Knowledge Base •  Zone


Sample survey application

This description shows how to build an simple survey application and highlights some of the common features of the survey support that may be useful. The example makes use of the templates system and the default rules engine included in Carousel.

Project's startup properties

The survey application requires some additional configuration that needs to be set up in project's startup.properties file. The example of the survey specific part of the file is shown below.

 
 
Listing 1 - project's startup.properties file
 
 
 
SurveysDir=surveys/
DefaultSurveyFile=hotelsurvey.xml
DefaultResponsesFile=responses.xml
SavePath=responses/
MultipleChoiceTemplate=checkboxTemplate.xml
MutuallyExclusiveTemplate=radiobuttonTemplate.xml
FreeTextTemplate=textfieldTemplate.xml
QuestionPerPage=5
XRulesEngine=com.xoetrope.survey.DefaultRulesEngine
LifeCycleListener=com.xoetrope.survey.SurveyManager
 
 

The SurveysDir specifies the directory from which survey files will be read, the DefaultSurveyFile specifies a survey file which will be opened by default, the DefaultResponsesFile is a file where the answers given by the user will be saved by default, the SavePath is a path where the files containing user's answers will be stored. The MutlipleChoiceTemplate, MutuallyExclusiveTemplate and the FreeTextTemplate point to files defining the templates for three supported types of questions. The number of questions that can be shown in single page of an application is defined by the QuestionPerPage parameter. The XRulesEngine points to a rules engine that should be used. The LifeCycleParameter has to point to "com.xetrope.survey.SurveyManager" class in order to read and setup the survey configuration.

Question Pages and Templates

A very simple question page that makes use of the template system can be defined as follows:

 
 
Listing 2 - question page
 
 
 
<XPage question_page="questionPage" 
  finish_page="ThankYou" 
  class="com.xoetrope.swing.survey.XQuestionPage">
	
  <Components>
    <Panel layout="Box" x="0" y="20" w="800" h="440" 
      style="Question" layoutStyle="1">
		
      <Repeat while="${hasMoreQuestions()}">   
        <Include execute="${getNextQuestion()}"
          file="${getCurrentQuestionTemplate()}"/>
					
      </Repeat>
    </Panel>
  </Components>
	
</XPage>
 
 

The question_page attribute of the <XPage> element specifies the next question page that should be shown (in most cases this will be same page as the current one). The finish_page is a page that will be shown when the survey is over. The com.xoetrope.swing.survey.XQuestionPage class, associated with the page, serves as a main "entry point" to the survey API. As the page xml is parsed the methods: hasMoreQuestions(...), getNextQuestion(..), getCurrentQuestionTemplate(..) are invoked which results in including the templates for successive questions belonging to the current question group. The getCurrentQuestionTemplateMethod(...) returns the name of the file (template) for the current question type. Each template contains a xml defining how the questions of certain type should appear on the page. The listing below shows a sample template associated with the "mutually exclusive" type of question.

 
 
Listing 3 - question template
 
 
 
<XPage>
  <Components>
    <Panel layout="Border" w="800" h="120" 
      constraint="center" opaque="false" border="0">
		
      <Panel constraint="north" w="800" h="60" 
        opaque="true" style="Question/Header">        
        <Label name="qtext" x="20" w="400" h="20" 
          content="${getCurrentQuestion()}" 
            constraint="CENTER" antialias="true" opaque="false"/>
      </Panel>
			
      <Panel layout="Flow" layoutStyle="0" 
        constraint="CENTER" w="800" h="100" opaque="false">
				
        <Layout vgap="15" hgap="8"/>
        <Repeat while="${hasMoreOptions()}">
          <Include file="radiobutton"/>					
        </Repeat>
      </Panel>
			
    </Panel>
  </Components>
</XPage>
 
 

The template from the listing above "iterates" over the options of the current question taking advantage of the API provided by the XQuestionPage class. Each "iteration" includes a radioButton template, shown in the listing below, as the current question type is a "mutually exclusive".

 
 
Listing 4 - radiobutton template
 
 
 
<XPage>
  <Components>
    <RadioButton w="100" h="20" qid="${getCurrentQuestionId()}" 
      content="${getNextOption()}" name="${getCurrentOptionName()}" 
      opaque="false"/>	  
  </Components>
	
  <Data>
    <Bind target="${getCurrentOptionName()}" 
      source="${getExclusiveOptionModelPath()}" 
      output="${getExclusiveOptionModelPath()}" reeval="false"/>
  </Data>
	
  <Events>
    <Event method="handleMouse" 
      target="${getCurrentOptionName()}" type="MouseHandler"/>
  </Events>	
</XPage>
 
 

The template from the listing above includes the actual "radioButton" component to the page, sets up the required bindings and events in order to save the answers given by the user. Each method being used by the template is defined in the XQuestionPage class so there is no user's code needed.

The survey API provides a various methods to navigate through the survey (i.e. showing the next page, changing the current question group, etc.) via the XQuestionPage class. The listing below shows a very simple "navigation page" that can be included as a "footer" in a survey application. It defines two buttons "previous" and "next" allowing to display previous or next question pages respectively.

 
 
Listing 4 - radiobutton template
 
 
 
<XPage class="com.xoetrope.swing.survey.XQuestionPage">
  <Components>
    <Image name="prevButton" imageName="prev.gif"/>
    <Label content="previous page" w="100" h="24" antialias="true"/>
    <Image name="nextButton" w="25" h="24" imageName="next.gif"/>
    <Label content="next page" w="100" h="24" antialias="true"/>
  </Components>
  <Events>
    <Event method="prevPage" target="prevButton" type="MouseHandler"/>
    <Event method="nextPage" target="nextButton" type="MouseHandler"/>
  </Events>
</XPage>
 
 

The screenshot below shows a simple application built with the templates described above (and no user's code).

 
 
 Sample question page
 
 

 
 

So far there was no user's code involved in building the application, however if some more sophisticated survey processing or navigation is required the user can easily add it by subclassing the XQuestionPage class.