Find Posts Dialog Box

The Find Posts dialog box can be a very useful feature to add to your plugin. For example, when we attach images to posts (from the Media >> Library menu) we use the Find Posts dialog box to search for our target objects.

Find Posts dialog box while attaching images to posts.

In the dialog box above, we can search for post and page objects.

Custom post types also get automatically added. Our example Find Posts dialog box above allows us to search for gallery and background objects, both of which are custom post types.

Searching for all post objects with the string - test.

Here we consider how to add a Find Posts dialog box to our plugin.

1. find_posts_div

We can add the Find Posts dialog box by using the find_posts_div WordPress function.

?>
<form name="plugin_form" id="plugin_form" method="post" action="">
        <?php wp_nonce_field('plugin_nonce'); ?> 
        // Other form elements and code ...
 	<?php find_posts_div(); ?>
</form>
<?php

Note – we want to include the find_posts_div function call within a HTML form, so that we may capture and further process its results.

2. Attach Find Posts dialog box to a button or link

After we add the find_posts_div command, we will not see anything new because it only shows up as a pop-up box that is tied to an event. For example, we may only want the dialog box to appear when we click on a button or a link.

We attach our dialog box to a link or button by using the Javascript onclick event.

<a onclick="findPosts.open('action','find_posts');return false;" href="#">
<?php esc_attr_e('Example Post Search'); ?>
</a>

The Javascript function findPosts.open will open our Find Posts dialog box and handle user search and selection. Once the user Selects a post object, our form will be automatically submitted. The results of the dialog box will be passed along with other elements of our form.

The findPosts.open function also allows us to pass in an additional form element if we so choose. In the example above, we pass in a form element called action with the value find_posts.

This form element will only get added when we submit the form through our Find Posts dialog box. Therefore, it is a good way to identify whether the form is submitted as a result of a search, or as a result of some other operation.

3. Add relevant scripts

When we click on the link however, nothing happens.

For our Find Posts dialog box to appear, we also need to add in the styles and scripts that it relies on.

	add_action("admin_print_styles", 'plugin_admin_styles' );
	add_action("admin_print_scripts", 'plugin_admin_scripts' );
	function plugin_admin_styles() {
		wp_enqueue_style('thickbox'); // needed for find posts div
	}
	
	function plugin_admin_scripts() {
		wp_enqueue_script('thickbox'); // needed for find posts div
		wp_enqueue_script('media');
		wp_enqueue_script('wp-ajax-response');
	}

The pop-up box is rendered using thickbox, so we need to add the thickbox style and script to our plugin page.

In addition, the Find Posts dialog box relies on the media and wp-ajax-response Javascript libraries.

Note – The general hooks admin_print_styles and admin_print_scripts will add the styles and scripts to ALL admin pages. Instead, it is more efficient to only add them to our specific plugin dialog box page.

To do this we can use the admin_print_scripts-{$plugin_page} and admin_print_scripts-{$plugin_page} hooks.

4. Get dialog box results

After we add the relevant scripts, our Find Posts dialog box will appear when we click on our Example Post Search link.

Once we choose the post that we want and click on the Select button, the results of our dialog box will be submitted with our form.

In particular, the following elements will be added to our form array –

$_POST['action'] = 'find_posts'$_POST['found_post_id'] = post object selected

The action form argument was added from the findPosts.open function call inputs. The found_post_id form argument is automatically added when the user selects a post object in our Find Posts dialog box.

5. We are done!

By using the find_posts_div native WordPress function, we can easily add the ability to search for posts without having to write any of the search code ourselves. Using such native functions will also give our plugin a more standard look, and allow us to benefit from new WordPress core features, such as custom post types.