Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CGI::FormBuilder::MultUser Contributed Perl DocumentCGI::FormBuilder::Multi(3)

NAME
       CGI::FormBuilder::Multi - Create	multi-page FormBuilder forms

SYNOPSIS
	   use CGI::FormBuilder::Multi;
	   use CGI::Session;   # or something similar

	   # Top-level "meta-form"
	   my $multi = CGI::FormBuilder::Multi->new(

	       # form 1	options
	       { fields	  => [qw(name email daytime_phone evening_phone)],
		 title	  => 'Basic Info',
		 template => 'page1.tmpl',
		 validate => { name => 'NAME', email =>	'EMAIL'	},
		 required => [qw(name email daytime_phone)],
	       },

	       # form 2	options
	       { fields	  => [qw(billing_name billing_card billing_exp
				 billing_address billing_city billing_state
				 billing_zip billing_phone)],
		 title	  => 'Billing',
		 template => 'page2.tmpl',
		 required => 'ALL',
	       },

	       # form 3	options
	       { fields	  => [qw(same_as_billing shipping_address
				 shipping_city shipping_state shipping_zip)],
		 title	  => 'Shipping',
		 template => 'page3.tmpl',
		 required => 'ALL',
	       },

	       # a couple options specific to this module
	       navbar => 1,

	       # remaining options (not	in hashrefs) apply to all forms
	       header => 1,
	       method => 'POST',
	       submit => 'Continue',
	       values => $dbi_hashref_query,
	   );

	   # Get current page's	form
	   my $form = $multi->form;

	   if ($form->submitted	&& $form->validate) {

	       # Retrieve session id
	       my $sid = $form->sessionid;

	       # Initialize session
	       my $session = CGI::Session->new("driver:File", $sid, {Directory=>'/tmp'});

	       # Automatically store updated data in session
	       $session->save_param($form);

	       # last page?
	       if ($multi->page	== $multi->pages) {
		   print $form->confirm;
		   exit;
	       }

	       # Still here, goto next page
	       $multi->page++;

	       # And re-get form (no "my" on $form!)
	       $form = $multi->form;

	       # Make sure it has the right sessionid
	       $form->sessionid($session->id);

	       # on page 3 we have special field handling
	       if ($multi->page	== 3) {
		   $form->field(name	=> 'same_as_billing',
				type	=> 'checkbox',
				options	=> 'Yes',
				jsclick	=> 'this.form.submit()');
	       }
	   }

	   # Fall through and print next page's	form
	   print $form->render;

DESCRIPTION
       This module works with "CGI::FormBuilder" to create multi-page forms.
       Each form is specified using the	same options you would pass directly
       into FormBuilder. See CGI::FormBuilder for a list of these options.

       The multi-page "meta-form" is a composite of the	individual forms you
       specify,	tied together via the special "_page" CGI param. The current
       form is available via the "form()" method, and the current page is
       available via "page()". It's up to you to navigate appropriately:

	   my $multi = CGI::FormBuilder::Multi->new(...);

	   # current form
	   my $form  = $multi->form;

	   $multi->page++;	   # page forward
	   $multi->page--;	   # and back
	   $multi->page	= $multi->pages;   # goto last page

	   # current form
	   $form = $multi->form;

       To make things are fluid	as possible, you should	title each of your
       forms, even if you're using a template. This will allow "::Multi" to
       create cross-links by-name instead of just "Page	2".

METHODS
       The following methods are provided:

   new(\%form1,	\%form2, opt =>	val)
       This creates a new "CGI::FormBuilder::Multi" object. Forms are
       specified as hashrefs of	options, in sequential order, similar to how
       fields are specified. The order the forms are in	is the order that the
       pages will cycle	through.

       In addition to a	hashref, forms can be directly specified as a $form
       object that has already been created. For existing objects, the below
       does not	apply.

       When the	first non-ref argument is seen,	then all remaining args	are
       taken as	common options that apply to all forms.	In this	way, you can
       specify global settings for things like "method"	or "header" (which
       will likely be the same), and then override individual settings like
       "fields"	and "validate" on a per-form basis.

       If you do not wish to specify any options for your forms, you can
       instead just specify the	"pages"	option,	for example:

	   my $multi = CGI::FormBuilder::Multi->new(pages => 3);

       With this approach, you will have to dynamically	assemble each page as
       you come	to them. The mailing list can help.

       The "SYNOPSIS" above is very representative of typical usage.

   form()
       This returns the	current	page's form, as	an object created directly by
       "CGI::FormBuilder->new".	All valid FormBuilder methods and options work
       on the form. To change which form is returned, us "page()".

   page($num)
       This sets and returns the current page. It can accept a page number
       either as an argument, or directly as an	assignment:

	   $multi->page(1);    # page 1
	   $multi->page	= 1;   # same thing

	   $multi->page++;     # next page
	   $multi->page--;     # back one

	   if ($multi->page == $multi->pages) {
	       # last page
	   }

       Hint: Usually, you should only change pages once	you have validated the
       current page's form appropriately.

   pages()
       This returns the	total number of	pages. Actually, what it returns is an
       array of	all forms (and hence it	has the	alias "forms()"), which	just
       so happens to become the	length in a scalar context, just like anywhere
       else in Perl.

   navbar($onoff)
       This returns a navigation bar that allows the user to jump between
       pages of	the form. This is useful if you	want to	let a person fill out
       different pages out of order. In	most cases, you	do not want this, so
       it's off	by default.

       To use it, the best way is setting "navbar => 1"	in "new()".  However,
       you can also get	it yourself to render your own HTML:

	   my $html = $multi->navbar;	   # scalar HTML
	   my @link = $multi->navbar;	   # array of links

       This is useful in something like	this:

	   my $nav = $multi->navbar;
	   $form = $multi->form;
	   $form->tmpl_param(navbar => $navbar);

       The navbar will have two	style classes: "fb_multi_page" for the current
       page's link, and	"fb_multi_link"	for the	others.

SEE ALSO
       CGI::FormBuilder

REVISION
       $Id: Multi.pm 100 2007-03-02 18:13:13Z nwiger $

AUTHOR
       Copyright (c) Nate Wiger	<http://nateware.com>. All Rights Reserved.

       This module is free software; you may copy this under the terms of the
       GNU General Public License, or the Artistic License, copies of which
       should have accompanied your Perl kit.

perl v5.24.1			  2016-08-16	    CGI::FormBuilder::Multi(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | REVISION | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CGI::FormBuilder::Multi&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help