JSurveyLib: Configuration Guide
Written for version 8.01.29
The purpose of this guide is to give you in-depth details about making JSurveyLib configuration files. This guide builds off of the Getting Started guide so you should read that first.
Besides the <?xml version="1.0" encoding="UTF-8"?> tag that appears at the top of most XML files, the surveyConfig is the first that appears on every survey configuration file. This tag has one required attribute named title. The value of this attribute will be displayed at the top of the SurveyPanel.
It is highly recommended that you also add the attributes that specify the survey's XSD to the surveyConfig tag. This is how it should look:
<?xml version="1.0" encoding="UTF-8"?> <surveyConfig title="My Title" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://jsurveylib.sourceforge.net/survey-8.01.29.xsd">
The surveyConfig tag has an optional attribute named saveToFileOnFinish. This attribute defaults to false. If set to true, the survey will require the user to save the survey results to a file when he clicks the "Finish" button. If the survey has already been saved to a file or opened from a file and no changes have been made since, clicking the button will save the file to that location then notify all SurveyListeners. If changes have been made, it will pop up a notification saying that the survey has unsaved changes and give you an OK/Cancel option to save to the same location. Canceling will close the notification, but the survey will remain open. If the file has not been saved/opened from a file, the same notification will appear but it will force you to save to a new location. In all cases, you can retrieve the path to this saved file in String form by calling Survey#getWorkingFilePath() later.
The surveyConfig tag has 5 optional DEPRECATED attributes that change the name of the static text that appears in the survey. These are nextString, previousString, finishString, pageString and ofString. These set the text of the "Next", "Previous", and "Finish" buttons and the text of "Page" and "of" in the phrase "Page 1 of 2". These attributes are DEPRECATED. Please use the strings tag instead.
The strings tag is used to internationalize the survey. The strings has many attributes that can be used to replace the default static text of the survey. Every attribute is optional. nextString, previousString and finishString are used to name the survey's buttons. pageString and ofString can be used to replace the label "Page x of n" on the survey panel. browseString is used to name the browse button for the fileChooser question type. fileString and viewString are used to name the menus. openString, saveString and saveAsString name the menu items in the File menu. firstPageString, previousPageString, nextPageString and lastPageStrings name the menu items in the View menu. When saveToFileOnFinish is set to true, the title of the dialog it brings up is specified by the unsavedChangesString attribute. The message of the dialog can be modify by setting the saveToWorkingFileNotificationString and saveToNewFileNotificationString attributes.
The menu tag is used to configure JSurveyLib's menu. The tag and all of its children are optional. To add the menu to your survey, you need to call this line on your JFrame:
frame.setJMenuBar(new SurveyMenu(survey, frame));
If you don't have a menu configured, this line will have no effect. Here is an example survey configuration with every possible menu item:
<menu> <open/> <save/> <saveAs/> <firstPage/> <previousPage/> <nextPage/> <lastPage/> </menu>
These tags will now be described in detail.
The open tag adds the "Open" menu item to the "File" menu. When you select this, a file chooser will appear and ask you to open some previous answers to this survey. The file the user chooe will be returned if you call Survey#getWorkingFilePath() after. The significance of this is that all further changes will be saved to this file when the "Save" menu item is selected or saveToFileOnFinish is true and the user clicks the "Finish" button.
The save tag adds the "Save" menu item to the "File" menu. If you select this and there is no current working file, it will ask you to save to a new one. If there is a new file, it will automatically overwrite that file. The file the user chose will be returned if you call Survey#getWorkingFilePath() after. The significance of this is that all further changes will be saved to this file when the "Save" menu item is selected or saveToFileOnFinish is true and the user clicks the "Finish" button.
The saveAs tag adds the "Save As" menu item to the "File" menu. When the user selects this menu item, he or she will be asked to save the survey to a file. The file the user chose will be returned if you call Survey#getWorkingFilePath() after. The significance of this is that all further changes will be saved to this file when the "Save" menu item is selected or saveToFileOnFinish is true and the user clicks the "Finish" button.
The firstPage tag adds the "First Page" menu item to the "View" menu. When the user selects this, he or she will be taken to the first page of the survey. This menu item is disabled if the user is already on the first page.
The previousPage tag adds the "Previous Page" menu item to the "View" menu. When the user selects this, he or she will be taken to the previous page of the survey. This menu item is disabled if the user is already on the first page.
The nextPage tag adds the "Next Page" menu item to the "View" menu. When the user selects this, he or she will be taken to the next page of the survey. This menu item is disabled if the user is unable to go to the next page. The details of this can be complex. Please read the Scripting Guide's section "setVisible, setEnabled and setValid" for a detailed discussion on this.
The lastPage tag adds the "Last Page" menu item to the "View" menu. When the user selects this, he or she will be taken to the last page of the survey that it is possible to go to. Basically, this menu item has the effect of clicking the "Next" button until it becomes disabled, for whatever reason (IE: you hit the last page, you hit a page with an unanswered, required question). This menu item is disabled when the user is unable to go to the next page. The details of this can be complex. Please read the Scripting Guide's section "setVisible, setEnabled and setValid" for a detailed discussion on this.
The page tag has an attribute named label and isSkipped.
label will be displayed at the top of the page when it exists and is optional.
isSkipped takes a boolean value. If set to "true", the page will not be reachable. For example, if the second page is skipped, clicking the next button on the first page will take you to the third page. Skipped pages are ignored when considering whether or not a survey is finished. For example, if a skipped page has an unanswered mandatory question or an invalid answer, you can still finish the survey. There must be at least one non-skipped page in the survey. The survey will start on the first non-skipped page. The default value of isSkipped is "false".
The label tag can appear in two places in the survey configuration file. It can appear anywhere inside the page tag and at the top inside the question tag.
When the label tag is defined in the page tag, it gets displayed relative to where it is defined. For example, if you define a label at the top of a page, it will display at the top of that page. If you put it between two questions, it will appear between those two questions.
When the label tag is defined under the question tag it gets displayed next to the question. Exactly where it is displayed depends on the question or it may actually be configurable for the question. This label text will show up in the answer xml file you output if you call Survey.saveXMLAnswers().
You can place anchor tags inside a label tag. Here's an example:
... <label><![CDATA[Please google for JSurveyLib to bring the page-rank up ;) <a href="http://www.google.com/search?q=jsurveylib">Click Me</a>]]></label> ...
This will place a label on the survey with a link on it. If the user clicks this link, it will open up a new browser window to the url specified in href. You can also use anchors to jump to different pages on the survey. Here's an example:
<label><![CDATA[Jump ahead to <a href="page://1">Page 2</a>.]]></label>
The href in this link is unique in that it's prefixed with "page://" and an integer. This integer specifies the page to go to. The index is zero based meaning that the first page you've defined has an index of 0, the second page has an index of 1 and so on. If you click on the words "Page 2" the survey will jump to that page. This will go to page 2 even if the next button is disabled. But, if the user passed over mandatory questions they will not be able to click the finish button until they go back and answer them.
The question tag is where you define attributes and child elements that apply to every question. For example, every question must have an id attribute. This attribute identifies every question on the survey and it must be unique. It requires a name that is a valid Java variable: The first character must be a letter or an underscore, the following characters must be a letter, underscore or number. You are forbidden from using the word "ENVIRONMENT" as an id. This word is reserved for internal usage in scripts. You can read all about scripts in the "Scripting Guide".
Another commonly used tag is the mandatory tag. This tag can either have a value of "true" or "false". If it's true, this question must be finished before you can go to the next page of the survey or hit the finish button. There are some exceptions to this rule: Mandatory questions do not need to be answered if they are invisible or disabled. The mandatory attribute is ignored for the checkbox question.
The question tag also a default attribute. Every time the survey starts, this question will take the value of the default attribute. Using the Survey#loadXMLAnswers will overwrite the default value.
Every question represents its value with a String called the "answer string". You can set this with the Survey#loadXMLAnswers() and the question tag's default attribute. You can get this String with Survey#getAnswer(), Survey#saveXMLAnswers() and Survey#getAnswerMap().
A "question type" must be defined for every question in the configuration. The "question type" tag identifies the question as a Checkbox, or a Text Field or any other possible question. Every question type has its own tag with its own attributes and child elements.
The following sections will describe the attributes, child elements, and valid values of the answer string of each question type.
The checkbox tag has one attribute named boxOnRight. If set to "true", the checkbox will appear on the right of the label. If set to "false", the checkbox will appear on the left side. This attribute defaults to "true".
The checkbox answer string is set to "checked" when it's checked and "unchecked" when it's unchecked.
The textField tag creates a one row text field. It has no attributes.
You can set its answer string to any value and it will return this same value.
The textArea tag creates a multi-row text field that will scroll if necessary. It has one attribute named rows that takes an integer as a value. This attribute specifies the number of rows that the textArea has. The default value is 5. This attribute is not mandatory.
You can set its answer string to any value and it will return this same value.
The yesNo tag creates a specific form of the radioButtons tag (to be explained later) that has two choices: "Yes" and "No". These choices are always displayed horizontally. This tag has no attributes.
Its answer string can be set to "yes" and "no" and these values will return "yes" and "no", respectively.
The fileChooser tag creates a question that lets you choose a file on the local file system. The fileChooser tag has no required attributes or child elements.
The chooserMode attribute has two possible values: "open" or "save". If "open" is used, the chooser uses an open dialog box to pick files. If "save" is used, the chooser uses a save dialog box to pick files. If you choose an already existing file with the save dialog box, the chooser will ask you if you want to overwrite the file. The default value for chooserMode is "open".
The openTo attribute takes a path to a directory. The file chooser will always open to this directory when the user clicks on the "Browse" button. This attribute is optional. If it is omitted, the user will start in the directory of the last file he selected with a JSurveyLib file chooser.
The fileChooser tag has an enableAllFilesFilter attribute that can be either be set to "true" or "false". The All Files filter allows you to pick any kind of file on the local file system. If you want to restrict the user to picking specific kinds of files you should set this to "false". It defaults to "true".
The fileChooser tag has one child element named fileFilter. This child element can be repeated any number of times and has two required attributes named description and extension. Each fileFilter elements defines a file filter that can be used to restrict the types of choose-able files. For example, defining the tag like this:
<fileFilter description="JPG Files" extension="jpg"/>
will define a filter with the name, "JPG Files" that, when selected, will only allow the user to see files that end in ".jpg" (case-insensitive [at least on Windows, not tested on *nix]). It is possible to define one filter that allows multiple files to be selected. Here is an example of that:
<fileFilter description="Image Files" extension="jpg,png,gif"/>
When this filter is selected, you will be able to choose JPG, PNG and GIF files. Notice that there is no space in the extension attribute. These attributes have no default value and must be defined.
The fileChooser answer string can be set to any value and it will return the value it was set to. When you choose a file via the GUI, the answer string will be set to the absolute path of that file in the format of the OS.
The radioButtons tag allows you to provide many options to the user but restricts them to selecting one. The radioButtons tag has three attributes, none of which are required.
The leftLabel and rightLabel attributes take a string value. This string value will be displayed on the left and right side of the radio buttons, respectively. They default to "".
The alignment attribute takes one of two values: "horizontal" and "vertical". This attribute picks the orientation of the radio buttons on the GUI. This attribute defaults to "horizontal".
The radioButtons tag has a child element named choice. You must specify at least two of these tags. The choice tag has two required attributes named id and label. The id attribute is used as an identifier for the answer string. The label attribute is what you see on the GUI for the choice. The id attribute must be unique between choices in a radioButtons tag.
The radioButtons answer string must be set to a choice's id attribute. This question (without a default) will start with an answer string of "" but it is illegal to set it to that value unless there is a choice with a "" id. If the radioButtons tag does have a choice with an id of "", this choice will be selected when the survey starts. When you get the answer string, it will return "" if the question is unanswered, otherwise it will return the id of the choice that was been selected.
The dropdown tag creates a dropdown question. A dropdown can have multiple answers but only one can be selected at a time.
The dropdown tag has one child element named choice that has two mandatory attributes: id and label. The id is what the dropdown uses internally to represent its answer. The label is what the user sees on the UI as options to choose from. The choice elements must be unique by id. When a dropdown is mandatory, it is considered unanswered if a choice with an id of "" is selected.
When a user selects a choice on the UI, the answer string of the question becomes the id of the choice. You must set the answer string to one of the dropdown's id attribute.
The template tag allows you to reuse the structure of a question over and over again in your configuration. For example, consider a radioButtons question with two options: "always" and "never". If your survey needs to use this question many times, there are two ways you can write the config file:
... <question id="first"> <label>Do you smoke more than one pack of cigarettes a day:</label> <radioButtons alignment="vertical" leftlabel="left" rightlabel="right"> <choice id="always" label="always"/> <choice id="never" label="never"/> </radioButtons> </question> <question id="second"> <label>Do you exercise more than 30 minutes a day:</label> <radioButtons alignment="vertical" leftlabel="left" rightlabel="right"> <choice id="always" label="always"/> <choice id="never" label="never"/> </radioButtons> </question> <question id="third"> <label>Do you go to fast food restaurants more than once a week:</label> <radioButtons alignment="vertical" leftlabel="left" rightlabel="right"> <choice id="always" label="always"/> <choice id="never" label="never"/> </radioButtons> </question> ...
... <question id="first"> <label>Do you smoke more than one pack of cigarettes a day:</label> <template name="alwaysNever"/> </question> <question id="second"> <label>Do you exercise more than 30 minutes a day:</label> <template name="alwaysNever"/> </question> <question id="third"> <label>Do you go to fast food restaurants more than once a week:</label> <template name="alwaysNever"/> </question> ...
The second configuration is much smaller and easier to read. Later, you may decide to add a third option named "sometimes". You only need to modify one part of the configuration file when you use a template. But, you must make this change three times to the first example. If you use this question structure hundreds of times, this can become an error-prone process.
With these examples we have shown how to use a template but not how to define one. Here is an example of two template definitions in one file:
<?xml version="1.0" encoding="UTF-8"?> <surveyConfig title="Template Usage" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://jsurveylib.sourceforge.net/survey-8.01.29.xsd"> <templates> <template name="alwaysNever"> <radioButtons> <choice id="always" label="always"/> <choice id="never" label="never"/> </radioButtons> </template> <template name="imageChooser"> <fileChooser> <fileFilter description="JPG Files" extension="jpg"/> <fileFilter description="GIF Files" extension="gif"/> </fileChooser> </template> </templates> <page> ...
Pay careful attention to the position of the templates tag: You define templates immediately after the surveyConfig tag and before the first page tag. Each template tag must be defined inside a templates tag. Each template tag requires a name attribute. This attribute must be unique between template tags.
Inside the template tag you define the question structure. This question structure is no different from the structure you'd use inside the question tag to define the specific attributes/elements of your question type. All the set/get rules of the answer string apply to the specific question type used.
This concludes the JSurveyLib Configuration Guide. For support and bug reports, please post a message in the JSurveyLib forum or tracker.