Widgets/Modules

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

Adding a new position for modules or 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 templateDetails.xml for Joomla or the theme.xml for WordPress 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 Modules/Widgets panel of your theme settings. Available values are class, style, icon, badge and display. Additionally, title and assignment are available in WordPress.

<!-- 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 Modules or Widgets panel at all.

Get more information about settings in the Widget/Module Settings 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

By adding a new <row> element to the table field panel_default in the Settings section your position will 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

By adding a new <row> element to the table field grid in the Layouts section your position will 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 a 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; ?>

Documentation on Github

Help us out! If you are feeling that our documentation has errors or can be improved, fork it at Github and send us a pull request. Any contribution is much appreciated. Thank you!