NAME

QWizard - Display a series of questions, get the answers, and act on the answers.

SYNOPSIS

  #
  # The following code works as a application *or* as a CGI script both:
  #

  use QWizard;

  my %primaries =
  (
   starting_node =>
   { title => "starting here",
     introduction => "foo bar",
     questions =>
     [{	type => 'text',
       	name => 'mytext',
       	text => 'enter something:',
       	default => "hello world" },
      { type => 'checkbox',
        text => 'yes or no:',
        values => ['yes','no'],
        name => 'mycheck'} ],
     actions => 
     [sub { return [
            "msg: text = " . qwparam('mytext'),
            "msg: checkbox = " . qwparam('mycheck')
            ];}]
    }
   );

  my $qw = new QWizard(primaries => \%primaries,
		       title => "window title");

  $qw->magic('starting_node');


  #
  # PLEASE see the examples in the examples directory.
  #

DESCRIPTION

QWizard displays a list of grouped questions, and retrieves and processes user-specified answers to the questions. Multiple question/answer sets may be displayed before the answers are dealt with. Once a "commit" action is taken (instigated by the user), a series of actions is performed to handle the answers. The actions are executed in the order required by the QWizard programmer.

QWizard's real power lies in its inherent ability to keep track of all state information between one wizard screen and the next, even in normally stateless transaction environments like HTTP and HTML. This allows a QWizard programmer to collect a large body of data with a number of simple displays. After all the data has been gathered and verified, then it can be handled as appropriate (e.g., written to a database, used for system configuration, or used to generate a graph.)

Current user interfaces that exist are HTML, Gtk2, Tk, and (minimally) ReadLine. A single QWizard script implementation can make use of any of the output formats without code modification. Thus it is extremely easy to write portable wizard scripts that can be used without modification by both graphical window environments (Gtk2 and Tk) and HTML-based web environments (e.g., CGI scripts.), as well with intercative command line enviornments (ReadLine).

Back-end interfaces (child classes of the QWizard::Generator module) are responsible for displaying the information to the user. Currently HTML, Gtk2, Tk and ReadLine, are the output mechanisms that work the best (in that order). Some others are planned (namely a curses version), but are not far along in development. Developing new generator back-ends is fairly simple and doesn't take a lot of code (assuming the graphic interface is fairly powerful and contains a widget library.)

QWizard operates by displaying a series of "screens" to the user. Each screen is defined in a QWizard construct called a primary that describes the attributes of a given screen, including the list of questions to be presented to the user. Primaries can contain questions, things to do immediately after the questions are answered (post_answers), and things to do once the entire series of screens have been answered (actions). Other information, such as a title and an introduction, can also be attached to a primary.

An example very minimal primary definition containing one question:

my %primaries = (
  myprimary =>
  {
    title => "my screen title",
    introduction => "optional introduction to the screen",
    questions =>
    [
      {
        type => 'checkbox',
        text => 'Should the chicken cross the road?',
      }
    ],
  }

After defining a set of primaries, a new QWizard object must be created. The QWizard new() constructor is given a set of options, such as window title and a reference to a hash table containing the primaries. (The complete set of options may be found in the "QWizard new() Options" section.) The question display and data collection is started by calling the magic() routine of the new QWizard object.

my $qw = new QWizard(primaries => \%primaries,
                     title => 'my title');
$qw->magic('myprimary');

There are examples distributed with the QWizard module sources that may help to understand the whole system and what it is capable of. See the examples directory of the QWizard source code tree for details. Also, QWizard was written mostly due to requirements of the Net-Policy project. Net-Policy makes very extensive use of QWizard and is another good place to look for examples. In fact, the QWizard CVS code is located inside the Net-Policy CVS tree. See http://net-policy.sourceforge.net/ for details on the Net-Policy project. There are a number of screen shots showing all the interfaces as well on the main net-policy web site.

MAGIC() PSEUDO-CODE

A pseudo-code walk-through of the essential results of the magic() routine above is below. In a CGI script, for example, the magic() routine will be called multiple times (once per screen) but the results will be the same in the end -- it's all taken care of magically ;-).

################
## WARNING:  pseudo-code describing a process! Not real code!
################

# Loop through each primary and display the primary's questions.
while(primaries to process) {
    display_primary_questions();
    get_user_input();
    check_results();
    run_primary_post_answers();
}

# Displays a "will be doing these things" screen,
# and has a commit button.
display_commit_screen();

# Loop through each primary and run its actions.
# Note: see action documentation about execution order!
foreach (primary that was displayed) {
    results = run_primary_actions();
    display(results);
}

# If magic() is called again, it restarts from
# the top primary again.

QWIZARD NEW() OPTIONS

Options passed to the QWizard new() operator define how the QWizard instance will behave. Options are passed in the following manner:

new QWizard (option => value, ...)

Valid options are:

title => "document title"

The document title to be printed in the title bar of the window.

generator => GENERATOR

GENERATOR is a reference to a valid QWizard generator. Current generator classes are:

- QWizard::Generator::Best           (default: picks the best available)
- QWizard::Generator::HTML
- QWizard::Generator::Gtk2
- QWizard::Generator::Tk
- QWizard::Generator::ReadLine       (limited in functionality)

The QWizard::Generator::Best generator is used if no specific generator is specified. The Best generator will create an HTML generator if used in a web context (i.e., a CGI script), or else pick the best of the available other generators (Gtk2, then Tk, then ReadLine).

This example forces a Gtk2 generator to be used:

my $wiz = new QWizard(generator => new QWizard::QWizard::Gtk2(),
                      # ...
                     );

generator_args => [ARGS],

If you want the default generator that QWizard will provide you, but would still like to provide that generator with some arguments you can use this token to pass an array reference of arguments. These arguments will be passed to the new() method of the Generator that is created.

top_location => "webaddress"

This should be the top location of a web page where the questions will be displayed. This is needed for "go to top" buttons and the like to work. This is not needed if the QWizard-based script is not going to be used in a CGI or other web-based environment (eg, if it's going to be used in mod_perl).

primaries => \%my_primaries

my_primaries will define the list of questions to be given to the user. my_primaries just defines the questions, but does not mean the user will be prompted with each question. The questions in this series that will be displayed for the user to answer is determined by the magic() function's starting arguments, described below. The format of the primaries hash is described in the Primaries Definition section below. The recognized values in the primaries hash is described in the Primaries Options section.

no_confirm => 1

If set, the final confirmation screen will not be displayed, but instead the resulting actions will be automatically run. This can also be achieved inside the wizard tokens primaries by setting a question name to no_confirm with a value of 1 (using a hidden question type.)

begin_section_hook => \&subroutine

This function will be called just before a set of questions is displayed. It can be used to perform such functions as printing preliminary information and initializing data.

end_section_hook => \&subroutine

This function will be called just after a set of questions is displayed.

topbar

A place to add extra widgets to a primary at the very top.

See the bar documentation in the QUESTION DEFINITIONS section below for details on this field.

leftside => [WIDGETS]

rightside => [WIDGETS]

Adds a left or right side frame to the main screen where the WIDGETS are always shown for all primaries. Basically, these should be "axillary" widgets that augment the widgets is the main set of questions. They can be used for just about anything, but the look and feel will likely be better if they're suplimental.

The WIDGETS are normal question widgets, just as can appear in the questions section of the primaries definition as described below.

In addition, however, there can be subgroupings with a title as well. These are then in a sub-array and are displayed with a title above them. EG:

leftside => [ 
             { type => 'button',
               # ...  normal button widget definition; see below
             },
             [
              "Special Grouped-together Buttons",
             	{ type => 'button',
             	  # ...
             	},
             	{ type => 'button',
             	  # ...
             	},
             ],
            ],

The above grouped set of buttons will appear slightly differently and grouped together under the title "Special Grouped-together Buttons".

The widget-test-screen.pl in the examples directory shows examples of using this.

Important note: Not all backends support this yet. HTML and Gtk2 do, though.

PRIMARIES DEFINITION

The primaries argument of the new() function defines the list of questions that may be posed to a user. Each primary in the hash will contain a list of questions, answers, etc., and are grouped together by a name (the key in the hash). Thus, a typical primary set definition would look something like:

%my_primaries =
  (
   # The name of the primary.
   'question_set_1' => 
   # its definition
   {
     title => 'My question set',
     questions =>
        # questions are defined in an array of hashes.
        [{type => 'checkbox',
          text => 'Is this fun?',
          name => is_fun,
          default => 1,
          values => [1, 0] },
         {type => 'text',
          text => 'Enter your name:',
          name => 'their_name'}],
     post_answers =>
        # post_answers is a list of things to do immediately after
        # this set of questions has been asked.
        [ sub { print "my question set answered" } ],
     actions =>
        # actions is a list of actions run when all is said and done.
        [ sub {
                return "msg: %s thinks this %s fun.\n",
                qwparam('their_name'),
                (qwparam('is_fun')) ? "is" : "isn't" 
               }],
     actions_descr =>
        # An array of strings displayed to the user before they agree
        # to commit to their answers.
        [ 'I\'m going to process stuff from @their_name@)' ]
    });

See the QWizard::API module for an alternative, less verbose, form of API for creating primaries which can produce more compact-looking code.

VALUE conventions

In the documentation to follow, any time the keyword VALUE appears, the following types of "values" can be used in its place:

- "a string"
- 10
- \&sub_to_call
- sub { return "a calculated string or value" }
- [\&sub_to_call, arguments, to, sub, ...]

Subroutines are called and expected to return a single value or an array reference of multiple values.

Much of the time the VALUE keyword appears in array brackets: []. Thus you may often specify multiple values in various ways. E.g., a values clause in a question may be given in this manner:

sub my_examp1 { return 3; }
sub my_examp2 { return [$_[0]..$_[1]]; }

values => [1, 2, \&my_examp1, [\&my_examp2, 4, 10]],

After everything is evaluated, the end result of this (complex) example will be an array passed of digits from 1 to 10 passed to the values clause.

In any function at any point in time during processing, the qwparam() function can be called to return the results of a particular question as it was answered by the user. I.e., if a question named their_name was answered with "John Doe" at any point in the past series of wizard screens, then qwparam('their_name') would return "John Doe". As most VALUE functions will be designed to process previous user input, understanding this is the key to using the QWizard Perl module. More information and examples follow in the sections below.

PRIMARY OPTIONS

These are the tokens that can be specified in a primary:

title => VALUE

The title name for the set of questions. This will be displayed at the top of the screen.

introduction => VALUE

Introductory text to be printed above the list of questions for a given primary. This is useful as a starting piece of text to help the user with this particular wizard screen. Display of the introductory text is controlled by the Net-Policy pref_intro user preference. The default is to display introductory text, but this setting can be turned off and on by the user.

questions => [{ QUESTION_DEFINITION }, { QUESTION_DEFINITION }, ...]

This is a list of questions to pose to the user for this screen.

The Question Definitions section describes valid question formatting.

post_answers => [ VALUES ]

This is a list of actions to run after the questions on the screen have been answered. Although this is a VALUES clause, as described above, these should normally be subroutines and not hard-coded values. The first argument to the VALUE functions will be a reference to the wizard. This is particularly useful to conditionally add future screens/primaries that need to be shown to the user. This can be done by using the following add_todos() function call in the action section:

if (some_condition()) {
    $_[0]->add_todos('primary1', ...);
}

See the QWizard Object Functions section for more information on the add_todos() function, but the above will add the 'primary1' screen to the list of screens to display for the user before the wizard is finished.

A post_answers subroutine MUST return the word "OK" for it to be successful. Returning anything else will print the result, as if it is an error message, to the user.

For HTML output, these will be run just before the next screen is printed after the user has submitted the answers back to the web server. For window-based output (Gtk2, Tk, etc.) the results are similar and these subroutines are evaluated before the next window is drawn.

actions => [ VALUES ]

The action functions will be run after the entire wizard series of questions has been displayed and answered and after the user has hit the "commit" button. It is assumed that the actions of the earlier screens are dependent on the actions of the later screens and so the action functions will be executed in reverse order from the way the screens were displayed. See the add_todos() function description in the QWizard Object Functions section for more information on to change the order of execution away from the default.

The collected values returned from the VALUES evaluation will be displayed to the user. Any message beginning with a 'msg:' prefix will be displayed as a normal output line. Any value not prefixed with 'msg:' will be displayed as an error (typically displayed in bold and red by most generators.)

actions_descr => [ VALUES ]

Just before the actions are run, a change-summary screen is shown to the user. A "commit" button will also be given on this screen. VALUE strings, function results, etc., will be displayed as a list on this commit screen. Strings may have embedded special @TAG@ keywords which will be replaced by the value for the question with a name of TAG. These strings should indicate to the user what the commit button will do for any actions to be run by this set of questions. If any question was defined whose name was no_confirm and whose value was 1, this screen will be skipped and the actions will be run directly.

sub_modules => [ 'subname1', ... ]

This hash value adds the specified sub-modules to the list of screens to display after this one. This is equivalent to having a post_answers clause that includes the function:

sub { $_[0]->add_todos('subname1', ...); }

doif => sub { LOGIC }

Allows primaries to be optional and only displayed under certain conditions.

If specified, it should be a CODE reference which when executed should return a 1 if the primary is to be displayed or a 0 if not. The primary will be entirely skipped if the CODE reference returns a 0.

topbar

A place to add extra widgets to a primary at the very top.

See the bar documentation in the QUESTION DEFINITIONS section below for details on this field.

leftside => [WIDGETS]

rightside => [WIDGETS]

Adds a left or right side frame to the main screen where the WIDGETS are shown for this primary.

Important note: See the leftside/rightside documentation for QWizard for more details and support important notes there.

take_over => \&subroutine

This hash value lets a subroutine completely take control of processing beyond this point. The wizard methodology functionally stops here and control for anything in the future is entirely passed to this subroutine. This should be rarely (if ever) used and it is really a way of breaking out of the wizard completely.

QUESTION DEFINITIONS

Questions are implemented as a collection of hash references. A question generally has the following format:

{
    type => QUESTION_TYPE
    text => QUESTION_TEXT,
    name => NAME_FOR_ANSWER,
    default => VALUE,
    # for menus, checkboxes, multichecks, ... :
    values => [ VALUE1, VALUE2, ... ],                # i.e., [VALUES]
    # for menus, checkboxes, multichecks, ... :
    labels => { value1 => label1, value2 => label2 }  # i.e., [VALUES]
}

Other than this sort of hash reference, the only other type of question allowed in the question array is a single "" empty string. The empty string acts as a vertical spatial separator, indicating that a space should occur between the previous question and the next question.

The fields available to question types are given below. Unless otherwise stated, the fields are available to all question types.

name => 'NAME'

Names the answer to the question. This name can then be used later in other sections (action, post_answers, etc.) to retrieve the value of the answer using the qwparam() function. For example, qwparam('NAME') at any point in future executed code should return the value provided by the user for the question named 'NAME'.

The namespace for these names is shared among all primaries (except 'remapped' primaries, which are described later). A warning will be issued if different questions from two different primaries use the same name. This warning will not be given if the question contains an override flag set to 1.

text => 'QUESTION TEXT'

Text displayed for the user for the given question. The text will generally be on the left of the screen, and the widget the user is supposed to interact with will be to the question text's right. (This is subject to the implementation of the back-end question Generator. The standard QWizard generators use this layout scheme.)

type => 'TYPE'

Defines the type of question. TYPE can be one of:

label

Displays information on the screen without requesting any input. The text of the question is printed on the left followed by the values portion on the right. If the values portion is omitted, the text portion is printed across the entire width of the screen.

paragraph

Paragraphs are similar to labels but are designed for spaces where text needs to be wrapped and is likely to be quite long.

text

Text input. Displays an entry box where a standard single line of text can be entered.

textbox

Text input, but in a large box allowing for multi-line entries.

hidetext

Obscured text input. Displays a text entry box, but with the typed text echoed as asterisks. This is suitable for prompting users for entering passwords, as it is not shown on the screen.

checkbox

A checkbox. The values clause should have only 2 values in it: one for its "on" value, and one for its "off" value (which defaults to 1 and 0, respectively).

If a backend supports key accelerators (GTk2): Checkbox labels can be bound to Alt-key accelerators. See QUESTION KEY-ACCELERATORS below for more information.

multi_checkbox

Multiple checkboxes, one for each label/value pair. The name question field is a prefix, and all values and/or label keywords will be the second half of the name.

For example, the following clauses:

{
    type => 'multi_checkbox',
    name => 'something',
    values => ['end1','end2'],
    ...
}

will give parameters of 'somethingend1' and 'somethingend2'.

If a backend supports key accelerators (GTk2): Checkbox labels can be bound to Alt-key accelerators. See QUESTION KEY-ACCELERATORS below for more information.

radio

Radio buttons, only one of which can be selected at a time. If two questions have the same name and are of type 'radio', they will be "linked" together such that clicking on a radio button for one question will affect the other.

If a backend supports key accelerators (GTk2): Radio button labels can be bound to Alt-key accelerators. See QUESTION KEY-ACCELERATORS below for more information.

menu

Pull-down menu, where each label is displayed as a menu item. If just the values clause (see below) is used, the labels on the screen will match the values. If the default clause is set, then that menu entry will be the menu's initial selection. If the labels clause is used, the values shown to the user will be converted to the screen representations that will differ from the qwparam() values available later. This is useful for displaying human representations of programmatic values. E.g.:

{
    type => 'menu',
    name => 'mymenu',
    labels => [ 1 => 'my label1',
                2 => 'my label2']
}

In this example, the user will see a menu containing 2 entries "my label1" and "my label2", but qwparam() will return 1 or 2 for qwparam('mymenu').

table

Table to display. The values section should return a reference to an array, where each element of the array is a row containing the columns to display for that row. The top-most table must actually be returned in an array itself. (This is due to an oddity of internal QWizard processing). E.g.:

{
    type => 'table',
    text => 'The table:',
    values => sub {
        my $table = [['row1:col1', 'row1:col2'],
                     ['row2:col1', 'row2:col2']];
        return [$table];
      }
}

This would be displayed graphically on the screen in this manner:

row1:col1     row1:col2

row2:col1     row2:col2

Additionally, a column value within the table may itself be a sub-table (another double-array reference set) or a hash reference, which will be a sub-widget to display any of the other types listed in this section.

Finally, a headers clause may be added to the question definition which will add column headers to the table. E.g.:

headers => [['col1 header','col2 header']]

fileupload

A dialog box for a user to upload a file into the application. When a user submits a file the question name can be used later to retrieve a read file handle on the file using the function qw_upload_file('NAME'). qwparam('NAME') will return the name of the file submitted, but because of the variability in how web-browsers submit file names along with the data, this field should generally not be used. Instead, get access to the data through the qw_upload_fh() function instead.

filedownload

A button that allows the user to download something generated by the application. The data that will be stored in this file should be defined in the 'data' field or the 'datafn' field. The name displayed within the button will be taken from the default question parameter.

The data field is processed early during display of the screen, so generation of large sets of data that won't always be downloaded or will take a lot of memor shouldn't use the data field. The data field is processed like any other value field where raw data or a coderef can be passed that will be called to return the data.

The datafn field should contain a CODE reference that will be called with five arguments:

a IO::File filehandle to print to

the file name (if appropriate) it's going to print to.

a QWizard object reference

a reference to the primary hash

a reference to the question hash

Example usage:

     { type => 'filedownload',
       text => 'Download a file:',
       datafn =>
       sub { 
	   my $fh = shift;
	   print $fh "hello world: val=" . qwparam('someparam') . "\n";
       }
     },

Currently only Gtk2 supports this button, but others will in the future.

image

Image file. The image name is specified by the image hash keyword. Several optional hash keys are recognized to control display of the image. imagealt specifies a string to display if the image file is not found. height specifies the height of the image. width specifies the width of the image. (height and width are currently only implemented for HTML.)

graph

Graph of passed data. This is only available if the GD::Graph module is installed. Data is passed in from the values clause and is expected to be an array of arrays of data, where the first row is the x-axis data, and the rest are y values (one line will be drawn for each y value).

Additionally, the GD::Graph options can be specified with a graph_options tag to the question, allowing creation of such things as axis labels and legends.

tree

Hierarchical tree. Displays a selectable hierarchical tree set from which the user should pick a single item. Two references to subroutines must be passed in via the parent and children question tags. Also, a root tag should specify the starting point.

Widget Options:

parent => CODEREF

The parent function will be called with a wizard reference and a node name. It is expected to return the name of the node's parent.

The function should return undef when no parent exists above the current node.

children => CODEREF

The children function will be passed a wizard reference and a node name. It is expected to return an array reference to all the children names. It may also return a hash reference for some names instead, which will contain an internal name tag along with a label tag for displaying something to the user which is different than is internally passed around as the resulting selected value.

An example return array structure could look like:

[
 'simple string 1',
 'simple string 2',
 {
  name => 'myanswer:A',
  label => 'Answer #A'
 },
 {
  name => 'myanswer:B',
  label => 'Answer #B'
 },
]

The function should return undef when no children exist below the current node.

expand_all => NUM

The expand_all tag may be passed which will indicate that all initial option trees sholud be expanded up to the number indicated by the expand_all tag.

button

Button widget. When the button is clicked, the QWizard parameter name (available by calling qwparam('name')) will be assigned the value indicated by the default clause. The parameter value will not be set if the button is not clicked. The button's label text will be set to the value of the values clause.

The button widget will be equivalent to pressing the next button. The next primary will be shown after the user presses the button.

If a backend supports key accelerators (GTk2): Button labels can be bound to Alt-key accelerators. See QUESTION KEY-ACCELERATORS below for more information.

bar

A bar widget is functionally a separator in the middle of the list of questions. It is useful for breaking a set of questions in two as well as providing button-containers or menu containers within widget sets and not having them tied to the normal QWizard left/right feel. One intentional artifact of this is they can be used to provide a visual difference between the flow of the questions. EG, if the QWizard primary showed a screen which had two questions in it, it would look something like the following when displayed by most of the generators that exist today:

+-------------------+-----------------+
| Question 1        |	Answer Widget 1 |
| Longer Question 2 |	Answer Widget 2 |
+-------------------+-----------------+

Adding a bar in the middle of these questions, however, would break the forced columns above into separate pieces:

+------------+------------------------+
| Question 1 | Answer Widget 1        |
+------------+------------------------+
|               BAR                   |
+-------------------+-----------------+
| Longer Question 2 | Answer Widget 2 |
+-------------------+-----------------+

Finally, there is an implicit top bar in every primary and the QWizard object as a whole. You can push objects onto this bar by adding objects to the $qwizard->{'topbar'} array or by adding objects to a primary's 'topbar' tag. E.G.

  my $qw = new QWizard(primaries => \%primaries,
		       topbar => [
				  {
				   type => 'menu', name => 'menuname',
				   values => [qw(1 2 3 4)],
				   # ...
				  }]);

The widgets shown in the topbar will be a merge of those from the QWizard object and the primary currently being displayed.

TODO: make it work better with merged primaries

TODO: make a bottom bar containing the next/prev/cancel buttons

hidden

This clause is used to set internal parameters (name => value), but these values are not shown to the user.

Note: This is not a secure way to hide information from the user. The data set using hidden are contained, for example, in the HTML text sent to the user.

dynamic

A dynamic question is one where the values field is evaluated and is expected to return an array of question definitions which are in turn each evaluated as a question. It is useful primarily when doing things like creating a user-defined number of input fields, or interacting with an external data source where the number of questions and their nature is directly related to the external data source.

raw

Raw data. The values portion is displayed straight to the screen. Use of this is strongly discouraged. Obviously, the values portion should be a subroutine that understands how to interact with the generator.

Really, don't use this. It's for emergencies only. It only works with HTML output.

values => [ VALUES ]

An array of values that may be assigned to question types that need choices (eg: menu, checkbox, multi_checkbox.) It should be a reference to an array containing a list of strings, functions to execute, and possibly sub-arrays containing a function and arguments, as described by the VALUE conventions section above. Any function listed in a values clause should return a list of strings.

The values clause is not needed if the labels clause is present.

labels => [ VALUE1 => 'LABEL1', VALUE2 => 'LABEL2', ... ]

Assigns labels to the question's values. Labels are displayed to the user instead of the raw values. This is useful for converting human-readable text strings into real-world values for use in code.

If the values clause is not specified and the labels clause is, the values to display are extracted from this labels clause directly. If a value from the values clause does not have a corresponding label, the raw value is presented and used instead. Generally, only the labels clause should be used with radio buttons, menus, or check boxes; but either or both in combination work.

The labels clause subscribes to all the properties of the VALUES convention previously discussed. Thus, it may be a function, an array of functions, or any other type of data that a VALUE may be. The final results should be an array, especially if the values clause is not present, as the order displayed to the user can be specified. It can also be a hash as well but the displayed order is subject to Perl keys() conventions and thus an array is preferred when no values clause has been defined.

default => VALUE

The default value to use for this question. It may be a subroutine reference which will be called to calculate and return the value.

check_value => \&subroutine

A script to check the answer submitted by the user for legality. The script should return 'OK' to indicate no error found. In the event an error is detected, it should return an error string. The string will be shown to the user as an error message that the user must fix before being allowed to proceed further in the wizard screens. Alternately, the script may return 'REDISPLAY' to indicate no error but that screen should be redisplyed (perhaps with new values set with qwparam() from within the script). In the case of error or 'REDISPLAY', the current primary screen will be repeated until the function returns 'OK'.

The arguments passed to the function are the reference to the wizard, a reference to the question definition (the hash), and a reference to the primary containing the question (also a hash.) The function should use the qwparam() function to obtain the value to check. An array can be passed in which the first argument should be the subroutine reference, and the remaining arguments will be passed back to the subroutine after the already mentioned default arguments.

There are a set of standard functions that can be used for checking values. These are:

\&qw_required_field

Ensures that a value is supplied or else a "This is a required field" error message is returned. The function only checks that the value is non-zero in length.

\&qw_integer

\&qw_optional_integer

Ensures that the value is an integer value (required or not, respectively.)

\&qw_hex

\&qw_optional_hex

Ensures that the value is a hex string (required or not, respectively.)

[\&qw_check_hex_and_length, length]

Ensures that a value is supplied and is a hex string sufficiently long for length bytes. This means that the hex string must be "length * 2" ASCII characters (two hex characters per byte.)

[\&qw_check_int_ranges, low1, high1, low2, high2, ...]

Ensures that the value specified falls within one of the lowX - highX ranges. The value must be between (low1 and high1) or (low2 and high2).

[\&qw_check_length_ranges, low1, high1, low2, high2, ...]

qw_check_length_ranges is similar to qw_check_int_ranges(), but it checks that the length of the data string specified by the user falls within the given ranges.

doif => sub { LOGIC }

Allows questions to be optional and only displayed under certain conditions.

If specified, it should be a CODE reference which when executed should return a 1 if the question is to be displayed or a 0 if not. The question will be entirely skipped if the CODE reference returns a 0.

helptext =item helpdescr

If specified, these define the help text for a question. helpdescr should be short descriptions printed on screen when the wizard screen is displayed, and helptext should be a full length description of help that will be displayed only when the user clicks on the help button. helpdescr is optional, and a button will be shown linking to helptext regardless.

submit => 1

When this is specified as a question argument, if the user changes the value then it will also be the equivelent of pressing the 'Next' button at the same time. With the HTML generator, this requires javascript and thus you shouldn't absolutely depend on it working.

refresh_on_change => 1

If the contents of a screen are generated based on data extracted from dynamically changing sources (e.g., a database), then setting this parameter to 1 will make the current question force a refresh if the value changes (ie, when they pull down a menu and change the value or click on a checkbox or ...) and the screen be redrawn (possibly changing its contents).

As an example, Net-Policy uses this functionality to allow users to redisplay generated data tables and changes the column that is used for sorting depending on a menu widget.

handle_results => sub { ... }

The handle_results tag can specify a CODE reference to be run when the questions are answered so each question can perform its own processing. This is sort of like a per-question post_answers hook equivalent.

QUESTION KEY-ACCELERATORS

Some generators (currently only Gtk2 actually) support key accelerators so that you can bind alt-keys to widgets. This is done by including a '_' (underscore) character where appropriate to create the binding. EG:

{
  type => 'radio',
  text => 'select one:',
  values => ['_Option1','O_ption2', 'Option3']
}

When Gtk2 gets the above construct it will make Alt-o be equivelent to pressing the first option and Alt-p to the second. It will also display the widget with a underline under the character that is bound to the widget. HTML and other non-accelerator supported interfaces will strip out the _ character before displaying the string in a widget.

In addition, unless a no_auto_accelerators = 1> option is passed to the generator creation arguments, widgets will automatically get accelerators assigned to them. In the above case the 't' in Option3 would automatically get assigned the Alt-t accelerator (the 't' is selected because it hasn't been used yet, unlike the o and p characters). You can also prefix something with a ! character to force a single widget to not receive an auto-accelerator (EG: "!Option4" wouldn't get one).

SPECIAL VARIABLES

A few QWizard parameters are special and help control how QWizard behaves. Most of these should be set in the primaries question sets using a hidden question type.

no_actions

If set to 1, the actions phase will not be run.

no_confirm

If set to 1, the screen which prompts the user to decide if they really want to commit their series of answers won't be shown. Instead, QWizard will jump straight to the actions execution (if appropriate.) This can also be given as a parameter to the QWizard new() function to make it always true.

allow_refresh

If the contents of a screen are generated based on data extracted from dynamically changing sources (e.g., a database), then setting this parameter to 1 will add a "Refresh" button beside the "Next" button so that the user can request the screen be redrawn (possibly changing its contents).

As an example, Net-Policy uses this functionality to allow users to redisplay generated graphs and maps that will change dynamically as network data are collected.

This token can also be set directly in a primary definition to affect just that primary screen.

QWizard_next

The button text to display for the "Next" button. This defaults to "Next" but can be overridden using this parameter.

QWIZARD RESERVED VARIABLES

The following parameters are used internally by QWizard. They should not be modified.

pass_vars

qw_cancel

no_cancel

qwizard_tree

display_help_p

disp_q_num

redo_screen

upd_time

wiz_confirmed

wiz_canceled

wizard_queue_list

QWizard OBJECT FUNCTIONS

The following functions are defined in the QWizard class and can be called as needed.

$qw->magic(primary_name, ...);

This tells QWizard to start its magic, beginning at the primary named primary_name. Multiple primaries will be displayed one after the other until the list of primaries to display is empty. The actions clauses of all these primaries will not be run, however, until after all the primaries have been processed.

The magic() routine exits only after all the primaries have been run up through their actions, or unless one of the following conditions occurs:

- $qw->{'one_pass'} == 1
- $qw->{'generator'}{'one_pass'} == 1

By default, some of the stateless generators (HTML) will set their one_pass option automatically since it is expected that the client will exit the magic() loop and return later with the next set of data to process. The magic() routine will automatically restart where it left off if the last set of primaries being displayed was never finished. This is common for stateless generators like HTTP and HTML.

$qw->add_todos([options], primary_name, ...);

Adds a primary to the list of screens to display to the user. This function should be called during the post_answers section of a primary. Options that can be passed before the first primary name are:

-early

Adds the primaries in question as early as possible in the todo list (next, unless trumped by future calls.) This is the default.

-late

Adds the primary to the end of the list of primaries to call, such that it is called last, unless another call to add_todos() appends something even later.

-actionslast

All the actions of subsequent primaries that have been added as the result of a current primary's post_answers clauses are called before the actions for the current primary. This means that the actions of any childrens are executed prior to the actions of their parents. This is done by default, as the general usage prediction is that parent primaries are likely to be dependent on the actions of their children in order for their own actions to be successful.

However, this flag indicates that the actions of the childrens' primaries listed in this call are to be called before the current primary's actions.

-merge

Merges all the specified primaries listed into a single screen. This has the effect of having multiple primaries displayed in one window.

Important note: you can not use both -remap (see below) and -merge at the same time! This will break the remapping support and you will not get expected results!

-remap => 'NAME'

If a series of questions must be called repeatedly, you can use this flag to remap the names of the child primary questions to begin with this prefix. The children's clauses (questions, actions, post_answers, etc.) will be called in such a way that they can be oblivious to the fact this is being done behind their backs, allowing qwparam() to work as expected. However, for the current primary (and any parents), the 'NAME' prefix will be added to the front of any question name values that the child results in defining.

This is rather complex and is better illustrated through an example. There is an example that illustrates this in the QWizard Perl module source code examples directory, in the file number_adding.pl. This code repeatedly asks for numbers from the user using the same primary.

Important note: you can not use both -remap and -merge at the same time! This will break the remapping support and you will not get expected results!

$qw->add_primary(key => value, key => value);

Adds a primary definition into the existing primary data set for the QWizard object. One key value pair MUST be a 'name' => 'NAME' pair, where NAME will be the installed primary name for later referral (e.g., in add_todos() calls.) If a name collision takes place (a primary already exists under the given name), the original is kept and the new is not installed.

$qw->merge_primaries(\%new_primaries);

Merges a new set of primaries into the existing set. If a name collision takes place, the original is kept and the new is not installed.

$qw->get_primary('NAME');

Returns a primary definition given its NAME.

$val = $qw->qwparam('NAME')

$val = qwparam('NAME')

$qw->qwparam('NAME', 'VALUE')

qwparam('NAME', 'VALUE')

Retrieves a value specified by NAME that was submitted by a user from a QWizard widget. If a VALUE is specified as a second argument, it replaces the previous value with the new for future calls.

QWizard parameters are accessible until the last screen in which all the actions are run and the results are displayed. Parameters are not retained across primary execution.

The qwparam() function is exported by the QWizard module by default, so the function shouldn't need to be called directly from the QWizard object. Thus, just calling qwparam('NAME') by itself will work.

$val = $qw->qwpref('NAME')

$val = qwpref('NAME')

$qw->qwpref('NAME', 'VALUE')

qwpref('NAME', 'VALUE')

qwpref() acts almost identically to qwparam(), except that it is expected to be used for "preferences" -- hence the name. The preferences are stored persistently across primary screens, unlike parameters. Preferences are not erased between multiple passes through the QWizard screens. (In the HTML generator, they are implemented using cookies).

HOOKS

TBD: Document the $qw->add_hook and $qw->run_hooks methods that exist.

(basically $qw->add_hook('start_magic', \&coderef) will run coderef at the start of the magic function. Search the QWizard code for run_hooks for a list of hook spots available.

DEBUGGING

The variable $QWizard::qwdebug controls debugging output from QWizard. If set to 1, it dumps processing information to STDERR. This can be very useful when debugging QWizard scripts as it displays the step-by-step process about how QWizard is processing information.

Additionally, a qwdebug_set_output() function exists which can control the debugging output destination. Its argument should be a reference to a variable where the debugging output will be stored. Thus, debugging information can be stored to a previously opened error log file by doing the following:

our $dvar;
$QWizard::qwdebug = 1;
$qw->qwdebug_set_output(\$dvar);
$qw->magic('stuff');
print LOGFILE $dvar;

EXAMPLES

There are a few usage examples in the examples directory of the source package. These examples can be run from the command line or installed as a CGI script without modification. They will run as a CGI script if run from a web server, or will launch a Gtk2 or Tk window if run from the command line.

EXPORT

qwparam(), qwpref()

qw_required_field(), qw_integer(), qw_optional_integer(), qw_check_int_ranges(), qw_check_length_ranges(), qw_hex(), qw_optional_hex(), qw_check_hex_and_length()

AUTHOR

Wes Hardaker, hardaker@users.sourceforge.net

SEE ALSO

For extra information, consult the following manual pages:

QWizard_Widgets

Manual page for more information about the Various QWizard display generators and the questions and arguments that each one supports. This page is actually generated from what the generator actually advertises that it supports.

QWizard::API

If you get tired of typing anonymous hash references, this API set will let you generate some widgets with less typing by using APIs instead.

Example API call:

perl -MQWizard::API -MData::Dumper -e 'print Dumper(qw_checkbox("my ?","it",'A','B', default => 'B'));'
$VAR1 = {
        'text' => 'it',
        'name' => 'my ?',
        'default' => 'B',
        'values' => [
                      'A',
                      'B'
                    ],
        'type' => 'checkbox'
      };

Net-Policy: http://net-policy.sourceforge.net/

The entire QWizard system was created to support a multiple-access-point network management system called "Net-Policy" and the SVN repository for Net-Policy actually contains the QWizard development tree.

cpanm QWizard

perl -MCPAN -e shell
install QWizard