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.


Adding Modules

Simply create a file called config.php in your child theme and make sure it returns a PHP array. This array acts as the module definition. Two array keys are required: name and main.

<?php

return [

    // Unique module name
    'name' => 'yootheme/child',

    // Bootstrap code, executed when module is loaded
    'main' => function() {

        // Executed when child theme is active

    },

    // Listen to any events triggered by YOOtheme Pro
    'events' => [

        'theme.site' => function ($theme) {

            // Before theme is rendered (regular site view)

        },

        'theme.admin' => function ($theme) {

            // Before customizer is rendered (admin view)

        },

        'view' => function () {

            // Before a layout is rendered (always)

        }

    ],

];

Asset Files

To add custom asset files in your child theme, listen for the theme.site event in your custom module definition. Use the add function of the Asset Managers for styles and scripts to add your files on each frontend site view. The first parameter is a unique identifier for the asset. The second parameter is the path of the script

'theme.site' => function ($theme) {

    $this->app['styles']->add('my-identifier', 'assets/css/custom.css');
    $this->app['scripts']->add('my-identifier', 'assets/js/custom.js');

}

Note Internally, styles and scripts each work with their own Asset Manager. As these are separate from each other, you can assign the same name to a CSS and JS file without conflict (both called my-identifier in the above example). However, no two scripts or stylesheets may have the same identifier.


Theme Settings

Each module in YOOtheme Pro brings its own configuration. Those configurations may be modified and extended during the application bootstrap.

Retrieve a module

All modules are handled by the Module Manager and any module can be retrieved by its name.

  'theme.init' => function ($theme) {

     $module = $this->app['modules']->get('yootheme/settings');

 }

Read config

To read the config of a module, you can access the config property of the module instance. This object is the result of both the default config stored inside the index.php and the module’s corresponding config file in /config/MODULE_NAME.php.

  'theme.init' => function ($theme) {

     $config = $this->app['modules']->get('yootheme/settings')->config;

 }

Modify config

To modify a module config, you'll have to read the config as shown above and then set or merge new values into it.

 'theme.init' => function ($theme) {

        $this->app['modules']->get('yootheme/settings')->config->merge([

            // Define the panel
            'panels' => [
                'my-panel' => [
                    'title'  => 'My Panel',
                    'width'  => 400,
                    'fields' => [
                        'my-field' => [
                            'label' => 'My Field',
                            'description' => 'My Field\'s Description.',
                        ],
                    ],
                ],
            ],

            // Add the panel to the menu
            'fields' => [
                'settings' => [
                    'items' => [
                        'my-panel' => 'My Panel',
                    ],
                ],

            ],

        ], true);

 }

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

YOOtheme Pro’s config values can be accessed through the theme module yootheme/theme, which is also passed as the first parameter to the the theme events. Here you can read or modify values directly.

 'theme.init' => function ($theme) {

       // Read a config value.
       $myConfigValue = $theme->get('my-config-value');

       // Set a config value.
       $theme->set('my-config-value', 'foo');

 }

YOOtheme Pro