/ 
App-ZofCMS-Plugin-StyleSwitcher-0.0102
/ App::ZofCMS::Plugin::StyleSwitcher

NAME

App::ZofCMS::Plugin::StyleSwitcher - CSS Style switcher plugin

SYNOPSIS

In your ZofCMS template but most likely in your Main Config File:

plugins => [ qw/StyleSwitcher/ ],
plug_style_switcher => {
    dsn                     => "DBI:mysql:database=test;host=localhost",
    user                    => 'test',
    pass                    => 'test',
    opt                     => { RaiseError => 1, AutoCommit => 1 },
    styles => {
        main => 'main.css',
        alt  => [ 'alt.css', '[IE]alt_ie.css' ],
    },
},

In your HTML::Template template:

<head>
    <tmpl_var name="style_switcher_style">
...

<body>
    <tmpl_var name="style_switcher_toggle">
....

DESCRIPTION

The module provides means to have what is known as "Style Switcher" thingie on your webpages. In other words, having several CSS stylesheets per website.

The http://alistapart.com/stories/alternate/ describes the concept in more detail. It also provides JavaScript based realization of the idea; this plugin does not rely on javascript at all.

FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

plugins

plugins => [ qw/StyleSwitcher/ ],

You need to include the plugin in the list of plugins to execute.

plug_style_switcher

plug_style_switcher => {
    dsn                     => "DBI:mysql:database=test;host=localhost",
    user                    => 'test',
    pass                    => 'test',
    opt                     => { RaiseError => 1, AutoCommit => 1 },
    create_table            => 0,
    q_name                  => 'style',
    q_ajax_name             => 'plug_style_switcher_ajax',
    t_prefix                => 'style_switcher_',
    table                   => 'style_switcher',
    max_time                => 2678400, # one month
    default_style           => 'main',
    xhtml                   => 0,
    # styles => {}
    styles => {
        main => 'main.css',
        alt  => [ 'alt.css', '[IE]alt_ie.css' ],
    },
},

plug_style_switcher => sub {
    my ( $t, $q, $config ) = @_;
    return {
        dsn                     => "DBI:mysql:database=test;host=localhost",
        user                    => 'test',
        pass                    => 'test',
    }
},

The plugin reads it's configuration from plug_style_switcher first-level ZofCMS Template or Main Config file template. Takes a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_style_switcher as if it was already there. If sub returns an undef, then plugin will stop further processing. The @_ of the subref will contain (in that order): ZofCMS Tempalate hashref, query parameters hashref and App::ZofCMS::Config object. Keys that are set in ZofCMS Template will override same ones that are set in Main Config file. Considering that you'd want the CSS style settings to be set on an entire site, it only makes sense to set this plugin up in your Main Config file.

dsn

dsn => "DBI:mysql:database=test;host=localhost",

Mandatory. The plugin needs access to an SQL database supported by DBI module. The dsn key takes a scalar as a value that contains the DSN for your database. See DBI for details.

user and pass

user => 'test',
pass => 'test',

Mandatory. The user and pass arguments specify the user name (login) and password for your database.

opt

opt => { RaiseError => 1, AutoCommit => 1 },

Optional. The opt key takes a hashref as a value. This hashref will be directly passed as "additional arguments" to DBI's connect_cached() method. See DBI for details. Defaults to: { RaiseError => 1, AutoCommit => 1 },

table

table => 'style_switcher',

Optional. Specifies the name of the table in which to store the style-user data. Defaults to: style_switcher

create_table

create_table => 0,

Optional. Takes either true or false values. Defaults to: 0 (false). When set to a true value plugin will automatically create the SQL tables that is needed for the plugin. Just set it to a true value, load any page that calls the plugin, and remove this setting. Alternatively you can create the table yourself: CREATE TABLE style_switcher ( host VARCHAR(200), style TEXT, time VARCHAR(10) );

q_name

q_name => 'style',

Optional. Takes a string as a value that must contain the name of the query parameter that will contain the name of the style to "activate". Defaults to: style

q_ajax_name

q_ajax_name => 'plug_style_switcher_ajax',

Optional. Some of you may want to change styles with JS along with keeping style information server-side. For this plugin supports the q_ajax_name, it must contain the name of a query parameter which you'd pass with your Ajax call (sorry to those who really dislike calling it Ajax). The value of this parameter needs to be a true value. When plugin will see this query parameter set to a true value, it will set the style (based on the value of the query parameter referenced by q_name plugin setting; see above) and will simply exit. Defaults to: plug_style_switcher_ajax

t_prefix

t_prefix => 'style_switcher_',

Optional. The plugin sets two keys in ZofCMS Template {t} special key. The t_prefix takes a string as a value; that string will be prefixed to those two keys that are set. See HTML::Template VARIABLES section below for imformation on those two keys. Defaults to: style_switcher_ (note the underscore (_) at the end).

max_time

max_time => 2678400, # one month

Optional. Takes a positive integer as a value that indicates how long (in seconds) to keep the style information for the user. The time is updated every time the user accesses the plugin. The plugin identifies the "user" by contatenating user's User-Agent HTTP header and his/her/its host name. Note that old entries are deleted only when someone sets the style; in other words, if you set max_time to one month and no one ever changes their style and that user comes back after two month the setting will be preserved. Defaults to: 2678400 (one month)

default_style

default_style => 'main',

Optional. Takes a string as a value that must be one of the keys in styles hashref (see below). This will be the "default" style. In other words, if the plugin does not find the particular user in the database it will make the default_style style active.

xhtml

xhtml => 0,

Optional. Takes either true or false values. When set to a true value will close <link> elements with an extra / to keep it XHTML friendly. Defaults to: 0

styles

styles => {
    main => 'main.css',
    alt  => [ 'alt.css', '[IE]alt_ie.css' ],
},

Mandatory. Takes a hashref as a value. The keys of a that hashref are the names of your styles. The name of the key is what you'd pass as a value of a query parameter indicated by plugin's q_name parameter. The value can be either a string or an arrayref. If the value is a string then it will be converted into an arrayref with just that element in it. Each element of that arrayref will be converted into a <link> element where the href="" attribute will be set to that element of the arrayref. Each element can contain string [IE] (including the square brackets) as the first four characters, in that case the href="" will be wrapped in <!--[if IE]> conditional comments (if you don't know what those are, see: http://haslayout.net/condcom).

HTML::Template VARIABLES

Note: examples include the default t_prefix in names of <tmpl_var>s.

style

<tmpl_var name="style_switcher_style">

The style variable will contain appropriate <link> elements. You'd want to put this variable somewhere in HTML <head>

toggle

<tmpl_var name="style_switcher_toggle">

The toggle variable will contain a style toggle link. By clicking this link user can load the next style (sorted alphabetically by its name). You don't have to use this one and write your own instead.

SEE ALSO

http://alistapart.com/stories/alternate/

AUTHOR

'Zoffix, <'zoffix at cpan.org'> (http://zoffix.com/, http://haslayout.net/, http://zofdesign.com/)

BUGS

Please report any bugs or feature requests to bug-app-zofcms-plugin-styleswitcher at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-ZofCMS-Plugin-StyleSwitcher. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::ZofCMS::Plugin::StyleSwitcher

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008 'Zoffix, all rights reserved.

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