As great as shortcodes are, there is still one small issue that can come up from time to time. Consider this snippet of code:
[related_posts limit="3" category="review"]
It may look simple enough to you, but remember that we are usually developers (although if you’re not, kudos for getting this far along), so you’re used to seeing code that looks like this. We developers generally can remember attributes and how to add them like this. However, for authors, it’s more likely that they will never have seen code like this before, and remembering attributes and how to add them can be quite a foreign experience for someone generally just used to writing copy. Fortunately, there is a really easy way of adding a better method for the authors to insert shortcodes: the TinyMCE interface (see Figure 6-3).
Figure 6-3. The TinyMCE editor interface is the range of buttons above the main editor window
The TinyMCE editor has a range of controls for users to add things like headers or bold styling to their content, but there’s also an API available for developers to be able to add their own buttons.
The first step is to create functions to register the button with the TinyMCE buttons and then include a JavaScript file that will handle the button processing:
function prowordpress_register_shortcode_button( $buttons ) { array_push( $buttons, "relatedposts" );
return $buttons; }
function prowordpress_add_shortcode_plugin( $plugin_array ) {
$plugin_array['relatedposts'] = get_template_directory_uri() . '/javascript/shortcode.js'; return $plugin_array;
Chapter 6 ■ Customize with hooks, shortCodes, and widgets
The first function takes the $buttons parameter as an array of the TinyMCE buttons, and then adds the name of the button (relatedposts) to the end of the array. The second function is the one that handles the JavaScript file; here you have another array as the parameter that you then add another key with the name of the shortcode to, pointing to the JavaScript file you’ll be using to control the functionality for the button.
Next you need to add a function to call the two other functions above to register the new button, of course this is done with actions but first you need to check whether the user is able to edit posts and whether you have the ability to use the rich editor (the TinyMCE editor).
function prowordpress_related_posts_button() {
if ( ! current_user_can('edit_posts') && ! current_user_can('edit_pages') ) { return;
}
if ( get_user_option('rich_editing') == 'true' ) {
add_filter( 'mce_external_plugins', 'prowordpress_add_shortcode_plugin' ); add_filter( 'mce_buttons', 'prowordpress_register_shortcode_button' ); }
}
add_action('init', 'prowordpress_related_posts_button');
This function is then added to the WordPress execution on the init hook, so you add the button before the page and editor are loaded.
Now you have the button being added via the PHP in the functions file, but you don’t have any code to make it do anything; this is where the JavaScript file comes in. There seem to be a couple of methods out there to do this, but I’ve opted for a method similar to the one used by Konstantinos Kouratoras in his Smashing Magazine article. His code contains a couple more functions, but I’ve just included the main piece of code that’s needed to give the button some functionality: (function() {
tinymce.create('tinymce.plugins.relatedposts', { init : function(ed, url) {
ed.addButton('relatedposts', { title : 'Related posts',
image : url+'/shortcode-icon.png', onclick : function() {
var limit = prompt("Number of posts to display", "5"); if (limit != null && limit != '') {
ed.execCommand('mceInsertContent', false, '[related_posts limit="'+limit+'"]'); } else { ed.execCommand('mceInsertContent', false, '[related_posts]'); } } }); } }); tinymce.PluginManager.add('relatedposts', tinymce.plugins.relatedposts); })();
This JavaScript function creates a new button based on the name you created in the PHP function 'relatedposts', and then you can add all necessary functionality within the init function.
The init function takes an object containing the title, image icon for the button, and what to do when the button is clicked. In the onclick function, you’re using a simple prompt to ask the user how many posts the shortcode should show (with a default of 5). Once the prompt has returned you can check the result and construct the shortcode with the mceInsertContent function. The result determines how the shortcode is constructed. The shortcode button now appears nicely at the end of the top line of the TinyMCE editor (see Figure 6-4).
Figure 6-4. Shortcode plugin button and the prompt to ask users for a number of posts
This was just a very brief look at how to add a button for your shortcodes; there are many more in-depth articles on the subject by Konstantinos Kouratoras as mentioned in his Smashing Magazine article:
http://wp-themes-book.com/06005 and by Gary Cao on his blog: http://wp-themes-book.com/06006.
Widgets (and Dynamic Sidebars)
Widgets were introduced in WordPress in version 2.8 as another way to allow content editors to easily add and control dynamic content. Widgets can range from adding a search box, to listing categories, archives, and posts or pages. Widgets use a simple drag-and-drop interface (see Figure 6-5) to allow users to position content within the theme wherever a widget area has been allocated and can be customized from within the Widget control panel, adding titles and choosing options about what or how that content will be displayed (see Figure 6-6).
Chapter 6 ■ Customize with hooks, shortCodes, and widgets
Note
■
although i’m using the term widget area, the wordpress Codex and a lot of other documentation refer to them
as sidebars, which is where the term dynamic sidebars comes from.
Figure 6-5. The Widgets control panel with the sidebar containing displayed widgets on the right