Writing Actions
|
Because ViewsFlash is a Java application, it is naturally extensible. There are two types of extensibility available: Action classes, and Notifications.
Actions (see built-in Actions)
These classes, which extend the base Validator class, allow you to add code to check a response's validity and compute a new field based on the values of other fields. To use these classes, you will need to write some Java code, compile it, and put it in the "classpath" where ViewsFlash can find it. To tie it all together, you add a question of type Action to your poll or survey. In the field right below it, you enter the name of the validation class, such as "Weighted Ranking", followed by a space, followed by the parameters required by the specific validation class.
1. Study the source code for testAction.java - a class designed to familiarize yourself with the common operations possible in an Action class.
You can also study source code provided for other classes in the viewsflash/src directory. Other examples are highlighted below.
2. Compile your code and move the .class file to the .../ViewsFlash/WEB-INF/com/cogix/vwf directory, and restart your application server. For complete instructions, click here.
3. In the questionnaire where you want to use the Action class, add a question of type Action. In the field provided, enter the classname, a space, and the parameters required by the Action class. Usually these include the name(s) of other questions, for example. If ViewsFlash cannot find your class, it will say so when you add this question. Once it finds it, if you change the code in the class, you will need to restart the web server to unload the class from the Java VM.
4. If the class can invalidate entries, be sure to review the options for Incomplete Entries on the Security page.
| Methods inherited from the parent Validator class that can be overridden: |
| boolean onPageComposition (RequestParams reqx, String questionname, String spec) |
This method is called before a survey page is composed and displayed to the person taking the survey. It can refer to any value entered using getParamValue. This method returns true to ask ViewsFlash to display a different survey page instead of the page it was about to display; the designated page is the one that contains the question set in the skipToQuestion method. All Actions on the destination page that have an onPageComposition method will be executed before the page is displayed, and any of them can redirect to another page. If this method returns false, it indicates that it has nothing to say. For an example, see BeforePageComposedGoTo.java |
| boolean onPageReceived (RequestParams reqx, String questionname, String spec) |
This method is called after a survey page is received but before the values entered in it are stored. This method returns true to ask ViewsFlash to act on its conclusions regarding data validity, which are indicated by the methods below. It returns false to tell ViewsFlash that it has nothing to say about the validity of the data in the current page. In either case, this method can modify the data entered using setParameterValue. For an example, see WhenPageReceivedGoTo.java |
| boolean checkValidity (RequestParams reqx, String questionname, String spec) |
| This method is deprecated. It has been replaced by the better-named onPageRecieved method, which has the same functionality. Classes that use this method continue to function as before. |
| String getDefinitionDisplayText (String classname, String args) |
Use this method to override what the survey designer sees in the Design Questions page and Index page for an Action. By default, the Action name and its parameters are displayed. |
| String checkArguments (String classname, String args) |
Use this method to examine the arguments provided to the class and report anything wrong with them in the returned String. If nothing is wrong, return null. If not overridden, this method returns null. |
| Convenience methods in the Validator class: |
| void setRedir (String s) |
| Sets redirection to this URL. Use * for redirection to the referring URL. |
| void setValid (boolean b) |
| Indicates whether the entry should be accepted or rejected as invalid. |
| void setMessage (String m) |
| Sets a message that will be displayed in the [/statusmsg] field of a results page. |
| void setErrorTemplate (String t) |
| Sets this as the path to a file to use as a template to display the invalid condition. Note that this is NOT the name of a style template, but rather the name of a file. |
| void setMissingEntries (String m) |
| Sets this string with the names of fields that are flagged as missing, separated by leading and trailing spaces. |
| void setAction (int nAction) |
|
Indicates what to do after returning true. It also calls setValid()
as described below. Valid values for nAction are: |
| Validator.AcceptAndRedirect means accept the vote and redirect to the URL set by setRedir(). Calls setValid(true). Use with setRedir (String). |
| Validator.ActionRefill means to reject the vote and redisplay the questions with the corresponding settings from the Security page for incomplete entries. Calls setValid (false). Use setMessage (String), setMissingEntries (String). If you don't call setErrorTemplate (String), the standard poll style will be used to redisplay the question; if you do, that page will be used as a template. |
| Validator.ActionRedirect means reject the vote and redirect to the URL set by setRedirect(). Calls setValid (false). Use with setRedir (String). |
| Validator.ActionShowPage means reject the vote and show results using the results page template set by setErrorTemplate(). Calls setValid (false). Use with setMessage (String) also. |
| Validator.ActionAcceptWhatThereIs means accept any data that is present and ignore any missing data. Calls setValid (true); |
| Validator.ActionUseInvalidSettingsonSecurityPage means take the action specified in the Security page. Requires that you call setValid (boolean) explicitly. |
| String getAnswerText (String qname, String answer) |
| Returns the full text of the "answer" to question "qname". Returns null if it can't find it. |
| String getDefaultAnswerValue (String qname) |
| Returns the default value for question "qname". This is the value checked as Default, which when used in Quizzes indicates the "correct" answer. |
| definition getDefinition () |
| Returns the internal definition class for the poll. Advanced use only. Returns null if not found. |
| Poll getPoll () |
| Returns the internal Poll class for the poll. Advanced use only. Returns null if not found. |
| String getParamValue ( RequestParams reqx, String qname ) |
| Returns the value of the answer entered by the visitor in question "qname". Returns null if not found. Returns "" for an empty text field. Returns null for an unchecked check box. Returns "value1,value2,value3" for a multiple check box. |
| boolean isValid () |
| Returns the value set earlier by setValid (boolean), or false if it has never been called. |
| void setParameterValue ( String qname, String value ) |
Will set question "qname" to value "qvalue". The value is available as if it had been included in the query string, and is useful for setting the result of a calculation in a field where it can be stored, tabulated, or analyzed. Note that to analyze such a field, you must define all its possible values; for example, you can set up a hidden field with answers that match the expected values. For an example, see WeightedScore.java |
| void skipToQuestion ( String qname ) |
Use this method to indicate that the next page shown to the person taking a survey should be the page that contains question 'qname'. Be sure to return true. |
| boolean valuesContain ( String valueslist, String value ) |
This method tests to see if 'value' is found in the comma-delimited values in 'valueslist'. This list is in the format returned by getParamValue. Returns true if value is found on the list. Returns false if either argument is null or empty. |
| String substitutePipedParameters ( String m ) |
This method performs question piping on String m. If m contains expressions of the form [/questionname], the current value of that question will be substituted in its place. See Question Piping. The returned String contains the original string with all [/questionname] values replaced by their respective substitutions. |
| void WriteLog ( String msgid, String msg ) |
This method writes to the ViewsFlash log and to the survey or poll's log, a message with ID 'msgid' and text 'msg'. 'msgid' is usually a code of the form "NNNE" or "NNNI". the E or I indicates an Error or Information. The NNN is a number; use numbers above 1000 for your own Actions. These messages are visible with the View Log buttons. Use this method liberally while debugging and sparsely when going to production. |