When I created the Sawchuk scheme for K2, I wanted a clean minimal theme that emphasized the content that I wrote. I wasn’t concerned with bells and whistles, I just wanted people to easily be able to read this website. WebDesignFromScratch has some great tips for emphasizing readability in webdesign. Those tips combined with a little common sense and style created the current look of Sawchuk.

However, the big problem with having different text styles available for use when writing posts is that you have to manually type out the class designations. For example, WordPress offers a blockquote button which theme authors can style using CSS. Sawchuk employs three different styles of blockquote each with their own background colour. In order to use these three different styles, the full class must be typed out like so: <blockquote class=”red”> Some text </blockquote>. The blockquote button alone isn’t enough to define the style (class=”red”) of the blockquote wanted.

This is where Owen’s ButtonSnap Class Library comes in. Using it, buttons can be added to the post editing screen for any class / span / element that a theme author / designer can imagine. Here is how its done:

1. Download the ButtonSnap Class Library and stick buttonsnap.php in its own folder. For now, you can get the buttonsnap class library by downloading the Sawchuk buttons plugin. The original home of ButtonSnap, RedAlt, recently suffered a breakdown and it is slowly being rebuilt. When it is back to normal, I expect most people to get it there.

Sawchuk Buttons Plugin

2. Create a new PHP file, save it in the same directory and then reference buttonsnap appropriately by including it like so:

include('buttonsnap.php')

3. Add an action so buttonsnap knows what to act on; that action should call the buttonsnap initialization function.

add_action('init', 'Sawchuk_button_init');
function Sawchuk_button_init() {

4. As part of the function, set up some unique button image URLs for the new buttons to use in the WYSWIG toolbar. These icons will show up only if using the WYSWIG editor, otherwise you’ll get text which is specified later. Note that in this case I have set the images to be in a subdirectory called ‘images’.

$Sawchuk_button_code_image_url = buttonsnap_dirname(__FILE__) . '/images/code.png';
// Repeat for every button you want to add changing variable name and graphic appropriately

5. Use the buttonsnap_ajaxbutton function to create each button you would like to add. buttonsnap_ajaxbutton takes three inputs: A) the path to an image file used to represent the button, B) the text used to represent the button, and C) a hook to the filter function that will . Here is an example:

buttonsnap_ajaxbutton($Sawchuk_button_code_image_url, 'Pcode', 'Sawchuk_code_insert_hook');

6. Here is the filter function to match the example above. It takes two inputs, first the hook, then the sink. The sink will define what the button is to do (shown in step 7). As well, the Sawchuk_button_init() function is closed to prepare for the separate functions of each button.

add_filter('Sawchuk_code_insert_hook', 'Sawchuk_code_insert_sink');
}


7. Each button you want to add gets its own function corresponding add_filter request shown above. The filter returns the selected text (after striping out slashes if the text contains quotes) AND the before and after text found in single quotes. It is this text where we add in the CSS reference.

function Sawchuk_code_insert_sink($selectedtext) {
return ‘<p class=”code”>’ . stripslashes($selectedtext) . ‘</p>’;
}

8. Finished! If you can follow that pattern you can create any amount of buttons you like. Here is a fully coded example from the Sawchuk Buttons plugin for the K2 Scheme Sawchuk I created. It brings each of the above steps into context a bit better.

Subscribe to MaxPower: zero shipping costs

[php]
< ?php
/*
Plugin Name: Sawchuk Buttons
Plugin URI: http://www.maxpower.ca
Description: Adds buttons to the post / page editor to take advantage of the Sawchuk scheme for K2 and its many post text styles
Version: RC 1
Author: Kirk Montgomery
Author URI: http://www.maxpower.ca
*/
// INSTALLATION / INSTRUCTIONS:
//
// This plugin requires both K2 (getk2.com) and the sawchuk scheme
// for K2 (http://www.maxpower.ca/sawchuk/2006/01/23/)
//
// Upload entire directory to your wordpress plugins folder. Head to the plugins
// menu and activate the plugin. Thats it. All these new buttons should be visible
// the next time you write a post (in whatever editor you use).
//
// REFERENCES / THANKS
//
// Icons used come from the Tango Desktop Project http://tango.freedesktop.org/Tango_Desktop_Project
// Buttonsnap is a CLASS LIBRARY By Owen Winkler (http://asymptomatic.net)
// This plugin uses a slightly modified version of buttonsnap done by
// John W Vanderbeck of http://www.jwvanderbeck.com. Thanks to both of you,
// for providing your code and hard work.

// 1. Initialize the buttonsnap php
include('buttonsnap.php');

// 2. Add an action so buttonsnap knows what to do
// The action calls a function, defined below
add_action('init', 'Sawchuk_button_init');

function Sawchuk_button_init() {
// 3. Set up some unique button image URLs for the new buttons to use iin the WYSI toolbar (does nothing in the Quicktags)
$Sawchuk_button_blockquote_green_image_url = buttonsnap_dirname(__FILE__) . '/images/bq_green.gif';
$Sawchuk_button_blockquote_red_image_url = buttonsnap_dirname(__FILE__) . '/images/bq_red.gif';
$Sawchuk_button_alert_image_url = buttonsnap_dirname(__FILE__) . '/images/alert.png';
$Sawchuk_button_blue_hilite_image_url = buttonsnap_dirname(__FILE__) . '/images/blue_hilite.png';
$Sawchuk_button_callout_image_url = buttonsnap_dirname(__FILE__) . '/images/callout.png';
$Sawchuk_button_code_image_url = buttonsnap_dirname(__FILE__) . '/images/code.png';
$Sawchuk_button_construction_image_url = buttonsnap_dirname(__FILE__) . '/images/construction.png';
$Sawchuk_button_download_image_url = buttonsnap_dirname(__FILE__) . '/images/download.png';
$Sawchuk_button_other_image_url = buttonsnap_dirname(__FILE__) . '/images/other.png';

// 4. Create a vertical separator in the WYSI toolbar (does nothing in the Quicktags)
buttonsnap_separator();
// 5. Create a button that uses Ajax to fetch replacement text from a WordPress plugin hook sink
buttonsnap_ajaxbutton($Sawchuk_button_blockquote_green_image_url, 'BQ: Green', 'Sawchuk_blockquote_green_insert_hook');
buttonsnap_ajaxbutton($Sawchuk_button_blockquote_red_image_url, 'BQ: Red', 'Sawchuk_blockquote_red_insert_hook');
buttonsnap_separator(); // Just another seperator to differentiate different types of Blockquotes
buttonsnap_ajaxbutton($Sawchuk_button_alert_image_url, 'Alert!', 'Sawchuk_alert_insert_hook');
buttonsnap_ajaxbutton($Sawchuk_button_blue_hilite_image_url, 'BlueHiLite', 'Sawchuk_blue_hilite_insert_hook');
buttonsnap_ajaxbutton($Sawchuk_button_callout_image_url, 'Callout', 'Sawchuk_callout_insert_hook');
buttonsnap_ajaxbutton($Sawchuk_button_code_image_url, 'Pcode', 'Sawchuk_code_insert_hook');
buttonsnap_ajaxbutton($Sawchuk_button_construction_image_url, 'Construction', 'Sawchuk_construction_insert_hook');
buttonsnap_ajaxbutton($Sawchuk_button_download_image_url, 'Download', 'Sawchuk_download_insert_hook');
buttonsnap_ajaxbutton($Sawchuk_button_other_image_url, 'Other', 'Sawchuk_other_insert_hook');

// 6. Add the filter to match the hook and sink together
add_filter('Sawchuk_blockquote_green_insert_hook', 'Sawchuk_blockquote_green_insert_sink');
add_filter('Sawchuk_blockquote_red_insert_hook', 'Sawchuk_blockquote_red_insert_sink');
add_filter('Sawchuk_alert_insert_hook', 'Sawchuk_alert_insert_sink');
add_filter('Sawchuk_blue_hilite_insert_hook', 'Sawchuk_blue_hilite_insert_sink');
add_filter('Sawchuk_callout_insert_hook', 'Sawchuk_callout_insert_sink');
add_filter('Sawchuk_code_insert_hook', 'Sawchuk_code_insert_sink');
add_filter('Sawchuk_construction_insert_hook', 'Sawchuk_construction_insert_sink');
add_filter('Sawchuk_download_insert_hook', 'Sawchuk_download_insert_sink');
add_filter('Sawchuk_other_insert_hook', 'Sawchuk_other_insert_sink');
}
// 7. Each function below corresponds to one button and matches to an above
// add_filter. The filter returns the selected text AND the before and after
// text found in single quotes.
function Sawchuk_blockquote_green_insert_sink($selectedtext) {
return '

‘ . stripslashes($selectedtext) . ”;
}

function Sawchuk_blockquote_red_insert_sink($selectedtext) {
return ‘

‘ . $selectedtext . ‘

‘;
}

function Sawchuk_alert_insert_sink($selectedtext) {
return ‘

‘ . stripslashes($selectedtext) . ‘

‘;
}

function Sawchuk_blue_hilite_insert_sink($selectedtext) {
return ‘

‘ . stripslashes($selectedtext) . ‘

‘;
}

function Sawchuk_callout_insert_sink($selectedtext) {
return ‘

‘ . stripslashes($selectedtext) . ‘

‘;
}

function Sawchuk_code_insert_sink($selectedtext) {
return ‘

‘ . stripslashes($selectedtext) . ‘

‘;
}

function Sawchuk_construction_insert_sink($selectedtext) {
return ‘

‘ . stripslashes($selectedtext) . ‘

‘;
}

function Sawchuk_download_insert_sink($selectedtext) {
return ‘

‘ . stripslashes($selectedtext) . ‘

‘;
}

function Sawchuk_other_insert_sink($selectedtext) {
return ‘

‘ . stripslashes($selectedtext) . ‘

‘;
}

// Fin.
?>
[/php]

ButtonSnap.php included in this download is slightly different than the version included with many plugins.

This version treats selected text properly when using the default editor in WordPress. Other plugins that use buttonsnap to put buttons on the toolbar may include an older version of ButtonSnap which may delete selected text. If another plugin you have enabled uses the buttonsnap.php class as well, it may supersede the version being distributed with this plugin. I recommend replacing the buttonsnap.php used in these other plugins with the one distributed here. Thanks go out to John W. Vanderbeck of jwvanderbeck.com for updating ButtonSnap. Check out his jPortfolio plugin.