NAME

OpenInteract::UI::Main - The primary user interface assembly 'conductor'

SYNOPSIS

 my $page = OpenInteract::UI::Main->handler();
 send_http_headers();
 print $page;

 # Subclass to define a new method for looking up template names:

 package OpenInteract::UI::LanguageChoice;

 use base qw( OpenInteract::UI::Main );

 my $DEFAULT_LANGUAGE = 'en';

 sub choose_template {
     my ( $class ) = @_;
     my ( $language );
     if ( $R->{auth}{is_logged_in} ) {
         $language = $R->{auth}{user}->language;
     }
     $language ||= $R->apache->param( 'lang' )
                   || $R->{session}{lang}
                   || $DEFAULT_LANGUAGE;
     my $R = OpenInteract::Request->instance;
     my $template = $R->{theme}->property_value( "template_$language" )
                    || $R->{theme}->property_value( 'main_template' );
     return $template;
 }

DESCRIPTION

This is the handler that puts the main content generated together with the template that surrounds the content on every page.

The action has already been parsed from the URL for us so we look up the class/method used to generate the content and call them. We then put that content into the main template which is specified in our theme, unless we have received another directive to use a separate template or no template at all.

Another alternative is that the content handler needs to return a file that is not HTML, such as a PDF, graphic, word processing document, archive, or whatever. If so the content handler should put the complete filename in the $R->{page}->{send_file} key.

A content author can set a main template to use for the generated content by setting:

 $R->{page}{_template_name_}

to the name of the template to use. This should be a fully-qualified template name -- such as 'mypkg::mytemplate'. If you do not specify a package the OI template provider will try to find the template in the global template directory.

You can also set a template that might vary by theme. This is not the name of the template directly but rather a placeholder within the theme which holds the name of the template. For instance, say you created a 'spooky_template' and implemented it in multiple themes. Even though you as an author do not know what theme will be used, you can still pick the right template by setting:

 $R->{page}{_template_key_}

And to use the 'simple' template, the author should set:

 $R->{page}{_simple_}

to a true value. The default 'simple' template is 'base_simple', although you can set its name under the template_names key of your server configuration.

Finally, the author can also set:

 $R->{page}{_no_template_}

to display the content without a template at all.

Main Template Variables

Any content handler can send information to be placed directly onto the main template by setting information using the $R->{main_template_vars} hashref. For instance:

 $R->{main_template_vars}{current_weather} = 'Rainy and cold';

would set the 'current_weather' template variable for display on the main template and not on any of the content handlers.

Note that while this sounds useful (and it can be), you will probably use it only very rarely. The 'boxes' concept is more comprehensive and full-featured and will almost certainly do what you need.

METHODS

handler()

Performs the actions described above. Returns either a single scalar with the full page generated or undef, in which case the information to be sent is likely a non-HTML page that needs to be sent on its own.

choose_template()

Class method to find the template name to wrap the content in. If undef is returned then handler() just returns the raw content. Otherwise we use the return value as the template name.

Here are the steps we execute, in order, to find the main template name:

1. If $R->{page}{_no_template_} is true we return undef.

2. If $R->{page}{_template_name_} is defined we return it.

3. If $R->{page}{_template_key_} is defined we return the value of that key in the current theme.

4. If $R->{page}{_simple_} is defined we return the value of 'simple_template' in the current theme.

5. We return the value of 'main_template' in the current theme.

DIRECTIVES

A directive (or 'page directive') is placed before the relevant action in the URL and tells OpenInteract to display the content in a certain manner. The directive should have been parsed out in the main content handler (OpenInteract.pm).

For instance:

 /Popup/User/show/?user_id=716

Says that OI should use the template corresponding to 'Popup' to display the action 'User'. The correspondence is currently done in this handler but this will change shortly.

The directives used are listed in the server configuration under the page_directives key.

TO DO

Nothing known, beyond write different ones of these (SOAP, etc.)

BUGS

None known.

COPYRIGHT

Copyright (c) 2001-2002 intes.net, inc.. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>

cpanm OpenInteract

perl -MCPAN -e shell
install OpenInteract