projekt kivitendo

__END__

=encoding utf-8

=head1 NAME

SL::Layout::Dispatcher - provides layouts by name.

=head1 SYNOPSIS

  use SL::Layout::Dispatcher;

  $::request->layout(SL::Layout::Dispatcher->new(style => 'login'));

  # same as

  use SL::Layout::Login;

  $::request->layout(SL::Layout::Login->new);

=head1 INTRODUCTION

A layout in kivitendo is anything that should be included into a text/html

response without having each controller do it manually. This includes:

=over 4

=item *

menus

=item *

status bars

=item

div containers for error handling and ajax responses

=item *

javascript and css includes

=item *

html header and body

=back

It does not include:

=over 4

=item *

http headers

=item *

anthing that is not a text/html response

=back

All of these tasks are handled by a layout object, which is stored in the

global L<$::request|SL::Request> object. An appropriate layout object will be

chosen during the login/session_restore process.

=head1 INTERFACE

Every layout must be instantiated from L<SL::Layout::Base> and must implement

the following eight callbacks:

=over 4

=item C<pre_content>

Content that must, for whatever reason, appear before the main content.

=item C<start_content>

An introcutory clause for the main content. Usually something like C<< <div

class='content'> >>.

=item C<end_content>

The corresponding end of L</start_content> like C<< </div> >>

=item C<post_content>

Any extra content that should appear after the main content in the response

source. Note that it is preferred to put extra content after the main content,

so that it gets rendered faster.

=item C<stylesheets>

A list of stylesheets that should be included as a full relative web path. Will

be rendered into the html header.

=item C<stylesheets_inline>

A list of stylesheet snippets that need to be included in the response. Will be

added to the html header.

=item C<javascripts>

A list of javascripts that should be included as a full relative web path.

Note:

There is no guarantee where these will end up in the content. Currently they

will be rendered into the header, but are likely to be moved into the footer in

the future.

=item C<javascripts_inline>

A list of javascript snippets that need to be included in the response.

Note:

These will end up in the footer, so make sure they don't contain

initializations to static javascript includes that may be included earlier.

=back

=head1 RUNTIME INTERFACE

Each layout object can add stylesheets and javascripts at runtime, as long as

its before the actual rendering has begun. This can be used to add special

javascripts only your controller needs.

=over 4

=item C<add_stylesheets>

Adds the list of arguments to the list of used stylesheets.

These will first be searched in the theme folder for the current user, and only

after that be searched from the common C<css/> folder.

Duplicated files will be only included once.

Non-existing files will be pruned from the list.

=item C<use_stylesheet>

Backwards compatible alias for C<add_stylesheets>. Deprecated.

=item C<add_javascripts>

Adds the list of arguments to the list of used javascripts.

Duplicated files will be only included once.

Non-existing files will be pruned from the list.

=item C<use_javascript>

Backwards compatible alias for C<add_javascripts>. Deprecated.

=item C<add_javascripts_inline>

Add a snippet of javascript.

=item C<add_stylesheets_inline>

Add a snippet of css.

=item C<focus>

If set with a selector, the layout will generate javascript to set the page

focus to that selector on document.ready.

=back

=head1 BUGS

None yet :)

=head1 TODO

non existing css or js includes should generate a log entry.

=head1 AUTHOR

Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>

=cut