Hooks/Filter Reference/builder get available views

From IThemes Codex
Revision as of 17:14, November 3, 2010 by Gaarai (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents

Description

This filter hook is called in the Builder core when deciding which layout should be used. It passes in a formatted array that associates a test function with a name, description, and a priority.

Three example uses of this filter are contained in the lib/layout-engine/available-views.php file. In this file are the builder_set_available_views, builder_add_blog_view, and builder_add_custom_post_types functions which add the default starting set of views, a "Blog" view when a static page is used for the front page of the site, and a view for any available custom post types, respectively.

An example entry found in the array is as follows:

'is_single' => array(
    'name'        => 'Post',
    'priority'    => '10',
    'description' => 'Any post',
)

"is_single" is a valid function name. This function will be tested to check for a view match. The name and description are simply used to clarify the purpose for the user when selecting a view in the theme's View settings. The priority is crucial as multiple available views may be matched (for example, a view can simultaneously match a specific category, Category, and Archives). A higher priority means that a specific view takes precedence and will be used in preference to lower priority matches. The lowest priority used in Builder is 5 and the highest is 20. The used priorities go up in multiples of 5. For details about the specific priorities used for different views, please see the lib/layout-engine-available-views.php file.

The layout selection logic is as follows:

  • Check to see if the current view is singular (Post, Page, etc).
    • If the view is singular, check to see if a custom layout has been selected for the content being viewed.
      • If a custom layout is in use, set that layout as the active one.
  • If the layout has not been set or if the selected layout does not exist, check the available views returned by the builder_get_available_views filter (the filter discussed here) for a view match.
    • Set a priority tracker variable that has a starting value of 0. This variable will be referred to in the following steps as "Max Priority".
    • Loop through all the available views. For the following steps, the current available view being checked in the loop will be referred to as the "Testing View".
      • Run the Testing View's function. If the function returns a true value, the Testing View's priority is greater than Max Priority, and a layout has been registered for the Testing View in the theme's View settings, set the Testing View's registered layout as the active one and set Max Priority to the Testing View's priority.
  • If the current view is a category, tag, author, or custom post type and a layout has been registered for the specific view in the theme's View settings, set the specific view's layout as the active one.
  • Run the builder_filter_current_layout filter to allow code to force an override of the current layout.
  • If a valid layout was not found, use the default layout.


Possible Uses

Using this filter gives developers access to add any needed custom views. From views that match posts that use a specific category to requests that have specific query variables set, the possibilities are limited only by creative use and developer ability.


Parameters

$views
(array) (required) Current set of available views.
Default: Far too long to list. Here is an example portion:
array(
    'builder_is_home'     => array(
        'name'        => 'Home',
        'priority'    => '20',
        'description' => 'The front page or home of your site',
    ),  
    'builder_is_singular' => array(
        'name'        => 'Singular',
        'priority'    => '5',
        'description' => 'Any post, page, or attachment',
    ),  
    'is_single'           => array(
        'name'        => 'Post',
        'priority'    => '10',
        'description' => 'Any post',
    ),
);


Return Value

The returned value should be a complete, valid array of available views to be checked. Note that it is best to merge the new views to the existing views before returning the modifications as shown in the examples below.

$views
(array) (required) Modified available views.
Default: None


Examples

The following could be added to a child theme's functions.php file to add custom views for the Uncategorized and News categories:

function custom_post_is_in_category( $category_name ) {
    if ( ! is_single() )
        return false;

    $categories = get_the_category();

    foreach ( (array) $categories as $category ) {
        if ( $category_name === $category->name )
            return true;
    }
}

function custom_is_category_uncategorized() {
    return custom_post_is_in_category( 'Uncategorized' );
}

function custom_is_category_news() {
    return custom_post_is_in_category( 'News' );
}

function custom_builder_add_new_views( $views ) {
    $new_views = array(
        'custom_is_category_uncategorized' => array(
            'name'          => 'Post in Uncategorized',
            'priority'      => '20',
            'description'   => 'Any individual post view in the Uncategorized category',
        ),
        'custom_is_category_news'         => array(
            'name'          => 'Post in News',
            'priority'      => '21',
            'description'   => 'Any individual post view in the News category',
        ),
    );

    return array_merge( $views, $new_views );
}
add_filter( 'builder_get_available_views', 'custom_builder_add_new_views' );

There are a number of points of interest in this code sample:

  • Since a simple "is this a post in a specific category" function, one had to be created.
  • The priority for News is higher than the priority for Uncategorized. This is because a post can belong to more than category. If a post belongs to both News and Uncategorized, then the layout selected for the "Post in News" view will be used. This still allows a post that is in both News and Uncategorized to use the "Post in Uncategorized" layout if one has not been set for the "Post in News" view.
  • Rather than creating a new $views array and returning it, the new available views are added to a $new_views variable and then the array_merge function is used to merge both arrays. This preserves the existing views.

Back to Builder Hooks

Personal tools
Namespaces
Variants
Actions
iThemes Codex
Codex Navigation
Toolbox