One of my all time favorite Genesis-only plugins is Nick Croft's (AKA @Nick_theGeek) Genesis Featured Widget Amplified. It's a framework sort of widget that allows you to extend it without having to hack it's core. Nick's design around this plugin is incredible.
So let me walk you through some of the advantages of this incredible plugin. Even though this is in the FAQ of the plugin, I thought it would be beneficial to review the hooks and filters.
The Hooks
Genesis Featured Widget Amplified has several hooks. They are as follows:
- gfwa_before_loop - before the query is formulated
- gfwa_before_post_content - before the content
- gfwa_post_content - standard content output
- gfwa_after_post_content - after content
- gfwa_endwhile - after the endwhile but before the endif
- gfwa_after_loop - after the loop endif
- gfwa_list_items - within additional list item loop
- gfwa_print_list_items - outside the additional list item loop, where list items are output
- gfwa_category_more - within the archive more link conditional block
- gfwa_after_category_more - after the archive more conditional block
- gfwa_form_first_column* within the widget form, end of first column
- gfwa_form_second_column* within the widget form, end of second column
*Note: These are misspelled in the code. On the FAQ form, they are spelled correctly; however, the hooks themselves are missing the 'n' at the end of column
I have updated my Genesis Hooks plugin to include these. So if you have Genesis Featured Widget Amplified and the Genesis Hooks plugins installed, you should be able to see all the Genesis Featured Widget Amplified's hooks.
The Filters
Genesis Featured Widget Amplified has a couple filters. They are as follows:
- gfwa_exclude_post_types - used to prevent post types from appearing in the post type list in the widget form
- gfwa_exclude_taxonomies - used to prevent taxonomies and related terms from appearing in the terms and taxonomies list in the widget form
Widget Instance Identification
Much like the traditional conditionals work, you can locate and identify whether you are dealing with a specific widget instance or not with Genesis Featured Widget Amplified's custom identification field. This is a newly added field at the bottom.
Extending the Plugin
Now for those who love to "improve" plugins, rather, customize it more to one's needs, Nick has included two great hooks to enable this. They are: gfwa_form_first_column and gfwa_form_second_column. These two hooks will allow you to do whatever you'd like to the plugin, extending it beyond any needs that you may have.
So, if I wanted to ask the user if they wanted to display the number of comments for a particular post. I would first need to add it to the form:
[php]
//NOTE: gfwa_form_first_colum is the spelling of the widget-plugin in 0.7.2 (and backwards probably). This should be corrected to gfwa_form_first_column in the next version most likely.
add_action( 'gfwa_form_first_colum' , 'wps_gfwa_add_comments_to_form' );
function wps_gfwa_add_comments_to_form( $instance ) {
global $wp_widget_factory;
if ( ! isset( $instance['wps_comments'] ) )
$instance['wps_comments'] = '';
?>
<div style="background: #f1f1f1; border: 1px solid #DDD; padding: 10px 10px 0px 10px; margin-top: 10px; <?php gfwa_display_option( $instance, 'post_type', 'post', false ); ?>">
<p style="<?php gfwa_display_option( $instance, 'post_type', 'post', false ); ?>">
<input class="widget-control-save" id="<?php echo 'widget-' . $wp_widget_factory->widgets['Genesis_Featured_Widget_Amplified']->id_base . '-' . $wp_widget_factory->widgets['Genesis_Featured_Widget_Amplified']->number . '-wps_comments'; ?>" type="checkbox" name="<?php echo 'widget-' . $wp_widget_factory->widgets['Genesis_Featured_Widget_Amplified']->id_base . '[' . $wp_widget_factory->widgets['Genesis_Featured_Widget_Amplified']->number . '][wps_comments]'; ?>" value="1" <?php checked( 1, $instance['wps_comments'] ); ?> />
<label for="<?php echo 'widget-' . $wp_widget_factory->widgets['Genesis_Featured_Widget_Amplified']->id_base . '-' . $wp_widget_factory->widgets['Genesis_Featured_Widget_Amplified']->number . '-wps_comments'; ?>"><?php _e( 'Show Comments', 'wps-domain' ); ?></label>
</p>
</div>
<?php
}
[/php]
Then I would need to add it to the output via a hook:
[php]
add_action( 'gfwa_after_post_content' , 'wps_gfwa_do_add_comments' );
function wps_gfwa_do_add_comments( $instance ) {
global $post;
if ( isset( $instance['wps_comments'] ) ) {
echo '<span class="wps-comments"> Comments: ' . get_comments_number( $post->ID ) . '</span>';
}
}
[/php]
And as you can see it is outputted:
Other Examples
Example #1:
Take for instance, you want to add some customized post meta (not the way the plugin does it but the way you want to do it) to each one except one. First, without the hooks and the custom field, how could you easily do this?
So I first will unhook the standard post meta function and then I will add my own.
[php]
remove_action( 'gfwa_after_post_content', 'gfwa_do_post_meta', 10, 1 );
add_action( 'gfwa_after_post_content', 'wps_do_post_meta' );
[/php]
Next in my function, I will check to see if the widget is a specific widget to which I do not want to add any post meta, with a simple if-then statement: if ( $instance['custom_field'] == 'digital-edition' ) return;. Then I will add my own post meta using the standard Genesis shortcodes (post_categories & post_tags), customizing the attributes.
[php]
function wps_do_post_meta( $instance ) {
if ( $instance['custom_field'] == 'digital-edition' )
return;
// Add Post Meta
$post_meta = '[ post_categories before="Posted in "]<br /> [ post_tags before="Tags: "]'; //no space after initial bracket
printf( '<p class="post-meta">%s</p>', do_shortcode( $post_meta ) );
}
[/php]
Now this particular example could also be accomplished within the widget form by simply placing [ post_categories before="Posted in "]
[ post_tags before="Tags: "] inside the Post Meta information; however, there is a bug in the code that prevents this. I've already attempted to notify Nick regarding this, which is a simple fix. When he does fix this, this example just demonstrates the amazing customization flexibility.
Example #2:
Now, if on the admin side, I didn't want my client to use a specific post type in the Genesis Featured Widget Amplified for whatever reason, OR, I want to be able to include attachments in the widget, I would need to access the filter gfwa_exclude_post_types.
To include attachments:
[php]add_filter( 'gfwa_exclude_post_types' , 'wps_add_attachments_to_gfwa' );
function wps_add_attachments_to_gfwa( ) {
return array( '' );
}[/php]
To remove pages (and add attachments):
[php]add_filter( 'gfwa_exclude_post_types' , 'wps_remove_pages_from_gfwa' );
function wps_remove_pages_from_gfwa( ) {
return array( 'page' );
}[/php]
To remove pages only:
[php]add_filter( 'gfwa_exclude_post_types' , 'wps_remove_pages_attachments_from_gfwa' );
function wps_remove_pages_attachments_from_gfwa( ) {
return array( 'page' , 'attachments' );
}[/php]
Example #3:
An even more powerful use that parallels the previous filter is the filter with gfwa_exclude_taxonomies. This can enable you to have some private taxonomies for organizational reasons. Out of the box, none are filtered (caveat: for some reason, it does filter nav_menu, but I bet that's a simple oversight and really doesn't have any effect on the plugin).
To remove post Formats:
[php]add_filter( 'gfwa_exclude_taxonomies' , 'wps_remove_post_formats_from_gfwa' );
function wps_remove_post_formats_from_gfwa( ) {
return array( 'post_format' );
}[/php]
To remove Tags:
[php]add_filter( 'gfwa_exclude_taxonomies' , 'wps_remove_post_formats_from_gfwa' );
function wps_remove_post_formats_from_gfwa( ) {
return array( 'post_tag' );
}[/php]
To remove post Formats and Tags:
[php]add_filter( 'gfwa_exclude_taxonomies' , 'wps_remove_post_formats_from_gfwa' );
function wps_remove_post_formats_from_gfwa( ) {
return array( 'post_tag' , 'post_format' );
}[/php]
From a Developer's Perspective
Nick has an extensive roadmap for this plugin that includes the inclusion of post formats, the Grid loop and more on post types (plus more!). Nick has also committed to fixing the spelling of the two hooks, fixing the validation and esc_html() use (which was the post meta problem discussed earlier), and to include a post class filter to be able to do something like this:
[php]
add_filter( 'gfwa_post_class_filter' , 'wps_add_post_class_to_gfwa' );
function wps_add_post_class_to_gfwa( $instance ) {
return $instance['custom_field'];
}[/php]