summaryrefslogtreecommitdiff
path: root/lib/Template/Library/Splash.pod
diff options
context:
space:
mode:
Diffstat (limited to 'lib/Template/Library/Splash.pod')
-rw-r--r--lib/Template/Library/Splash.pod1030
1 files changed, 1030 insertions, 0 deletions
diff --git a/lib/Template/Library/Splash.pod b/lib/Template/Library/Splash.pod
new file mode 100644
index 0000000..e8c4f8b
--- /dev/null
+++ b/lib/Template/Library/Splash.pod
@@ -0,0 +1,1030 @@
+#============================================================= -*-perl-*-
+#
+# Template::Library::Splash
+#
+# DESCRIPTION
+# The Splash! library is built on top of the HTML library and
+# implements a set of widgets for easy construction of stylish HTML
+# pages
+#
+# AUTHOR
+# Andy Wardley <abw@andywardley.com>
+#
+# COPYRIGHT
+# Copyright (C) 1996-2001 Andy Wardley. All Rights Reserved.
+# Copyright (C) 1998-2001 Canon Research Centre Europe Ltd.
+#
+# This module is free software; you can redistribute it and/or
+# modify it under the same terms as Perl itself.
+#
+# REVISION
+# 2.69
+#
+#========================================================================
+
+
+#------------------------------------------------------------------------
+# IMPORTANT NOTE
+# This documentation is generated automatically from source
+# templates. Any changes you make here may be lost.
+#
+# The 'docsrc' documentation source bundle is available for download
+# from http://www.template-toolkit.org/docs.html and contains all
+# the source templates, XML files, scripts, etc., from which the
+# documentation for the Template Toolkit is built.
+#------------------------------------------------------------------------
+
+=head1 NAME
+
+Template::Library::Splash - Template library for building stylish HTML user interfaces
+
+=head1 DESCRIPTION
+
+B<NOTE:> This documentation is incomplete, incorrect and outdated.
+The Splash! library is still evolving and subject to change. See
+the examples for a much more recent and accurate demonstration of
+use.
+
+=head2 Introduction
+
+The 'Splash' template library is distributed as part of the Template
+Toolkit. It can be found in the 'templates' sub-directory of the
+installation directory.
+
+ /your/tt2/installation
+ |
+ +-- docs
+ | ...
+ |
+ +-- images
+ | ...
+ |
+ +-- examples
+ | ...
+ |
+ +-- templates
+ |
+ +-- html
+ | ...
+ +-- pod
+ | ...
+ +-- splash <<<< YOU ARE HERE
+ ...
+
+
+To use the Splash library, you first need to tell the Template Toolkit
+where to find the template files.
+
+ use Template;
+
+ my $tt2 = Template->new({
+ INCLUDE_PATH => '/usr/local/tt2/templates',
+ });
+
+For a portable way to determine the installation 'templates' directory,
+you can use the C<Template::Config-E<gt>instdir()> class method.
+
+ use Template;
+
+ my $tt2 = Template->new({
+ INCLUDE_PATH => Template::Config->instdir('templates'),
+ });
+
+Note that you should set the INCLUDE_PATH to the 'templates' directory
+as shown here and don't be tempted to set the INCLUDE_PATH to
+'templates/splash'. Many of the Splash! components use elements in
+the 'html' directory and contain directives of the form:
+
+ [% INCLUDE html/something %].
+
+=head2 Configuration
+
+The 'splash/config' template defines a 'splash' hash array which
+contains numerous configuration items for the Splash library. You
+must PROCESS this template to ensure that the hash definition is
+imported into your calling template. An INCLUDE is not sufficient as
+it localises variables and prevents the 'splash' hash array from
+existing outside the splash/config template.
+
+ [% PROCESS splash/config %]
+
+Alternately, you can define the splash/config template as a PRE_PROCESS
+item when you create the Template processor.
+
+ use Template;
+
+ my $tt2 = Template->new({
+ INCLUDE_PATH => Template::Config->instdir('templates'),
+ PRE_PROCESS => 'splash/config',
+ });
+
+You can modify the default configuration by creating your own
+PRE_PROCESS config file which loads the 'splash/config' and then
+tweaks the settings to your own preferences.
+
+ my $tt2 = Template->new({
+ INCLUDE_PATH => [ '/home/abw/tt2/templates',
+ Template::Config->instdir('templates') ],
+ PRE_PROCESS => 'config'
+ });
+
+/home/abw/tt2/templates/config:
+
+ [% # load the 'splash' configuration
+ PROCESS splash/config;
+
+ # tweak values to personal preferences
+ splash.images = '/~abw/tt2/images/splash'
+ splash.select.col = 'leaf'
+ splash.unselect.col = 'bud'
+ %]
+
+The splash/config file includes some instructional comments on
+things you might like to tweak.
+
+=head2 Colours
+
+The Splash! library uses the colours defined in the html/rgb template.
+The 'rgb' hash defined therein is imported as the 'splash.rgb' hash.
+
+ [% INCLUDE splash/box col='grey75' %]
+
+See the examples for further enlightenment on using colour.
+
+=head2 Style
+
+There are two very primitive "styles" implemented called "select" and
+"unselect". These are used to indicate which item on a menu is
+selected, for example. Each style defines characteristics like
+background colour, font face, size and colour, text alignment, and so
+on.
+
+The styles are implemented as hashes within the 'splash' hash. Many
+of the components respond to a 'style' variable being set and you can
+pass a direct reference to splash.select or splash.unselect (or your
+own styles). e.g.
+
+ [% INCLUDE splash/button
+ content = "Unselected"
+ style = splash.unselect
+ %]
+ [% INCLUDE splash/button
+ content ="Selected"
+ style = splash.select
+ %]
+
+Alternately, you can use the 'select' variable to indicate either
+of the inbuilt styles: splash.select or splash.unselect.
+
+ [% INCLUDE splash/button
+ content = "Unselected"
+ select = 0
+ %]
+ [% INCLUDE splash/button
+ content = "Selected"
+ select = 1
+ %]
+
+=head1 COMPONENT TEMPLATES
+
+This section describes some of the component templates in the Splash!
+library. This documentation is incomplete and may also be inaccurate
+in places. The examples in the 'examples' directory are likely to be
+a much better reference.
+
+
+=head2 splash/text
+
+Simple template to format text according to a selected/unselected style,
+adding links, etc.
+
+ [% INCLUDE splash/text
+ content = 'Template Toolkit'
+ link = 'http://www.template-toolkit.org'
+ select = 0
+ bold = 1
+ %]
+
+
+Configuration items:
+
+=over 4
+
+
+=item content
+
+Text content.
+
+
+=item link
+
+URL which can be defined to make the text a link.
+
+
+=item style
+
+Reference to a style hash.
+
+
+=item select
+
+Flag to default the style to splash.select (select == true value) or
+splash.unselect (select == false value).
+
+
+=back
+
+The following items default to the relevant style values:
+
+=over 4
+
+
+=item col (style.col.text)
+
+
+=item font (style.font.face)
+
+
+=item bold (style.font.bold)
+
+
+=item size (style.font.size)
+
+
+=back
+
+
+
+=head2 splash/table
+
+A thin wrapper around html/table, allowing a colour to be specified
+by name.
+
+ [% WRAPPER splash/table
+ col = 'aqua'
+ pad = 4
+ width = '100%'
+ %]
+ <tr>
+ <td>Foo</td>
+ <td>Bar</td>
+ </tr>
+ [% END %]
+
+
+Configuration items:
+
+=over 4
+
+
+=item content
+
+Table content.
+
+
+=item col
+
+Background colour.
+
+
+=item border
+
+Border width (default: 0)
+
+
+=item width
+
+Width in absolute pixels (e.g. '100') or as a percentage (e.g. '50%').
+
+=item pad
+
+Cell padding.
+
+
+=item space
+
+Cell padding.
+
+
+=back
+
+
+
+=head2 splash/row
+
+Creates a row for an HTML table.
+
+ [% WRAPPER splash/table %]
+
+ [% WRAPPER splash/row col='marine' %]
+ <td>Foo</td><td>Bar</td>
+ [% END %]
+
+ [% WRAPPER splash/row col='aqua' %]
+ <td>Foo</td><td>Bar</td>
+ [% END %]
+
+ [% END %]
+
+
+Configuration items:
+
+=over 4
+
+
+=item content
+
+Row content.
+
+
+=item col
+
+Background colour.
+
+
+=item valign
+
+Vertical alignment
+
+
+=item rowspan
+
+Number of rows to span.
+
+
+=back
+
+
+
+=head2 splash/cell
+
+Creates a cell for an HTML table.
+
+ [% WRAPPER splash/table + splash/row + splash/cell col='grey75' %]
+ Hello World
+ [% END %]
+
+
+Configuration items:
+
+=over 4
+
+
+=item content
+
+Cell content.
+
+
+=item col
+
+Background colour.
+
+
+=item align
+
+Horizontal alignment
+
+
+=item colspan
+
+Number of columns to span.
+
+
+=back
+
+
+
+=head2 splash/box
+
+A box created from a union of splash/table, splash/row and splash/cell.
+The following is equivalent to the previous example.
+
+ [% WRAPPER splash/box col='grey75' %]
+ Hello World
+ [% END %]
+
+Configuration items are as per the individual templates.
+
+
+=head2 splash/button
+
+Creates a small button with rounded corners.
+
+ [% INCLUDE splash/button
+ content = 'Template Toolkit'
+ select = 1
+ width = '50%'
+ %]
+
+
+Configuration items:
+
+=over 4
+
+
+=item content
+
+Button content.
+
+
+=item style
+
+Reference to a style hash.
+
+
+=item select
+
+Flag to default the style to splash.select (select == true value) or
+splash.unselect (select == false value).
+
+
+=item width
+
+Width in absolute pixels (e.g. '100') or as a percentage (e.g. '50%').
+
+=back
+
+The following items default to the relevant style values:
+
+=over 4
+
+
+=item col (style.col.text)
+
+
+=item textcol (style.col.text)
+
+
+=item font (style.font.face)
+
+
+=item size (style.font.size)
+
+
+=item bold (style.font.bold)
+
+
+=item width (style.button.width)
+
+
+=item align (style.button.align)
+
+
+=back
+
+
+
+=head2 splash/bar
+
+Creates a bar with rounded corners at either the top or bottom, and
+square corners on the other. Default has rounded at the top, set
+'invert' to select bottom.
+
+ [% INCLUDE splash/bar
+ content = 'Hello World',
+ select = 1
+ %]
+
+
+Configuration items:
+
+=over 4
+
+
+=item content
+
+Bar content.
+
+
+=item style
+
+Reference to a style hash.
+
+
+=item select
+
+Flag to default the style to splash.select (select == true value) or
+splash.unselect (select == false value).
+
+
+=item width
+
+Width in absolute pixels (e.g. '100') or as a percentage (e.g. '50%').
+
+=item invert
+
+Flag to invert bar to hang down instead of sitting
+upright.
+
+
+=back
+
+The following items default to the relevant style values:
+
+=over 4
+
+
+=item col (style.col.text)
+
+
+=item textcol (style.col.text)
+
+
+=item font (style.font.face)
+
+
+=item size (style.font.size)
+
+
+=item bold (style.font.bold)
+
+
+=item width (style.button.width)
+
+
+=item align (style.button.align)
+
+
+=back
+
+
+=head2 splash/hair
+
+Generates a frame enclosing the content within crosshair corners.
+
+ [% INCLUDE splash/hair
+ content = 'Template Toolkit'
+ %]
+
+
+Configuration items:
+
+=over 4
+
+
+=item content
+
+Hair content.
+
+
+=item style
+
+Reference to a style hash.
+
+
+=back
+
+The following items default to the relevant style values:
+
+=over 4
+
+
+=item col (style.col.text)
+
+
+=item bgcol (style.col.back)
+
+
+=item align (style.button.align)
+
+
+=back
+
+
+=head2 splash/menu
+
+Creates a menu as a series of splash/button elements.
+
+ [% buttons = [
+ { text => 'One', link => 'one.html' }
+ { text => 'Two', link => 'two.html' }
+ ]
+ %]
+
+ [% INCLUDE splash/menu
+ select = 2 # Two
+ %]
+
+
+Configuration items:
+
+=over 4
+
+
+=item buttons
+
+A reference to a list of hash arrays containing 'text' and 'link' items.
+
+
+=item select (n or 0)
+
+Indicates which button should be selected. First item is 1. 0 indicates
+no button selected.
+
+
+=item width
+
+Width in absolute pixels (e.g. '100') or as a percentage (e.g. '50%').
+
+=item align
+
+Horizontal alignment
+
+
+=back
+
+
+
+=head2 splash/menubar
+
+As above, but incorporated into a wider bar.
+
+ [% WRAPPER splash/menubar %]
+ Section Title
+ [% END %]
+
+
+Configuration items:
+
+=over 4
+
+
+=item buttons
+
+A reference to a list of hash arrays containing 'text' and 'link' items.
+
+
+=item select (n or 0)
+
+Indicates which button should be selected. First item is 1. 0 indicates
+no button selected.
+
+
+=item width
+
+Width in absolute pixels (e.g. '100') or as a percentage (e.g. '50%').
+
+=item align
+
+Horizontal alignment
+
+
+=back
+
+
+
+=head2 splash/panel
+
+A table with a coloured edge.
+
+ [% WRAPPER splash/panel edge='black' fill='grey75' border=2 %]
+ <tr>
+ <td>Hello World</td>
+ </tr>
+ [% END %]
+
+
+Configuration items:
+
+=over 4
+
+
+=item content
+
+Panel content.
+
+
+=item style
+
+Reference to a style hash.
+
+
+=item select
+
+Flag to default the style to splash.select (select == true value) or
+splash.unselect (select == false value).
+
+
+=item width
+
+Width in absolute pixels (e.g. '100') or as a percentage (e.g. '50%').
+
+=item align
+
+Horizontal alignment
+
+
+=item border
+
+Border width (default: 0)
+
+
+=back
+
+The following items default to the relevant style values:
+
+=over 4
+
+
+=item edge (style.col.edge)
+
+
+=item fill (style.col.fill)
+
+
+=item pad (style.pad)
+
+
+=back
+
+
+
+=head2 splash/pane
+
+A union of splash/row + splash/cell.
+
+ [% WRAPPER splash/panel select=1 %]
+ [% WRAPPER splash/pane col='grey75' %]
+ Hello World
+ [% END %]
+
+ [% WRAPPER splash/pane col='grey50' %]
+ Hello Again
+ [% END %]
+ [% END %]
+
+
+=head2 splash/tab
+
+A simple button looking like a page tab.
+
+ [% INCLUDE splash/tab
+ content = 'Option 1'
+ col = 'aqua'
+ %]
+
+
+Configuration items:
+
+=over 4
+
+
+=item content
+
+Tab content.
+
+
+=item style
+
+Reference to a style hash.
+
+
+=item select
+
+Flag to default the style to splash.select (select == true value) or
+splash.unselect (select == false value).
+
+
+=item width
+
+Width in absolute pixels (e.g. '100') or as a percentage (e.g. '50%').
+
+=item align
+
+Horizontal alignment
+
+
+=back
+
+The following items default to the relevant style values:
+
+=over 4
+
+
+=item col (style.col.text)
+
+
+=item textcol (style.col.text)
+
+
+=item font (style.font.face)
+
+
+=item size (style.font.size)
+
+
+=item bold (style.font.bold)
+
+
+=item tabalign (style.tab.align)
+
+
+=back
+
+
+
+=head2 splash/tabset
+
+A set of splash/tab components, similar to a menu.
+
+
+Configuration items:
+
+=over 4
+
+
+=item tabs
+
+List of hash references containing text/link entries, as per
+menu buttons.
+
+
+=item select
+
+Flag to default the style to splash.select (select == true value) or
+splash.unselect (select == false value).
+
+
+=item invert
+
+Flag to invert tab to hang down instead of sitting
+upright.
+
+
+=back
+
+
+
+=head2 splash/tabbox
+
+Add a splash/tab to the top of a splash/box.
+
+
+Configuration items:
+
+=over 4
+
+
+=item title
+
+ title.
+
+
+=item content
+
+ content.
+
+
+=item width
+
+Width in absolute pixels (e.g. '100') or as a percentage (e.g. '50%').
+
+=item tabwidth
+
+Width of tabs.
+
+
+=item select
+
+Flag to default the style to splash.select (select == true value) or
+splash.unselect (select == false value).
+
+
+=item border
+
+Border width (default: 0)
+
+
+=back
+
+The following items default to the relevant style values:
+
+=over 4
+
+
+=item col (style.col.text)
+
+
+=item fill (style.col.fill)
+
+
+=item tabalign (style.tab.align)
+
+
+=item tablocate (style.tab.locate)
+
+
+=back
+
+
+
+=head2 splash/tabsbox
+
+Add a splash/tabset to the top of a splash/box.
+
+
+Configuration items:
+
+=over 4
+
+
+=item tabs
+
+List of hash references containing text/link entries, as per
+menu buttons.
+
+
+=item select
+
+Flag to default the style to splash.select (select == true value) or
+splash.unselect (select == false value).
+
+
+=item content
+
+ content.
+
+
+=item width
+
+Width in absolute pixels (e.g. '100') or as a percentage (e.g. '50%').
+
+=item border
+
+Border width (default: 0)
+
+
+=item invert
+
+Flag to invert to hang down instead of sitting
+upright.
+
+
+=back
+
+The following items default to the relevant style values:
+
+=over 4
+
+
+=item col (style.col.text)
+
+
+=item fill (style.col.fill)
+
+
+=item tabalign (style.tab.align)
+
+
+=item tablocate (style.tab.locate)
+
+
+=back
+
+
+=head2 splash/tabspanel
+
+As per splash/tabsbox, but attached to a splash/panel instead of a
+splash/box.
+
+
+=head1 EXAMPLES
+
+See the examples in the 'examples' sub-directory of the installation
+for comprehensive examples showing use of the Splash! library.
+
+=head1 AUTHOR
+
+Andy Wardley E<lt>abw@andywardley.comE<gt>
+
+L<http://www.andywardley.com/|http://www.andywardley.com/>
+
+
+
+
+=head1 VERSION
+
+2.69, distributed as part of the
+Template Toolkit version 2.13, released on 30 January 2004.
+
+=head1 COPYRIGHT
+
+ Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+ Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
+
+This module is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+L<Template::Library::HTML|Template::Library::HTML>
+
+=cut
+
+# Local Variables:
+# mode: perl
+# perl-indent-level: 4
+# indent-tabs-mode: nil
+# End:
+#
+# vim: expandtab shiftwidth=4:
generated by cgit v1.2.3 (git 2.25.1) at 2026-03-06 09:58:55 +0000