Widget Positions

Learn how to create new positions, layouts and styles for WordPress widgets.

Adding a new position for widgets to your theme is fairly straightforward. You have to name a position and define where the position gets rendered within the theme layout.

Add a New Position

Add a new position to the theme.xml to make your content management system know it exists. The new option will then be displayed in your theme settings.

<position>top-a</position>
<position>MY-POSITION</position>
<position>bottom-a</position>

Add Settings

With the settings attribute you can control the options for the widget appearance of your position. You will find these in the Widgets panel of your theme settings. Available values are class, style, icon, badge and display, title and assignment.

<!-- all option are available -->
<position>MY-POSITION</position>

<!-- no option are available -->
<position settings="">MY-POSITION</position>

<!-- only the style and badge options are available -->
<position settings="style badge">MY-POSITION</position>

Note If no settings attribute is given, your position automatically shows all available options. If you use the settings attribute without adding a value, it won't be displayed in the Widgets panel at all.

Get more information about settings in the Widget Manager chapter.

Theme Settings for Positions

Edit the config.xml to add further position options in the theme settings to the Settings and Layouts panels.

Set Default widget Rendering for Your Position

Add a new <row> element to the table field panel_default in the Settings section in order for your position to have the option to choose a default style.

<fields name="Settings">
    ...
    <field type="table" name="panel_default">
        <rows label="Position">
            <row>MY-POSITION</row>
            ...

Set Default Layout Rendering for Your Position

Add a new <row> element to the table field grid in the Layouts section in order for your position to have options to set a layout, the responsive behavior and a divider.

<fields name="Layouts">
    ...
    <field type="table" name="grid">
        <rows label="Position">
            <row>MY-POSITION</row>
            ...

Take a look at the Config.xml chapter for more information about it.

Render Position

The /layouts/theme.php provides the basic markup of the theme. Here you can define where widget positions get rendered and add new ones.

<?php if ($this['widgets']->count('MY-POSITION')):?>
    <section class="uk-grid" data-uk-grid-match="{target:'> div > .uk-panel'}">
        <?php echo $this['widgets']->render('MY-POSITION', array('layout'=>$this['config']->get(
        'grid.MY-POSITION.layout'))); ?>
    </section>
<?php endif;?>

Note You only need to add the $this['config']->get('grid.MY-POSITION.layout') syntax, if you have declared an option in the config.xml.

Take a look at Theme Layout for a better understanding of the widget render methods.

Advanced Way to Add CSS Classes

If your position is declared as a new <row> in the table field grid of the config.xml, we provide an easy way to add the CSS classes. Just add the <?php echo $grid_classes['MY-POSITION']; ?> to your class attribute. This will give your position the options to set a layout, the responsive behavior and a divider.

<?php if ($this['widgets']->count('MY-POSITION')) : ?>
    <section class="<?php echo $grid_classes['MY-POSITION']; ?>" data-uk-grid-match="{target:'> div > .uk-panel'}"
    data-uk-grid-margin><?php echo $this['widgets']->render('MY-POSITION', array('layout'=>
    $this['config']->get('grid.MY-POSITION.layout'))); ?></section>
<?php endif; ?>