147 And that’s all there is to it! Depending on placement of the function call, your comments area should now feature quick and easy “spam” and “delete” buttons next to each individual comment. Even better, this improved function is version- independent, backwards-compatible, and thus will work for any version of WordPress. 5.3.5 Example #2: Sitewide Shortcode Functionality In short, WordPress shortcodes are shortcuts for frequently used content such as links, images, and titles. As you blog, instead of writing out the entire link to your homepage, for example, shortcodes enable you to simply write “[home]” anywhere you would like the link to appear. Of course, more complex shortcodes are possible, including shortcodes that include varying attributes. This functionality is made possible thanks to a set of functions called the Shortcode API that was introduced in WordPress 2.5. When a shortcode is encountered, it is processed by the WordPress API and its associated functionality is executed. The easiest way to implement shortcode functionality is to specify your shortcodes via the functions.php file. Here is a PHP function that will convert the [home] shortcode into a link to your site’s homepage: 148 When you are building a theme, and the circumstance comes up where you need to create a link to a specific page hard-baked right into the theme, there is a function you should be using. Not great <a href="/contact/">Contact</a> Much better <a href="<?php echo get_permalink(12); ?>">Contact</a> That “12” would be the ID of the Post or Page. Why is this better? • If the slug ever changes, you are still cool. • If the site moves from a sub directory (like if you were developing and then moving) to a top level domain or vice versa, you are still cool. Doing it this way is a permanent reference to that Post or Page that will always be correct. This works great when we are working within our theme files, but what about when we are working within WordPress and actually writing Posts and Pages? By default, we can’t run PHP within the content of our Posts and Pages*, so we can’t use the get_permalink function. What we can do, is create a shortcode with just about the same functionality. * If you need to run PHP inside Post content, check out this plugin: http://digwp.com/u/465 function permalink_thingy($atts) { extract(shortcode_atts(array( 'id' => 1, 'text' => "" // default value if none supplied ), $atts)); if ($text) { $url = get_permalink($id); return "<a href='$url'>$text</a>"; } else { return get_permalink($id); } } add_shortcode('permalink', 'permalink_thingy'); This shortcode can be used in two ways: Basic <a href="[permalink id=49]">Using without providing text</a> Provide only the ID parameter and it only returns a URL. This way you can use that URL however you want. For example, if you needed to add a special class name to the link or something (but only occasionally). Providing text [permalink id=49 text='providing text'] This way returns a fully formatted anchor link back, using the text you pass. Easy Shortcode Permalinks 149 <?php // shortcode for homepage link function myHomePage() { return '<a href="http://domain.tld/" title="My Website Homepage">My Homepage</a>'; } add_shortcode('home', 'myHomePage'); ?> Place this function in your theme’s functions.php file, and then call the function by using the shortcode. Simply write “[home]” anywhere in your blog post and WordPress will run the myHomePage function and display the link to your homepage. 5.3.6 Example #3: Transferring Plugins to functions.php As we have seen in the previous two examples, the functions.php file is perfect for extending the functionality of WordPress. In addition to these types of functions, we can also move entire plugins into the functions.php file. One reason for doing this involves isolating the plugin’s functionality to a specific theme. Plugin functionality affects all themes, whereas a functions.php file will only affect its associated theme. Transferring the contents of most plugins is as simple as copying and pasting the contents into the functions.php file. Some plugins may require additional modifications to work properly when relocated to the functions.php. 150 5.3.7 Example #4: Transferring Functions to a Plugin Just as it is easy to transfer a plugin to a functions.php, it is also easy to create a plugin from any functions.php function. For either of the two example functions given above, we would simply copy and paste the contents into an empty PHP file (named anything you like) and activate via the WordPress Admin area. Before uploading to the server, we need to specify the plugin details at the beginning of the plugin file. There are several pieces of information that are required, as seen in this example for a plugin based on our shortcode functionality: <?php /* Plugin Name: Easy Admin Buttons for Comments Plugin URI: http://digwp.com/ Description: Provides easy comment moderation links. Version: 1.0 Author: Digging into WordPress Author URI: http://digwp.com/ */ ?> After placing this code at the beginning of the plugin file, edit the information appropriate to your plugin and you’re good to go. Generally we would prefer to place simple functions in the functions.php file, but implementing them in plugin format does have its benefits, including the ability to affect functionality across multiple themes. These examples and techniques are just the tip of the iceberg when it comes to the wide range of functionality that may be implemented via your theme’s functions.php file. Of course, beyond plugins and theme functions, there are other ways to extend the functionality of WordPress as well. Let’s take a look. 151 5.4.1 Other Ways to Extend WordPress Functionality So far we have explored the two most common ways of extending WordPress functionality, namely, plugins and the functions.php file. In addition to these methods, you may also implement custom functionality directly within your theme template files. 5.4.2 Functions Within Theme Files As discussed in the Themes Chapter of this book, theme template files contain numerous template tags, PHP scripts, and (X)HTML markup. Within these files, designers and developers may place just about any custom functionality they wish. For example, the previous functions.php example for “Easy Admin Buttons” could be placed directly within the theme file instead. Within the comment loop, we could add the script as follows: <p><?php comment_author_link(); ?><p> <p><?php if (current_user_can('edit_post')) { echo '<a href="'.get_bloginfo('wpurl').'/wp-admin/comment.php ?action=cdc&c='.comment_ID().'">Delete</a>'; echo ' | <a href="'.get_bloginfo('wpurl').'/wp-admin/comment.php ?action=cdc&dt=spam&c='.comment_ID().'">Spam</a>'; } ?></p> <?php comment_text(); ?> 152 This setup will output the following markup, which will vary depending on the actual content of your site: <p><a href='http://domain.tld/' rel='external nofollow'>Author</a></p> <p><a href="http://domain.tld/wp-admin/comment.php ?action=cdc&c=123">Delete</a> | <a href="http://domain.tld/wp-admin/ comment.php?action=cdc&dt=spam&c=123">Spam</a></p> <p>Hello, thanks for this article, it is exactly what I needed!</p> The key to placing functions directly in your theme template files involves removing the function declaration from the function itself. Of course, this is just one example of a custom function that works well when integrated directly into a theme template file. Another great example of this involves just about any sort of custom loop functionality. The WordPress loop is the core component of many theme files. Integrating custom loop functionality directly into the loop itself is easier and simpler than trying to separate customizations into a plugin or functions.php file. In other situations, it makes more sense to keep snippets of custom functionality in theme files, if for no other reason than to keep your templates clear and easy to understand. 5.4.3 Hacking the WordPress Core And of course, last and certainly least, we arrive at the “forbidden” method of extending WordPress, which is more accurately described as modifying default WordPress functionality, aka “hacking the WordPress core.” Hacking the WordPress core is nothing short of a heinous crime by today’s standards, but it remains an effective way to achieve functionality not available through other, more legitimate methods. 153 While some WordPress heads will argue that you should absolutely, positively never hack a core WordPress file on any occasion or for any reason whatsoever and forever and ever and ever, the truth is that there are some cases where getting the job done is more important than following ideals and best practices. When functional goals cannot be met with existing plugins and scripts, a solution may be found in the editing of the WordPress core. “What!?” I hear some purists freaking out right now, screaming loudly and shaking their fists in opposition, “this is blasphemy against the WordPress gods!” But if you think about it, there really is nothing sacred about the WordPress core. The usual arguments against editing core files revolve mostly around the concept of maintainability. WordPress is continually updated with patches, fixes, and new versions. Thus, having a bunch of core edits to worry about reduces the ease of which these updates are applied to your site, or so the thinking goes. Regardless of the debate, there may be situations where you have no choice but to hack a few lines of core code to do the job. So, rather than pretend that people don’t do it, here are some tips for when you find yourself doing the “evil” deed: Super-Easy Post-Thumbnails Surfing the Web, you will notice that many blogs include a thumbnail image for each post. For example, at DigWP.com, we attach a thumbnail to every post to help improve the user-experience for visitors. Before WordPress version 2.9, including these post-thumbnails required use of custom-fields, but now with 2.9 and better, WordPress features a much easier way of doing it. To get started with post thumbnails, add the following line of code to your theme’s functions.php file: if (function_exists('add_theme_support')) { add_theme_support('post-thumbnails'); } With that code in place, go to write or edit a post as usual in the Admin, and click on the “Set Thumbnail” link in the “Post Thumbnail” panel. From there, select and tag your image from within the Media Library. Then, to display your post thumbnails in your theme, add the following template tag within the loop: <?php has_post_thumbnail(); ?> There is much more that can be done with WordPress' post-thumbnail feature. To learn more about additional tags and ways to customize things, check out Chapter 11.2.7. 154 • Don’t hack the core unless you have absolutely no other option • Do your research and understand exactly what you are doing • Create a “read-me-before-updating” text le that details the changes Bottom line: Before hacking the core, do your research, know what you are doing, and make absolutely certain that no other options exist. Also, take good notes and refer to them before every future WordPress upgrade. You never know, you may actually learn something new from digging around under the hood! 5.5.1 WordPress as a Content Management System (CMS) As we have seen, the possibilities for extending WordPress functionality are virtually endless. What began as a humble blogging platform called b2/cafelog way back in 2001 is now robust and flexible enough to serve as a highly customizable Content Management System (CMS). One of the main distinctions between a CMS and a simple blog involves the flexibility of the underlying software and its ability to create and manage multiple users and various types of digital media, which may include everything from text and images to audio and video content. 5.5.2 CMS Features Built Into WordPress Out of the box, WordPress provides many features that help any number of users publish and manage a wide variety of digital content, and with the addition of a few key plugins, transforming WordPress into a fully functional CMS is a breeze. In this section, we’ll first examine the CMS functionality that is built into WordPress, and then explore some key plugins that take WordPress’ CMS capabilities to the next level. Update: WordPress 3.0 Check out Chapter 12 to learn about all of the new CMS- related functionality that is now included with WordPress. 155 5.5.3 Working With Custom Fields Perhaps the most powerful CMS-enabling feature included with WordPress is found in its robust custom-fields functionality. WordPress Custom Fields enable users to associate additional custom content and information with each Post. To better understand how Custom Fields work, let’s consider a scenario where you would like to associate thumbnail images with your posts. You could include the image information along with the post text. But this setup would force you to display the thumbnail along with the post, in the exact order that it appears in the post content. If you wanted to display the thumbnail outside of the post, say in the sidebar, how would you go about it? Easy. Custom Fields to the rescue. By setting a custom field key named “thumbnail” with a corresponding value of “http://domain.tld/images/ thumbnail-01.jpg”, we have associated the thumbnail with our post in such a way that will enable us to display it anywhere on the page. With the custom fields added to our posts, we are now ready to tap into some core WordPress functionality and display our custom post-images in the desired fashion. The function we will be using to retrieve the custom images is get_post_meta(), which is a native WordPress function designed to retrieve specific custom-field key values. The get_post_meta() function takes the following three parameters: $post_id - defines the post from which the custom-field data is called $key - defines the key of the desired custom-field meta value $single - specifies whether to return the data as a string or as an array Good Using custom elds for post thumbnails is the way to go. Bad Putting post thumbnails in the content itself isn’t very exible. 156 Plugged into the get_post_meta() function, these parameters look like this: <?php get_post_meta($post_id, '$key', $single); ?> To specify the ID parameter, $post_id, for each post, we use “$post->ID”, which requires the function to be placed within the loop. For the $key parameter, we will use the name of the target key, which in this case is “thumbnail”. And finally, because we want the key value returned as a string, we use “true” for the $single parameter. At this point our get_post_meta() function looks like this: <?php get_post_meta($post->ID, 'thumbnail', true); ?> And we are almost there. As is, this code will simply return the custom-field value without printing it to the web page. So, we make one final edit to “echo” the data to appear in the browser: <?php echo get_post_meta($post->ID, 'thumbnail', true); ?> When placed in the loop, this function will output each post’s “thumbnail” custom- field value, which at this point is simply a URL to the specific thumbnail image. For example: http://domain.tld/path/custom-01.png Not very useful for your visitors, however, by enclosing our function with a little markup, we can easily transform that URL into an actual image that links to its corresponding post: <a href="<?php the_permalink() ?>" title="<?php the_title(); ?>"> <img src="<?php echo get_post_meta($post->ID, 'thumbnail', true); ?>" alt="Icon for Post #<?php the_ID(); ?>" /> </a> . help improve the user-experience for visitors. Before WordPress version 2.9, including these post-thumbnails required use of custom-fields, but now with 2.9 and better, WordPress features a. improved function is version- independent, backwards-compatible, and thus will work for any version of WordPress. 5.3.5 Example #2: Sitewide Shortcode Functionality In short, WordPress shortcodes are. With Custom Fields Perhaps the most powerful CMS-enabling feature included with WordPress is found in its robust custom-fields functionality. WordPress Custom Fields enable users to associate