NAME

Liz::Survey - Survey module


SYNOPSIS

 use Liz::Survey;

 $answer = new Liz::Survey;


EXAMPLES

 #!/usr/local/bin/perl

 use Liz::Survey;


DESCRIPTION

The Liz::Survey package allows for very simple storage of sets of questions (a survey) and answers by participants.


Incorporate into Client Module

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.


CLASS METHODS

The following methods can be called without an object specification, but as a class method such as Liz::Survey->method().


surveys

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.

Input Parameters

 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)
Output Parameters

 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
Example

 $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( @_ ) }


new

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.

Input Parameters

 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)
Output Parameters

 1 instantiated object
 2 flag indicating whether Survey was just created
Example

 $hn = new HN;
 $answer = $hn->Survey( 'technology' );

In HN.pm:

 sub Survey { Liz::Survey->new( @_ ) }


reset

Remove all answers from this Survey.

Example

 $survey->reset;
 print "All answers have been removed\n";


CONTENT METHODS

The following methods allow changes to information that is associated with an entire survey.


Closed

Set/Return whether the Survey is closed.

Input Parameters

 1 new status for closed: 1=closed, 0=open
   (default: no change)
Output Parameters

 1 current/previous status for closed
Example

 $closed = $survey->Closed;
 $survey->Closed( 1 );


Conclusion

Set/Return the conclusion of the Survey.

Input Parameters

 1 new conclusion of the survey
   (default: no change)
Output Parameters

 1 current/previous conclusion
Example

 $conclusion = $survey->Conclusion;
 $survey->Conclusion( $conclusion );


DefaultFontID

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.

Input Parameters

 1 new default font(ID)
   (default: no change)
Output Parameters

 1 current/previous default fontID
Example

 $survey->DefaultFontID( 'gdGiantFont' );
 $survey->DefaultFontID( $fontID );
 $defaultfontID = $survey->DefaultFontID;


FirstQuestionID

Specify or return the ID of the first question of the survey object.

Input Parameters

 1 new ID of first question of survey
   (default: no change)
Output Parameters

 1 current/old ID of first question of survey
Example

 $xxlink = new xxLINK;
 $survey = $xxlink->Survey( 'eurest' );
 $survey->FirstQuestionID( $questionID );


Name

Specify or return the current name of the survey object. The name can be anything to further identify the goal of the survey.

Input Parameters

 1 new name of survey
   (default: no change)
Output Parameters

 1 current/old name of survey
Example

 $xxlink = new xxLINK;
 $survey = $xxlink->Survey( 'eurest' );
 $survey->Name( 'Eurestjes' );


UniqueBy

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)
Input Parameters

 1 new type of check to be performed
   (default: no change; value: 'none','email','session' or 'visitor')
Output Parameters

 1 current/previous check to be performed
Example

 $xxlink = new xxLINK;
 $survey = $xxlink->Survey( 'eurest' );
 $survey->UniqueBy( 'session' );


OBJECT METHODS

The following methods create object related to a Survey.


Answer

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.

Input Parameters

 1 ID to create Answer object with
   (default: none = new answer)
Output Parameters

 1 instantiated Answer object
Example

 $hn = new HN;
 $survey = $hn->Survey( 'technology' );

 $answer = $survey->Answer;
 $answer = $survey->Answer( $answerID );


CategorySet

Return the CategorySet object that is used by the Liz::Survey object.

Output Parameters

 1 CategorySet object
Example

 $categoryset = $survey->CategorySet;


Graph

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.

Input Parameters

 1 ID to create Graph object with
   (default: none = new graph)
Output Parameters

 1 instantiated Graph object
Example

 $hn = new HN;
 $survey = $hn->Survey( 'technology' );

 $graph = $survey->Graph;
 $graph = $survey->Graph( $graphID );


PictureSet

Return the PictureSet object that is used by the Liz::Survey object.

Output Parameters

 1 PictureSet object
 2 flag indicating whether PictureSet was just created
Example

 $pictureset = $survey->PictureSet;


Question

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.

Input Parameters

 1 ID to create Question object with
   (default: none = new answer)
Output Parameters

 1 instantiated Question object
Example

 $hn = new HN;
 $survey = $hn->Survey( 'technology' );

 $question = $survey->Question;
 $question = $survey->Question( $questionID );


QUESTION CREATION METHODS

The following methods create questions in the Survey.


MultipleChoice

Create a new Liz::Survey::Question object for a question that requires a single Use method Question to open an existing question.

Input Parameters

 1 text for the question
 2 reference to list of texts for the alternatives
Output Parameters

 1 ID of the newly created Question
 2 instantiated Question object if further action are necessary
Example

 $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;


OpenQuestion

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.

Input Parameters

 1 text for the question
Output Parameters

 1 ID of the newly created Question object
 2 the question object (if further actions are necessary)
Example

 $hn = new HN;
 $survey = $hn->Survey( 'technology' );

 $ID = $survey->OpenQuestion( 'How do you feel about this?' );


CHOICE METHODS

The following methods are related to the choices of a Question object.


Choices

Return the (number of) choices that are associated with a Question as indicated by a questionID.

Input Parameters

 1    questionID for which to return the choices
Output Parameters

 1..N the choices (number of choices in a scalar context)
Example

 $choices = $survey->Choices( $questionID );
 @choice = $survey->Choices( $questionID );


Choices2Check

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.

Input Parameters

 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
Output Parameters

 1 HTML of complete checkbox sequence
Example

 print $survey->Choices2Check( $questionID,'keuzeID',"<BR>\n" );


Choices2Pulldown

Return the HTML for the choices of a question in the form of a pulldown menu.

Input Parameters

 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
Output Parameters

 1 HTML of complete pulldown menu
Example

 print $survey->Choices2Pulldown( $questionID,'keuzeID' );


Choices2Radio

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.

Input Parameters

 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
Output Parameters

 1 HTML of complete radiobutton sequence
Example

 print $survey->Choices2Radio( $questionID,'keuzeID',"<BR>\n" );


ChoiceTextIDListHash

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.

Input Parameters

 1 questionID for which to return the list/hash
Output Parameters

 1 reference to list of textID's of the choices
 2 reference to hash with texts of  the choices
Example

 ($list,$text) = $survey->ChoiceTextIDListHash( $questionID );
 foreach (@{$list)) {
  print "$_: $$text{$_}\n";
 }


ChoiceTextIDResult

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.

Input Parameters

 1 questionID for which to make the SQL-result handle
Output Parameters

 1 SQL-result handle
Example

 $result = $survey->ChoiceTextIDResult( $questionID );
 print $result->Result2Radio( $result );


ChoiceTextIDs

Return the list of the textIDs of the choices of a Question if it is a multiple choice type object.

Input Parameters

 1    questionID for which to obtain the textID's
Output Parameters

 1..N textID's of the choices
Example

 @choiceID = $survey->ChoiceTextIDs( $questionID );


ChoiceOrdinals

Return the list of the ordinal numbers of the choices of this Question if it is a multiple choice type object.

Output Parameters

 1..N ordinal numbers of the choices
Example

 foreach ($survey->ChoiceOrdinals( $questionID )) {
   $choice = $question->Choice( $_ );
 }


DropChoices

Remove all the choices that are associated with a Question.

Input Parameters

 1 questionID for which to remove the choices
 2 ordinal number above which all choices should be removed
   (default: 0 = all)
Example

 $survey->DropChoices( $questionID );


ANSWER METHODS

The following methods have to do with answers in the Survey.


AddAnswer

Add an Answer to the survey directly, without having to create an intermediate Answer object.

Input Parameters

 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)
Output Parameters

 1 the ID with which the answer was stored
   (undef: error occurred, check field ERROR)
Example

 if ($error = $surver->AddAnswer( \@answer,$email )) {
   print "The following error has occurred: $error\n";
 }


AnswersListHash

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.

Input Parameters

 1 ID of the question of which to return the list/hash
 2 extra condition to apply to Answers
   (default: none)
Output Parameters

 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
Example

 ($list,$freq) = $survey->QuestionID2AnswersListHash;


ChosenTextIDs

Return the textIDs of the selected choices of a specific Answer.

Input Parameters

 1    answerID of which to return the chosen textIDs
Output Parameters

 1..N the textIDs of the selected choices
Example

 foreach ($survey->ChosenTextIDs( $answerID )) {
  print "$_\n";
 }


ChosenTexts

Return the texts of the selected choices of a specific Answer.

Input Parameters

 1    answerID of which to return the chosen texts
Output Parameters

 1..N the texts of the selected choices
Example

 foreach ($survey->ChosenTexts( $answerID )) {
  print "$_\n";
 }


LastAnswer

Return the timestamp of the answer last given.

Output Parameters

 1 timestamp of last answer given
Example

 $lastvote = $survey->LastAnswer;


LIST METHODS

The following methods return lists of information in various forms.


Answers

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
Input Parameters

 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)
Output Parameters

 1 SQL statement handle (on which method "fetchrow" can be applied)


Questions

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
Input Parameters

 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)
Output Parameters

 1 SQL statement handle (on which method "fetchrow" can be applied)


Graphs

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
Input Parameters

 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)
Output Parameters

 1 SQL statement handle (on which method "fetchrow" can be applied)


UTILITY METHODS

The following methods perform different types of utility operations.


HasAnswered

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.

Input Parameters

 1 email address to check
   (default: none)
 2 session key to check
   (default: $ENV{'AUTOMATICSESSIONCOOKIE'})
 3 visitor key to check
   (default: $ENV{'VISITORID'}
Output Parameters

 1 flag: true if already answered, false if not
Example

 $hasanswered = $survey->HasAnswered( $email );
Note

The email address is assumed to be a proper email address. The session and visitor key fields are assumed to be SQL-query safe.


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )


COPYRIGHT

(C) 1999 International Network Consultants


HISTORY

Version 0.44, 3 December 1999

Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in methods new and PictureSet.

Version 0.43, 25 November 1999

Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in method Answer, Graph and Question.

Version 0.42, 20 October 1999

Fixed problem in new that caused categories to lose their parents.

Version 0.41, 30 September 1999

Now no longer puts Exporter in ISA: it was not needed.

Version 0.4, 26 September 1999

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.

Version 0.3, 23 September 1999

Removed ``parentfontID'' setting from method new: now moved to the PictureSet method.

Version 0.2, 22 September 1999

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.

Version 0.1, 20 September 1999

First version of this true Perl module.