Feature a Page Widget 2.0 Documentation

Pro Tip: Hit CTRL + F (PC) or CMD + F (Mac) to search within this page for answers to your questions!

The 2.0 version widget formWhat’s New in 2?

Feature a Page Widget 2.0 includes new options, filters, and templates, enable nearly all of the most-requested features while still providing one of the simplest and straight-forward “Featured Content” widgets out there. This includes:

  1. Default support for featuring Pages and Posts with a filter to add custom post types.
  2. Four new options to toggle the Title, Image, Excerpt, and Read More link.
  3. New templates provide separate files for each layout and use a normal post loop.
  4. New widget design feels at home in WordPress admin.
  5. Five (5!) new filters allow modifying post types, widget templates, read more text, image size, and whether to auto-generate an excerpt.

You’ll find documentation and code snippets for all of this below.

IMPORTANT: WordPress 3.8+ and 1.0 Template Compatibility

Feature a Page Widget 2.0 supports only WordPress 3.8+ and features a new templating system. The widget should be backwards compatible with many, if not all, Version 1.0 custom templates. However, 1.0 templates don’t support all widget options and support may be removed in the future. Please update or remove your old custom widget templates as soon as possible.

The Basics

The Feature a Page Widget uses the “Featured Image” and “Excerpt” fields which are saved and edited on the page you want to feature. The widget indicates whether those fields are set in the “Page to Feature” select list and “Featured Page Status” section of the widget form.

If you need to add or modify the Featured Image or Excerpt, click the edit link (pencil icon) in the widget settings form to edit the page in a new tab or window.

Customizing the Widget

When customizing the widget, there are three options of increasing complexity to override the widget. The following order of modification methods is recommended:

  1. Custom CSS Rules
  2. Filters
  3. Template Overrides

Detailed information on all three options is included below.

Never modify core plugin files. Your changes will be lost when the plugin updates.

Custom CSS

Write CSS to change the widget’s appearance should always be your first option when modifying the widget’s appearance. It’s fairly lightweight, easy to maintain, and requires the least technical knowledge to implement.

Store your CSS rules in a theme, child theme, plugin, or with a Custom CSS plugin like Jetpack’s Custom CSS module.

To help you get started, you’ll find tons of prewritten and commented CSS selectors in /wp-content/plugins/feature-a-page-widget/css/fpw_starter_styles.css. Simply copy the selectors you need to wherever you keep custom CSS and write the styling rules you want to modify the widget.

Filters

Feature a Page Widget 1.0 had three filters. Version 2.0 includes five new filters(!), adding the ability to implement the most-requested features.

New Filters in FaPW 2.0

The code snippets below would go in a theme’s functions.php file, plugin, or mu-plugin.

fpw_post_types

Add or remove “featureable” post types for the widget.

<?php
/**
* add a post type that can be featured in the Feature a Page Widget
*
* Any post types added via this filter automatically have support added for excerpts and featured images
*
* This example adds the ability to feature the "book" post type
*
* @param $post_types array array of post_type slugs that can be featured with the widget
*/
add_filter( 'fpw_post_types', 'fpw_add_post_type_to_feature' );
function fpw_add_post_type_to_feature( $post_types ) {
$post_types[] = 'book';
return $post_types;
}
/**
* remove a post type that can be featured in the Feature a Page Widget
*
* This example removes the [now default] ability to feature the Post post type
*
* @param $post_types array array of post_type slugs that can be featured with the widget
*/
add_filter( 'fpw_post_types', 'fpw_remove_post_type_to_feature' );
function fpw_remove_post_type_to_feature( $post_types ) {
return array_diff( $post_types, array( 'post' ) );
}

fpw_widget_templates

Remove, add, or set single widget template.

<?php
/**
* remove a default template
*
* default templates are: big, banner, wrapped
*
* this example removes the "Big Image" template
*
* @param $templates array slug => label pairs of templates
*/
function fpw_remove_widget_template( $templates ) {
unset( $templates['big'] );
return $templates;
}
add_filter( 'fpw_widget_templates', 'fpw_remove_widget_template' );
/**
* add a custom template
*
* In addition to this filter, you must create a file named my_new_template.php in a /fpw2_views/ folder in the active child or parent theme
*
* @param $templates array slug => label pairs of templates
*/
function fpw_add_widget_template( $templates ) {
$templates['my_new_template'] = __( 'My New Template', 'your-text-domain' );
return $templates;
}
add_filter( 'fpw_widget_templates', 'fpw_add_widget_template' );
/**
* add one layout for all widgets (& remove Layout setting)
*
* Example sets widget to always use the "Banner" layout
*
* @param $templates array slug => label pairs of templates
*/
function fpw_set_widget_template() {
$template = array( 'banner' => 'Banner Image' ); // note array length = 1
return $template;
}
add_filter( 'fpw_widget_templates', 'fpw_set_widget_template' );

fpw_read_more_text

Set the “Read More” phrase in the accessible read more link. (The read more link displays “Read More…” to sighted users but reads in full “Read More about {Page Title}…”

<?php
/**
* modify the "Read More" text in the accessible "Read More" link
*
* example: change it to "Continue Reading"
*
* @param $read_more_text string The "________" in "________ about {Page Title}"
*/
function fpw_change_read_more( $read_more_text ) {
$read_more_text = __( 'Continue Reading', 'your-text-domain' );
return $read_more_text;
}
add_filter( 'fpw_read_more_text', 'fpw_change_read_more' );

fpw_read_more_ellipsis

Change or hide the “…” in the “Read More…” link in Feature a Page Widget 2.0.2

/**
* changes read more link from "Read More…" to "Read More!"
*
* @param string $ellipsis punctionation at end of read more link
*
* @return string new punctuation
*/
add_filter( 'fpw_read_more_ellipsis', 'fpw_change_read_more_ellipsis_to_exclamation' );
function fpw_change_read_more_ellipsis_to_exclamation() {
return '!';
}
/**
* hide ellipsis in "Read More…" link
*/
add_filter( 'fpw_read_more_ellipsis', '__return_null' );

fpw_image_size

Use custom image size for one or more widget image sizes. The widget registers three image sizes by default—one for each layout:

  • fpw_big – 400px-600px, cropped
  • fpw_square – 200px-200px, cropped
  • pw_banner – 400px-150px, cropped
<?php
/**
* replace one of the widget image sizes
*
* examples replaces the banner layout's image with the 'large' size image from Settings > Media
*
* If you replacing $size with a custom image size, you must register that separately with add_image_size()
*
* @param $size string slug of registered image size
* @return string|array slug of registered image size or "array( width, height )" (not recommended)
*/
function fpw_change_image_size( $size ) {
// check if image uses the "banner" layout image size
if( $size === 'fpw_banner' ) {
$size = 'large';
}
return $size;
}
add_filter( 'fpw_image_size', 'fpw_change_image_size' );

fpw_auto_excerpt

By default, the widget only displays text explicitly set in the “Excerpt” field of the featured Page/Post. Use the following snippet below to use a truncated version of the body content as the excerpt.

<?php
/**
* Set fpw_auto_excerpt to TRUE to allow auto-generated excerpts if the Excerpt field is blank
*
* Uses the_excerpt() and associated filters.
*/
add_filter( 'fpw_auto_excerpt', '__return_true' );

Feature a Page Widget 1.0 Filters

fpw_page_title

Filter the page title’s text. (Text only, does not include HTML heading tags.)

fpw_excerpt

Filter the content of the page’s excerpt text.

fpw_featured_image

Filter the HTML output for the featured image.

Template Overrides

If you haven’t already, see the note at the top of the page about Version 1.0 Template Override Compatibility.

Feature a Page Widget 2.0 comes with three individual template files, one for each layout. You can override, one, two, or all three layout files depending on your needs. You can also remove default layout options or add custom layouts with the fpw_widget_templates filter (see above).

  1. Create a new /fpw2_views/ folder in the active theme’s folder.
  2. From /wp-content/plugins/feature-a-page-widget/fpw2_views/ copy only the layout files you want to override into the folder you created in Step 1.
  3. Modify the template file as much as you like. For best results:
    • The template is run inside a post loop so all template tags should work.
    • See if you can do what you want with CSS (see starter styles in /css/fpw_starter_styles.css) or filters first. Template overrides are best for changing the widgets markup (e.g. heading level of page title tag or order of image/title/excerpt in source). Make sure to save your styles to a child theme or external CSS file that won’t be overwritten when the plugin is updated.
    • Try adding classes rather than removing or replacing classes in the widget unless you really know what you’re doing :)
    • You can find useful CSS selectors and comments in /wp-content/plugins/feature-a-page-widget/css/fpw_starter_styles.css. Copy and paste these styles somewhere safe. Do not modify this file.

If you need plugin support, you can post to the free plugin support forum on WordPress.org.

2 thoughts on “Feature a Page Widget 2.0 Documentation”

  1. Hi, I really like the plugin. However, it currently breaks “Custom Sidebars” Plugin by WPMU DEV (https://wordpress.org/plugins/custom-sidebars/). Reproduce like this:
    – Activate “Feature a Page Widget” plugin
    – Activate “Custom Sidebars” plugin
    – Go to “Design->Widgets” and click “New Sidebar”
    – Spinner will spin like forever

    Deactivating your plugIn resolves the issue for me.

Comments are closed.