__PACKAGE__->navigate;
- sub base_dir_abs { '/var/www/templates' }
+ sub template_path { '/var/www/templates' }
-------- File: /var/www/templates/my_cgi/main.html --------
__PACKAGE__->navigate;
- sub base_dir_abs { '/var/www/templates' }
+ sub template_path { '/var/www/templates' }
sub main_hash_swap {
my $self = shift;
__PACKAGE__->navigate;
- sub base_dir_abs { '/var/www/templates' }
+ sub template_path { '/var/www/templates' }
sub main_hash_swap { {date => sub { scalar localtime }} }
There are infinite possibilities. There is a longer "SYNOPSIS" after
the process flow discussion and more examples near the end of this
document. It is interesting to note that there have been no databases
-so far. CGI::Ex::App is Controller/Viewer that is somewhat Model
-agnostic.
+so far. It is very, very difficult to find a single database
+abstraction that fits every model. CGI::Ex::App is Controller/Viewer
+that is somewhat Model agnostic and doesn't come with any default
+database abstraction.
=head1 DESCRIPTION
run_step {
->pre_step (hook)
- # exits nav_loop if true
+ # skips this step if true and exit nav_loop
->skip (hook)
- # skips this step if true (stays in nav_loop)
+ # skips this step if true and stays in nav_loop
->prepare (hook - defaults to true)
->info_complete (hook - ran if prepare was true)
->ready_validate (hook)
- return false if ! ready_validate
+ # returns false from info_complete if ! ready_validate
->validate (hook - uses CGI::Ex::Validate to validate form info)
->hash_validation (hook)
->file_val (hook)
- ->base_dir_abs
+ ->vob_path (defaults to template_path)
->base_dir_rel
->name_module
->name_step
->ext_val
- returns true if validate is true or if nothing to validate
+ # returns true if validate is true or if nothing to validate
->finalize (hook - defaults to true - ran if prepare and info_complete were true)
=over 4
-=item base_dir_abs
+=item template_path
-Absolute path or arrayref of paths to the base templates directory. Default "".
+Absolute path or arrayref of paths to the base templates directory. Defaults to
+base_dir_abs which defaults to ['.'].
=item base_dir_rel
-Relative path inside of the base_dir_abs directory where content can be found. Default "".
+Relative path inside of the template_path directory where content can be found. Default "".
=item name_module
In this example we would most likely set values as follows:
- base_dir_abs /home/user/templates
+ template_path /home/user/templates
base_dir_rel content
name_module my_app
the user has requested is "step1" then the following values would be
returned:
- base_dir_abs /home/user/templates
+ template_path /home/user/templates
base_dir_rel content
name_module my_app
name_step step1
the following:
my $t = $self->template_obj({
- INCLUDE_PATH => $self->base_dir_abs,
+ INCLUDE_PATH => $self->template_path, # defaults to base_dir_abs
});
$t->process($self->file_print($step), \%vars);
The template engine would then look for the relative file
-inside of the absolute paths (from base_dir_abs).
+inside of the absolute paths (from template_path).
The call to the validation engine would pass the absolute
filename that is returned by file_val.
additional directories included. The previous example could
also have been setup using the following values:
- base_dir_abs /home/user/templates
+ template_path /home/user/templates
base_dir_rel
name_module content/my_app
=item base_dir_abs (method)
-Used as the absolute base directory to find template files and validation files.
+Used as the absolute base directory to find template, validation and conf files.
It may return a single value or an arrayref of values, or a coderef that
returns an arrayref or coderef of values. You may pass base_dir_abs
as a parameter in the arguments passed to the "new" method.
-Default value is "".
+Default value is ['.'].
For example, to pass multiple paths, you would use something
similar to the following:
return ['/my/path/one', '/some/other/path'];
}
-The base_dir_abs value is used along with the base_dir_rel, name_module,
-name_step, ext_print and ext_values for determining the values
-returned by the default file_print and file_val hooks. See those methods
-for further discussion.
+The base_dir_abs value is used by template_path along with the
+base_dir_rel, name_module, name_step, ext_print and ext_values for
+determining the values returned by the default file_print and file_val
+hooks. See those methods for further discussion.
See the section on FINDING TEMPLATES for further discussion.
+The base_dir_abs method is also used as the default value for conf_path and vob_path.
+
=item base_dir_rel (method)
Added as a relative base directory to content under the base_dir_abs directory.
Default value is "".
-The base_dir_abs method is used as top level where template includes may
-pull from, while the base_dir_rel is directory relative to the base_dir_abs
+The template_path method is used as top level where template includes may
+pull from, while the base_dir_rel is directory relative to the template_path
where the content files will be stored.
A value for base_dir_rel may passed as a parameter in the arguments passed
to the new method.
-See the base_dir_abs method for more discussion.
+See the template_path and base_dir_abs methods for more discussion.
See the section on FINDING TEMPLATES for further discussion.
path
path_i
history
- __morph_lineage_start_index
- __morph_lineage
+ _morph_lineage_start_index
+ _morph_lineage
hash_errors
hash_fill
hash_swap
hash_common
+=item conf (method)
+
+Used by default in init_from_conf if load_conf returns true.
+Will try to read the file returned by the conf_file method
+using the object returned by conf_obj using that object's read
+method. If conf_validation returns a non-empty hashref, the
+conf hash will be validated using $self->vob->validate (see the
+validate method).
+
+This method may be used for other purposes as well (including when
+load_conf is false)..
+
+Caches results in $self->{'conf'}.
+
+=item conf_file (method)
+
+Used by conf for finding the configuration file to load. Defaults
+to $self->{'conf_file'} which defaults $self->name_module with the extention
+returned by $self->conf_ext added on. For example, if name_module
+returns "my_app" and conf_ext returns "ini" the value returned will
+be "my_app.ini".
+
+The value returned can absolute. If the value will be searched for
+in the paths passed to conf_obj.
+
+The conf_ext may be any of those extentions understood by CGI::Ex::Conf.
+
+=item conf_ext
+
+Used by the default conf_file method. Defaults to $self->{'conf_ext'} which
+defaults to 'pl' meaning that the read configuration file should return a
+valid perl hashref.
+
+=item conf_obj
+
+Used by the conf method to load the file returned by conf_file. Defaults
+to conf_obj which defaults to loading args from conf_args, adding in paths
+returned by conf_path, and calling CGI::Ex::Conf->new.
+
+Any object that provides a read method that returns a hashref can be used.
+
+=item conf_path
+
+Defaults to $self->{'conf_path'} which defaults to base_dir_abs. Should be
+a path or an arrayref of paths to look the configuration file returned by
+conf_file when that file is not absolute.
+
+=item conf_args
+
+Used by conf_obj.
+
+Defaults to $self->{'conf_args'} which defaults to {}. Will have
+paths => $self->conf_path added before passing to CGI::Ex::Conf->new.
+
+=item conf_validation
+
+Used by default conf method.
+Defaults to an empty hashref. If non-empty hashref is passed, the
+hashref returned by conf_obj->read will be validated using the hashref
+returned by conf_validation.
+
=item current_step (method)
Returns the current step that the nav_loop is functioning on.
" view - post_print - post_print - 0.00003 - 0"
];
+=item error_step (method)
+
+Defaults to "__error". The name of a step to run should a dying error
+be caught by the default handle_error method. See the handle_error method.
+
=item exit_nav_loop (method)
This method should not normally used but there is no problem with
See the section on FINDING TEMPLATES for further discussion.
-=item first_step (method)
-
-Returns the first step of the path. Note that first_step may not be the same
-thing as default_step if the path was overridden.
-
-=item form (method)
-
-Returns a hashref of the items passed to the CGI. Returns
-$self->{form} which defaults to CGI::Ex::get_form.
-
-=item handle_error (method)
-
-If anything dies during execution, handle_error will be called with
-the error that had happened. Default action is to die with that error.
-
-=item history (method)
-
-Returns an arrayref which contains trace history of which hooks of
-which steps were ran. Useful for seeing what happened. In general -
-each line of the history will show the current step, the hook
-requested, and which hook was actually called.
-
-The dump_history method shows a short condensed version of this
-history which makes it easier to see what path was followed.
-
-In general, the arrayref is free for anything to push onto which will
-help in tracking other occurrences in the program as well.
-
-=item init (method)
-
-Called by the default new method. Allows for any object
-initilizations that may need to take place. Default action does
-nothing.
-
=item fill_args (hook)
Returns a hashref of args that will be passed to the CGI::Ex::Fill::fill.
hook. Adds method base_dir_rel to hook name_module, and name_step and
adds on the default file extension found in $self->ext_print which
defaults to the property $self->{ext_print} which will default to
-".html". Should return a filename relative to base_dir_abs that can be
+".html". Should return a filename relative to template_path that can be
swapped using Template::Alloy, or should be a scalar reference to
the template content that can be swapped. This will be used by the
hook print.
- sub base_dir_abs { '/var/www/templates' }
- sub base_dir_rel { 'content' }
- sub name_module { 'recipe' }
- sub ext_print { 'html' } # default
+ sub template_path { '/var/www/templates' }
+ sub base_dir_rel { 'content' }
+ sub name_module { 'recipe' }
+ sub ext_print { 'html' } # default
# ->file_print('this_step')
# would return 'content/recipe/this_step.html'
=item file_val (hook)
-Returns a filename containing the validation. Performs the same
-as file_print, but uses ext_val to get the extension, and it adds
-base_dir_abs onto the returned value (file_print is relative to
-base_dir_abs, while file_val is fully qualified with base_dir_abs).
-If base_dir_abs returns an arrayref of paths, then each path is
-checked for the existence of the file.
+Returns a filename containing the validation. Performs the same as
+file_print, but uses ext_val to get the extension, and it adds
+vob_path (which defaults to template_path which defaults to
+base_dir_abs) onto the returned value (file_print is relative to
+template_path, while file_val is fully qualified with vob_path). If
+vob_path returns an arrayref of paths, then each path is checked for
+the existence of the file.
The file should be readable by CGI::Ex::Validate::get_validation.
This hook is only necessary if the hash_validation hook has not been
overridden.
-
+5B
This method an also return a hashref containing the validation - but
then you may have wanted to override the hash_validation hook.
See the run_hook method and the morph method for more details.
+=item first_step (method)
+
+Returns the first step of the path. Note that first_step may not be the same
+thing as default_step if the path was overridden.
+
=item forbidden_step (method)
Defaults to "__forbidden". The name of a step to run should the current
step name be invalid, or if a step found by the default path method
is invalid. See the path method.
+=item form (method)
+
+Returns a hashref of the items passed to the CGI. Returns
+$self->{form} which defaults to CGI::Ex::get_form.
+
=item form_name (hook)
Return the name of the form to attach the js validation to. Used by
be done via the auth_args hash. See the auth_args method and
CGI::Ex::Auth perldoc for more information.
+=item handle_error (method)
+
+If anything dies during execution, handle_error will be called with
+the error that had happened. Default action is to try running the
+step returned by the error_step method.
+
=item hash_base (hook)
A hash of base items to be merged with hash_form - such as pulldown
returned or if the get_validation fails, an empty hash will be returned.
Validation is implemented by ->vob which loads a CGI::Ex::Validate object.
+=item history (method)
+
+Returns an arrayref which contains trace history of which hooks of
+which steps were ran. Useful for seeing what happened. In general -
+each line of the history will show the current step, the hook
+requested, and which hook was actually called.
+
+The dump_history method shows a short condensed version of this
+history which makes it easier to see what path was followed.
+
+In general, the arrayref is free for anything to push onto which will
+help in tracking other occurrences in the program as well.
+
=item info_complete (hook)
Calls the ready_validate hook to see if data is ready to validate. If
sure the data is ready and valid. Will not be run unless
prepare returns true (default).
+=item init (method)
+
+Called by the default new method. Allows for any object
+initilizations that may need to take place. Default action does
+nothing.
+
+=item init_from_conf (method)
+
+Called by the default new method. If load_conf is true, then the
+conf method will be called and the keys returned will be added to
+the $self object.
+
+This method is called after the init method. If you need to further
+fix up values added during init_from_conf, you can use the pre_navigate
+method.
+
=item insert_path (method)
Arguments are the steps to insert. Can be called any time. Inserts
Returns the last step of the path. Can be used to jump to the last step.
+=item load_conf (method)
+
+Defaults to ->{load_conf} which defaults to false. If true, will
+allow keys returned by the conf method to be added to $self during
+the init_from_conf method.
+
+Enabling this method allows for out-of-the-box file based configuration.
+
=item morph (method)
Allows for temporarily "becoming" another object type for the
=item print (hook)
-Take the information generated by prepared_print, format it, and print
-it out. Default incarnation uses CGI::Ex::Template (a subclass of
-Template::Alloy) which is compatible with Template::Toolkit.
-Arguments are: step name (used to call the file_print hook), swap
-hashref (passed to call swap_template), and fill hashref (passed to
-fill_template).
+Take the information generated by prepared_print, format it using
+swap_template, fill it using fill_template and print it out using
+print_out. Default incarnation uses CGI::Ex::Template (a subclass of
+Template::Alloy) which is compatible with Template::Toolkit to do the
+swapping. Arguments are: step name (used to call the file_print
+hook), swap hashref (passed to call swap_template), and fill hashref
+(passed to fill_template).
During the print call, the file_print hook is called which should
return a filename or a scalar reference to the template content is
+=item print_out (hook)
+
+Called with the finished document. Should print out the appropriate headers.
+The default method calls $self->cgix->print_content_type and then
+prints the content.
+
+The print_content_type is passed $self->mimetype (which defaults to
+$self->{'mimetype'} which defaults to 'text/html') and $self->charset
+(which defaults to $self->{'charset'} which defaults to '').
+
=item ready_validate (hook)
Should return true if enough information is present to run validate.
Arguments are the template and the swap hashref. The template can be
either a scalar reference to the actual content, or the filename of
the content. If the filename is specified - it should be relative to
-base_dir_abs (which will be used to initialize INCLUDE_PATH by
+template_path (which will be used to initialize INCLUDE_PATH by
default).
The default method will create a template object by calling the
my $t = HTML::Template->new(source => $file,
type => $type,
- path => $self->base_dir_abs,
+ path => $self->template_path,
die_on_bad_params => 0,
);
Returns a hashref of args that will be passed to the "new" method of CGI::Ex::Template.
The method is normally called from the swap_template hook. The swap_template hook
-will add a value for INCLUDE_PATH which is set equal to base_dir_abs, if the INCLUDE_PATH
+will add a value for INCLUDE_PATH which is set equal to template_path, if the INCLUDE_PATH
value is not already set.
The returned hashref can contain any arguments that CGI::Ex::Template (a subclass of Template::Alloy)
=item template_obj (method)
Called from swap_template. It is passed the result of template_args
-that have had a default INCLUDE_PATH added. The default
+that have had a default INCLUDE_PATH added via template_path. The default
implementation uses CGI::Ex::Template (a subclass of Template::Alloy)
but can easily be changed to use Template::Toolkit by using code
similar to the following:
return Template->new($args);
}
+=item template_path (method)
+
+Defaults to $self->{'template_path'} which defaults to base_dir_abs. Used by
+the template_obj method.
+
=item unmorph (method)
Allows for returning an object back to its previous blessed state if
The following example shows the creation of a basic recipe
database. It requires the use of DBD::SQLite, but that is all.
-Once you have configured the db_file and base_dir_abs methods
+Once you have configured the db_file and template_path methods
of the "recipe" file, you will have a working script that
does CRUD for the recipe table. The observant reader may ask - why
not use Catalyst or Ruby on Rails? The observant programmer will
debug shift->dump_history;
}
- sub base_dir_abs { '/var/www/templates' }
+ sub template_path { '/var/www/templates' }
sub base_dir_rel { 'content' }
Krassimir Berov - feedback and some warnings issues with POD examples.
-=head1 AUTHOR
-
-Paul Seamons <paul at seamons dot com>
-
=head1 LICENSE
This module may be distributed under the same terms as Perl itself.
+=head1 AUTHOR
+
+Paul Seamons <perl at seamons dot com>
+
=cut