Creating a new simple shortcode

Shortcodes are a very popular tool in WordPress that allow users to easily add content generated by plugins or themes to any page or post without needing to be familiar with PHP code and editing theme template files. As they are very simple to create, shortcodes can also be used to easily automate the display of content that repeatedly needs to be inserted on your site.

How to do it...

Follow these steps to create a new custom shortcode that will accelerate the task of linking to a specific Twitter page in any post or page:

1. Navigate to the WordPress plugins directory of your development installation.
2. Create a new directory called ch2-twitter-shortcode.
3. Navigate to this directory and create a new text file called ch2-twitter-shortcode.php.
4. Open the new file in a code editor and add an appropriate header at the top of the plugin file, naming the plugin Chapter 2 - Twitter Shortcode.
5. Add the following line of code to declare a new shortcode, simply using the two tl characters, and specify the name of the function that should be called when the code is encountered in posts or pages:

   add_shortcode( 'tl', 'ch2ts_twitter_link_shortcode' );

6. Add the following code section to provide an implementation for the ch2ts_twitter_link_shortcode function:

   function ch2ts_twitter_link_shortcode( $atts ) {
       $output =
           '<a href="https://twitter.com/ylefebvre">';
       $output .= 'Twitter Feed</a>';
       return $output;
   }

7. Save and close the plugin file.
8. Log in to the administration page of your development WordPress installation.
9. Click on Plugins in the left-hand navigation menu.
10. Activate your new plugin.
11. Edit an existing post on your site and use the [tl] shortcode in the code editor:

Figure 2.10 – Inserting the [tl] shortcode in the new page contents

12. Save and view the post to see that the shortcode was replaced by a link to a Twitter page attached to the words Twitter Feed.

How it works...

Shortcodes have similarities with both action hooks and filter hooks, since their associated custom function is called when it is time to perform a task, just like an action hook, but they must return their output through a return value, just like a filter hook. In terms of external data, the function associated with a shortcode will receive data in the case of some types of shortcodes, while it will only produce output in other cases.

When used in the content of a post or page, any shortcode surrounded by a pair of square brackets is identified by the WordPress engine, which then searches for functions registered for that specific code. If found, the associated function is called, and the expected result is used to replace the original shortcode text in the item's content. Just like filter functions, shortcode functions must not output any text directly, since it will likely appear in an unexpected place in the page layout, as WordPress calls all shortcode-processing functions before displaying the body of an item.

For simple shortcodes, such as the one found in this recipe, the plugin functions associated with them must return information, but they do not receive any additional data through function parameters. That being said, they can rely on utility functions, such as get_the_ID, get_the_title, and other WordPress utility functions, to get more information on the item that contains them and be able to produce tailored output. Other types of shortcodes seen in later recipes will have more context and configuration options. It is also possible for shortcodes to access stored options data, which will be covered in Chapter 3, User Settings and Administration Pages.

See also

• The Creating a plugin file and header recipe