Displaying Your WordPress Widget on the Site

The final stage of creating your widget is to display its output on the site. You do this by further editing the WP_Widget class.

This is the final part in a five part series which you'll need to follow to get this far:

What You'll Need

To follow this tutorial, you'll need:

A development installation of WordPress
A code editor
The code from the previous tutorial on creating your widget's form.
The code from my earlier tutorial on context-sensitive sidebar navigation.

Coding the Widget's Output

There are two parts to this: adding a function outside the widget which will identify the ancestor page to use, and editing the widget function inside the WP_Widget class.

Adding the Ancestor Function

This function is taken directly from my earlier tutorial to create a plugin for context-sensitive sidebar navigation.

Above your WP_Widget class, add the function to your plugin file:

<?php
function tutsplus_check_for_page_tree() {

    //start by checking if we're on a page
	if( is_page() ) {
	
		global $post;
	
		// next check if the page has parents
		if ( $post->post_parent ){
		
			// fetch the list of ancestors
			$parents = array_reverse( get_post_ancestors( $post->ID ) );
			
			// get the top level ancestor
			return $parents[0];
			
		}
		
		// return the id  - this will be the topmost ancestor if there is one, or the current page if not
		return $post->ID;
		
	}

}
?>

You will then use this later on when defining a query to run in the widget.

Editing the Widget Function

Next you'll need to edit the empty widget function you created earlier, in your plugin file. Start by defining the variable based on the form's input:

function widget( $args, $instance ) {
    
	extract( $args );
	echo $before_widget;		
	echo $before_title . 'In this section:' . $after_title;	

}

Next, add your query and its output, editing the function so it reads like this:

function widget( $args, $instance ) {
    
	// kick things off
	extract( $args );
	echo $before_widget;		
	echo $before_title . 'In this section:' . $after_title;		
	
	// run a query if on a page
	if ( is_page() ) {

		// run the tutsplus_check_for_page_tree function to fetch top level page
		$ancestor = tutsplus_check_for_page_tree();

		// set the arguments for children of the ancestor page
		$args = array(
			'child_of' => $ancestor,
			'depth' => $instance[ 'depth' ],
			'title_li' => '',
		);
		
		// set a value for get_pages to check if it's empty
		$list_pages = get_pages( $args );
		
		// check if $list_pages has values
		if( $list_pages ) {

			// open a list with the ancestor page at the top
			?>
			<ul class="page-tree">
				<?php // list ancestor page ?>
				<li class="ancestor">
					<a href="<?php echo get_permalink( $ancestor ); ?>"><?php echo get_the_title( $ancestor ); ?></a>
				</li>
				
				<?php
				// use wp_list_pages to list subpages of ancestor or current page
				wp_list_pages( $args );;
			
	
			// close the page-tree list
			?>
			</ul>
	
		<?php
		}
	}

	
}

This checks if we're on a page and then defines the arguments for the list_pages() function using the output of the previous function and the value of the $depth variable which is set by the widget's form.

Now save your widget and check your site. Your list should display wherever you've added the widget:

The Final Plugin

You now have a complete widget plugin!

To recap what you've covered in all five tutorials, here's what the plugin code should look like in full:

<?php 
/*Plugin Name: List Subpages Widget
Description: This widget checks if the current page has parent or child pages and if so, outputs a list of the highest ancestor page and its descendants. This file supports part 5 of the series to create the widget and doesn't give you a functioning widget.
Version: 0.5
Author: Rachel McCollin
Author URI: https://rachelmccollin.com
License: GPLv2
*/
?>
<?php
?>
<?php
/*******************************************************************************
function tutsplus_check_for_page_tree() - checks if the current page is in a page tree.
*******************************************************************************/
?>
<?php
function tutsplus_check_for_page_tree() {

    //start by checking if we're on a page
	if( is_page() ) {
	
		global $post;
	
		// next check if the page has parents
		if ( $post->post_parent ){
		
			// fetch the list of ancestors
			$parents = array_reverse( get_post_ancestors( $post->ID ) );
			
			// get the top level ancestor
			return $parents[0];
			
		}
		
		// return the id  - this will be the topmost ancestor if there is one, or the current page if not
		return $post->ID;
		
	}

}
?>
<?php
class Tutsplus_List_Pages_Widget extends WP_Widget {
	
	function __construct() {
	
		parent::__construct(
			
			// base ID of the widget
			'tutsplus_list_pages_widget',
			
			// name of the widget
			__('List Related Pages', 'tutsplus' ),
			
			// widget options
			array (
				'description' => __( 'Identifies where the current page is in the site structure and displays a list of pages in the same section of the site. Only works on Pages.', 'tutsplus' )
			)
			
		);
		
	}
	
	function form( $instance ) {
	
		$defaults = array(
			'depth' => '-1'
		);
		$depth = $instance[ 'depth' ];
		
		// markup for form ?>
		<p>
			<label for="<?php echo $this->get_field_id( 'depth' ); ?>">Depth of list:</label>
			<input class="widefat" type="text" id="<?php echo $this->get_field_id( 'depth' ); ?>" name="<?php echo $this->get_field_name( 'depth' ); ?>" value="<?php echo esc_attr( $depth ); ?>">
		</p>
				
	<?php
	}
	
	function update( $new_instance, $old_instance ) {
	
		$instance = $old_instance;
		$instance[ 'depth' ] = strip_tags( $new_instance[ 'depth' ] );
		return $instance;
		
	}
	
	function widget( $args, $instance ) {
		
		// kick things off
		extract( $args );
		echo $before_widget;		
		echo $before_title . 'In this section:' . $after_title;		
		
		// run a query if on a page
		if ( is_page() ) {
	
			// run the tutsplus_check_for_page_tree function to fetch top level page
			$ancestor = tutsplus_check_for_page_tree();
	
			// set the arguments for children of the ancestor page
			$args = array(
				'child_of' => $ancestor,
				'depth' => $instance[ 'depth' ],
				'title_li' => '',
			);
			
			// set a value for get_pages to check if it's empty
			$list_pages = get_pages( $args );
			
			// check if $list_pages has values
			if( $list_pages ) {
	
				// open a list with the ancestor page at the top
				?>
				<ul class="page-tree">
					<?php // list ancestor page ?>
					<li class="ancestor">
						<a href="<?php echo get_permalink( $ancestor ); ?>"><?php echo get_the_title( $ancestor ); ?></a>
					</li>
					
					<?php
					// use wp_list_pages to list subpages of ancestor or current page
					wp_list_pages( $args );;
				
		
				// close the page-tree list
				?>
				</ul>
		
			<?php
			}
		}
	
		
	}
	
}
?>
<?php
/*******************************************************************************
function tutsplus_register_list_pages_widget() - registers the widget.
*******************************************************************************/
?>
<?php
function tutsplus_register_list_pages_widget() {

	register_widget( 'Tutsplus_List_Pages_Widget' );

}
add_action( 'widgets_init', 'tutsplus_register_list_pages_widget' );
?>

Summary

Creating a widget does involve a few steps. These are:

Registering your widget
Creating the class to hold the widget functions
Writing a construct function to construct your widget
Writing a form function for the form in the Widgets screen
Writing an update function so the widget can update from the form
Writing a widget function with the output.

Once you've done all these, you will have a working widget, which you can adapt however you want.

1	<?php
2	function tutsplus_check_for_page_tree() {
3
4	//start by checking if we're on a page
5	if( is_page() ) {
6
7	global $post;
8
9	// next check if the page has parents
10	if ( $post->post_parent ){
11
12	// fetch the list of ancestors
13	$parents = array_reverse( get_post_ancestors( $post->ID ) );
14
15	// get the top level ancestor
16	return $parents[0];
17
18	}
19
20	// return the id - this will be the topmost ancestor if there is one, or the current page if not
21	return $post->ID;
22
23	}
24
25	}
26	?>

1	function widget( $args, $instance ) {
2
3	// kick things off
4	extract( $args );
5	echo $before_widget;
6	echo $before_title . 'In this section:' . $after_title;
7
8	// run a query if on a page
9	if ( is_page() ) {
10
11	// run the tutsplus_check_for_page_tree function to fetch top level page
12	$ancestor = tutsplus_check_for_page_tree();
13
14	// set the arguments for children of the ancestor page
15	$args = array(
16	'child_of' => $ancestor,
17	'depth' => $instance[ 'depth' ],
18	'title_li' => '',
19	);
20
21	// set a value for get_pages to check if it's empty
22	$list_pages = get_pages( $args );
23
24	// check if $list_pages has values
25	if( $list_pages ) {
26
27	// open a list with the ancestor page at the top
28	?>
29	<ul class="page-tree">
30	<?php // list ancestor page ?>
31	<li class="ancestor">
32	<a href="<?php echo get_permalink( $ancestor ); ?>"><?php echo get_the_title( $ancestor ); ?></a>
33	</li>
34
35	<?php
36	// use wp_list_pages to list subpages of ancestor or current page
37	wp_list_pages( $args );;
38
39
40	// close the page-tree list
41	?>
42	</ul>
43
44	<?php
45	}
46	}
47
48
49	}

1	<?php
2	/*Plugin Name: List Subpages Widget
3	Description: This widget checks if the current page has parent or child pages and if so, outputs a list of the highest ancestor page and its descendants. This file supports part 5 of the series to create the widget and doesn't give you a functioning widget.
4	Version: 0.5
5	Author: Rachel McCollin
6	Author URI: https://rachelmccollin.com
7	License: GPLv2
8	*/
9	?>
10	<?php
11	?>
12	<?php
13	/*******************************************************************************
14	function tutsplus_check_for_page_tree() - checks if the current page is in a page tree.
15	*******************************************************************************/
16	?>
17	<?php
18	function tutsplus_check_for_page_tree() {
19
20	//start by checking if we're on a page
21	if( is_page() ) {
22
23	global $post;
24
25	// next check if the page has parents
26	if ( $post->post_parent ){
27
28	// fetch the list of ancestors
29	$parents = array_reverse( get_post_ancestors( $post->ID ) );
30
31	// get the top level ancestor
32	return $parents[0];
33
34	}
35
36	// return the id - this will be the topmost ancestor if there is one, or the current page if not
37	return $post->ID;
38
39	}
40
41	}
42	?>
43	<?php
44	class Tutsplus_List_Pages_Widget extends WP_Widget {
45
46	function __construct() {
47
48	parent::__construct(
49
50	// base ID of the widget
51	'tutsplus_list_pages_widget',
52
53	// name of the widget
54	__('List Related Pages', 'tutsplus' ),
55
56	// widget options
57	array (
58	'description' => __( 'Identifies where the current page is in the site structure and displays a list of pages in the same section of the site. Only works on Pages.', 'tutsplus' )
59	)
60
61	);
62
63	}
64
65	function form( $instance ) {
66
67	$defaults = array(
68	'depth' => '-1'
69	);
70	$depth = $instance[ 'depth' ];
71
72	// markup for form ?>
73	<p>
74	<label for="<?php echo $this->get_field_id( 'depth' ); ?>">Depth of list:</label>
75	<input class="widefat" type="text" id="<?php echo $this->get_field_id( 'depth' ); ?>" name="<?php echo $this->get_field_name( 'depth' ); ?>" value="<?php echo esc_attr( $depth ); ?>">
76	</p>
77
78	<?php
79	}
80
81	function update( $new_instance, $old_instance ) {
82
83	$instance = $old_instance;
84	$instance[ 'depth' ] = strip_tags( $new_instance[ 'depth' ] );
85	return $instance;
86
87	}
88
89	function widget( $args, $instance ) {
90
91	// kick things off
92	extract( $args );
93	echo $before_widget;
94	echo $before_title . 'In this section:' . $after_title;
95
96	// run a query if on a page
97	if ( is_page() ) {
98
99	// run the tutsplus_check_for_page_tree function to fetch top level page
100	$ancestor = tutsplus_check_for_page_tree();
101
102	// set the arguments for children of the ancestor page
103	$args = array(
104	'child_of' => $ancestor,
105	'depth' => $instance[ 'depth' ],
106	'title_li' => '',
107	);
108
109	// set a value for get_pages to check if it's empty
110	$list_pages = get_pages( $args );
111
112	// check if $list_pages has values
113	if( $list_pages ) {
114
115	// open a list with the ancestor page at the top
116	?>
117	<ul class="page-tree">
118	<?php // list ancestor page ?>
119	<li class="ancestor">
120	<a href="<?php echo get_permalink( $ancestor ); ?>"><?php echo get_the_title( $ancestor ); ?></a>
121	</li>
122
123	<?php
124	// use wp_list_pages to list subpages of ancestor or current page
125	wp_list_pages( $args );;
126
127
128	// close the page-tree list
129	?>
130	</ul>
131
132	<?php
133	}
134	}
135
136
137	}
138
139	}
140	?>
141	<?php
142	/*******************************************************************************
143	function tutsplus_register_list_pages_widget() - registers the widget.
144	*******************************************************************************/
145	?>
146	<?php
147	function tutsplus_register_list_pages_widget() {
148
149	register_widget( 'Tutsplus_List_Pages_Widget' );
150
151	}
152	add_action( 'widgets_init', 'tutsplus_register_list_pages_widget' );
153	?>