Although the main meat of any page will be in the main content area, it’s often the page extras in other areas – the photos, category listings, blog excerpts, graphic links and widgets of one sort or another – that add visual interest to the page. A set of Wingfinger Widgets allows you to insert page extras in these other editable regions of the page.

This is the technical reference page for our widgets, giving the information you need to be able to deploy them on site pages. If this all looks a bit daunting, see Using posts as page extras for a gentler introduction to the subject.

Please note that although most of the widgets can be inserted in various regions of the page, they will sometimes need additional styling by Wingfinger in order for them to look their best. Similarly, changing some of the parameters may also necessitate further styling work. Our cheaper web packages usually include widget styles for just one or two page regions and a more limited range of parameter options.

Wingfinger Widgets are all controlled in the same way, using the Custom Fields area below the main Editing panel. (If this is not visible, you may need to turn it on in the Screen Options panel just below the Admin Bar.)

Custom Fields

To insert a widget anywhere other than the main editable text area of a page, the standard method is to create a Custom Field with the appropriate name (eg: left-1-post) and enter the required parameters as a set of name-value pairs, such as…

ids = 205
show_title = true
style = basic

The order of the pairs doesn’t matter, and the system is fairly tolerant of additional spaces. The main thing to note is that each name-value pair should be on a new line. For each widget, details of the parameters are listed on a separate page.

The first bit of the Custom Field name (left) specifies whereabouts on the page the widget should be inserted (one of several predefined regions). The second bit (the number) is used to specify the order in which the widgets appear in that particular page region (lowest numbers first). The last bit (post) specifies the type of widget to insert.

Shortcodes

To insert a post or widget into the main content area (if the particular widget allows for this), instead of a custom field you use a shortcode. The format is very similar to the custom field version, but this time the whole thing is on one line and enclosed in square brackets (which I can’t show here without WordPress executing the shortcode!)…

shortcode_post ids=205 show_title=true style=loud

This time you’ll probably find the code easier to read if you remove the spaces around the = sign.

Warning: One thing that shortcodes can’t cope with is a value string containing spaces. So if you try to specify something like…

heading=Latest news – this won’t work.

Instead, you need to replace all the spaces with underscores…

heading=Latest_news – and this will work.

Page regions

All Wingfinger’s WordPress sites are set up so that each page has a number of pre-defined regions where page extras can be added. Some pages – particularly the Home page – may have additional areas defined. And most of our widgets can also be used within the main content area, using the shortcode system outlined above.

Whenever a post, listing or widget is added to a page, the relevant region always forms the first part of the custom field name. So, to add a vertical scroller widget to the left column, you would use a custom field name of left-0-vscroller. Similarly, to add a graphic after the scroller in the left column, you would use a custom field name of left-1-post (because WordPress regards media items like photos and graphics as just another sort of post).

To swap the positions of these two page extras, you would change the custom field names to left-1-vscroller and left-0-post. And as soon as you press the Update button, WordPress also helpfully rearranges the custom fields in alphabetical order, which will reflect the order in which the items appear on the page (within any given region).

Inheritance – how sub-pages are handled

By default, any widgets you specify for a page region outside the main content area will also appear on all descendant sub-pages, unless you interrupt this inheritance behaviour for a particular sub-page (and all its own descendants). You can do this on the sub-page concerned by:

• specifying another set of widgets for this region (and the new set will then be inherited), or
• specifying any single widget for this region and entering a value of ‘0’ in its custom field (which turns off the inheritance without adding the widget).