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

FreeBSD Manual Pages

  
 
  

home | help
CGI::Ex(3)	      User Contributed Perl Documentation	    CGI::Ex(3)

NAME
       CGI::Ex - CGI utility suite - makes powerful application	writing	fun
       and easy

VERSION
       version 2.50

CGI::Ex	SYNOPSIS
	   ### You probably don't want to use CGI::Ex directly
	   ### You probably should use CGI::Ex::App instead.

	   my $cgix = CGI::Ex->new;

	   $cgix->print_content_type;

	   my $hash = $cgix->form;

	   if ($hash->{'bounce'}) {

	       $cgix->set_cookie({
		   name	 => ...,
		   value => ...,
	       });

	       $cgix->location_bounce($new_url_location);
	       exit;
	   }

	   if (scalar keys %$form) {
		my $val_hash = $cgix->conf_read($pathtovalidation);
		my $err_obj = $cgix->validate($hash, $val_hash);
		if ($err_obj) {
		    my $errors	= $err_obj->as_hash;
		    my $input	= "Some	content";
		    my $content	= "";
		    $cgix->swap_template(\$input, $errors, $content);
		    $cgix->fill({text => \$content, form => $hashref});
		    print $content;
		    exit;
		} else {
		    print "Success";
		}
	   } else {
		print "Main page";
	   }

DESCRIPTION
       CGI::Ex provides	a suite	of utilities to	make writing CGI scripts more
       enjoyable.  Although they can all be used separately, the main
       functionality of	each of	the modules is best represented	in the
       CGI::Ex::App module.  CGI::Ex::App takes	CGI application	building to
       the next	step.  CGI::Ex::App is not quite a framework (which normally
       includes	pre-built html)	instead	CGI::Ex::App is	an extended
       application flow	that dramatically reduces CGI build time in most
       cases.  It does so using	as little magic	as possible.  See
       CGI::Ex::App.

       The main	functionality is provided by several other modules that	may be
       used separately,	or together through the	CGI::Ex	interface.

       "CGI::Ex::Template"
	   A Template::Toolkit compatible processing engine.  With a few
	   limitations,	CGI::Ex::Template can be a drop	in replacement for
	   Template::Toolkit.

       "CGI::Ex::Fill"
	   A regular expression	based form filler inner	(accessed through
	   ->fill or directly via its own functions).  Can be a	drop in
	   replacement for HTML::FillInForm.  See CGI::Ex::Fill	for more
	   information.

       "CGI::Ex::Validate"
	   A form field	/ cgi parameter	/ any parameter	validator (accessed
	   through ->validate or directly via its own methods).	 Not quite a
	   drop	in for most validators,	although it has	most of	the
	   functionality of most of the	validators but with the	key additions
	   of conditional validation.  Has a tightly integrated	JavaScript
	   portion that	allows for duplicate client side validation.  See
	   CGI::Ex::Validate for more information.

       "CGI::Ex::Conf"
	   A general use configuration,	or settings, or	key / value file
	   reader.  Has	ability	for providing key fallback as well as
	   immutable key definitions.  Has default support for yaml, storable,
	   perl, ini, and xml and open architecture for	definition of others.
	   See CGI::Ex::Conf for more information.

       "CGI::Ex::Auth"
	   A highly configurable web based authentication system.  See
	   CGI::Ex::Auth for more information.

CGI::Ex	METHODS
       "->fill"
	   fill	is used	for filling hash or cgi	object values into an existing
	   html	document (it doesn't deal at all with how you got the
	   document).  Arguments may be	given as a hash, or a hashref or
	   positional.	Some of	the following arguments	will only work using
	   CGI::Ex::Fill - most	will work with either CGI::Ex::Fill or
	   HTML::FillInForm (assume they are available unless specified
	   otherwise).	(See CGI::Ex::Fill for a full explanation of
	   functionality).  The	arguments to fill are as follows (and in order
	   of position):

	   "text"
	       Text should be a	reference to a scalar string containing	the
	       html to be modified (actually it	could be any reference or
	       object reference	that can be modified as	a string).  It will be
	       modified	in place.  Another named argument scalarref is
	       available if you	would like to copy rather than modify.

	   "form"
	       Form may	be a hashref, a	cgi style object, a coderef, or	an
	       array of	multiple hashrefs, cgi objects,	and coderefs.  Hashes
	       should be key value pairs.  CGI objects should be able to call
	       the method param	(This can be overrided).  Coderefs should
	       expect the field	name as	an argument and	should return a	value.
	       Values returned by form may be undef, scalar, arrayref, or
	       coderef (coderef	values should expect an	argument of field name
	       and should return a value).  The	code ref options are available
	       to delay	or add options to the bringing in of form information
	       - without having	to tie the hash.  Coderefs are not available
	       in HTML::FillInForm.  Also HTML::FillInForm only	allows CGI
	       objects if an arrayref is used.

	       NOTE: Only one of the form, fdat, and fobject arguments are
	       allowed at a time.

	   "target"
	       The name	of the form that the fields should be filled to.  The
	       default value of	undef, means to	fill in	all forms in the html.

	   "fill_passwords"
	       Boolean value defaults to 1.  If	set to zero - password fields
	       will not	be filled.

	   "ignore_fields"
	       Specify which fields to not fill	in.  It	takes either array ref
	       of names, or a hashref with the names as	keys.  The hashref
	       option is not available in CGI::Ex::Fill.

	   Other named arguments are available for compatibility with
	   HTML::FillInForm.  They may only be used as named arguments.

	   "scalarref"
	       Almost the same as the argument text.  If scalarref is used,
	       the filled html will be returned.  If text is used the html
	       passed is filled	in place.

	   "arrayref"
	       An array	ref of lines of	the document.  Forces a	returned
	       filled html document.

	   "file"
	       An filename that	will be	opened,	filled,	and returned.

	   "fdat"
	       A hashref of key	value pairs.

	   "fobject"
	       A cgi style object or arrayref of cgi style objects used	for
	       getting the key value pairs.  Should be capable of the ->param
	       method and ->cookie method as document in CGI.

	   See CGI::Ex::Fill for more information about	the filling process.

       "->object"
	   Returns the CGI object that is currently being used by CGI::Ex.  If
	   none	has been set it	will automatically generate an object of type
	   $PREFERRED_CGI_MODULE which defaults	to CGI.

       "->validate"
	   Validate has	a wide range of	options	available. (See
	   CGI::Ex::Validate for a full	explanation of functionality).
	   Validate has	two arguments:

	   "form"
	       Can be either a hashref to be validated,	or a CGI style object
	       (which has the param method).

	   "val_hash"
	       The val_hash can	be one of three	items.	First, it can be a
	       straight	perl hashref containing	the validation to be done.
	       Second, it can be a YAML	document string.  Third, it can	be the
	       path to a file containing the validation.  The validation in a
	       validation file will be read in depending upon file extension.

       "->get_form"
	   Very	similar	to CGI->new->Vars except that arrays are returned as
	   arrays.  Not	sure why CGI didn't do this anyway (well - yes -
	   legacy Perl 4 - but at some point things need to be updated).

	       my $hash	= $cgix->get_form;
	       my $hash	= $cgix->get_form(CGI->new);
	       my $hash	= get_form();
	       my $hash	= get_form(CGI->new);

       "->set_form"
	   Allow for setting a custom form hash.  Useful for testing, or other
	   purposes.

	       $cgix->set_form(\%new_form);

       "->get_cookies"
	   Returns a hash of all cookies.

	       my $hash	= $cgix->get_cookies;
	       my $hash	= $cgix->get_cookies(CGI->new);
	       my $hash	= get_cookies();
	       my $hash	= get_cookies(CGI->new);

       "->set_cookies"
	   Allow for setting a custom cookies hash.  Useful for	testing, or
	   other purposes.

	       $cgix->set_cookies(\%new_cookies);

       "->make_form"
	   Takes a hash	and returns a query_string.  A second optional
	   argument may	contain	an arrayref of keys to use from	the hash in
	   building the	query_string.  First argument is undef,	it will	use
	   the form stored in itself as	the hash.

       "->content_type"
	   Can be called multiple times	during the same	session.  Will only
	   print content-type once.  (Useful if	you don't know if something
	   else	already	printed	content-type).	Calling	this sends the
	   Content-type	header.	 Trying	to print ->content_type	is an error.
	   For clarity,	the method ->print_content_type	is available.

	       $cgix->print_content_type;

	       # OR
	       $cgix->print_content_type('text/html');

	       # OR
	       $cgix->print_content_type('text/html', 'utf-8');

       "->set_cookie"
	   Arguments are the same as those to CGI->new->cookie({}).  Uses
	   CGI's cookie	method to create a cookie, but then, depending on if
	   content has already been sent to the	browser	will either print a
	   Set-cookie header, or will add a <meta http-equiv='set-cookie'> tag
	   (this is supported on most major browsers).	This is	useful if you
	   don't know if something else	already	printed	content-type.

       "->location_bounce"
	   Depending on	if content has already been sent to the	browser	will
	   either print	a Location header, or will add a <meta
	   http-equiv='refresh'> tag (this is supported	on all major
	   browsers).  This is useful if you don't know	if something else
	   already printed content-type.  Takes	single argument	of a url.

       "->last_modified"
	   Depending on	if content has already been sent to the	browser	will
	   either print	a Last-Modified	header,	or will	add a <meta
	   http-equiv='Last-Modified'> tag (this is supported on most major
	   browsers).  This is useful if you don't know	if something else
	   already printed content-type.  Takes	an argument of either a	time
	   (may	be a CGI -expires style	time) or a filename.

       "->expires"
	   Depending on	if content has already been sent to the	browser	will
	   either print	a Expires header, or will add a	<meta
	   http-equiv='Expires'> tag (this is supported	on most	major
	   browsers).  This is useful if you don't know	if something else
	   already printed content-type.  Takes	an argument of a time (may be
	   a CGI -expires style	time).

       "->send_status"
	   Send	a custom status.  Works	in both	CGI and	mod_perl.  Arguments
	   are a status	code and the content (optional).

       "->send_header"
	   Send	a http header.	Works in both CGI and mod_perl.	 Arguments are
	   a header name and the value for that	header.

       "->print_js"
	   Prints out a	javascript file.  Does everything it can to make sure
	   that	the javascript will cache.  Takes either a full	filename, or a
	   shortened name which	will be	looked for in @INC. (ie
	   /full/path/to/my.js or CGI/Ex/validate.js or	CGI::Ex::validate)

	       #!/usr/bin/perl
	       use CGI::Ex;
	       CGI::Ex->print_js($ENV{'PATH_INFO'});

       "->swap_template"
	   This	is intended as a simple	yet strong subroutine to swap in tags
	   to a	document.  It is intended to be	very basic for those who may
	   not want the	full features of a Templating system such as
	   Template::Toolkit (even though they should investigate them because
	   they	are pretty nice).  The default allows for basic	template
	   toolkit variable swapping.  There are two arguments.	 First is a
	   string or a reference to a string.  If a string is passed, a	copy
	   of that string is swapped and returned.  If a reference to a	string
	   is passed, it is modified in	place.	The second argument is a form,
	   or a	CGI object, or a cgiex object, or a coderef (if	the second
	   argument is missing,	the cgiex object which called the method will
	   be used).  If it is a coderef, it should accept key as its only
	   argument and	return the proper value.

	     my	$cgix =	CGI::Ex->new;
	     my	$form =	{foo  => 'bar',
			 this => {is =>	{nested	=> ['wow', 'wee']}}
			};

	     my	$str =	$cgix->swap_template("<html>[% foo %]<br>[% foo	%]</html>", $form));
	     # $str eq '<html>bar<br>bar</html>'

	     $str = $cgix->swap_template("[% this.is.nested.1 %]", $form));
	     # $str eq 'wee'

	     $str = "[%	this.is.nested.0 %]";
	     $cgix->swap_template(\$str, $form);
	     # $str eq 'wow'

	     # may also	be called with only one	argument as follows:
	     # assuming	$cgix had a query string of ?foo=bar&baz=wow&this=wee
	     $str = "<html>([% foo %]) <br>
		     ([% baz %]) <br>
		     ([% this %]) </html>";
	     $cgix->swap_template(\$str);
	     #$str eq "<html>(bar) <br>
	     #	      (wow) <br>
	     #	      (wee) </html>";

	   For further examples, please	see the	code contained in
	   t/samples/cgi_ex_* of this distribution.

	   If at a later date, the developer upgrades to Template::Toolkit,
	   the templates that were being swapped by CGI::Ex::swap_template
	   should be compatible	with Template::Toolkit.

MODULES
       See also	CGI::Ex::App.

       See also	CGI::Ex::Auth.

       See also	CGI::Ex::Conf.

       See also	CGI::Ex::Die.

       See also	CGI::Ex::Dump.

       See also	CGI::Ex::Fill.

       See also	CGI::Ex::Template.

       See also	CGI::Ex::Validate.

LICENSE
       This module may be distributed under the	same terms as Perl itself.

AUTHOR
       Paul Seamons <perl at seamons dot com>

perl v5.32.1			  2020-07-08			    CGI::Ex(3)

NAME | VERSION | CGI::Ex SYNOPSIS | DESCRIPTION | CGI::Ex METHODS | MODULES | LICENSE | AUTHOR

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

home | help