Liz::Survey - Survey module
use Liz::Survey;
$answer = new Liz::Survey;
#!/usr/local/bin/perl
use Liz::Survey;
The Liz::Survey package allows for very simple storage of sets of questions (a survey) and answers by participants.
The Liz::Survey module itself works best when incorporated into a client module because it moves the responsibility of aquiring a connection to a database to the client module and it allows any customisation to take place transparently to the developer.
Take for example the Survey method of HN.pm module:
sub Survey { Liz::Survey->new( @_ ) }
Because of the above code in HN.pm, it is now possible to write the following code:
$hn = new HN; $survey = $hn->Survey( 'technology' );
Note that the database connection of the answer is hidden in the creation
of the $hn object.
The following methods can be called without an object specification, but as a class method such as Liz::Survey->method().
Return list of answer identification names of all surveys in the database specified. Usually not called by itself, but rather incorporated inside a Client Module.
1 Liz::SQL compatible handle or reference to routine that performs connect (default: &Connect from caller's namespace) 2 wildcard specification to match (default: all)
1 reference to list of identification names in the current database 2 reference to hash with full names 2 reference to hash with database versions
$hn = new HN;
($id,$name) = $hn->Surveys;
$surveys = @{$id};
print "All $surveys surveys in Hospitality Net:\n";
foreach( @{$id} ) {
print " Survey '$$name{$_}' ($_)\n";
}
In HN.pm:
sub Surveys { Liz::Survey->surveys( @_ ) }
Create a new Liz::Survey object. Creates connection or re-establishes connection with the MySQL database. Usually not called by itself, but rather incorporated inside a Client Module.
1 Liz::SQL compatible handle or reference to routine that performs connect (default: &Connect from caller's namespace) 2 identification name of survey (default: default survey for database)
1 instantiated object 2 flag indicating whether Survey was just created
$hn = new HN; $answer = $hn->Survey( 'technology' );
In HN.pm:
sub Survey { Liz::Survey->new( @_ ) }
Remove all answers from this Survey.
$survey->reset; print "All answers have been removed\n";
The following methods allow changes to information that is associated with an entire survey.
Set/Return whether the Survey is closed.
1 new status for closed: 1=closed, 0=open (default: no change)
1 current/previous status for closed
$closed = $survey->Closed; $survey->Closed( 1 );
Set/Return the conclusion of the Survey.
1 new conclusion of the survey (default: no change)
1 current/previous conclusion
$conclusion = $survey->Conclusion; $survey->Conclusion( $conclusion );
Set/Return the default FontID for this Survey. A new fontID can be specified as either a fontID or the font text as known by GD::Font.
1 new default font(ID) (default: no change)
1 current/previous default fontID
$survey->DefaultFontID( 'gdGiantFont' ); $survey->DefaultFontID( $fontID ); $defaultfontID = $survey->DefaultFontID;
Specify or return the ID of the first question of the survey object.
1 new ID of first question of survey (default: no change)
1 current/old ID of first question of survey
$xxlink = new xxLINK; $survey = $xxlink->Survey( 'eurest' ); $survey->FirstQuestionID( $questionID );
Specify or return the current name of the survey object. The name can be anything to further identify the goal of the survey.
1 new name of survey (default: no change)
1 current/old name of survey
$xxlink = new xxLINK; $survey = $xxlink->Survey( 'eurest' ); $survey->Name( 'Eurestjes' );
Specify or return the type of check to be performed on votes that are added to the survey. There are four values possible:
- none (default if never specified) - email (check email address) - session (check session key/cookie) - visitor (check visitorID string)
1 new type of check to be performed (default: no change; value: 'none','email','session' or 'visitor')
1 current/previous check to be performed
$xxlink = new xxLINK; $survey = $xxlink->Survey( 'eurest' ); $survey->UniqueBy( 'session' );
The following methods create object related to a Survey.
Create a new Liz::Survey::Answer object, either from existing information or for a new entry. For more documentation, see the Liz::Survey::Answer object itself.
1 ID to create Answer object with (default: none = new answer)
1 instantiated Answer object
$hn = new HN; $survey = $hn->Survey( 'technology' );
$answer = $survey->Answer; $answer = $survey->Answer( $answerID );
Return the CategorySet object that is used by the Liz::Survey object.
1 CategorySet object
$categoryset = $survey->CategorySet;
Create a new Liz::Survey::Graph object, either from existing information or for a new entry. For more documentation, see the Liz::Survey::Graph object itself.
1 ID to create Graph object with (default: none = new graph)
1 instantiated Graph object
$hn = new HN; $survey = $hn->Survey( 'technology' );
$graph = $survey->Graph; $graph = $survey->Graph( $graphID );
Return the PictureSet object that is used by the Liz::Survey object.
1 PictureSet object 2 flag indicating whether PictureSet was just created
$pictureset = $survey->PictureSet;
Create a new Liz::Survey::Question object, either from existing information or for a new entry. For more documentation, see the Liz::Survey::Question object itself.
This is the generic way of creating a Question object. It is usually much easier to use the specialised methods for creating a specific type of question, e.g. OpenQuestion and MultipleChoice.
1 ID to create Question object with (default: none = new answer)
1 instantiated Question object
$hn = new HN; $survey = $hn->Survey( 'technology' );
$question = $survey->Question; $question = $survey->Question( $questionID );
The following methods create questions in the Survey.
Create a new Liz::Survey::Question object for a question that requires a single Use method Question to open an existing question.
1 text for the question 2 reference to list of texts for the alternatives
1 ID of the newly created Question 2 instantiated Question object if further action are necessary
$hn = new HN; $survey = $hn->Survey( 'technology' );
$question = $survey->MultipleChoice( 'How do you feel about this?', ['ok','not so ok','don\'t know','none of the above'] ); $ID = $question->update;
Create a new Liz::Survey::Question object for a question that requires an open (free text) answer. Use method Question to open an existing question.
1 text for the question
1 ID of the newly created Question object 2 the question object (if further actions are necessary)
$hn = new HN; $survey = $hn->Survey( 'technology' );
$ID = $survey->OpenQuestion( 'How do you feel about this?' );
The following methods are related to the choices of a Question object.
Return the (number of) choices that are associated with a Question as indicated by a questionID.
1 questionID for which to return the choices
1..N the choices (number of choices in a scalar context)
$choices = $survey->Choices( $questionID ); @choice = $survey->Choices( $questionID );
Return the HTML for the choices of a question in the form of a checkbox sequence. This implies that there can be more than one answer possible.
1 questionID for which to return the HTML 2 name of variable (optionally with namespace if checking is to be performed) 3 extra HTML to be put between CHECK buttons 4 flag: return HTML as dummy <CHECK...> HTML
1 HTML of complete checkbox sequence
print $survey->Choices2Check( $questionID,'keuzeID',"<BR>\n" );
Return the HTML for the choices of a question in the form of a pulldown menu.
1 questionID for which to return the HTML 2 name of variable (optionally with namespace if checking is to be performed) 3 extra HTML to be added at the beginning 4 flag: return HTML as dummy <PULLDOWN...> HTML 5 flag: extra fields (0=add empty field at beginning, 1=don't, ref(@list)=list) (default: add empty field at beginning
1 HTML of complete pulldown menu
print $survey->Choices2Pulldown( $questionID,'keuzeID' );
Return the HTML for the choices of a question in the form of a radiobutton sequence. This implies that there can be only one answer possible.
1 questionID for which to return the HTML 2 name of variable (optionally with namespace if checking is to be performed) 3 extra HTML to be put between RADIO buttons 4 flag: return HTML as dummy <RADIO...> HTML
1 HTML of complete radiobutton sequence
print $survey->Choices2Radio( $questionID,'keuzeID',"<BR>\n" );
Return a reference to the list of the textIDs of the choices of a Question and a reference to a hash with the texts of the choices.
1 questionID for which to return the list/hash
1 reference to list of textID's of the choices 2 reference to hash with texts of the choices
($list,$text) = $survey->ChoiceTextIDListHash( $questionID );
foreach (@{$list)) {
print "$_: $$text{$_}\n";
}
Return a SQL-result handle for a query in which the first field is the textID and the second field is the associated text for a particular question.
1 questionID for which to make the SQL-result handle
1 SQL-result handle
$result = $survey->ChoiceTextIDResult( $questionID ); print $result->Result2Radio( $result );
Return the list of the textIDs of the choices of a Question if it is a multiple choice type object.
1 questionID for which to obtain the textID's
1..N textID's of the choices
@choiceID = $survey->ChoiceTextIDs( $questionID );
Return the list of the ordinal numbers of the choices of this Question if it is a multiple choice type object.
1..N ordinal numbers of the choices
foreach ($survey->ChoiceOrdinals( $questionID )) {
$choice = $question->Choice( $_ );
}
Remove all the choices that are associated with a Question.
1 questionID for which to remove the choices 2 ordinal number above which all choices should be removed (default: 0 = all)
$survey->DropChoices( $questionID );
The following methods have to do with answers in the Survey.
Add an Answer to the survey directly, without having to create an intermediate Answer object.
1 reference to list of textID's of choices made
2 email address of person giving the answer
(default: none)
3 comment to be associated with this answer
(default: none)
4 session key of person giving the answer
(default: $ENV{'AUTOMATICSESSIONCOOKIE'})
5 visitor key of person giving the answer
(default: $ENV{'VISITORID'}
6 reference to hash of extra fields to insert (values keyed on fields)
(default: none)
1 the ID with which the answer was stored (undef: error occurred, check field ERROR)
if ($error = $surver->AddAnswer( \@answer,$email )) {
print "The following error has occurred: $error\n";
}
Return a reference to the list of possible choices (textID's) and a hash that contains the number of answers that matched that choice for a particular question.
1 ID of the question of which to return the list/hash 2 extra condition to apply to Answers (default: none)
1 reference to a list of choices of that question 2 reference to a hash with the number of answers for the choice 3 total number of answers found
($list,$freq) = $survey->QuestionID2AnswersListHash;
Return the textIDs of the selected choices of a specific Answer.
1 answerID of which to return the chosen textIDs
1..N the textIDs of the selected choices
foreach ($survey->ChosenTextIDs( $answerID )) {
print "$_\n";
}
Return the texts of the selected choices of a specific Answer.
1 answerID of which to return the chosen texts
1..N the texts of the selected choices
foreach ($survey->ChosenTexts( $answerID )) {
print "$_\n";
}
Return the timestamp of the answer last given.
1 timestamp of last answer given
$lastvote = $survey->LastAnswer;
The following methods return lists of information in various forms.
Return an SQL statement handle for a list of answers.
The following fields may be specified with the first parameter:
ID The ID of the answer
status Status of the answer
created Timestamp value when this answer was created
updated Timestamp when the answer was last updated
IP The IP-number at which the answer was made
email Email address of the maker of the answer
session The session key of the maker of the answer
visitor The visitor key of the maker of the answer
1 fields to return (comma delimited) (default: 'ID,status,created,updated,IP,email,session,visitor' ); 2 fieldname on which to order the result (default: 'created') 3 extra condition to be applied (default: none)
1 SQL statement handle (on which method "fetchrow" can be applied)
Return an SQL statement handle for a list of questions.
The following fields may be specified with the first parameter:
ID The ID of the question
created Timestamp value when this answer was created
updated Timestamp when the answer was last updated
type Type of question
textID The ID of the text of the question
data Additional data for this question
1 fields to return (comma delimited) (default: 'ID,created,updated,type,textID,data' ); 2 fieldname on which to order the result (default: 'created') 3 extra condition to be applied (default: none)
1 SQL statement handle (on which method "fetchrow" can be applied)
Return an SQL statement handle for a list of graphs. Please note that the graphs of all Questions will be returned. Make sure to add ``questionID=###'' as an extra condition if you only would like to receive the graphs of a specific Question.
The following fields may be specified with the first parameter:
ID The ID of the graph
questionID The questionID of the graph
legenda The legenda (title) of this graph
finalpictureID The pictureID of the finished image for the graph
created Timestamp value when this graph was created
updated Timestamp when the graph was last updated
pictureID The pictureID of the base image for the graph
direction The direction of the bars in the graph
alignment The alignment of the bars in the graph
sizing The sizing of the bars in the graph
fontID The fontID of the font of the legenda of the graph
barfontID The fontID of the font of the legenda of the bars of the graph
1 fields to return (comma delimited) (default: 'ID,questionID,legenda,finalpictureID,created,updated,pictureID,direction,alignment,sizing,fontID,barfontID' ); 2 fieldname on which to order the result (default: 'created') 3 extra condition to be applied (default: none)
1 SQL statement handle (on which method "fetchrow" can be applied)
The following methods perform different types of utility operations.
Return flag indicating whether a combination of email address, session or visitor key has given an answer already.
Uses the setting previously specified by UniqueBy to determine whether a person has already given an answer.
1 email address to check
(default: none)
2 session key to check
(default: $ENV{'AUTOMATICSESSIONCOOKIE'})
3 visitor key to check
(default: $ENV{'VISITORID'}
1 flag: true if already answered, false if not
$hasanswered = $survey->HasAnswered( $email );
The email address is assumed to be a proper email address. The session and visitor key fields are assumed to be SQL-query safe.
Elizabeth Mattijsen ( lizperl@INC.nl )
(C) 1999 International Network Consultants
Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in methods new and PictureSet.
Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in method Answer, Graph and Question.
Fixed problem in new that caused categories to lose their parents.
Now no longer puts Exporter in ISA: it was not needed.
Support for Liz::Survey::Graph added: new methods Graph and Graphs and DefaultFontID.
Methods Closed and Conclusion added: they were general enough to copy them from the first client module ``Stemming''.
Method PictureSet now also returns flag to indicate whether the PictureSet was just created. Also fixed internal problem which would prevent it from working at all.
Removed ``parentfontID'' setting from method new: now moved to the PictureSet method.
Added method CategorySet for obtaining the CategorySet of the Survey. Added method PictureSet for obtaining the PictureSet of the Survey.
Added table creation of graphic related tables in method new.
First version of this true Perl module.