Working with WordPress APIs, Objects, and Helper Functions

18 January 2022 Hits: 1062

In this article, we cover several WordPress APIs, objects, and helper functions that aren’t otherwise covered in the rest of the blog but are still important pieces of a WordPress developer’s arsenal.

Table of contents[Show]

Shortcode API

Shortcodes are specially formatted pieces of text that can be used to insert dynamic output into your posts, pages, widgets, and other static content areas.

Shortcodes come in three main flavors.:

A single shortcode like [myshortcode]
Shortcodes with attributes like [myshortcode id="1" type="text"]
Enclosing shortcodes like [myshortcode id="1"] ... some content here ... [/myshortcode]

In This Post, we shared an example of how to use shortcodes to add arbitrary content into a WordPress post or page. In that example, like flavor number one, we simply swapped out the shortcode for our content. You can also add attributes to the shortcode to affect the callback function processing it or wrap some content in an opening and closing shortcode pair to filter some particular content.

The primary step of creating shortcodes is to define the callback function for your shortcode using the add_shortcode() function. Any attributes are added to an array that is passed to the callback as the first $atts parameter. Any enclosed content is passed to the callback as the second $content parameter.

The following code creates a shortcode called msg and makes use of attributes and enclosed content:

<?php
/*
  shortcode callback for [msg] shortcode
  Example: [msg type="error"]This is an error message.[/msg]
  Output:
  <div class="message message-error">
      <p>This is an error message.</p>
  </div>
*/
function sp_msg_shortcode($atts, $content)
{
  //default attributes
  extract( shortcode_atts( array(
        'type' => 'information',
	), $atts ) );
  $content = do_shortcode($content);	//allow nested shortcodes
  $r = '<div class="message message-' .
    $type . '"><p>' . $content . '</p></div>';
  return $r;
}
add_shortcode('msg', 'sp_msg_shortcode');
?>

Notice that the content you want displayed is returned from the callback function rather than echoed to the output buffer. This is because the shortcode filter is typically run before any content has been pushed to the screen. If there were any echo calls inside this function, the output would show up at the top of the page instead of inline where you want it.

Shortcode Attributes

The other important piece demonstrated in the preceding code is how the default attributes are set. The shortcode_atts() function takes three parameters: $pairs, $atts, and $shortcode.

$pairs is an array of default attributes, where each key is the attribute name and each value is the attribute value.

$atts is a similar array of attributes, usually passed in straight from the $atts parameter passed to the shortcode callback function. The shortcode_atts() function merges the default and passed attributes into one array.

The $shortcode parameter is optional. If set to match the shortcode name, it will trigger a filter shortcode_atts_{shortcode} that can be used by other plugins and so on to override the default attributes.

The results of shortcode_atts() are then passed to the PHP function extract(), which creates a variable in the local scope for every key in the attributes array.

In this way, the variable $type in our example is available to the rest of the function and contains either the default value of message or whatever value was set in the shortcode itself.

Nested Shortcodes

Finally, we pass the inner $content through the do_shortcode() function to enable nested shortcodes. If you had a [help_link] shortcode that generated a link to your documentation depending on what section of a site you were on or the type of user logged in, you might want to use that shortcode within the [msg] shortcode:

[msg type="error"]
	An error has occurred. Use the following link for help: [help_link].
[/msg]

As long as the callback function for the [msg] shortcode passes its results through do_shortcode(), the inner [help_link] shortcode will be filtered as intended.

Caution

Though nested shortcodes of different types will work, nesting the same shortcode within itself will break. The regular expression (regex) parser that pulls the shortcodes out of content is engineered for speed. The parser needs to scan through the content only once. Handling nested shortcodes of the same type would require multiple passes through the content, which would slow the algorithm down. The solution to this is to either 1) avoid nesting the same shortcode within itself, 2) use differently named shortcodes that link to the same callback function, or 3) write a custom regex parser for your shortcode and parse the shortcodes out yourself.

You can also use the do_shortcode() function to apply shortcodes to custom fields, content pulled from custom tables, or other content not already being run through the the_content filter. In most cases outside of shortcode callback functions themselves, it will be more appropriate to use apply_filters( "the_content", $content ), which will apply all filters on the the_content hook including the shortcode filter:

<?php
global $post;
$sidebar_content = $post->sidebar_content;
?>
<div class="post">
  <?php the_content(); ?>
</div>
<div class="sidebar">
  <?php
    //echo do_shortcode($sidebar_content);
    echo apply_filters('the_content', $sidebar_content);
  ?>
</div>

Removing Shortcodes

As with actions and filters, you can remove registered shortcodes to keep them from being applied to a certain post or on content you are passing directly to do_shortcode() or through the the_content filter. The remove_shortcode() function takes the shortcode name as its only parameter and will unregister the specified shortcode. remove_all_shortcodes() will unregister all shortcodes.

Note

When calling remove_shortcode(), make sure that the call comes late enough in the execution of WordPress for the shortcode you want removed to have already been added. For example, if a plugin adds the shortcode during the init action on priority 10, you will want to put your call to remove_shortcode() during the init action on priority 11 or higher or through another hook that fires after init.

The array of registered shortcodes is stored in a global variable $shortcode_tags. It can be useful to make copies of this variable or edit it directly. For example, if you want to exclude certain shortcodes from a specific piece of content, you can make a backup copy of all shortcodes, remove the offending shortcodes, apply shortcodes, and then restore the original list of shortcodes:

//make a copy of the original shortcodes
global $shortcode_tags;
$original_shortcode_tags = $shortcode_tags;

//remove the [msg] shortcode
unset($shortcode_tags['msg']);

//do shortcodes and echo
$content = do_shortcode($content);
echo $content;

//restore the original shortcodes
$shortcode_tags = $original_shortcode_tags;

The following functions are useful when working with shortcodes:

shortcode_exists( $tag ): Checks whether the shortcode $tag has been registered.
has_shortcode( $content, $tag ): Checks whether the shortcode $tag appears within the $content variable.
shortcode_parse_atts( $text ): Pulls attributes out of a shortcode. This is done for you when parsing a shortcode, but can be called directly if you want to pull attributes out of other text like HTML tags or other templates.
strip_shortcodes( $text ): Strips all shortcodes out of the $text variable and replaces them with empty text instead of calling the callback function.

More details about the Shortcode API can be found in the WordPress Codex.

Widgets API

Widgets allow you to place contained pieces of code and content in various widget areas throughout your WordPress site. The most typical use cases are to add widgets to a sidebar or footer area. You could always hardcode these sections on a website, but using widgets allows your nondevelopers to drag and drop widgets from one area to another or to tweak their settings through the Widgets page in the admin dashboard. WordPress comes with many built-in widgets, including the basic text widget shown in Figure 7-1.

Plenty of plugins also include widgets for showing various content. We don’t get into the use and styling of widgets here, since this is covered well in the WordPress Codex page on widgets, but we will explore how to add widgets and widget areas to your plugins and themes.

Note

The UI of the Widgets page in the admin dashboard is going through an overhaul for WordPress version 3.8; however, the functions and API calls to add new widgets through code should not be affected much, if at all.

Before you go about developing a new widget, it’s worth spending some time to see whether an existing widget will work for you. If you get creative, you can sometimes avoid building a new widget.

Search the repository for plugins that may already have the widget you need. If so, double-check the code there and see whether it will work.

Text widgets can be used to add arbitrary text into a widget space. You can also embed JavaScript code this way or add a shortcode to the text area and use a shortcode to output the functionality you want (you may have created the shortcode already for other use) instead of creating a new widget.

If your widget is displaying a list of links, it might make sense to build a menu of those links and use the Custom Menu widget that is built in to WordPress. Other widgets that display recent posts from a category often will work with CPTs and custom taxonomies either out of the box or with a little bit of effort.

If you do need to add a brand-new widget, the following section covers the steps required.

Adding Widgets

To add a new widget to WordPress, you must create a new PHP class for the widget that extends the WP_Widget class of WordPress. The WP_Widget class, found in wp-includes/widgets.php, is a good read. The comments in the code explain how the class works and which methods you must override to build your own widget class. There are four main methods that you must override, shown clearly in the following code by the sample widget class from the WordPress Codex page for the Widgets API:

/*
  Taken from the Widgets API Codex Page at:
  http://codex.wordpress.org/Widgets_API
*/
class My_Widget extends WP_Widget {

	public function __construct() {
		// widget actual processes
	}

	public function widget( $args, $instance ) {
		// outputs the content of the widget
	}

 	public function form( $instance ) {
		// outputs the options form on admin
	}

	public function update( $new_instance, $old_instance ) {
		// processes widget options to be saved
	}
}
add_action( 'widgets_init', function(){
     register_widget( 'My_Widget' );
});

The add_action() call passes an anonymous function as the second parameter, which is supported only in PHP versions 5.3 and higher. Technically, WordPress requires only PHP version 5.2.4 and higher. The alternative is to use the create_function() function of PHP, which is slower and potentially less secure than using an anonymous function. However, if you plan to release your code to a wide audience, you might want to use the alternative method shown in the following code:

/*
  Taken from the Widgets API Codex Page at:
  http://codex.wordpress.org/Widgets_API
*/
add_action('widgets_init',
     create_function('', 'return register_widget("My_Widget");')
);

Pulling this all together, Example 7-1 presents a new widget for the SchoolPress site. This widget will show either a globally defined note set in the widget settings or a note specific to the current BuddyPress group set by the group administrators.

Example 7-1. SchoolPress note widget

<?php
/*
  Widget to show the current class note.
  Teachers (Group Admins) can change note for each group.
  Shows the global note set in the widget settings if non-empty.
*/
class SchoolPress_Note_Widget extends WP_Widget
{
  public function __construct() {
    parent::__construct(
    'schoolpress_note',
	'SchoolPress Note',
	array( 'description' => 'Note to Show on Group Pages' );
  }

  public function widget( $args, $instance ) {
	global $current_user;

	//saving a note edit?
	if ( !empty( $_POST['schoolpress_note_text'] )
		&& !empty( $_POST['class_id'] ) ) {
	  //make sure this is an admin
	  if(groups_is_user_admin($current_user->ID,intval($_POST['class_id']))){
		//should escape the text and possibly use a nonce
		update_option(
			'schoolpress_note_' . intval( $_POST['class_id'] ),
			$_POST['schoolpress_note_text']
		);
	  }
	}

	//look for a global note
	$note = $instance['note'];

	//get class id for this group
	$class_id = bp_get_current_group_id();

	//look for a class note
	if ( empty( $note ) && !empty( $class_id ) ) {
		$note = get_option( "schoolpress_note_" . $class_id );
	}

	//display note
	if ( !empty( $note ) ) {
		?>
		<div id="schoolpress_note">
			<?php echo wpautop( $note );?>
		</div>
		<?php

		//show edit for group admins
		if ( groups_is_user_admin( $current_user->ID, $class_id ) ) {
		?>
		<a id="schoolpress_note_edit_trigger">Edit</a>
		<div id="schoolpress_note_edit" style="display: none;">
		<form action="" method="post">
		<input type="hidden"
			name="class_id"
			value="<?php echo intval($class_id);?>" />
		<textarea name="schoolpress_note_text" cols="30" rows="5">
		<?php echo esc_textarea(get_option('schoolpress_note_'.$class_id))
		;?>
		</textarea>
		<input type="submit" value="Save" />
		<a id="schoolpress_note_edit_cancel" href="javascript:void(0);">
			Cancel
		</a>
		</form>
		</div>
		<script>
		jQuery(document).ready(function() {
			jQuery('#schoolpress_note_edit_trigger').click(function(){
				jQuery('#schoolpress_note').hide();
				jQuery('#schoolpress_note_edit').show();
			});
			jQuery('#schoolpress_note_edit_cancel').click(function(){
				jQuery('#schoolpress_note').show();
				jQuery('#schoolpress_note_edit').hide();
			});
		});
		</script>
		<?php
		}
	}
  }

  public function form( $instance ) {
	if ( isset( $instance['note'] ) )
		$note = $instance['note'];
	else
		$note = "";
	?>
	<p>
		<label for="<?php echo $this->get_field_id( 'note' ); ?>">
			<?php _e( 'Note:' ); ?>
		</label>
		<textarea id="<?php echo $this->get_field_id( 'note' ); ?>"
			name="<?php echo $this->get_field_name( 'note' ); ?>">
			<?php echo esc_textarea( $note );?>
		</textarea>
	</p>
	<?php
  }

  public function update( $new_instance, $old_instance ) {
	$instance = array();
	$instance['note'] = $new_instance['note'];

	return $instance;
  }
}
add_action( 'widgets_init', function() {
		register_widget( 'SchoolPress_Note_Widget' );
	} );
?>

To add widget areas or sidebars to your theme, you need to do two things. First, register the widget area with WordPress. Then, add code to your theme at the point where you want your widget area to appear.

Registering a widget area is fairly straightforward using the register_sidebar() function, which takes an array of arguments as its only parameter. The available arguments are as follows, taken from the WordPress Codex page on the register_sidebar() function:

name: Sidebar name (defaults to Sidebar#, where # is the ID of the sidebar)
id: Sidebar ID—must be all in lowercase, with no spaces (default is a numeric auto-incremented ID)
description: Text description of what/where the sidebar is; shown on widget management screen since 2.9 (default: empty)
class: CSS class name to assign to the widget HTML (default: empty)
before_widget: HTML to place before every widget (default: <li id="%1$s" class="widget %2$s">); uses sprintf for variable substitution
after_widget: HTML to place after every widget (default: </li>\n)
before_title: HTML to place before every title (default: <h2 class="widgettitle">)
after_title: HTML to place after every title (default: </h2>\n)

To register a bare-bones sidebar for the assignment pages of our SchoolPress theme, we would add the following to our theme’s functions.php or includes/sidebars.php file:

register_sidebar(array(
  'name' => 'Assignment Pages Sidebar',
  'id' => 'schoolpress_assignment_pages',
  'description' => 'Sidebar used on assignment pages.',
  'before_widget' => '',
  'after_widget' => '',
  'before_title' => '',
  'after_title' => ''
));

The values for before/after_widget and before/after_title would be set based on how our theme styles widgets and titles. Some expect <li> elements; others use <div> elements. But if all of the styling is handled by our widget’s code, we can just set everything to empty strings. Next, we need to actually embed the widget area into our theme. We do this using the dynamic_sidebar() function, which takes the ID of a registered sidebar as its only parameter:

if(!dynamic_sidebar('schoolpress_student_status'))
{
  //fallback code in case my_widget_area sidebar was not found
}

The code will load the schoolpress_student_status sidebar if found. If it is not found, dynamic_sidebar() will return false and the code inside the curly braces there will be executed instead. This can be used to show default content in a sidebar area if the sidebar area doesn’t have any widgets within it or doesn’t exist at all.

Historically, WordPress themes were developed with a sidebar area, and themes would hardcode certain features into them. Widgets were first introduced primarily to replace these static sidebars with dynamic sidebars that could be controlled through the Widgets page of the dashboard. This is why the term sidebar is used to define widget areas, even though widgets are used in places other than just sidebars.

If you need to know whether a sidebar is registered and in use (has widgets) without actually embedding the widgets, you can use the is_active_sidebar() function. Just pass in the ID of the sidebar, and the function will return true if the sidebar is registered or false if it is not. The Twenty Thirteen theme uses this function to check that a sidebar has widgets before rendering the wrapping HTML for the sidebar:

<?php
//from twenty-thirteen/sidebar.php
if ( is_active_sidebar( 'sidebar-2' ) ) : ?>
	<div id="tertiary" class="sidebar-container" role="complementary">
		<div class="sidebar-inner">
			<div class="widget-area">
				<?php dynamic_sidebar( 'sidebar-2' ); ?>
			</div><!-- .widget-area -->
		</div><!-- .sidebar-inner -->
	</div><!-- #tertiary -->
<?php endif; ?>

The normal process to add widgets to your pages is described in the previous section, where you define a dynamic sidebar and then add your widget to the sidebar through the Widgets page in the admin dashboard.

Alternatively, if you know exactly which widget you want to include somewhere and don’t want the placement of the widget left up to the administrators controlling the Widgets settings in the dashboard, you can embed a widget using the the_widget( $widget, $instance, $args ) function:

$widget: The PHP class name for your widget
$instance: An array containing the settings for your widget
$args: An array containing the arguments normally passed to register_sidebar()

Besides hardcoding the placement of the widget, using the the_widget() function also allows you to set the settings of the widget programmatically. In the following code, we embed the StudentPress Note widget directly into a theme page. We set the instance array to include an empty string for the $note value, ensuring that the group note is shown if available:

//show note widget, overriding global note
the_widget('SchoolPress_Note_Widget',  //classname
		  array('note'=>''), 	        //instance vars
		  array(		        //widget vars
		  	'before_widget' => '',
			'after_widget' => '',
			'before_title' => '',
			'after_title' => ''
		  )
);

Dashboard Widgets API

Dashboard widgets are the boxes that appear on the home page of your WordPress admin dashboard (see Figure 7-2).

By default, WordPress includes a few different dashboard widgets. By adding and removing widgets from the dashboard using the Dashboard Widgets API, you can make your WordPress app more useful by placing the information and tools most required by your app directly on the dashboard home page. It’s a nice touch that should be done for all WordPress apps with users who will be accessing the WordPress administrator.

Removing Dashboard Widgets

The dashboard widgets are really just meta boxes assigned to the dashboard page of the administrator. The WordPress Codex Dashboard Widgets API page lists the default widgets shown on the WordPress dashboard:

// From the Dashboard Widgets API Codex Page
// Main column:
$wp_meta_boxes['dashboard']['normal']['high']['dashboard_browser_nag']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_right_now']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_recent_comments']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_incoming_links']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_plugins']

// Side Column:
$wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_recent_drafts']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_primary']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_secondary']

To remove widgets from the dashboard, you can use the remove_meta_box( $id, $page, $context ) function:

$id: The ID defined when the meta box was added. This is set as the id attribute of the <div> element created for the meta box.
$page: The name of the administrator page the meta box was added to. Use dashboard to remove dashboard meta boxes.
$context: Either normal, advanced, or side, depending on where the meta box was added.

To remove all of the default widgets, you can hook into wp_dashboard_setup and make a call to remove_meta_box() for each widget you’d like to remove:

// Remove all default WordPress dashboard widgets
function sp_remove_dashboard_widgets()
{
 	remove_meta_box('dashboard_browser_nag', 'dashboard', 'normal');
	remove_meta_box('dashboard_right_now', 'dashboard', 'normal');
	remove_meta_box('dashboard_recent_comments', 'dashboard', 'normal');
	remove_meta_box('dashboard_incoming_links', 'dashboard', 'normal');
	remove_meta_box('dashboard_plugins', 'dashboard', 'normal');

	remove_meta_box('dashboard_quick_press', 'dashboard', 'side');
	remove_meta_box('dashboard_recent_drafts', 'dashboard', 'side');
	remove_meta_box('dashboard_primary', 'dashboard', 'side');
	remove_meta_box('dashboard_secondary', 'dashboard', 'side');
}
add_action('wp_dashboard_setup', 'sp_remove_dashboard_widgets');

A different set of widgets is added to the multisite network dashboard, and you must use a different hook to remove the network dashboard widgets. The following code hooks on wp_network_dashboard_setup and removes the meta boxes added to the dashboard-network $page:

//Remove network dashboard widgets
function sp_remove_network_dashboard_widgets()
{
  remove_meta_box('network_dashboard_right_now', 'dashboard-network', 'normal');
  remove_meta_box('dashboard_plugins', 'dashboard-network', 'normal');
  remove_meta_box('dashboard_primary', 'dashboard-network', 'side');
  remove_meta_box('dashboard_secondary', 'dashboard-network', 'side');
}
add_action('wp_network_dashboard_setup', 'sp_remove_network_dashboard_widgets');

You could use similar code to remove default meta boxes from other dashboard pages, like the edit page and edit post pages. The $page value to use when removing meta boxes there are page and post, respectively.

The wp_add_dashboard_widget() function is a wrapper to add_meta_box() that adds a widget to your admin dashboard page. The wp_add_dashboard_widget() function takes four parameters:

$widget_id: An ID for your widgets that is added as a CSS class name to the wrapper for the widget and also used as the array key for the dashboard widgets array.
$widget_name: Name of the widget displayed in the widget heading.
$callback: Callback function that renders the widget.
$control_callback: Optional. Defaults to null. Callback function to handle the display and processing of a configuration page for the widget.

Example 7-2 adds a dashboard widget to show the status of current assignments (Figure 7-3). The code includes the call to wp_add_dashboard_widget() to register the dashboard widget, as well as the callback function to display that actual widget and another callback function to handle the widget’s configuration view (Figure 7-4).

Example 7-2. Assignments dashboard widget

<?php
/*
    Add dashboard widgets
*/
function sp_add_dashboard_widgets() {
	wp_add_dashboard_widget(
		'schoolpress_assignments',
		'Assignments',
		'sp_assignments_dashboard_widget',
		'sp_assignments_dashboard_widget_configuration'
	);
}
add_action( 'wp_dashboard_setup', 'sp_add_dashboard_widgets' );

/*
	Assignments dashboard widget
*/
//widget
function sp_assignments_dashboard_widget() {
	$options = get_option( "assignments_dashboard_widget_options", array() );

	if ( !empty( $options['course_id'] ) ) {
		$group = groups_get_group( array(
			'group_id'=>$options['course_id']
			) );
	}

	if ( !empty( $group ) ) {
		echo "Showing assignments for class " .
			$group->name . ".<br />...";
		/*
			get assignments for this group and list their status
		*/
	}
	else {
		echo "Showing all assignments.<br />...";
		/*
			get all assignments and list their status
		*/
	}
}
//configuration
function sp_assignments_dashboard_widget_configuration() {
	//get old settings or default to empty array
	$options = get_option( "assignments_dashboard_widget_options", array() );

	//saving options?
	if ( isset( $_POST['assignments_dashboard_options_save'] ) ) {
		//get course_id
		$options['course_id'] = intval(
			$_POST['assignments_dashboard_course_id']
			);

		//save it
		update_option( "assignments_dashboard_widget_options", $options );
	}

	//show options form
	$groups = groups_get_groups( array( 'orderby'=>'name', 'order'=>'ASC' ) );
	?>
	<p>Choose a class/group to show assignments from.</p>
	<div class="feature_post_class_wrap">
		<label>Class</label>
		<select name="assignments_dashboard_course_id">
		<option value="" <?php selected( $options['course_id'], "" );?>>
			All Classes
		</option>
		<?php
		$groups = groups_get_groups( array( 'orderby'=>'name',
						'order'=>'ASC' ) );

		if ( !empty( $groups ) && !empty( $groups['groups'] ) ) {
			foreach ( $groups['groups'] as $group ) {
			?>
			<option value="<?php echo intval( $group->id );?>"
			<?php selected( $options['course_id'], $group->id );?>>
			<?php echo $group->name;?>
			</option>
			<?php
			}
		}
		?>
		</select>
	</div>
	<input type="hidden" name="assignments_dashboard_options_save" value="1" />
	<?php
}
?>

The configuration view of our assignments widget

Note that we hook into wp_dashboard_setup for the function that adds our widget. If we wanted our widget to show up on the network dashboard, we would need to use the wp_network_dashboard_setup hook.

The sp_assignments_dashboard_widget() function draws the actual widget shown on the dashboard page. This is where we would add our code to loop through assignments and show stats on what percentage of assignments have been turned in.

The sp_assignments_dashboard_widget_configuration() function draws the configuration form and also includes code to process the form submission and update the option we use to store the configuration.

Settings API

WordPress offers an API you can use to generate options and settings forms for your plugins in the administrator dashboard. This Settings API is very thoroughly documented in the WordPress Codex. Tom McFarlin also has a great WordPress Settings API tutorial at Envato Tutsplus. These resources cover the details of adding menu pages and settings within them for use in your plugins and themes. Following are some tips specific to app developers.

Do You Really Need a Settings Page?

Before spending the time to create a settings page and adding to the technical debt of your app, consider using a global variable to store an array of the options used by your plugin or app:

global $schoolpress_settings;
$schoolpress_settings = array(
  'info_email' => This email address is being protected from spambots. You need JavaScript enabled to view it.',
  'info_email_name' => 'SchoolPress'
);

For apps that won’t be managed by nondevelopers and/or won’t be distributed, using a global variable to store your settings might be enough. Just store a global variable like the one in the preceding code at the top of your plugin file or within a includes/settings.php file. Why build the UI if you aren’t going to use it?

Even if your plugin or theme will eventually be distributed, we like to start with a global variable like this anyway. The settings that you think you need in the beginning may not be the ones you need at the end of your project. Settings may be added or removed throughout development. Settings you think need a drop-down list may need a free text field instead. The Settings API makes it easy to add settings and update them later, but it is still much easier to change one element in a global array than it is to add or modify a handful of function calls and definitions.

If most of the following statements apply to you, consider using a global variable for your settings instead of building a settings UI:

This plugin will not be distributed outside my team.
The only people changing these settings are developers.
These settings will not need to be different across our different environments.
These settings are likely to change before release.

Could You Use a Hook or Filter Instead?

Another alternative to adding a setting to your plugin through the Settings API is to use a hook or filter instead. If a setting you are imagining would be used only by a minority of your users, consider adding a hook or filter to facilitate it.

For example, someone using our WP-Doc plugin may request the ability to restrict .doc generation to administrators only or a specific subset of WordPress roles. We could add a settings page with a list of roles with checkboxes to enable or disable .doc downloads for that role. Maybe it should just be one checkbox to enable downloads for all roles or just administrators. Maybe it should be a free text field to enter a capability name to check for before allowing the download.

A filter might be a better way to do this. We can add a capability check before the .doc is served and use a filter to let developers override the default array of capabilities checked. This code should be added to the wpdoc_template_redirect() function of the WP-Doc plugin, before the .doc page is rendered:

//don't require any caps by default, but allow developers to add checks
$caps = apply_filters('wpdoc_caps', array());

if(!empty($caps))
{
  //guilty until proven innocent
  $hascap = false;

  //must be logged in to have any caps at all
  if(is_user_logged_in())
  {
    //make sure the current user has one of the caps
    foreach($caps as $cap)
    {
      if(current_user_can($cap))
      {
        $hascap = true;
        break;  //stop checking
      }
    }
  }

  if(!$hascap)
  {
    //don't show them the file
    header('HTTP/1.1 503 Service Unavailable', true, 503);
    echo "HTTP/1.1 503 Service Unavailable";
    exit;
  }
}

You could then override the wpdoc_caps array by adding actions like these:

//require any user account
add_filter('wpdoc_caps', function($caps) { return array('read'); });

//require admin account
add_filter('wpdoc_caps', function($caps) { return array('manage_options'); });

//authors only or users with a custom capability (doc)
add_filter('wpdoc_caps', function($caps) { return array('edit_post', 'doc'); });

Note

The preceding example uses anonymous functions, also known as closures, so the add_filter() call can be written on one line without using a separate callback function. This syntax requires PHP version 5.3 or higher.

To recap, the greater the number of the following statements that are true, the more it makes sense to use a hook or filter instead of a settings UI:

Only a small number of people will want to change this setting.
The people changing this setting are likely to be developers.
The people changing this setting are likely to have custom needs.
This setting would require a large number of individual settings or more complicated UI.

Use Standards When Adding Settings

If and when you do need to add settings to your plugin or theme, refer to the tutorials listed earlier in this blog to make sure you are using the Settings API correctly to add your settings.

Using the Settings API takes a bit of upfront work, but does let you add and edit settings more easily later on. And as you’re doing things the WordPress way, other developers will understand how your code works and will be able to hook into it. If a developer wants to make an add-on for your plugin, they will be able to hook into your existing menus and settings sections to add new settings for their plugins.

Using the Settings API will also ensure that your settings look similar to the other settings through a user’s WordPress dashboard. You don’t want developers to have to learn a new UI just to use your plugin.

Ignore Standards When Adding Settings

Though you typically want to use the Settings API and the WordPress standards when adding settings for your plugin, sometimes it make sense to ignore those standards.

The main case here is whether you have a large number of settings that deserve a very custom UI. If you have only one or two settings, users won’t be spending a lot of time inside the settings screens. They will just want to change those two settings as fast as possible.

However, if your plugin requires dozens of settings, possibly across multiple tabs or screens, possibly related to one another, it makes sense to treat the settings for your app as an app itself. You should devote some attention to make sure that the UI and UX for your settings screen is as optimized as possible.

The WordPress Settings API is pretty flexible in terms of how things are displayed. You can control how each section is rendered and how each individual setting field is rendered. But in the end, it really is focused on one or more tabs with sections with fields on them. For applications with a large number of settings that interact with one another, you might want to use a different organization for your settings.

Don’t be scared to ignore the standards here. Add a menu to the dashboard, have the callback function for it include a set of organized .php files to generate the settings form and process it, and follow these tips if possible:

Add your menu sections and items per the standards, even if your settings pages themselves use a custom layout.
Remember to sanitize your inputs and use nonces when appropriate.
Use hooks and filters to whenever possible, if you’d like to allow others to extend your settings.
Use the same HTML elements and CSS classes whenever possible so the general style remains consistent with the rest of WordPress now and through future updates.

Due to the complexity of ecommerce software, it makes sense that ecommerce plugins often have complicated settings screens. Here are two examples of plugins that do custom settings pages well:

Paid Memberships Pro (whose code is posted on GitHub)
WooCommerce (whose code is posted on GitHub)

Rewrite API

Apache comes with a handy module called mod_rewrite that allows you to route incoming URLs to different URLs or file locations using rules that are typically added to an .htaccess file in your site root folder. Other web servers have similar URL rewriting systems; here are the standard rules for WordPress:

# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress

If you’d like to understand more about Apache’s mod_rewrite module and how the WordPress rules work, David Walsh does an excellent line-by-line explanation of the WordPress .htaccess file on his blog. Generally, these rules reroute all incoming traffic to any nondirectory or nonfile URL to the index.php file of your WordPress installation.

WordPress then parses the actual URL to determine which post, page, or other content to show. For example, under most permalink settings, the URL /about/ will route to the page or post with the slug “about.”

For the most part, you can let WordPress do its thing and handle permalink redirects on its own. However, if you need to add your own rules to handle certain URLs in particular ways, you can do this through the Rewrite API.

Adding Rewrite Rules

The basic function to add a rewrite rule is add_rewrite_rule( $rule, $rewrite, $position ):

$rule: A regular expression to match against the URL, just like you would use in an Apache rewrite rule.
$rewrite: The URL to rewrite to if the rule is matched. Matched groups from the rule regular expressions are contained in an array called $matches.
$position: Specifies whether to place the rules above the default WordPress rules (top) or below them (bottom).

If you want to pass a subject line to your contact form through the URL, you could use a URL like /contact/special-offer/, which would load the contact page and prepopulate the subject to special-offer. You could add a rewrite rule like this:

add_rewrite_rule(
	  '/contact/([^/]+)/?',
	  'index.php?name=contact&subject=' . $matches[1],
	  'top'
	);
add_rewrite_rule(
flush_rewrite_rules();

With this added to the rewrite rules, a visit to /contact/special-offer/ would redirect to the /contact/ page and populate the global $wp_query->query_vars['subject'] with the value special-offer, or whatever text was added after /contact/. Your contact form could use this value to prepopulate the subject value of the email sent.

Flushing Rewrite Rules

WordPress caches the rewrite rules. So when you add a rule like this, you need to flush the rewrite rules so they take effect. Flushing the rewrite rules can take some time, so it’s important that you don’t do it on every page load. To keep the rewrite rules in order, every plugin that affects them should do these three things:

Add the rule during plugin activation and immediately flush the rewrite rules using the flush_rewrite_rules() function.
Add the rule during the init hook in case the rules are flushed manually through the Permalinks Settings page of the dashboard or by another plugin.
Add a call to flush_rewrite_rules() during deactivation so the rule is removed on deactivation.

The following code shows how our contact subject rule should be added according to the three previous steps:

//Add rule and flush on activation.
function sp_activation()
{
	add_rewrite_rule(
	  '/contact/([^/]+)/?',
	  'index.php?name=contact&subject=' . $matches[1],
	  'top'
	);
	flush_rewrite_rules();
}
register_activation_hook(__FILE__, 'sp_activation');

/*
  Add rule on init in case another plugin flushes,
  but don't flush cause it's expensive
*/
function sp_init()
{
	add_rewrite_rule(
	  '/contact/([^/]+)/?',
	  'index.php?name=contact&subject=' . $matches[1],
	  'top'
	);
}
add_action('init', 'sp_init');

//Flush rewrite rules on deactivation to remove our rule.
function sp_deactivation()
{
	flush_rewrite_rules();
}
register_deactivation_hook(__FILE__, 'sp_deactivation');

Other Rewrite Functions

WordPress offers some other functions to insert special kinds of rewrite rules:

add_rewrite_tag(): Another way to add custom querystring variables.
add_feed(): Add a new kind of feed to function like the RSS and ATOM feeds.
add_rewrite_endpoint: Add querystring variables to the end of a URL.

The Codex pages for each function explains things well. Some functions will make more sense for certain uses versus others. Example 7-3 shows how to use the add_rewrite_endpoint() function to detect when /doc/ is added to the end of a URL and to force the download of a .doc file. This code makes use of the fact that any HTML document with a .doc extension will be read by Microsoft Word as a .doc file.

The add_rewrite_endpoint() function takes two parameters:

$name*: Name of the endpoint—for example, 'doc'.
$places*: Specifies which pages to add the endpoint rule to. Uses the EP_* constants defined in wp-includes/rewrite.php.

Example 7-3. The WP DOC plugin

<?php
/*
Plugin Name: WP DOC
Plugin URI: http://bwawwp.com/wp-docx/
Description: Add /doc/ to the end of a page or post to download a .docx version.
Version: .1
Author: Stranger Studios
*/

/*
	Register Rewrite Endpoint
*/
//Add /doc/ endpoint on activation.
function wpdoc_activation()
{
	add_rewrite_endpoint('doc', EP_PERMALINK | EP_PAGES);
	flush_rewrite_rules();
}
register_activation_hook(__FILE__, 'wpdoc_activation');

//and init in case another plugin flushes, but don't flush cause it's expensive
function wpdoc_init()
{
	add_rewrite_endpoint('doc', EP_PERMALINK | EP_PAGES);
}
add_action('init', 'wpdoc_init');

//flush rewrite rules on deactivation to remove our endpoint
function wpdoc_deactivation()
{
	flush_rewrite_rules();
}
register_deactivation_hook(__FILE__, 'wpdoc_deactivation');

/*
	Detect /doc/ use and return a .doc file.
*/
function wpdoc_template_redirect()
{
	global $wp_query;
	if(isset($wp_query->query_vars['doc']))
	{
		global $post;

		//double check this is a post
		if(empty($post->ID))
			return;

		//headers for MS Word
		header("Content-type: application/vnd.ms-word");
		header('Content-Disposition: attachment;Filename='.
            $post->post_name.'.doc');

		//html
		?>
		<html>
		<body>
		<h1><?php echo $post->post_title; ?></h1>
		<?php
			echo apply_filters('the_content', $post->post_content);
		?>
		</body>
		</html>
		<?php

		exit;
	}
}
add_action('template_redirect', 'wpdoc_template_redirect');
?>

Note in the preceding example that we follow the three steps we used in the add_rewrite_rule() example to define our rule on activation and initialization and flush all rules on activation and deactivation.

We used EP_PERMALINK | EP_PAGES when defining our endpoint, which will add the endpoint to single post pages and page pages.¹ The full list of endpoint mask constants is as follows:

EP_NONE
EP_PERMALINK
EP_ATTACHMENT
EP_DATE
EP_YEAR
EP_MONTH
EP_DAY
EP_ROOT
EP_COMMENTS
EP_SEARCH
EP_CATEGORIES
EP_TAGS
EP_AUTHORS
EP_PAGES
EP_ALL

For more information on the Rewrite API, both the Rewrite API Codex page and the WP_Rewrite class Codex page are good sources of information. There is much more that can be done with the WP_Rewrite class that we didn’t get into here.

WP-Cron

A cron job is a script that is run on a server at set intervals. The WP-Cron functions in WordPress extend that functionality to your WordPress site. Cron jobs, sometimes called events, can be set up to run every few minutes, every few hours, every day, or on specific days of the week or month. Some typical uses of cron jobs include queueing up digest emails, synching data with third-party APIs, and preprocessing CPU-intensive computations used in reports and comparative analysis.

There are three basic parts to adding a cron job to your app:

Schedule the cron event. This will fire a specific hook/action at the defined interval.
Hook a function to that action.
Place the code you actually want to run within the callback function.

This code can be added to a custom plugin file to schedule some cron jobs:²

//schedule crons on plugin activation
function sp_activation()
{
	//do_action('sp_daily_cron'); will fire daily
	wp_schedule_event(time(), 'daily', 'sp_daily_cron');
}
register_activation_hook(__FILE__, 'sp_activation');

//clear our crons on plugin deactivation
function sp_deactivation()
{
	wp_clear_scheduled_hook('sp_daily_cron');
}
register_deactivation_hook(__FILE__, 'sp_deactivation');

//function to run daily
function sp_daily_cron()
{
	//do this daily
}
add_action("sp_daily_cron", "sp_daily_cron");

The function wp_schedule_event( $timestamp, $recurrence, $hook, $args ) has the following attributes:

$timestamp: Timestamp for first time to run the hook. You can typically set it to time().
$recurrence: How often the event should run. You can pass hourly, daily, or twicedaily, or use the cron_schedules hook to add other intervals.
$hook: The name of the action to fire on each recurrence.
$args: Any arguments you’d like to pass along to the hook fired can be added to the end of the wp_schedule_event() call.

We like to give our cron events generic names based on the interval. By doing it this way, if we wanted to run another function daily, we could then just add add_action('sp_daily_cron', 'new_function_name'); to our codebase.

Adding Custom Intervals

By default, the wp_schedule_event() function accepts only intervals of hourly, daily, or twicedaily. To add other intervals, you need to use the cron_schedules hook:

//add a monthly interval to use in cron jobs
function sp_cron_schedules($schedules)
{
	$schedules['monthly'] = array(
		'interval' => 60*60*24*30, //really 30 days
		'display' => 'Once a Month'
	);
}
add_filter( 'cron_schedules', 'sp_cron_schedules' );

Unlike Unix-based cron jobs, WP-Cron doesn’t support intervals based on day of the week. To do this, you can use a daily cron job and have the function called check the day of the week:

//run on Mondays
function sp_monday_cron()
{
	//get day of the week, 0-6, starting with Sunday
	$weekday = date("w");

	//is it Monday?
	if($weekday == "1")
	{
		//execute this code on Mondays
	}
}
add_action("sp_daily_cron", "sp_monday_cron");

You could write similar code to check for a specific day of the month (date("j")) or even specific months (date("m")).

Scheduling Single Events

The preceding examples show how to execute code at some interval. You may also have times when you want to fire an event once at some point in the future. For example, you may want to schedule email delivery of new blog posts one hour after they are posted. This will give authors an hour to fix any issues with a blog post before it gets pushed around the world. The wp_schedule_single_event() function can be used in these cases in which we want to schedule an event to fire just once.

Kicking Off Cron Jobs from the Server

In all of the previous examples, we assumed that events scheduled with wp_schedule_event() would actually run when they are scheduled. That’s almost true.

On Unix systems, the cron service runs every minute (generally) to check whether there is a script to run. In WordPress, that check is done on every page load. So if no one loads your website in a given day, or only pages from a static cache are loaded, your cron jobs may not fire that day. They will fire at the next page load.

This setup is fine for casual WordPress sites, but our apps need reliability. Luckily, it is easy to disable the internal cron timer and set one up on your web server to fire when you need it to.

To disable the WordPress cron timer, simply add the following to your wp-config.php file:

define('DISABLE_WP_CRON', true);

You still add and manage events as we did earlier; this constant enables or disables the check for events that are ready to fire. We just need to manually hit the wp-cron.php file in our WordPress installation often enough to fire our scripts when needed.

If you have only daily scripts, you can add a cron job like this via the crontab -e command:

0 0 * * * wget -O - -q -t 1 http://yoursite.com/wp-cron.php?doing_wp_cron=1

Tip

Information on how to use cron can be found at its Wikipedia entry. Consult the wget manual on how to use wget.

The 0 0 * * * part of the preceding entry tells cron to execute this script at 0 minutes on the 0th hour (midnight) every day of the week.

The wget -O - -q -t 1 http://yoursite.com/wp-cron.php?doing_wp_cron=1 part uses the wget command to load up the wp-cron.php page in your WordPress install. The -O - tells wget to send output to devnull, and the -q enables quiet mode. This will keep cron from adding files to your server or emailing you the outputs of each cron run. The -t 1 tells cron to try once. This will keep wget from hitting your server multiple times if the first try fails. If the call to wp-cron.php is failing, the rest of your website is probably failing too; hopefully you’ve already been notified.

Be sure to change yoursite.com to your actual site URL. And finally, the ?doing_wp_cron=1 on the end of the URL is needed since wp-cron.php will check for that $_GET parameter before running.

Caution

Double-check that the URL to wp-cron.php is excluded from any caching mechanisms you may have installed on your site.

This one cron job will fire every day, and any daily cron jobs you scheduled inside WordPress will fire daily. If you need your crons to run more often, you can change the cron entry to run every hour or every few minutes. Note that a call to wp-cron.php is basically a hit to your website. A check every minute is effectively the same as an additional 1,440 users hitting your site. So schedule your cron jobs conservatively.

Using Server Crons Only

If you aren’t distributing your code or don’t mind telling your users that they must set up server-side cron jobs, you don’t need to schedule your cron events in WordPress at all. Just schedule a server-side cron job that calls a special URL to kick off your callback function. This is especially useful if you need to have more control over what times of day your crons run or otherwise just feel more comfortable managing your cron jobs in Unix instead of WordPress.

Note

The information on scheduling server-side cron jobs in this section can be used to replace WP-Cron for recurring events. Single events set using wp_schedule_single_event() will still need to be handled using WP-Cron or some other mechanism.

If we were running our Monday cron job from earlier, we would update the code in WordPress:

//run on Mondays
function sp_monday_cron()
{
	//check that cron param was passed in
	if(empty($_REQUEST['sp_cron_monday']))
		return false;

	//execute this code on Mondays
}
add_action("init", "sp_monday_cron");

And your cron job entry would look like this:

0 0 * * 1 wget -O - -q -t 1 http://yoursite.com/?sp_cron_monday=1

Note

Again, make sure that the URL to ?sp_cron_monday=1 is excluded from any caching mechanisms you may have installed on your site.

WP Mail

The wp_mail() function is a replacement for PHP’s built-in mail() function. It looks like this:

wp_mail( $to, $subject, $message, $headers, $attachments )

Its attributes are as follows:

$to: A single email address, comma-separated list of email addresses, or array of email addresses the email will be sent to (using the “To:” field).
$subject: The subject of the email.
$message: The body of the email. By default, the email is sent as a plain-text message and should not include HTML. However, if you change the content type (see the following example), you should include HTML in your message.
$headers: Optional array of mail headers to send with the message. This can be used to add CCs, BCCs, and other advanced mail headers.
$attachments: A single filename or array of filenames to be attached to the outgoing email.

There are two major improvements wp_mail() makes over mail():

The wp_mail() function is hookable. The wp_mail filter will pass an array of all of the parameters passed into the wp_mail() function for you to filter. You can also filter the sending address using the wp_mail_from and wp_mail_from_name filters.
The wp_mail() function can be passed a single filename or array of filenames in the $attachments parameters, which will be attached to the outgoing email. Attaching files to emails is very complicated, but wp_mail() makes it easy by wrapping around the PHPMailer class, which itself wraps around the default PHP mail() function.

Sending Nicer Emails with WordPress

By default, emails sent through the wp_mail() function are sent from the administrator email address set on the General Settings page of the administrator dashboard, with “WordPress” used as the name. This is not ideal. You can change these values using the wp_mail_from and wp_mail_from_name filters.

Also by default, emails are sent using plain text. You can use the wp_mail_content_type filter to send your emails using HTML.

Finally, it is nice to add a styled header and footer to all of your outgoing emails. You can do this by filtering the email message using the wp_email filter.

The following code combines these techniques to pretty up the emails being sent by your WordPress app:

//Update from email and name
function sp_wp_mail_from($from_email)
{
  return This email address is being protected from spambots. You need JavaScript enabled to view it.';
}
function sp_wp_mail_from_name($from_name)
{
  return 'SchoolPress';
}
add_filter('wp_mail_from', 'sp_wp_mail_from');
add_filter('wp_mail_from_name', 'sp_wp_mail_from_name');

//send HTML emails instead of plain text
function sp_wp_mail_content_type( $content_type )
{
  if( $content_type == 'text/plain')
  {
    $content_type = 'text/html';
  }
  return $content_type;
}
add_filter('wp_mail_content_type', 'sp_wp_mail_content_type');

//add a header and footer from files in the active theme
function sp_wp_mail_header_footer($email)
{
  //get header
  $headerfile = get_stylesheet_directory() . "email_header.html";
  if(file_exists($headerfile))
    $header = file_get_contents($headerfile);
  else
    $header = "";

  //get footer
  $footerfile = get_stylesheet_directory() . "email_footer.html";
  if(file_exists($footerfile))
    $footer = file_get_contents($footerfile);
  else
    $footer = "";

  //update message
  $email['message'] = $header . $email['message'] . $footer;

  return $email;
}
add_filter('wp_mail', 'sp_wp_mail_header_footer');

Sending emails from your server can present interesting network problems. Running a local SMTP server for sending emails can be time-consuming on top of the work of running a web server. Deliverability of your emails can be affected by spam filters that haven’t whitelisted your apps IP range. The Configure SMTP plugin can be used to send your outgoing email through an external SMTP server like a Google Apps account. Services like Mandrill and SendGrid, each with its own WordPress plugin, also offer ways to send email from their trusted servers with additional tracking of open and bounce rates.

File Header API

The comment block at the top of the main theme and plugin files are often referred to as headers. The File Header API consists of three functions, get_plugin_data(), wp_get_theme(), and get_file_data(), which allow you to parse these comment blocks.

As a reminder, here is what a plugin’s file header may look like:

/*
Plugin Name: Paid Memberships Pro
Plugin URI: http://www.paidmembershipspro.com
Description: Plugin to Handle Memberships
Version: 1.7.3.2
Author: Stranger Studios
Author URI: http://www.strangerstudios.com
*/

You can pull this data into an array by calling the get_plugin_data() function:

get_plugin_data( $plugin_file, $markup = true, $translate = true )

Its attributes are:

$plugin_file: The absolute path to the main plugin file where the header will be parsed.
$markup: A flag that, if set to true, will apply HTML markup to some of the header values. For example, the plugin URI will be turned into a link.
$translate: A flag that, if set to true, will translate the header values using the current locale and text domain.

The following code loops through the plugins directory and will show data for most of the plugins there. It actually takes quite a bit of logic to find all plugins in all formats. For that you can use the get_plugins() function, which will return an array of all plugins or take a look at the code for that function found in wp-admin/includes/plugin.php. More information on get_plugins() can be found on the WordPress Codex’s Function Reference page:

//must include this file
require_once(ABSPATH . "wp-admin/includes/plugin.php");

//remember current directory
$cwd = getcwd();

//switch to themes directory
$plugins_dir = ABSPATH . "wp-content/plugins";
chdir($plugins_dir);

echo "<pre>";

//loop through theme directories and print theme info
foreach(glob("*", GLOB_ONLYDIR) as $dir)
{
	$plugin = get_plugin_data($plugins_dir .
        "/" . $dir . "/" . $dir . ".php", false, false);
	print_r($plugin);
}

echo "</pre>";

//switch back to current directory just in case
chdir($cwd);

Similarly, you can use wp_get_theme() to get information out of a theme’s file header:

wp_get_theme( $stylesheet, $theme_root )+

Its attributes are as follows:

$stylesheet: The name of the directory for the theme. If not set, this parameter will be the current theme’s directory.
$theme_root: The absolute path to the theme’s root folder. If not set, the value returned by get_raw_theme_root() is used.

The following code loops through the themes directory and will show data for most of the themes there. It actually takes quite a bit of logic to find all themes. For that you can use the wp_get_themes() function, which will return an array of all WP_Theme objects, or take a look at the code for that function found in wp-includes/theme.php. More information on wp_get_themes() can be found on their WordPress Codex page:

//remember current directory
$cwd = getcwd();

//switch to themes directory
$themes_dir = dirname(get_template_directory());
chdir($themes_dir);

echo "<pre>";

//loop through theme directories and print theme info
foreach(glob("*", GLOB_ONLYDIR) as $dir)
{
	$theme = wp_get_theme($dir);
	print_r($theme);
}

echo "</pre>";

//switch back to current directory just in case
chdir($cwd);

Adding File Headers to Your Own Files

Both the get_plugin_info() and wp_get_theme() functions make use of the get_file_data() function. You can access the get_file_data() function directly to pull file headers out any file. This can help you to create your own drop-ins or sub-plugins (often referred to as modules or add-ons) for your plugins.

get_file_data( $file, $default_headers, $context = "" ) has the following attributes:

$file

The full path and filename of the file to pull data from.

$default_headers

An array of the header fields to look for. The keys of the array should be the header names, and the values of the array should be regex expressions for parsing the label that comes before the “:” in the comment. You can usually just enter the header name as the regex as well.

$context

A label to differentiate between different kinds of headers. This parameter determines which extra_{context}_headers filter is applied to the default headers passed in:

//set headers for our files
$default_headers = array(
	"Title" => "Title",
	"Slug" => "Slug",
	"Version" => "Version"
);

//remember current directory
$cwd = getcwd();

//change to reports directory
$reports_dir = dirname(__FILE__) . "/reports";
chdir($reports_dir);

echo "<pre>";

//loop through .php files in reports directory
foreach (glob("*.php") as $filename)
{
	$data = get_file_data($filename, $default_headers, "report");
	print_r($data);
}

echo "</pre>";

//change back to the current directory in case someone expects the default
chdir($cwd);

Adding New Headers to Plugins and Themes

The extra_plugin_headers and extra_theme_headers filters can be used to add further headers to the information returned by get_plugin_data() and wp_get_theme(), respectively. You can also use filters for your custom contexts to work with get_file_data(). The format is extra_{context}_headers.

Example 7-4 adds an Allow Updates header to plugins. If this header is found and the value is no or false, that plugin will not be flagged to update.

Example 7-4. The Stop Plugin Updates plugin

<?php
/*
Plugin Name: Stop Plugin Updates
Plugin URI: http://bwawwp.com/plugins/stop-plugin-updates/
Description: "Allow Updates: No" i a plugin's header keeps it from updating.
Version: .1
Author: Stranger Studios
Author URI: http://www.strangerstudios.com
*/

//add AllowUpdates header to plugin
function spu_extra_plugin_headers( $headers ) {
    $headers['AllowUpdates'] = "Allow Updates";
	return $headers;
}
add_filter( "extra_plugin_headers", "spu_extra_plugin_headers" );

/*
	loop through plugins
	check if updates are disallowed and if so remove it from list
*/
function spu_pre_set_site_transient_update_plugins( $update_plugins ) {
  //see if there are any plugins needing updates
  if ( !empty( $update_plugins ) && !empty( $update_plugins->response ) ) {
    //loop through plugins
    $new_plugins = array();
    foreach ( $update_plugins->response as $pluginpath => $plugin ) {
	//check if the plugin is allowed or not
	$plugin_data = ABSPATH . '/wp-content/plugins/' . $pluginpath;
	$plugin_data = get_plugin_data( $plugin_data );
	if ( strtolower( $plugin_data['Allow Updates'] ) == "no" ||
	  strtolower( $plugin_data['Allow Updates'] ) == "false" ) {
	  //change checked version and don't add to the new response
	  $update_plugins->checked[$pluginpath] = $plugin_data['Version'];
	}
	else {
		//not blocked. add plugin to new response
		$new_plugins[$pluginpath] = $plugin;
	}
    }
    $update_plugins->response = $new_plugins;
  }

return $update_plugins;
}
add_action(
	'pre_set_site_transient_update_plugins',
	'spu_pre_set_site_transient_update_plugins'
);
?>

Heartbeat API

The Heartbeat API, introduced in WordPress 3.9, is near-real-time Ajax communication to push and pull specific content to and from the WordPress database. If activated, the Heartbeat API will beat every 15 to 30 seconds by default on a loaded page to check whether something has happened; this is called the Heartbeat pulse. You can also set the pulse manually in code for up to 60 seconds.

Note

Check out the Heartbeat Control plugin developed by Jeff Matson. It’s great for easily adjusting how often Heartbeat pulses are sent to the server and where Heartbeat pulses are being sent from; you can even turn them off.

The Heartbeat API is more of a WordPress backend feature, and although it can be used on the front, it probably shouldn’t be (or at least should be used very sparingly). As you can imagine, the Heartbeat API could be pretty labor intensive on server resources, depending what you are using it for and how many people are using it. This API is being used in WordPress core to do such things as post locking; you know that nice little administrative pop up on a post you’re currently editing that lets you know that someone else wants to take over? If this has happened to you, you might have thought to yourself, can’t they see the little lock icon next to the post and the warning pop up saying that I’m actually working on it right now? This is a great example of the Heartbeat API being used to check the status of who’s working on a post and to take action accordingly. When the post listing page first loads, it knows who’s working on what pages; then the Heartbeat API takes over to check every x seconds if a user is done with a post they were working on or if someone opened another post and started working on that. WordPress knows these actions from the loaded page by sending data asynchronously via the Heartbeat API to the server to be processed and returned to update the loaded page via JavaScript. So that person totally knew that you were working on that post and decided to just take it over anyways…smh!

The Heartbeat API works in three main steps:

Sending data to the server from the client via jQuery. This is done with the heartbeat-send event.
Processing the request on the server and providing a response via PHP. This is done with the heartbeat_received filter.
Processing the response on the client via jQuery. This is done with the heartbeat-tick event.

In our example, we’ll build a simple plugin that leverages the Heartbeat API to show staff at a grade school when a parent arrives to pick up their kid(s) from the car line. Almost every grade school we’ve dealt with has this archaic and dangerous method of teachers walking car to car in the heat, cold, rain, and snow to have parents sign a piece of paper to pick up their children. It’s 2020, school board members; we can do better!

First let’s build a basic plugin that displays an administrator screen on a monitor in the cafeteria where students wait patiently for their parents to arrive. This will be a shorthand version of a WordPress plugin concept to keep the code short and sweet to highlight the Heartbeat API functionality:

Make a folder in your plugin directory called the-teacher-life-saver.
Make a file in this folder called the-teacher-life-saver.php.
Review and copy the following code.
Save and activate the plugin, then test it on the administrator dashboard.

Example 7-5 creates an administrator dashboard widget that will automatically display content processed on the server via the WP Heartbeat API without manually refreshing the page.

Example 7-5. The Teacher Life Saver plugin

<?php
/**
* Plugin Name: The Teacher Life Saver
* Plugin URI:  https://schoolpress.me/
* Description: Alert teachers of parent arrivals
* Version:     0.0.1
*/

// Action hook for creating a dashboard widget
function ttls_dashboard_widget() {
	global $wp_meta_boxes;

// widget ID, widget name, callback function
wp_add_dashboard_widget('ttls_widget', 'Student Pick Ups', 'ttls_dashboard');
}
add_action('wp_dashboard_setup', 'ttls_dashboard_widget');

// Markup for the dashboard widget
function ttls_dashboard() {
	echo "<div id='ttls_message'></div>";
}

// Change the default pulse to every 15 seconds so we don't have to wait as long
function ttls_heartbeat_settings( $settings ) {
    $settings['interval'] = 15; // Anything between 15-60 seconds
    return $settings;
}
add_filter( 'heartbeat_settings', 'ttls_heartbeat_settings', 1 );

// Enqueue heartbeat.js and our JavaScript functions
function ttls_heartbeat_init()
{
	  // Only run this on the dashboard page (index.php)
	  global $pagenow;
	  if( $pagenow != 'index.php' )
		  return;

  // Enqueue the Heartbeat API
  wp_enqueue_script('heartbeat');

  // Load our JavaScript functions in the footer
  add_action("admin_footer", "ttls_js_wp_footer");
}
add_action("admin_init", "ttls_heartbeat_init");

// JavaScript functions ran in the footer
function ttls_js_wp_footer()
{
?>
<script>
jQuery(document).ready(function() {

// Use heartbeat-send to send any keys/values in the data array
	jQuery(document).on('heartbeat-send', function(e, data) {
		data['client'] = 'check-for-parents';
});

// Use heartbeat-tick function check for data and take action
jQuery(document).on('heartbeat-tick', function(e, data) {
if(data['server'])
	document.getElementById("ttls_message").innerHTML = data['server']
	+ document.getElementById("ttls_message").innerHTML;
	});
});
</script>
<?php
}

// Server-side function to receive and process the request then return a response
function ttls_heartbeat_received($response, $data)
{
// Look for whatever data was passed from JS heartbeat-send function
if($data['client'] == 'check-for-parents')
{
  // Build whatever response you want
  $r = '<p>';
  $r .= date( 'm/j/y g:i a', current_time( 'timestamp', 0 ) );
  $r .= " - Nina Messenlehner's father Brian Messenlehner ";
  $r .= "has arrived in a 2007 White Hummer H2.";
  $r .= '</p>';

  return $r;
}
add_filter('heartbeat_received', 'ttls_heartbeat_received', 10, 2);
?>

If you did this correctly you should see whatever content you loaded into the $response[server] var in the ttls_heartbeat_received function pop up in your new dashboard widget around every 15 seconds. You can really do whatever processing you want on the server side and return anything you want in the response to be processed on the client side. In our example, we basically hardcoded a simple response to showcase how it works, but you could take it much further. Imagine a parent having a mobile app on their smartphone in conjunction with a geofence around the school parking lot. As soon as the parent pulls into the parking lot, their status could be updated; and the next time the Heartbeat pulse checks for new parents, it could return that parent’s information to the monitor. In our example we returned very basic information, but we could include a lot more like the student name, parent name, parent photo, vehicle type, vehicle photo, license plate number, and anything else that might be important.

¹ Posts with post_type page.

² If you move this code into a subdirectory of your plugin, you need to update the register_activation_hook() and register_deactivation_hook() calls to point to the main plugin file.

Вас заинтересует / Intresting for you:

The Future of WordPress: how p... 572 views dbstalker Mon, 31 Jan 2022, 17:11:40

WordPress optimization: minimu... 3497 views Fortan Wed, 13 Nov 2019, 12:45:25

Optimizing WordPress for SEO 3708 views Fortan Wed, 13 Nov 2019, 11:25:09

Secure WordPress: Basics & Adv... 1185 views dbstalker Mon, 31 Jan 2022, 15:54:50

WordPress

Comments (1)

ildergun

about 2 years ago

#12

This comment was minimized by the moderator on the site

Great description for Shortcode API for WP code developers!

ildergun

There are no comments posted here yet

Leave your comments

Posting as Guest

Login to your account

What Are You Looking For?

Popular Tags

Working with WordPress APIs, Objects, and Helper Functions

Shortcode API

Shortcode Attributes

Nested Shortcodes

Caution

Removing Shortcodes

Note

Other Useful Shortcode-Related Functions

Widgets API

Figure 7-1. Text widget settings

Note

Before You Add Your Own Widget

Adding Widgets

Example 7-1. SchoolPress note widget

Defining a Widget Area

Embedding a Widget Outside of a Dynamic Sidebar

Dashboard Widgets API

Figure 7-2. Dashboard widgets

Removing Dashboard Widgets

Adding Your Own Dashboard Widget

Example 7-2. Assignments dashboard widget

Figure 7-3. Our assignments widget

Figure 7-4. The configuration view of our assignments widget

Settings API

Do You Really Need a Settings Page?

Could You Use a Hook or Filter Instead?

Note

Use Standards When Adding Settings

Ignore Standards When Adding Settings

Rewrite API

Adding Rewrite Rules

Flushing Rewrite Rules

Other Rewrite Functions

Example 7-3. The WP DOC plugin

WP-Cron

Adding Custom Intervals

Scheduling Single Events

Kicking Off Cron Jobs from the Server

Tip

Caution

Using Server Crons Only

Note

Note

WP Mail

Sending Nicer Emails with WordPress

File Header API

Adding File Headers to Your Own Files

Adding New Headers to Plugins and Themes

Example 7-4. The Stop Plugin Updates plugin

Heartbeat API

Note

Example 7-5. The Teacher Life Saver plugin

Вас заинтересует / Intresting for you:

Ваш аккаунт