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!

What’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.

https://gist.github.com/cb48eb0700aebc45c273

fpw_widget_templates

Remove, add, or set single widget template.

https://gist.github.com/fd2adace8679b6bfa711

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}…”

https://gist.github.com/b1001f45e94b3c604791

fpw_read_more_ellipsis

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

https://gist.github.com/mrwweb/00e24b9e8e0fe2b9bc43

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

https://gist.github.com/56edda993e0b7062c7af

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.

https://gist.github.com/bebf4cbdcf50d4eadd46

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.