PHP Styleswitcher: Version 2 Documentation

Styleswitcher Documentation

Introduction
Code Overview
Styleswitcher Class
StyleSet Class
Style Class

Introduction

This document is intended to provide more in-depth coverage of the code that powers the Styleswitcher. It is assumed that the reader has some basic knowledge of PHP and of Object Oriented Programming.

For general information on how to install and set up the styleswitcher, refer to either the Styleswitcher Tutorial or the Upgrade Guide.

Code Overview

The code is broken down into three sections: the Styleswitcher class, the StyleSet class, and the Style class. The Styleswitcher class uses both of the other smaller classes; the StyleSet class uses the Style class.

The primary programming and user interaction is with the Styleswitcher class which implements most of the script's logic. The other two classes are supporting classes.

Styleswitcher Class

This is the primary class for the style switcher. It uses the two classes StyleSet and Style.

Fields

acceptQuery: Boolean – Flag determining whether "query" (GET) input is accepted. To accept info from some forms and from HTML links, this must be true. This is true by default.
acceptPost: Boolean – Flag determining whether POST input is accepted. This must be turned on to accept information from forms using the POST method. This is true by default.
bounceToReferer: Boolean – Flag determining whether or not the script should redirect the user to the refering address (the script will try to find a referer in the POST/GET information or in the HTTP headers). true by default.
cookieDomain: String – The domain name for the cookies set by the styleswitcher.
cookieName: String – The name for the cookie where the information will be stored. This is by default the same as version 1, but may be changed to avoid conflict.
home: String – This string is a link back to the page that should be used when not using bounceToReferer or when the refer is not present.
includeType: Boolean – Flag determining whether or not 'type="text/css"' is set. By default this is set to true, meaning 'type="text/css"' will be added to each link.
sets: Array – This field is mostly used for internal use, but contains a list of all the StyleSets that are created.
styleSet: Array – This field contains all of the Styles that are created.
styleVariable: String – This field contains the name, checked by default for style information.

Constructor

new Styleswitcher([home, domain])

home: String – An optional argument for setting where the home page is (see the home field above).
domain: String – An optional argument for setting the cookie domain.

Methods

addStyle(style [, file, media, title, static])

This method adds a style to the Styleswitcher object.

style: String – The name for the style (not to be confused with the style title).
file: String – The link for the stylesheet.
media: String – The media type for the stylesheet.
title: String – The title attribute for the stylesheet link.
static: Boolean – Flag determining if this style is always present or only when specified. false by default.

Example

$ss = new Styleswitcher();
$ss->addStyle("basic", "css/basic.css");

addStyleToSet(setName, style [, default])

This method adds a style to a set of styles. Both the set and the style must be created before this method can be used. If a style is marked as the default style, it will be used when no other style has been selected for this set (or if, in the bizarre circumstance, more than one style is selected for a set, including the default).

setName: String – The name of the set the style should be added to.
style: String – The name for the style (not to be confused with the style title).
default: Boolean – An optional flag specifying whether or not this style is the default style for the set. false by default.

Example

$ss = new Styleswitcher();
$ss->addStyle("large", "css/large-text.css");
$ss->addStyle("small", "css/small-text.css");
$ss->createSet("fonts");
$ss->addStyleToSet("fonts", "large");
$ss->addStyleToSet("fonts", "small");

createSet(setName [, setItems])

This method creates a new style set. Style sets are used to handle multiple styles that are mutually exclusive (i.e., only one style from a set may be present at a time.)

setName: String – The name of this set.
setItems: Array – An optional argument specifying an array of styles to be added to the set.

Example

$ss = new Styleswitcher();
$ss->addStyle("large", "css/large-text.css");
$ss->addStyle("small", "css/small-text.css");
$ss->createSet("fonts");
$ss->addStyleToSet("fonts", "large");
$ss->addStyleToSet("fonts", "small");

printAlternateStyles([printAll])

This method prints out the alternate stylesheets for a page. If the printAll argument is true, then it will print out alternate links for all stylesheets, including those that are printed for immediate use and those that are static.

printAll: Boolean – An optional flag to print out all stylesheets as alternate links or just those that are not going to be used by the page. true by default.

See Also: printStyles()

printSetInputChecked(set, input)

This method is useful when using form-based style changers (for instance, checkboxes or radio buttons) because it will print out the proper checked="checked" for the element depending on whether or not it is set in the user's cookies or is the default for a style set (in the case that no styles from that set are located in the user's cookies).

set: String – The set name for this element. For example, if this element is associated with the "fonts" set, that is the name you would pass in.
input: String – The style name associated with this form element.

Example

<form action="php/switcher.php" method="post">
<input type="radio" name="fontSet" id="fontSet1"\
 <?php $ss->printSetInputChecked("fonts", "large"); ?> /> 
 <label for="fontSet1">Large Text<label>
<input type="radio" name="fontSet" id="fontSet2" 
 <?php $ss->printSetInputChecked("fonts", "small"); ?> /> 
 <label for="fontSet2">Small Text<label>

printSetStyles()

This method prints out the correct styles for each available set. The "correct" style is either: the default style in the absence of all other styles, the default in the case that default is present along with other styles, the first style within the set (in the case that there are more than one from each set), or the one style choosen for each set.

See Also: printStyles()

printStyles([printAlt])

This is a method which encapsulates all the other print style methods. Typically, this is the only one that needs to be called.

printAlt: Boolean – An optional flag for whether or not alternate style sheets should be printed.

printStaticStyles()

This method is used to print out all styles marked as being "static" (and not within a set – static styles should not be within sets.

See Also: printStyles()

printUserStyles()

This prints styles selected by the user that are not within sets (i.e., those styles that are not mutually exclusive.

See Also: printStyles()

setHome(home)

A simple method for setting the Styleswitcher's home.

home: The styleswitcher's home. This is used when redirection to the refer is not used or cannot be completed.

start()

This method is used when accepting information about setting cookies for remembering a user's style changes.

styleCookieSet()

This method is handy for checking if the style cookie has been set. It returns true if the cookie is present and false if not.

Example

if($ss->styleCookieSet){
    print "You have chosen a different style.";
}

StyleSet Class

This is the first of two supporting classes for the Styleswitcher class. This class implements a set (an array) of Styles. You do not need to call any of the methods from this class to use the styleswitcher.

Fields

styles: An array of all the styles within this set.
default: The name of the default style for this set.
set: The name of the style that is to be printed for this set (mostly used in the Styleswitcher printStyles() method.

Constructor

new StyleSet([default])

default: String – An optional string that names the default style for this set.

Methods

addStyle(style [, file, media, title, static])

This method adds a style to this set. Typically you may use the addStyleToSet() method to add a style to the styleswitcher.

style: String – The name of the style to be added.
file: String – An optional argument. The file for this style.
media: String – An optional argument. The media attribute for this style link.
title: String – An optional argument. The title attribute for this style link.
static: Boolean – An optional argument that deals with whether this style is static or not.

exists(style)

This method checks whether a style exists within a style set.

style: The name of the style.

getStyle(style)

This method returns the Style object for the specified style.

style: The name of the style.

Style Class

This class models a stylesheet. It is used to hold information regarding stylesheets for the styleswitcher.

Fields

name: The name of the stylesheet (for use with the styleswitcher).
file: The file name of the stylesheet.
media: The media attribute for the stylesheet.
static: A boolean flag determing whether this style is static or not.
title: The title attribute of the stylesheet.

Constructor

new Style(name [, file, media, title, static])

The arguments to this constructor are the same as the fields list above.

This page's CSS and XHTML validate. Does yours?