Modules and Events

Create your own module to extend or customize YOOtheme Pro.

YOOtheme Pro uses Modules to set up its application code. The code is structured into many single modules. This modular architecture helps to keep our code base clean and tidy. In a child theme, you can also use your own custom module to extend or modify YOOtheme Pro’s functionality.

The module definition is used to provide bootstrapping, routing and other configuration options. Here you can listen for events, add custom classes and your own controllers.


Using Plugins

Plugins are a very good way to package and distribute your code and share it with your fellow YOOtheme Pro users. Take a look at the extensions page to see what is available from our developer community.

Joomla provides a developer guide which explains the basics of creating a plugin. Apart from listening to Joomla events you are also able to extend or modify YOOtheme Pro’s functionality. You would need to create a system plugin and use the onAfterInitialise event to bootstrap your modules or register events.

<?php

defined('_JEXEC') or die;

use Joomla\CMS\Plugin\CMSPlugin;
use YOOtheme\Application;

class plgSystemMyPlugin extends CMSPlugin
{
    public function onAfterInitialise()
    {
        // check if YOOtheme Pro is loaded
        if (!class_exists(Application::class, false)) {
            return;
        }

        // load your classes directly or with composer
        require __DIR__ . '/src/MyListener.php';
        require __DIR__ . '/vendor/autoload.php';

        // bootstrap modules
        $app = Application::getInstance();
        $app->load(__DIR__ . '/modules/*/bootstrap.php');
   }
}

Adding Modules

Simply create a file called bootstrap.php in your module folder and make sure it returns a PHP array. Here you can register your own classes with functions that listen to the events.

<?php

return [

    'theme' => [
        // Set default theme config values
    ],

    // Listen to any events triggered by YOOtheme Pro and handle them in your own listener
    'events' => [

        'theme.head' => [
            // Before the head is rendered (site view)
            MyListener::class => 'initHead',
        ],

        'theme.init' => [
            // Before theme is rendered (site view)
            MyListener::class => ['initTheme', 10],
        ],

        'customizer.init' => [
            // Before customizer is rendered (admin view)
            MyListener::class => ['initCustomizer', -10],
        ],

    ],

];

Asset Files

To add custom asset files, listen for the theme.head event in your module bootstrap.php. In your listener class you can then use the YOOtheme\Metadata service to add custom assets to the head:

<?php

use YOOtheme\Metadata;

class MyListener
{
    function initHead(Metadata $metadata)
    {
        // style file
        $metadata->set('style:my-css', ['href' => 'assets/css/custom.css']);

        // inline style
        $metadata->set('style:my-inline-css', 'body {color: blue}');

        // script file
        $metadata->set('script:my-js', ['src' => 'assets/js/custom.js', 'defer' => true]);

        // inline script
        $metadata->set('script:my-inline-js', 'var custom = 123;');
    }
}

Note By prefixing metadata style: and script: you can add CSS and JS to the HTML document . After the : choose a unique identifier for your document metadata.


Theme Configuration

The configuration may be modified and extended by using the module bootstrap.php. To modify the default theme configuration you can either use a simple array or a callback function.

<?php

return [

    // using an array
    'theme' => [
        'defaults' => [
            'lazyload' => false
        ],
    ],

    // using a callback and return an array
    'theme' => function ($config, $app) {

        // dynamic config code ...

        return [];
    },

];

The example above will change the theme default value for the lazyload option to false.

It is also possible to access and change the theme configuration after your local theme settings are merged. Listen to the theme.init event and handle it in your own function and use the YOOtheme\Config service to modify the ~theme configuration values.

<?php

use YOOtheme\Config;

class MyListener
{
    function initTheme(Config $config)
    {
        // Gets the theme config
        $config->get('~theme.lazyload');

        // Sets the theme config
        $config->set('~theme.lazyload', 'foo');
    }
}

Customizer Configuration

The customizer has its own init event customizer.init which you can listen on in the bootstrap.php. The customizer config is loaded using the YOOtheme\Config service. The configuration values can be loaded from config/customizer.json files. For example vendor/yootheme/theme/config/customizer.json You can access its values through the customizer namespace and get/set a value from a deeply nested array using "dot" notation.

<?php

use YOOtheme\Config;

class MyListener
{
    function initCustomizer(Config $config)
    {
        // Gets the registered panels for the customizer
        $config->get('customizer.panels');

        // Adds a new panel called "My Panel" to the customizer
        $config->set('customizer.panels.my-panel', [
            'title'  => 'My Panel',
            'width'  => 400,
            'fields' => [
                'my-field' => [
                    'label' => 'My Field',
                    'description' => 'My Field\'s Description.',
                ],
            ],
        ]);

        // Adds the panel to the menu in the "settings" section
        $config->set('customizer.sections.settings.fields.settings.items.my-panel', 'My Panel');
    }
}

The example above will add a panel my-panel to the settings panel of the customizer.

YOOtheme Pro Documentation