JSurveyLib: Getting Started Guide
Written for version 8.01.29
This guide will give you a quick overview of JSurveyLib. And information presented here may not be repeated in other more in-depth guides. It is recommended you read this first.
You can download the JSurveyLib zip by visiting the home page here: https://sourceforge.net/projects/jsurveylib/
Extract the zip to a folder to your local file system. Change your directory to the folder that has just been extracted.
Windows Users: java -cp "jsurveylib-8.01.29.jar;lib\bsh-2.0b4.jar;lib\junit-4.4.jar;lib\xercesImpl.jar" org.jsurveylib.TestBench surveyGettingStarted.xml
*nix Users: java -cp 'jsurveylib-8.01.29.jar:lib/bsh-2.0b4.jar:lib/junit-4.4.jar:lib/xercesImpl.jar' org.jsurveylib.TestBench surveyGettingStarted.xml
If you see a survey pop up, that means you've followed these steps correctly. Congrats on running your first survey! It should also say, "This is your first Survey!". If a survey pops up and it doesn't say that, it means you typed in the last argument incorrectly. Make sure it says "surveyGettingStarted.xml"
First, lets create our XML file in the same directory as the survey we just ran. Name it mySurvey.xml
Lets edit the XML file so that JSurveyLib can interpret it. Copy and paste this into mySurvey.xml
<?xml version="1.0" encoding="UTF-8"?> <surveyConfig title="My Survey" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://jsurveylib.sourceforge.net/survey-8.01.29.xsd"> <page> <question id="checkbox"> <label>Checkbox:</label> <checkbox/> </question> </page> </surveyConfig>
Save and close the file.
Running this survey is almost the same as running the last one. The only difference is that we must change the name of the XML file.
Windows Users: java -cp "jsurveylib-8.01.29.jar;lib\bsh-2.0b4.jar;lib\junit-4.4.jar;lib\xercesImpl.jar" org.jsurveylib.TestBench mySurvey.xml
*nix Users: java -cp 'jsurveylib-8.01.29.jar:lib/bsh-2.0b4.jar:lib/junit-4.4.jar:lib/xercesImpl.jar' org.jsurveylib.TestBench mySurvey.xml
Your one-page survey should pop up with one question on it labeled, Checkbox:
The first section of the configuration file is this:
<?xml version="1.0" encoding="UTF-8"?> <surveyConfig title="My Survey" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://jsurveylib.sourceforge.net/survey-8.01.29.xsd"> ... </surveyConfig>
The most important thing here is the definition of the XSD: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://jsurveylib.sourceforge.net/survey-8.01.29.xsd"
It is highly recommended (but not required) that you put this on every survey configuration and use a tool that takes advantage of it (provides autocompletion and validation). Writing your own survey will require a lot memorization, otherwise.
<page> ... </page>
Here we have defined our first (and only) page for this survey. All questions must be defined inside a page tag.
<question id="checkbox"> ... </question>
Here we have defined our first (and only) question. You must give every question an id attribute and the id attribute must be unique for the whole survey. This unique restriction is enforced by the XSD (one of the many reasons you should use it).
The question tag is optional. You may want to define a page that acts as an introduction to the survey that has no questions on it.
<label>Checkbox:</label>
Here we have defined a label for this question. This will show up right next to the question in the survey and is printed to the result.xml file after you click the finish button. A label tag is optional.
<checkbox/>
This tag specifies the type of question you are using. We could have changed this to <textField/> and then our survey would have showed a text field instead of a checkbox. A tag that identifies the type of question is required and there are many different identifying tags you can use. Often, these identifying tags have attributes and child elements that are specific to that type of question. For example, you can use the boxOnRight attribute on the checkbox tag to make the checkbox show up on a different side of the question. This will make the checkbox appear on the left side of the label:
<checkbox boxOnRight="false"/>
Up until now, every survey has executed inside a JSurveyLib class called TestBench. It's often more useful to run a survey in your own class. This gives you the ability to add a survey to your already existing application and to have custom behavior when a survey finishes.
This is how you would make your own class that mimics the way TestBench works:
import org.jsurveylib.ClientSurvey; import org.jsurveylib.Survey; import org.jsurveylib.SurveyAdapter; import org.jsurveylib.gui.swing.SurveyPanel; import org.jsurveylib.gui.swing.SurveyMenu; import javax.swing.JFrame; import java.awt.BorderLayout; import java.io.IOException; public class MySurvey extends SurveyAdapter { public MySurvey() { JFrame frame = new JFrame(); frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); try { ClientSurvey survey = new Survey("surveyGettingStarted.xml"); SurveyPanel surveyPanel = new SurveyPanel(survey); survey.addSurveyListener(this); frame.setLayout(new BorderLayout()); frame.add(surveyPanel, BorderLayout.CENTER); frame.setJMenuBar(new SurveyMenu(survey, frame)); } catch (Exception e) { e.printStackTrace(); } frame.pack(); frame.setVisible(true); frame.setExtendedState(JFrame.MAXIMIZED_BOTH); } public void surveyFinished(Survey survey) { try { survey.saveXMLAnswers("result.xml"); } catch (IOException e) { e.printStackTrace(); } System.exit(0); } public static void main(String[] args) { new MySurvey(); } }
Most of this code is related to setting up a JFrame. The points of interest are in bold.
ClientSurvey survey = new Survey("surveyGettingStarted.xml"); SurveyPanel surveyPanel = new SurveyPanel(survey); survey.addSurveyListener(this);
First, we instantiate our survey object by specifying its configuration file. The ClientSurvey interface is useful because it only exposes the methods that are not for internal use. Then we instantiate a SurveyPanel and pass in this survey as parameter. Finally, we tell the survey to notify us when it's finished.
NOTE: the SurveyPanel class has been moved into the package "org.jsurveylib.gui.swing". It used to reside in the "org.jsurveylib.gui" package. A copy of this class was left in "org.jsurveylib.gui" so old classes still compile but it is deprecated and will be removed in the next version.
frame.setLayout(new BorderLayout()); frame.add(surveyPanel, BorderLayout.CENTER);
Here we have placed the surveyPanel object on the frame to make it visible.
frame.setJMenuBar(new SurveyMenu(survey, frame));
Surveys can be configured to have a menu bar. This adds features like the ability to save or open surveys in the middle of taking one and keyboard accelerators for navigating the survey. You can read more about this in the Configuration Guide. If your survey has no menu configured, this line will have no effect.
public void surveyFinished(Survey survey) { try { survey.saveXMLAnswers("result.xml"); } catch (IOException e) { e.printStackTrace(); } System.exit(0); }
This method will be called when the finish button has been clicked on the survey. The main thing we do here is save the answers of the survey into a file named results.xml.
This concludes the Getting Started guide. We encourage you to experiment with the methods in the Survey class to see what else is possible. Please note that the only part of JSurveyLib that you should be using directly are the Survey, ClientSurvey, SurveyPanel and SurveyAdapter classes. Some of the methods in these classes are for internal use only. Read the javadoc to find out which methods you should and should not be using. All other classes of JSurveyLib are for internal use only.