An Alternative to the Shortcode Madness [Part 1]

I tend to spend a good amount of my time continuing to learn WordPress and improve the ways I go about coding themes. With the vast majority of my WordPress development being done for clients, it is important to me to keep a good relationship with them. I feel part of maintaining that relationship is to provide a seamless, simple, and easy solution to their website project. I refer to this as the “Don’t make me think” approach, which pairs nicely with “Just because you can, doesn’t mean you should”…

In most cases, clients spend most of their time adding/editing content in the editor. It is then important to keep things simple yet provide as much functionality as possible. If your clients or users are anything like mine, more than likely they don’t spend the vast majority of their time cleaning code in their favorite text editor and are probably not catching up on their RSS feed full of their favorite web related sites just before they go to bed at 2 am like the rest of us. Clients also get confused when they hear “It’s as simple as adding a class to the element” when trying to create the desired green glossy web 2.0 button. Usually this will lead you to a variety of blank stares as their idea of a class and elements is a room of kids and the periodic table.

Basically, for me to expect my clients to know, remember, and filter through the HTML to add a class to an anchor tag, buried in the middle of the text, is not my idea of a seamless, simple, and easy solution. This goes without mentioning the sometimes bizarre and crazy markup that can be made by the visual editor in the first place (insert previous “cleaning code” remark here ____).

So then, how can the client or user make that link look pretty and green, with rounded corners, a text shadow… and the groovy gradient gloss effect?

SHORTCODES!!! … or simply select the style from a drop down menu within the visual editor.

Implementing A Custom Styles Drop Down Menu

The first alternative up for debate is to provide a custom styles drop down menu. This method is simple to implement for developers and simple to use for users. This is by no means revolutionary as it has been done before, but it is certainly effective. Part of the beauty of adding a new styles drop down into the editor is:

1. The client does not have to remember a class name, or a shortcode name for that matter… both of which are usually found written down on a yellow post-it-note stuck to the outside edge of their monitor. I have an alternative for this as well that will be covered in another article.
2. It’s inside the visual editor. No need for the HTML view and code sifting.
3. It’s a common practice and recognized functionality.
4. “Don’t make me think” rule applied.

Below is the code necessary to implement a simple styles drop down box.

/** 
 * Filter TinyMCE Buttons
 *
 * Here we are filtering the TinyMCE buttons and adding a button
 * to it. In this case, we are looking to add a style select 
 * box (button) which is referenced as "styleselect". In this 
 * example we are looking to add the select box to the second
 * row of the visual editor, as defined by the number 2 in the
 * mce_buttons_2 hook.
 */
function themeit_mce_buttons_2( $buttons ) {
  array_unshift( $buttons, 'styleselect' );
  return $buttons;
}
add_filter( 'mce_buttons_2', 'themeit_mce_buttons_2' );

/**
 * Add Style Options
 *
 * First we provide available formats for the style format drop down.
 * This should contain a comma separated list of formats that 
 * will be available in the format drop down list.
 *
 * Next, we provide our style options by adding them to an array.
 * Each option requires at least a "title" value. If only a "title"
 * is provided, that title will be used as a divider heading in the
 * styles drop down. This is useful for creating "groups" of options.
 *
 * After the title, we set what type of element it is and how it should
 * be displayed. We can then provide class and style attributes for that
 * element. The example below shows a variety of options.
 *
 * Lastly, we encode the array for use by TinyMCE editor
 *
 * {@link http://tinymce.moxiecode.com/examples/example_24.php }
 */
function themeit_tiny_mce_before_init( $settings ) {
  $settings['theme_advanced_blockformats'] = 'p,a,div,span,h1,h2,h3,h4,h5,h6,tr,';

  $style_formats = array(
      array( 'title' => 'Button',         'inline' => 'span',  'classes' => 'button' ),
      array( 'title' => 'Green Button',   'inline' => 'span',  'classes' => 'button button-green' ),
      array( 'title' => 'Rounded Button', 'inline' => 'span',  'classes' => 'button button-rounded' ),
      
      array( 'title' => 'Other Options' ),
      array( 'title' => '½ Col.',      'block'    => 'div',  'classes' => 'one-half' ),
      array( 'title' => '½ Col. Last', 'block'    => 'div',  'classes' => 'one-half last' ),
      array( 'title' => 'Callout Box',        'block'    => 'div',  'classes' => 'callout-box' ),
      array( 'title' => 'Highlight',          'inline'   => 'span', 'classes' => 'highlight' )
  );

  $settings['style_formats'] = json_encode( $style_formats );
  return $settings;
}
add_filter( 'tiny_mce_before_init', 'themeit_tiny_mce_before_init' );

Now, to apply our green button style to a link, all the user has to do is highlight the links text and select the “Green Button” style from the new drop-down. This link will now take on the simple and universal CSS-based button style set in your themes stylesheet. There is various methods to doing this. Instead of a span tag for the button, you could use an “a” tag. Play around and see what you think.

Take It Another Step Further with Editor Styles

So now we have made things easier for our users to style elements without having to touch any code or add a single shortcode. Let’s take things one step further and add those styles to the visual editor so the users can see the results. To do this, we will simply add a few lines of code to the functions.php and create a new stylesheet for the editor to use.

/**
 * Add Editor Style
 *
 * This provides the theme with the functionality to add a custom
 * TinyMCE editor stylesheet. By default, the add_editor_style() will
 * look for a stylesheet named editor-style.css in your theme. Here
 * we have chosen to define our own stylesheet name, style-editor.css.
 * This stylesheet can be named whatever you want, just be sure it is
 * defined in the function below and included in your theme files.
 *
 *{@link http://codex.wordpress.org/Function_Reference/add_editor_style }
 */
 
function themeit_add_editor_style() {
  add_editor_style( 'style-editor.css' );
}
add_action( 'after_setup_theme', 'themeit_add_editor_style' );

By providing the add_editor_style() function, we are telling WordPress the theme is including a custom TinyMCE editor stylesheet. Now we can include any custom styles the theme may use into a css file called style-editor.css, which we defined in the add_editor_style() function. By default, if a stylesheet name is not defined here, WordPress will look for a file called editor-style.css. I usually change the name to style-editor.css for organizational purposes so the file is listed next to my style.css file. For a great starting point, take look at the Twenty Eleven theme’s editor-style.css file.

Down the Road…

I have a few other, possibly more advanced methods, I would like to share down the road regarding this topic of shortcode alternatives. These methods are a little more robust and allow for more advanced styling to elements. For the sake of an already lengthy article, I’ve decided to split it up into multiple “Parts”. In short, these methods include the use of Quicktags, Advanced TinyMCE Buttons, and “Smart” Editor styles. If your like me and prefer to dig around in code to figure things out on your own, all these methods are currently used in the Debut Theme on Press75.com.