Hooks/Filter Reference/builder get modules

From IThemes Codex
Revision as of 05:12, September 2, 2010 by Ronald (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents

Description

This filter hook is created in the Builder core lib/layout-engine/modules.php file. It is passed an empty array and returns an array of all the registered modules.

Possible Uses

This filter gives access to all the class structures of each module. These class structures include the methods used to register sidebars, render the module, and validate module data. In addition, the class instances contain each module's name, internal variable name, and description.

While this filter is of limited value for simple changes, it opens up advanced abilities for large customizations such as the ability to directly render a module that does not exist on the layout with a completely-custom set of data.

The capabilities and information available through this filter is best understood by inspecting the code of the LayoutModule class which is in lib/layout-engine/modules/class.module.php.

Parameters

array()
(array) (required) Empty array.
Default: None

Return Value

$modules
(array) (required) Array of registered modules.
Default: None

Example Use

I created an Extension that shows off the potential of this filter called Floating Navbar. It renders a custom Navigation Module to add a static page navigation in the top-right corner of the site view. The functions.php file of the Extension contains the following code and shows how the filter can be used.

add_action( 'builder_layout_engine_render_container', 'custom_builder_floating_nav', 0 );

function custom_builder_floating_nav( $render_data ) { 
    echo "<div class='floating-navigation builder-module-navigation builder-module-navigation-pages'>\n";
    
    $module_data = array(
        'module'        => 'navigation',
        'data'          => array(
            'type'              => 'pages',
            'remove_wrappers'   => '1',
        ),
    );
    
    $module_data = array_merge( $render_data, $module_data );
    
    $modules = apply_filters( 'builder_get_modules', array() );
    
    if ( isset( $modules['navigation'] ) ) { 
        $modules['navigation']->_can_remove_wrappers = true;
        
        $modules['navigation']->render( $module_data );
        
        $modules['navigation']->_can_remove_wrappers = false;
    }
    
    echo "</div>\n";
}

Using the direct access to the module class instances, I temporarily changed the module's default setting to not permit the removal of the wrappers. This allows for breaking the module content completely out of any layout constraints.

Note the use of the builder_layout_engine_render_container_start action to be able to have a place inside the rendering area to add the content.

Download the extension

To use the extension, unzip the contents and put the floating-navbar directory in your theme's extensions directory. Then add it to a layout in the layout editor.

Notes

With only the default Builder core modules, $modules has the following format:

array(
    'content'     => LayoutModuleContent,
    'footer'      => LayoutModuleFooter,
    'html'        => LayoutModuleHTML,
    'image'       => LayoutModuleImage,
    'navigation'  => LayoutModuleNavigation,
    'widget-bar'  => LayoutModuleWidgetBar,
)

See the LayoutModule class documentation for more details on using modules.


Back to Builder Hooks

Personal tools
Namespaces
Variants
Actions
iThemes Codex
Codex Navigation
Toolbox