bioneural.net

The first version of my site preference panel for WordPress needed lots of JavaScript for the toggle (Proto.aculo.us), more JavaScript to switch styles, and still more JavaScript to change text size. Version 2 still uses JavaScript for the toggle effect—but no additional load—since jQuery is already utilised by K2. The rest is accomplished using server-side PHP, and the revised 3-column panel layout makes use of more recent CSS know-how. I've tried to modularize the preferences panel as much as possible, but some simple template editing is still required (at 4 points). It is optimised for K2 (tested using RC3 and RC4) and although I haven't tested it with other themes (that's your job!) I don't see why it couldn't be used (*Some tweaking may be required. Batteries not included.)

Get the files

Let's get it done, then come back to the how and why if you're interested. Download the files to create your own preference panel as siteprefs.zip, available here. Expand the archive and upload the folder "siteprefs" into your K2 main directory:

/wp-content/themes/k2/siteprefs/

At this point you may also want to download and activate the Theme Switcher plugin if you plan on allowing your audience to change the WordPress theme they see on a per-user basis (storing their preference in a cookie). Support for the plugin is built into the preference panel (see features, below).

It's yours to play with and customise; all I ask is that you retain the little "i" icon with it's link back to these instructions. Feedback and suggestions for improvement are welcome. If you do modify it in a novel way (or use it in a theme other than K2), please leave a comment so I and others can check it out.

Right then, let's hack some templates!

Step 1: Look for cookies

Add the following code into PHP block at the top of K2's header.php (e.g. before the closing "?>"):

// Check cookie for stored site prefs
$layout = (isset($_COOKIE['layout']) && ($_COOKIE['layout'] == "alternate")) ? "alternate" : "style";

Here, "style" is the name of your main stylesheet (style.css in K2) and "alternate" is the name of a stylesheet we'll create at Step 5. If you're not using K2 pop this between PHP start and end tags at the top of your header template and set "style" to the name of your primary CSS file.

Step 2: Know your style

We need to replace the relative link to your stylesheet with one into which we can insert the value of the variable $layout. While we're here, we might as well link to the styling for the preference panel. In the head element of header.php replace this line (or your theme's equivalent):

<link rel="stylesheet" type="text/css" media="screen" href="<?php bloginfo('stylesheet_url'); ?>" />

with:

<link rel="stylesheet" type="text/css" media="screen" href="<?php bloginfo('template_url'); ?>/<?php echo $layout; ?>.css" />
<link rel="stylesheet" type="text/css" media="screen" href="<?php bloginfo('template_url'); ?>/siteprefs/siteprefs.css" />

Your K2 custom stylesheet will still be loaded too, if you're using one.

Step 3: Flick the switch

Create a toggle to switch visibility of the preference panel on or off (it will be hidden on page load). The actual "switch" might be a text or an image link, inserted into an appropriate place (e.g your header or sidebar). If you prefer to add the toggle in the form of a tab in your K2 menu, look for ul class="menu" in header.php and replace this code:

	<?php wp_register('<li class="admintab">','</li>'); ?>
</ul>

with the following code:

	<?php wp_register('<li class="admintab">','</li>'); ?>
	<li><a id="siteprefs-toggle" href="#" title="Click to show/hide site preferences (requires JavaScript)">Prefs</a></li>
</ul>
<script type="text/javascript">
	jQuery(document).ready(function() {

	// hide #siteprefs as soon as the DOM is ready
	jQuery('#siteprefs').hide();

	// toggle #siteprefs on clicking the #prefs-toogle link
	jQuery('a#siteprefs-toggle').click(function() {
	jQuery('#siteprefs').slideToggle(400);
	return false;
	});

});
</script>

If you'd rather use the supplied image (sitepref2.gif), place the following code after p class="description" (which is within div id="header") and before ul class="menu" in K2's header.php.

<a id="siteprefs-toggle" href="#" title="Click to show/hide site preferences (requires JavaScript)"><img src="<?php bloginfo('template_directory'); ?>/siteprefs/img/sitepref2.gif" width="52" height="28" alt="siteprefs" /></a>
<script type="text/javascript">
	jQuery(document).ready(function() {

	// hide #siteprefs as soon as the DOM is ready
	jQuery('#siteprefs').hide();

	// toggle #siteprefs on clicking the #prefs-toogle link
	jQuery('a#siteprefs-toggle').click(function() {
	jQuery('#siteprefs').slideToggle(400);
	return false;
	});

});
</script>

The CSS to position the #siteprefs-toggle image within K2's header image area is included in the download (it will be ignored if you create a menu tab instead). If this position doesn't suit your theme of course you can overwrite this in siteprefs.css.

The toggle's "slide" effect depends on jQuery, which comes with K2 by default. If you're not using K2, you'll need to include the jQuery library in your head, find an alternative JavaScript (here is how v1 did it using Proto.aculo.us), or you may wish to dispense with the toggle altogether and ventilate your preferences permanently.

Step 4: Feel included

The file siteprefs.php includes the XHTML and PHP to build your preference panel. As well as providing the Theme Switcher control, it works with layout.php to toggle your main and alternate stylesheets (and store your choice in a cookie), and advises your audience on link behaviour. You can change the content of these three columns as you see fit just by editing siteprefs.php.

To get siteprefs.php into your theme we have to include it e.g. immediately below the closing tag of the div #header in header.php, so it appears to slide out from the K2 menu:

<?php include (TEMPLATEPATH . '/siteprefs/siteprefs.php'); ?>

If you prefer you could put it at the top of your page, in the sidebar, or in the footer. Or anywhere. For sidebar placement, for example, you would likely edit siteprefs.php and siteprefs.css to respectively create and style a single vertical column.

At this point, if you refresh your site you should see the bioneural.net preference panel installed. If all went well and you're using a default K2 installation, you should be something like this:

Click thumbnail to enlarge image

Site preferences installed into default K2 theme (using image toggle)

Step 5: Go alternative

Finally we create an alternate stylesheet, named alternate.css (the name is specified in Step 1 and in layout.php).

What you put in here is up to you. You will likely want to import existing styling from your main stylesheet, and then write a handful of rules which, owing to the CSS "cascade", will overwrite some of those you just imported.

Here's a barebones example that increases font size and turns the default K2 fixed-width theme into a fluid/ liquid layout:

@import 'style.css';

body { font-size: 90%; } /* approx 30% larger than K2 default */
#page { width: 100% !important; border: 0; padding: 0; }
#primary { width: 100%; margin-left: -30px; padding-left: 30px; background-color: #fff;}
.content { background-color: #fff; } /* Match bg colour to #primary */
#sidebar-main.secondary { padding-left: 30px; border-right: 10px solid #f2f2f2; padding-bottom: 20px; } /* Border colour matches bg colour of .secondary */
.secondary { width: 100% !important; margin-left: -30px; background: #f2f2f2; }
#footer { background-color: #ccc; }

Upload alternate.css into the same directory as your main stylesheet (e.g. styles.css i.e. /wp-content/themes/k2/). This is important as the switch relies on your main and alternate stylesheets being in the same directory.

If you're having trouble overwriting rules for your alternate stylesheet, try !important e.g. width: 100% !important; but bear in mind IE6 will ignore it.

Build notes, features and credits

You don't have to read on—unless you're interested in how, why, and who helped make it work the way it does ;-)

The toggle effect

The toggle uses the jQuery JavaScript library and the code for this was covered in a previous article.

What if the user doesn't have JavaScript, or has it but disabled it? Version 1 hid the preference panel on page load using CSS, and showing it required JavaScript to change the styling to "display". Version 2 uses JavaScript to initially hide the panel, so if there is no JavaScript the panel will be revealed at the outset. Furthermore, because none of the controls in the panel utilize any JavaScript, no functionality is impaired. The only (minor) outcome is that the panel can't be hidden, but at least the "accessibility" preferences are, err, accessible.

A flexible 3-column framework

The XHTML mark-up and CSS for this is adapted from an example multi-column layout given in an ALA article by Alan Pearce. Alan cleverly builds on previous work that makes use of borders to simulate equal-height columns. Initially my mark-up used borders too, but after 2 days of trying to get it to work in IE6 and 7 with in-column padding I realised I didn't need them.

The fixed-width two-column K2 theme I use defaults to a width of 780px. To create our basic layout we create 3 divs (one for each column), and wrap these in a container div. The container sets up the 3 columns using floats and negative margins and then uses padding to effectively pull the outer columns back inside the container! We then create a header div and a footer div, and style the width of the outer columns (including padding) to 260px i.e. one third of our page width:

We can then apply a horizontally-repeating background image to the header and footer divs, match the background colours, and clear floats for the footer to position correctly. Here's what our panel now looks like topographically:

But the preference panel resizes, too. If your alternate stylesheet is "fluid" i.e. page content fits to the width of the browser window, the three columns will automatically space themselves out equally to fill the window:

Note that the left and right column width doesn't actually change, but the width of the middle column is no longer an implied 260px since we have set #siteprefs-center to occupy 100% width.

At this point everything is looking good—in Firefox, Safari, and IE7. You guessed it: Internet Exploder 6 is singing protest songs. We need to patch our CSS to make it work with IE6:

The IE escaping floats bug causes the contents of #siteprefs-header not to display. We just add width: 100%; to fix this.

The IE doubled float-margin bug causes #siteprefs-right to float outside of #siteprefs-wrapper! To fix this we add display: inline; to #siteprefs-right.

Switching whole themes

The Theme Switcher plugin for WordPress is by Ryan Boren. It sets a cookie so that the user's browser remembers their choice of theme for subsequent visits.

The bioneural.net preference panel uses conditional PHP to show the theme switcher dropdown menu or, if the TS plugin is not present or is present but not activated, they will see a "not enabled" message:

There are a few other things you might consider if you allow theme switching on your site; see Ben's list. To press the point, the preference panel includes a warning when the switcher is displayed that using it "may reduce functionality". At the very least you need to allow users to easily switch back to the previous theme—otherwise they'll have to wait a year until the cookie expires (not really; they could just delete the cookie!). In the sidebar of each theme you have installed, just paste the following:

<?php if (function_exists('wp_theme_switcher')) { ?>
	<?php wp_theme_switcher('dropdown'); ?>
<?php } ?>

If you don't like the list styling, this CSS (as used in siteprefs.css) will remove it:

#themeswitcher { list-style: none; padding-left: 0; }

Switching stylesheets

Previously I had used JavaScript to effect both a change in layout (fixed or fluid-width) and in text size (smaller, default, larger). Both of these are really accessibility issues—adapting to the size of your screen or the acuity of your vision. Add to this the observation that enlarging text size very soon causes problems within the confines of a fixed-width layout and it becomes clear why I decided to merge these features in version 2 i.e. biiger text, bigger container.

Stylesheet switching with memory is ideal, for example, if you want your iPhone/ tablet—or screen resolution-challenged work PC—to always use an alternative "accessible" layout. Cookies could likewise ensure that a different default style makes full use of your stunning 23" Apple Display.

Having decided against reusing the original ALA styleswitcher JavaScript, and considered using jQuery (as here—also JavaScript, but better), I looked at a few PHP options and settled on Roger Johansson's method.

Identifying off-site links

By default (Option 1) any link you tag with rel="external" will display the "off-site" icon (dimmed for visited links) using the included CSS. I prefer this option for identifying off-site links because it gives your audience the choice as to how links behave (the alternative is forcing them to open new windows using JavaScript or the depreciated target="_bank"). If you haven't religiously tagged your off-site links with rel="external" (or can't be bothered), you have two alternative options:

1. Open siteprefs.css and uncomment Option 2 (making sure the CSS for Options 1 and 3 is commented); this will apply the icon to all links other than to your own domain (credit). See the instructions in the file.
2. A WordPress plugin is available that will do it for you (Option 3). Once the Link Indication plugin is activated just uncomment the CSS for Option 3 in siteprefs.css (ensuring the CSS for Options 1 and 2 is commented-out).

Option 1 works in Firefox, IE7, and Safari (but not IE6). Option 2 works in Firefox and Safari (but not IE7 or IE6). Option 3 works in Firefox, IE7, IE6, and Safari (but does not differentiate between visited/ unvisited links).

Change log

Version	Notes
1.0	11.05.06. Initial 1.x release.
2.0	22.01.08. Initial 2.x release.
2.1	28.01.08. Corrected CSS for off-site links. Added alternative methods of identifying off-site links using pseudo-class (Option 2) or class (Option 3).