A primer on writing WordPress plugins – part 2

In the previous article I described how easy it is to create a useful plugin.

The result was a plugin, that can be used to display a ‘read more’ link on an excerpt, which has none by default.

But something is missing. The plugin shows ‘Read More’, and if the user of this plugin wants it to display something different, he or she has to modify the plugin to let it show ‘Blah blah blah’ if wanted. All other plugins have cool menus in the admin panel, with cool forms to make changes to their behavior. That’s something we can easily add to this plugin (and any plugin you create).

Let’s start. There are actually four things we want to do:

  1. create a menu in the admin panel
  2. create a form to enter our custom text
  3. put that value in the database
  4. extract that value to show on the website

The cool part of it all is, is that WordPress takes care of all security aspects, and even internationalization is been taken care of.

Create a menu in the admin panel

To create a menu item in the admin menu, we have to call the add_action() function, to add an action to well, a hook. This action registers a function, which will actually call the menu building code.

The actual registration looks like this:

add_action('admin_menu', 'my_plugin_menu');

which registers the my_plugin_menu() function to the admin menu. This my_plugin_menu() function creates the actual menu item:

function my_plugin_menu() {
  add_options_page('WP Excerpt More Options', 'WP Excerpt More', 8, 'wp-excerpt-more', 'plugin_options');
}

I use the add_options_page() function, because this will add the menu item to ‘options’, where most other plugins create their menu items as well. Other possibilities are: add_posts_page() to add a menu item to the posts menu, add_theme_page() to add to the themes menu, add_pages_page() to add… you get the picture.

These functions take a few options: ‘WP Excerpt More Options’ is the text that is displayed in your browser window (and the tab, if applicable – the page title), ‘WP Excerpt More’ is the text shown in the menu (under options). The ’8′ is the minimum capability a user needs to have to access this menu, in this case ‘Administrator’. I would not suggest anything lower than 8. The fourth parameter needs to be an unique identifier, just go ahead and be unique. The last parameter is the function that we’re going to use to create the actual form in. for now, just add this:

function plugin_options() {
  echo '<div class="wrap">';
  echo '<p>This is where the form will be.</p>';
  echo '</div>';
}

If you append these three snippets to the plugin you hopefully copied from the first article, at the bottom, just before the closing php tag, and you open the options menu in the admin panel, then you’ll actually see an additional menu option, called ‘WP Excerpt More’ (or whatever you typed as second parameter), and if you click that, you’ll see the text from the last snippet.

Create a form to enter our custom text and adding the value to the database

I’m somewhat combining these two, since it could be very messy if we used different files or functions for the form and the submission of it. This is my plugin_options() function (just replace the above one with this one). It’s kinda long, so bare with me:

function plugin_options() {
  // variables for the field and option names
  $opt_name = 'wp_excerpt_more';
  $hidden_field_name = 'wp_excerpt_submit_hidden';
  $data_field_name = 'wp_excerpt_more';
 
  // Read in existing option value from database
  $opt_val = get_option( $opt_name );
 
  // See if the user has posted us some information
  // If they did, this hidden field will be set to 'Y'
  if( $_POST[ $hidden_field_name ] == 'Y' ) {
  // Read their posted value
    $opt_val = $_POST[ $data_field_name ];
 
  // Save the posted value in the database
    update_option( $opt_name, $opt_val );
 
  // Put an options updated message on the screen
 
?>
<div class="updated"><p><strong>< ?php _e('Options saved.', 'mt_trans_domain' ); ?></strong></p></div>
< ?php
 
  }
 
  // Now display the options editing screen
 
  echo '<div class="wrap">';
 
  // header
 
  echo "<h2>" . __( 'Menu WP Excerpt More Plugin Options', 'mt_trans_domain' ) . "</h2>";
 
  // options form
 
?>
 
<form name="form1" method="post" action="<?php echo esc_url(str_replace( '%7E', '~', $_SERVER['REQUEST_URI'])); ?>">
  <input type="hidden" name="<?php echo $hidden_field_name; ?/>" value="Y">
 
  <p>< ?php _e("Read More String to Display:", 'mt_trans_domain' ); ?>
  <input type="text" name="<?php echo $data_field_name; ?/>" value="< ?php echo $opt_val; ?>" size="50">
  </p><hr />
 
  <p class="submit">
  <input type="submit" name="Submit" value="<?php _e('Update Options', 'mt_trans_domain' ) ?/>" />
  </p>
</form>
 
 
< ?php
 
}

The opt_name variable holds the option name that actually will be in the wp_options table in the database. I chose wp_excerpt_more, since that somewhat resembles the name of the plugin. Also in this case you need to be unique, what you don’t want is overwrite some existing (and possibly important) settings. The other two variables are for the form, the hidden_field_name to verify whether submit has been pressed or not, the last one to hold the text typed into the form. In this case we only need one text file (the text that will be displayed in the ‘read more’ link).

  // Read in existing option value from database
  $opt_val = get_option( $opt_name );

WordPress delivers us some functions to retrieve option values from, and put option values into the wp_options table, without us actually having to know what this table is called. The get_option() function is the one that retrieves the value. It takes one parameter: the option it's supposed to get the value for. In our case that's the value for 'wp_excerpt_more', if it has one.

  // See if the user has posted us some information
  // If they did, this hidden field will be set to 'Y'
  if( $_POST[ $hidden_field_name ] == 'Y' ) {
  // Read their posted value
    $opt_val = $_POST[ $data_field_name ];
 
  // Save the posted value in the database
    update_option( $opt_name, $opt_val );
 
  // Put an options updated message on the screen
 
?>
<div class="updated"><p><strong>< ?php _e('Options saved.', 'mt_trans_domain' ); ?></strong></p></div>

This part checks whether the submit button has been pressed, and if it has, it'll put the text, typed into the form, into the database with the update_option() function. This function needs two parameters: the option the value belongs to, and the actual value. The '_e' function could be replaced by an echo, however this function is internationalization aware (leave the 'mt_trans_domain' for granted).

< ?php
 
  }
 
  // Now display the options editing screen
 
  echo '<div class="wrap">';
 
  // header
 
  echo "<h2>" . __( 'Menu WP Excerpt More Plugin Options', 'mt_trans_domain' ) . "</h2>";
 
  // options form
 
?>
 
<form name="form1" method="post" action="<?php echo esc_url(str_replace( '%7E', '~', $_SERVER['REQUEST_URI'])); ?>">
  <input type="hidden" name="<?php echo $hidden_field_name; ?/>" value="Y">
 
  <p>< ?php _e("Read More String to Display:", 'mt_trans_domain' ); ?>
  <input type="text" name="<?php echo $data_field_name; ?/>" value="< ?php echo $opt_val; ?>" size="50">
  </p><hr />
 
  <p class="submit">
  <input type="submit" name="Submit" value="<?php _e('Update Options', 'mt_trans_domain' ) ?/>" />
  </p>
</form>
 
 
< ?php
 
}

This snippet displays the actual form. The div class="wrap" is needed to display the form in the correct admin panel layout, I haven't tried to change that (or leave it out all together). The rest is fairly simple: create a form, that calls itself after submission (that's where we needed the hidden submit field for), read some data (input type="text"), and submit it.

All the above code (which isn't that much) is needed to create a option menu, create a form, and put the option into the database. You can use this part already, however it will not change the text in the web page (the 'Read more' part).

Extract the option value to show on the website

Remember this part from the previous article:

function WPReadMore_Link()
{
  global $post;
 
  // get the URL to the post
  $link=get_permalink($post->ID);
 
  // get the post title
  $title=$post->post_title;
 
  // create a Read More and return it
  return ‘<a class="myreadmorelink" href="’.$link. ‘" title="’.$title.‘">Read more</a>’;
}

So we change that into this:

function WPReadMore_Link()
{
  global $post;
  $opt_name = 'wp_excerpt_more';
 
  // Read in existing option value from database
  $opt_val = get_option( $opt_name );
  if ($opt_val == "") 
    $opt_val = "Read more";
 
 
  // get the URL to the post
  $link=get_permalink($post->ID);
 
  // get the post title
  $title=$post->post_title;
 
  // create a Read More and return it
  return '<div class="wpexcerptmore"><a href="'.$link. '" title="'.$title.'">'.$opt_val.'</a></div>';
}

The first part is reading the options database:

  $opt_name = 'wp_excerpt_more';
 
  // Read in existing option value from database
  $opt_val = get_option( $opt_name );
  if ($opt_val == "") 
    $opt_val = "Read more";

We put, if found in the database, the value for option 'wp_excerpt_more' into the variable $opt_val, and if it's empty (which it is when the plugin is first installed) give it the value 'Read more'. So $opt_val will always have a value, which can be used in the actual display on the web page.

Here's where we use it:

  return '<div class="wpexcerptmore"><a href="'.$link. '" title="'.$title.'">'.$opt_val.'</a></div>';

Conclusion

It could be that I lost you somewhere during this discussion, so here's the complete plugin:

< ?php
/*
Plugin Name: WP Excerpt More
Version: 0.7
Description: Automatically adds Read More link to your excerpts.
Author: Peter Boosten
Author URI: http://www.boosten.org
Plugin URL: http://www.boosten.org
*/
 
 
/* Version check */
global $wp_version;
 
$exit_msg='WP Excerpt More requires Wordpress 2.6 or newer.
<a href="http://codex.wordpress.org/Upgrading_WordpPress">Please update!';
 
if (version_compare($wp_version,"2.6","< "))
{
  exit ($exit_msg);
}
 
/* Show a Read More link */
 
function WPReadMore_Link()
{
  global $post;
  $opt_name = 'wp_excerpt_more';
 
  // Read in existing option value from database
  $opt_val = get_option( $opt_name );
  if ($opt_val == "")
      $opt_val = "Read more";
 
  // get the URL to the post
  $link=get_permalink($post->ID);
 
  // get the post title
  $title=$post->post_title;
 
  // create a Read More and return it
  return '<div class="wpexcerptmore"><a href="'.$link. '" title="'.$title.'">'.$opt_val.'</a></div>';
}
 
/* Add Read more to the end of the excerpt */
 
function WPReadMore_ContentFilter($excerpt)
{
  return $excerpt.WPReadMore_Link();
}
 
add_filter('the_excerpt','WPReadMore_ContentFilter');
 
/* Vanaf hier is toegevoegd voor options */
 
add_action('admin_menu', 'my_plugin_menu');
 
function my_plugin_menu() {
//  add_options_page('My Plugin Options', 'My Plugin', 8, 'your-unique-identifier', 'my_plugin_options');
  add_options_page('WP Excerpt More Options', 'WP Excerpt More', 8, 'wp-excerpt-more', 'plugin_options');
}
 
function plugin_options() {
  // variables for the field and option names
  $opt_name = 'wp_excerpt_more';
  $hidden_field_name = 'wp_excerpt_submit_hidden';
  $data_field_name = 'wp_excerpt_more';
 
  // Read in existing option value from database
  $opt_val = get_option( $opt_name );
 
  // See if the user has posted us some information
  // If they did, this hidden field will be set to 'Y'
  if( $_POST[ $hidden_field_name ] == 'Y' ) {
  // Read their posted value
    $opt_val = $_POST[ $data_field_name ];
 
  // Save the posted value in the database
    update_option( $opt_name, $opt_val );
 
  // Put an options updated message on the screen
 
?>
<div class="updated"><p><strong>< ?php _e('Options saved.', 'mt_trans_domain' ); ?></strong></p></div>
< ?php
 
  }
 
  // Now display the options editing screen
 
  echo '<div class="wrap">';
 
  // header
 
  echo "<h2>" . __( 'Menu WP Excerpt More Plugin Options', 'mt_trans_domain' ) . "</h2>";
 
  // options form
 
?>
 
<form name="form1" method="post" action="<?php echo esc_url(str_replace( '%7E', '~', $_SERVER['REQUEST_URI'])); ?>">
  <input type="hidden" name="<?php echo $hidden_field_name; ?/>" value="Y">
 
  <p>< ?php _e("Read More String to Display:", 'mt_trans_domain' ); ?>
  <input type="text" name="<?php echo $data_field_name; ?/>" value="< ?php echo $opt_val; ?>" size="50">
  </p><hr />
 
  <p class="submit">
  <input type="submit" name="Submit" value="<?php _e('Update Options', 'mt_trans_domain' ) ?/>" />
  </p>
 
</form>
 
 
< ?php
 
}
 
 
?>

And if you really don't have time to type it all, here's the link to the complete plugin: http://devnull.boosten.org/plugins/wp-excerpt-more.zip

That's all for now.

This entry was posted on Monday, September 21st, 2009 at 8:23 pm and is filed under webpublishing. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

7 Comments to A primer on writing WordPress plugins – part 2

  • A primer on writing WordPress plugins – part 2 | boosten.org says:
    September 22, 2009 at 1:59 am

    [...] reading here: A primer on writing WordPress plugins – part 2 | boosten.org Comments0 Leave a Reply Click here to cancel [...]

    Reply to this Comment
  • A primer on writing WordPress plugins – part 2 | boosten.org | www.kotihost.com says:
    September 22, 2009 at 10:33 am

    [...] the original post: A primer on writing WordPress plugins – part 2 | boosten.org Share and [...]

    Reply to this Comment
  • A primer on writing bWordPress plugins/b – part 2 | boosten.org says:
    September 22, 2009 at 11:19 am

    [...] the rest here: A primer on writing bWordPress plugins/b – part 2 | boosten.org SHARETHIS.addEntry({ title: "A primer on writing bWordPress plugins/b – part 2 | boosten.org", [...]

    Reply to this Comment
  • A primer on writing WordPress plugins – part 2 | boosten.org | Hot WP Themes says:
    September 22, 2009 at 12:17 pm

    [...] used to display a ‘read more’ link on an excerpt, which has none by …Read more: A primer on writing WordPress plugins – part 2 | boosten.orgRelated Posts:A primer on writing WordPress plugins – part 2 | boosten.org130 WordPress Plugins [...]

    Reply to this Comment
  • A primer on writing WordPress plugins – part 2 | boosten.org | Hot WP Themes says:
    September 22, 2009 at 12:18 pm

    [...] a ‘read more’ link on an excerpt, which has none by …Go here to see the original:A primer on writing WordPress plugins – part 2 | boosten.orgRelated Posts:A primer on writing WordPress plugins – part 2 | boosten.org130 WordPress Plugins [...]

    Reply to this Comment
  • Algeo says:
    September 28, 2009 at 4:58 am

    [...] the original post: A primer on writing WordPress plugins – part 2 | boosten.org Share and [...];

    Reply to this Comment
  • free palm pre says:
    October 23, 2009 at 8:50 pm

    Excellent article, bookmarked for future referrence

    Reply to this Comment

    • Leave a Reply

    Spam Protection by WP-SpamFree

    Subscribe without commenting