view release on metacpan or  search on metacpan

lib/CGI/WebToolkit.pm  view on Meta::CPAN

CGI::WebToolkit will try one module after another until it has found the
subroutine named I<my_tiny_function> and then calls it.











=head2 Methods for session management

Session data is data that is stored on the server side and can be accessed
throughout several webpage requests. In the CGI::WebToolkit the session is a flat hash
of arbitrary data that is stored in the database or a flat file.

In order to identify the session, a session id is used. This session id
has to be submitted by the client for each request, either through a 
cookie, a POST variable or a GET variable. The name of this variable
is usually I<sid>, but can be configured. CGI::WebToolkit takes automaticly care of
that the session id is submitted via links and form submits to
the application script.

To group certain session data entries, usually a dot-based notation is used,
e.g. I<my_workflow.my_name>. This method is stronlgy recommended as well
as limiting the amount of session entries to the absolute minimum.

When the CGI::WebToolkit instance is created, the session is loaded automaticly and
can be accessed through the following methods:

=head3 get()

	my $value = $wtk->get( "my_name" );

=head3 set()

	$wtk->set( "my_name", "value" );

=head3 unset()

This method removes the entry from the session. When you try to
retrieve the entry's value afterwards, you will get an undefined
value.

	$wtk->set( "my_name" );







=head2 Methods for template management

By definition a template is something that contains placeholders that
are replaced by actual values when the template is I<filled>. In CGI::WebToolkit
a template is a function that returns any kind of string, usually
that would be XHTML or XML.

=head3 fill()

The fill() method fills a hash of data into a template by replacing
the placeholders inside the template with actual values. Here are
some examples for fill() calls:

	my $name1 = 'group.subgroup.name';
	my $name2 = 'othername';
	
	my $hash = { 'title' => "...", -info => "..." };
	
	my $string1 = $wtk->fill( $name1,   $hash );
	my $string2 = $wtk->fill( $name2, [ $hash, $hash ] );

The first parameter to the fill() method is
the name of the template. See below for details on template names.

The second parameter to the fill() method is the hash with
the actual information. The values inside the hash are (usually)
all strings. If an array (reference) of multiple hashs is supplied,
the template is loaded for each hash and the final result is the
concatenation of the filled templates.

When the information is filled into the template, each placeholder
is replaced with the value of the key of the same name, e.g.
the hash key I<info> provides the value for the placeholder I<info>.
Inside the template the placeholders are usually noted inside
curly brackets. Here is an example of a template:

	<h1>{title}</h1>
	<p>{info}</p>

The hash keys can be noted in any case with an optional dash at
the beginning in order to allow easy notation, e.g. the hash
keys I<Info>, I<-info>, I<-InFO> etc. refer to the same
placeholder I<info>.


=head3 Template names and themes

In CGI::WebToolkit Themes are sets of templates. Each theme has its own subdirectory
inside the I<templates> directory. These theme directories can
contain more subdirectories to group templates semantically.

Here some examples fof valid names and the corresponding
template files, assuming the template fallback is set to
I<myproject> as the first theme and I<core> as the second theme:

	my $name1 = 'page';      # "<private-path>/templates/myproject/page.html"
	my $name2 = 'form.text'; # "<private-path>/templates/core/form/text.html"

Each dot in the name is converted to a slash to form the
final template filename. Then the fallback theme directories are
sequentially checked for a file with that name and the first
match is used as the template file.

If you want to load the template from a specific theme, you
can use the following syntax:

	# This will load from the "core" theme
	my $string1 = $wtk->fill( 'core:form.date', @data );
	
	# This will load from the theme that is first
	# defined inside the fallback hierarchy of themes
	my $string2 = $wtk->fill( 'form.date', @data );


=head3 Generator functions

If no template could be found using the theme fallbacks declared
in the configuration (s.a.), then a generator function of that
name is called.

[...]


=head3 Common template placeholders

The following placeholders are always available and can therefor
be used in any template loaded with the fill() method:

B<{script_url}>

The URL of the script executable, including the script name.

B<{public_url}>

The URL of the public directory.

B<{clear}>

The special XHTML snippet <div class="clear"></div>

B<{do_nothing_url}>

This URL can be used in Links that should do nothing.
It containts the Javascript snippet javascript:void(1);

B<{javascript_url}>

This URL points to the special core workflow function I<core.combine.javascript>
and therefor points to a combined javascript.

B<{css_url}>

This URL points to the special core workflow function I<core.combine.css>
and therefor points to a combined stylesheet.


=head3 Default placeholder values

Any placeholders in a template that have not been filled, are
by default replaced with an empty string. Sometimes you want to
have a special default value instead of the empty string.
Example:

	<b>{title:This is the default title}</b>


=head3 Simplified calling of fill()

To make it visually clearer what template is filled, there is an
alternative way of calling the fill() method. The following
statements mean the same:

	my $string = $wtk->fill('form.date', {-month => '...', -year => '...'});
	
	my $string = $wtk->FormDate(-month => '...', -year => '...');

Using the general method of using the functional style of
invocation, this even gets shorter:

	my $string = FormDate(-month => '...', -year => '...');

In case you want the template from a specific theme, use this
syntax for the functional invocation:

	my $string = Core_FormDate(-month => '...', -year => '...');


=head3 Template Macros

Template macros are a way of loading templates from within
templates.

For example, if you want to create a general piece of markup
that is considered "a box", you wish you were able to
keep this markup in one place and use it from anywhere else
in other templates. That is what these macros are for.

Example of a box markup: