Contents

Installation

Free Version

  1. Download the widget-display-options.zip file from the WordPress Plugin Repository
  2. Extract the zip file so that you have a folder called “widget-display-options”
  3. Upload the “widget-display-options” folder to the /wp-content/plugins/ directory
  4. Activate the plugin through the Plugins menu in WordPress
  5. Configure your settings in the Settings > Widget Display Options panel
  6. Visit the widgets page under Appearance > Widgets and you should find the extra input fields at the bottom of any active widgets.

Pro Version

  1. After purchase you will receive a link to download the widget-display-options-pro.zip file
  2. Extract the zip file so that you have a folder called “widget-display-options-pro”
  3. Upload the “widget-display-options-pro” folder to the /wp-content/plugins/ directory
  4. Activate the plugin through the Plugins menu in WordPress
  5. Configure your settings in the Settings > Widget Display Options panel
  6. Visit the widgets page under Appearance > Widgets and you should find the extra input fields at the bottom of any active widgets.

Upgrading to Pro

Upgrading to Widget Display Options Pro from Widget Display Options couldn’t be easier. Just follow the Pro Installation instructions above. If you have the Lite version installed it will automatically be deactivated and the Pro version will start using the settings and widget options set with the Lite version. You can go ahead and delete the Lite version from your Plugins page if you wish.

Settings

Once you’ve successfully installed the plugin you will have a link to the Settings page under Settings > Widget Display Options in the main admin menu. Visit this page to set up your installation options.

Inline Help

Because we know that working with conditional logic can be a bit confusing we’ve include some inline help options to get information directly in the display options interface.

  • Link: Link help buttons to external manual.
    This is the default help setting. It adds buttons to the interface (shaped like question marks) that, when clicked, will open a new tab/window to the relevant section of this manual relating to the section or conditional you want information on.
  • Tooltips: Display help as inline tooltips.
    This will add the same question mark links as Link, but instead of linking to the manual they will provide relevant data on hover. This is off by default because, due to the asynchronous nature of the WordPress widget interface, the extra javascript this generates can cause the interface to slow down or even crash on sites that use a lot of widgets (particularly if you are using older versions of Internet Explorer, heaven help you). If you don’t run a lot of widgets (less than 10-ish) you may want to try using this feature as it can make learning the conditionals a lot easier. Just be sure to turn it off if your widgets.php page starts loading very slow.
  • None: Do not display inline help at all.

Hide from Print Pro Version Only

Use this setting to allow widgets to be hidden from printers. Many themes, such as Twenty Twelve, already hide the widget areas from printers, so disabling this feature in those cases will remove the option from the interface thereby simplifying it a bit.

Note: Setting this option will not in itself hide the widgets from print view. Instead, it makes the option available to be applied on a widget by widget basis.

mobble Integration Pro Version Only

The mobble plugin is an excellent tool for detecting device sets (such as handheld and tablet) as well as specific devices (such as iPhone and Nintendo). If you have mobble installed, setting this option will allow the custom conditionals it provides to be used from within the Widget Display Options interface. Visit the mobble website for more information.

Usage

Adding Classes

In addition to conditional displays, the Widget Display Options plugin allows you to add classnames to the widgets output wrapper to facilitate CSS and Javascript targeting of specific widgets (the tags which are used to wrap the widget are determined by your theme).

For example, the Twenty Twelve theme wraps each widget in an ASIDE tag. Adding a class “my-widget” via the display options input field would, in this case, allow you to target that widgets ASIDE wrapper via css using “.my-widget”.

Hide from Print Pro Version Only

Checking the Hide from Print field will cause the widget to be hidden when a page is printed. Widget Display Options accomplishes this functionality by embedding print media queries into wp_head(), as opposed to the conditionals which suppress the html output altogether. Please note that Hide from Print is not effected by the conditionals, if checked it will be applied on all pages.

Conditional Display

Checking the Conditional Display field will expand the conditional logic settings and the list of conditionals (grouped by category). By default the Common conditionals will be expanded and the rest will be collapsed. To expand a category and access its conditionals, click the “+” symbol or the category title. Once you’ve saved the widget any categories that have conditionals applied will be expanded and the title will be bolded.

Conditional Logic

The conditional logic section is at the top of the conditionals list in blue. This section allows you to determine if the widget should be hidden or shown when the conditions are met. Its settings are applied to all active conditionals.

Hide/Show

By default the widgets are hidden only if the conditions are met, but you can change the select box at the beginning of the sentence to Show to reverse the logic. The effect of choosing Show is that the widget will never be displayed unless the conditions are met. If you are using the free version from the WordPress Repository the conditions will considered met if ANY of the selected conditionals return true.

Any/All Pro Version Only

If you are using the Pro Version you will be able to choose if the Hide/Show logic is applied when ANY of the conditions are met, or when ALL of the conditions are met. By default the conditions will return true if any of them are met (logical OR). If you change the select box in the middle of the conditional logic area to ALL the conditions will only return true if all of them are met (logical AND).

Using Conditionals

At their heart, the Widget Display Options conditionals are simply boolean functions that return true if their associated conditions are met, and false otherwise. Many of them use built in WordPress functions such as is_front_page() and is_archive() and behave exactly as described in the WordPress Codex.

Activating a condition is achieved by checking the box next to the conditions name and then saving the widget.

Note: When Widget Display Options is installed the fields added in the Display Options section become part of each widgets options, therefore the widget MUST BE SAVED in order for any of its features to be applied.

For example, let’s say you want to display a list of blog categories in the sidebar only on the primary blog archive.

  1. First, drag the Categories widget into the sidebar.
  2. Next, find the Display Options area and check the box next to Conditional Display. This will expand the conditional logic options and the list of conditionals.
  3. Now, change the select box that says Hide to Show in the conditional logic area (the section with the blue background).
  4. Below, under the heading Common, you will see a conditional labeled Blog Index. Check the box to the left of it.
  5. Finally, press the blue Save button at the very bottom of this widgets options.

What we have done is told the widget to only display itself on the Blog Index pages of the site. On any other page it will be as if the widget doesn’t exist. This conditional uses the is_home() function built in to WordPress.

Adding Parameters

Many of the conditionals accept parameters to further refine your logic. If a conditional accepts parameters a text field will appear when the condition is selected.

Some parameters are optional, some accept multiple values (comma separated), and some require that a parameter is entered. A brief explanation is provided in each parameter field placeholder and more detailed information is provided via the inline help tools or the Conditionals List in this manual.

Note: If a parameter is required and you don’t provide one no errors will be generated. The condition will simply never return true.

We can expand on the Categories example above by using parameters to further refine our conditions. Let’s say we not only want to show the Category list on the Blog Index, but also on any single blog posts.

  1. Go to the Display Options area of the Category widget that was set up in the previous section.
  2. If you are using the Pro Version make sure the Any/All select box in the conditional logic area is set to Any.
  3. Go to the conditional list and find a conditional labeled Singular Post Type.
  4. Check the box to the left of the label and the parameter text field will appear.
  5. Enter the text “post” into the parameter field and save the widget.

This will tell the widget to display itself on any page that is considered singular and has a post type of “post” (which is the post type for blog articles) .

The Singular Post Type parameter field accepts a post type, a comma separated list of post types, or can be left blank to return true on any page that is displaying a single piece of content (as opposed to a list or an archive page).

Parameter Helpers Pro Version Only

If you’re using the Pro Version you will see a button labeled “+” the right of each parameter field. Clicking this button will open a popup that loads a list of possible parameter values relating to the conditional it is associated with.

For example, clicking the “+” button next to the Singular Post Type parameter field will load a select box populated with possible post types. The generated list will not only include the built in types “Pages” and “Posts”, but any custom post types generated by your theme or plugins. Selecting a post type and clicking the blue Insert button will add the post type slug to the parameter field. In this case, because Singular Post Type accepts multiple parameters, you can open it again and select another post type to be added to the list.

If the associated conditional does not accept multiple parameters inserting a new one will simply replace the contents of the parameter field with the new value.

The “!” (not) Field Pro Version Only

If you’re using the Pro Version you will see a checkbox labeled with a “!” to the right of each active conditional. This is the NOT option which allows you to reverse the natural output of each conditional so that if it returns true it is changed to false and if it returns false it is changed to true. This option is generally only useful when more than one conditional is active.

For example, let’s say you want to show a widget only to logged in users but NOT if they are subscribers. You use can the Show logic with All selected (to ensure ALL conditions are met) and the Logged In conditional under Permissions activated, but this will show the widget to anyone who is logged in, regardless of their user role.

To further refine your logic activate the Role conditional, add the text “subscriber” to its parameter field and check the “!” box to reverse it. This will tell the widget to “Only SHOW if the current user is logged in AND they are NOT a subscriber”.

The Not field is usually unnecessary if you’re only using one conditional, as in that case the logic can be reversed by simply toggling the Hide/Show field under conditional logic.

Hiding the Interface

Because the Widget Display Options can potentially add a lot of space to each widget we’ve included a hide feature which allows you to collapse the interface into a single button that can be opened only when you need it. The hide function does not affect any of the selected options, so you can safely collapse the interface at any time without losing your settings (as long as you save the widget settings).

To hide the interface, click the small “hide” link at the top right of the display options area, to the right of the “Display Options” heading.

The interface will retain it’s opened/closed state when you save the widget, so if it’s closed when you hit save it will remain closed until you open it again, and visa versa.

Conditionals List

Common

Front Page

Checks if the current page being displayed is the Main Page (or Home Page) of the site.

More Info: is_front_page

Blog Index

Checks if the current page being displayed is the Blog Posts Index Page.

More Info: is_home

Page

Checks if the current page being displayed is a singular Page (has a post type of “page”).

Accepts: Page ID, Page Title or Page Slug (optional, comma separated)

More Info: is_page

Single

Checks if the current page being displayed is singular (as opposed to an Archive).

Accepts: Post ID, Post Title or Post Slug (optional, comma separated)

More Info: is_single

Singular Post Type

Checks if the current page being displayed is singular and has a given Post Type(s). If left blank this will return true for any post type if the content is singular.

Accepts: Post Type (optional, comma separated)

More Info: is_singular

Post Type

Checks if the current page being displayed has a given Post Type(s). Works for archives or singular views. If left blank this will always return false!

Accepts: Post Type (required, comma separated)

Search Results

Checks if the current page being displayed is a Search Results page.

More Info: is_search

Page Template

Checks if the current page being displayed uses a given Page Template. If left blank this will return true if the page uses any Page Template.

Accepts: Full template filename with ext (optional)

More Info: is_page_template

Sticky Post

Checks if the current page being displayed is a Sticky Post.

Accepts: The post ID (optional)

More Info: is_sticky

Attachment

Checks if the current page being displayed is an Attachment.

More Info: is_attachment

404

Checks if a 404 error is being displayed.

More Info: is_404

Archive

Archive (common)

Checks if the current page being displayed is a common Archive (Category, Tag, Author or Date).

More Info: is_archive

Date Archive

Checks if the current page being displayed is a Date Archive.

More Info: is_date

Tag Archive

Checks if the current page being displayed is a Tag Archive. If left blank this will return true for any Tag Archive.

Accepts: Tag slug (optional, comma separated)

More Info: is_tag

Category Archive

Checks if the current page being displayed is a Category Archive. If left blank this will return true for any Category Archive.

Accepts: Category ID, Category Title, Category Slug (optional, comma separated)

More Info: is_category

Taxonomy Archive

Checks if the current page being displayed is a Taxonomy Archive. If left blank this will return true for any Taxonomy Archive except Category and Tag archives.

Accepts: Taxonomy slug or slugs (optional, comma separated)

More Info: is_tax

Post Type Archive

Checks if the current page being displayed is an Archive of a given Post Type(s). If left blank this will return true for any Post Type Archive.

Accepts: Post Type (optional, comma separated)

More Info: is_post_type_archive

Author Archive

Checks if the current page being displayed is an Author Archive. If left blank this will return true for any Author Archive.

Accepts: Author ID or Author Nickname (optional)

More Info: is_author

Hierarchical

Hierarchical Pro Version Only

Checks if the current page being displayed is singular and has a hierarchical post type.

Has Children Pro Version Only

Checks if the current page being displayed has any children.

Ancestor Pro Version Only

Checks if the current page being displayed is an ancestor of another page (or any hierarchical post type). If left blank this will always return false!

Accepts: Post ID, Post Title or Post Slug (required, comma separated)

Child Of Pro Version Only

Checks if the current page being displayed is a child of another page (or any hierarchical post type). If left blank this will always return false!

Accepts: Post ID, Post Title or Post Slug (required, comma separated)

Permissions

Logged In Pro Version Only

Checks if the current visitor is logged in.

More Info: is_user_logged_in

Has Capability Pro Version Only

Checks if the current visitor has a given Capability. If left blank this will always return false!

Accepts: Capability (required)

More Info: current_user_can

Has Role Pro Version Only

Checks if the current visitor has a given Role. If left blank this will always return false!

Accepts: Role(s) (required, comma separated)

mobble

Handheld Pro Version Only

Checks if the current visitor is using any handheld device (phone, tablet, Nintendo). This conditional requires the mobble plugin.

More Info: is_handheld

Mobile Pro Version Only

Checks if the current visitor is any type of mobile phone (iPhone, Android, etc). This conditional requires the mobble plugin.

More Info: is_mobile

Tablet Pro Version Only

Checks if the current visitor is using any tablet device (currently iPad, Galaxy Tab). This conditional requires the mobble plugin.

More Info: is_tablet

iOS Pro Version Only

Checks if the current visitor is using any Apple device (iPhone, iPad, iPod). This conditional requires the mobble plugin.

More Info: is_ios

iPhone Pro Version Only

Checks if the current visitor is using an iPhone. This conditional requires the mobble plugin.

More Info: is_iphone

iPad Pro Version Only

Checks if the current visitor is using an iPad. This conditional requires the mobble plugin.

More Info: is_ipad

iPod Pro Version Only

Checks if the current visitor is using an iPod. This conditional requires the mobble plugin.

More Info: is_ipod

Android Pro Version Only

Checks if the current visitor is using an Android device. This conditional requires the mobble plugin.

More Info: is_android

Blackberry Pro Version Only

Checks if the current visitor is using a Blackberry. This conditional requires the mobble plugin.

More Info: is_blackberry

Opera Mobile Pro Version Only

Checks if the current visitor is using Opera Mobile. This conditional requires the mobble plugin.

More Info: is_opera_mobile

Palm Pro Version Only

Checks if the current visitor is using a Palm device. This conditional requires the mobble plugin.

More Info: is_palm

Symbian Pro Version Only

Checks if the current visitor is using a Symbian device. This conditional requires the mobble plugin.

More Info: is_symbian

Windows Mobile Pro Version Only

Checks if the current visitor is using Windows Mobile. This conditional requires the mobble plugin.

More Info: is_windows_mobile

Motorola Pro Version Only

Checks if the current visitor is using a Motorola device. This conditional requires the mobble plugin.

More Info: is_motorola

Samsung Pro Version Only

Checks if the current visitor is using a Samsung device. This conditional requires the mobble plugin.

More Info: is_samsung

Samsung Tablet Pro Version Only

Checks if the current visitor is using a Samsung Tablet. This conditional requires the mobble plugin.

More Info: is_samsung_tablet

Sony Ericsson Pro Version Only

Checks if the current visitor is using a Sony Ericsson device. This conditional requires the mobble plugin.

More Info: is_sony_ericsson

Nintendo Pro Version Only

Checks if the current visitor is using a Nintendo. This conditional requires the mobble plugin.

More Info: is_nintendo


Don’t Have Pro? Get It Here:

Price: $15