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 monthOptional. 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/
REPOSITORY
Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS
BUGS
To report bugs or request features, please use https://github.com/zoffixznet/App-ZofCMS/issues
If you can't access GitHub, you can email your request to bug-App-ZofCMS at rt.cpan.org
AUTHOR
Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)
LICENSE
You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.