Creating a theme (changing the design)

What is a theme?

A theme refers to the ability to perform a complete reload or substitution of website template without modifying the code of the project's template files. Within a theme, you can replace existing php templates, js/css/image files, and also create new ones.

Let's consider the process of working with a theme using an example theme called example.

To create a theme skeleton, you need to:

• Log in to the control panel.
• Go to developer mode (located in the upper right user menu).
• Go to the "Add-Ons/Themes" section and click on the "Create Theme" link in the upper right corner.
• Indicate whether you want to use one of the existing themes as a base (override) or create a new theme.
• Specify the name of your new theme, for example, "My Theme".
• Specify the name of the theme in Latin characters, for example, "example" (valid characters are a-z, 0-9, _).
• Click on "Create".
• The system will create the theme directory /themes/example/ and the index.php file in it.
• The created theme will be displayed in the control panel in the "Add-Ons/Themes" section.

Activating a theme

Each theme needs to be activated in order for it to work in the project.

• Only one theme can be active at a time.
• The first action available for a theme is installation, during which all necessary preliminary actions defined by the theme will be performed: copying of static files, possible changes to the database structure (running migrations), and other actions.
• If the installation is successful, the theme can be activated, and it will start working in the project.
• If necessary, the theme can also be deactivated and re-activated at any stage later.
• Additionally, the theme can be deleted, which cancels its installation but does not physically remove it. To completely remove the theme, you need to delete the theme directory in the /themes/ directory.

Theme file structure

The file storage in the theme directory follows this hierarchy:

• PHP template files should have a similar nested structure of storage, similar to the original path, for example:
• Path to the original file (the one that needs to be modified): /modules/site/tpl/def/index.php
• Path to the template in the theme directory: /themes/example/modules/site/tpl/def/index.php
• Static files (images / javascript / css) should be located in the /static/ directory in the theme directory.
• Path to the original file (the one that needs to be modified): /public_html/js/app.js
• Path to the file in the theme directory: /themes/example/static/js/app.js
• During theme installation/activation, these files will be copied to the directory: /public_html/themes/example/
• After that, whenever the project tries to include a file, the system will check if a similar file exists in the theme directory, and if it does, it will include it.  

During theme development, it may be inconvenient to enable/disable the theme to apply changes made to static files. For this purpose, a debug mode is provided, which, when enabled, automatically updates the static files. The activation order of debug mode is described in this article. Remember to disable it after development is complete, as this setting creates additional load.

Customizations

You can customize a theme by completely copying it and making changes to the copy of the code. In this case, you will lose the ability to receive updates in the future. Use this approach only as a last resort and only if you plan to completely redesign the design and interface. If the changes you need are minor, we recommend using the theme inheritance mechanism, specifying the source theme in the creation form. In this case, a gray arrow icon and the name of the source theme will appear next to the name of the newly created theme in the theme list. Copy only the necessary files to the directory of your created theme, while maintaining the original directory structure and nested directories, and all other files will be included from the source theme. This approach allows you to build a new theme based on an existing one without making direct changes to the code. When updating the source theme, you can refer to the list of changes and transfer them to your version. The list of changes is available in the settings of the source theme in developer mode immediately after updating, and it only shows the difference in files before and after the update. The parent theme is identified using the theme_parent setting:

$this->setSettings(array(
    'theme_title'   => 'New Theme',
    'theme_parent'  => 'base',
));

In the example, New Theme inherits Base Theme (base). If New Theme is active and a template file is not found in it, the template file from the Base Theme will be included. This applies to both php template files and static files such as js/css/images. It works the same way when substituting the system's original files with the theme's files.

index.php File Structure

In the theme directory, it is mandatory to have an index.php file. Let's consider an example of its contents, using a theme named 'example':

<?php

class Theme_Example extends Theme
{
    public function init()
    {
        parent::init();

        $this->setSettings(array(
            'theme_title'   => 'My Theme',
            'theme_version' => '1.0.0',
            'extension_id'  => '1234567890123456789012345678901234567890', // unique identifier for the extension
        ));

        /**
         * Settings filled in the admin panel
         */
        $this->configSettings(array(
            // ...
        ));
    }

    /**
     * Method called upon theme startup
     */
    protected function start()
    {
        // ...
    }
}

Let's describe it in more detail:

• The theme class name always starts with the prefix Theme_ and the class itself inherits the base class Theme.
• The obligatory init function specifies the theme name, its version, and declares additional settings.
• The rest of the theme code should be placed in the start function, as well as in the functions of this class. Additional PHP files with functions should also be included in the start function or immediately before use.

For each of the actions described above, there is a corresponding function that is called upon that action:

• install - installation
• uninstall - removal
• activate - activation
• deactivate - deactivation
• update - update

If it is necessary to perform additional actions, they can be extended as follows:

    protected function install()
    {
        if ( ! parent::install()) return false;
        // additional actions
        return true;
    }

• The example shows an extension of the theme installation function.
• First, the base function is called and a return is made if the result is negative.
• Then, custom code can be added instead of the comment.
• In the end, the function should return true if the actions were successful or false if errors occurred in the process.
• The same rules apply to the other mentioned functions.

Errors

Errors can occur during the theme's operation and the theme developer can record them in an error log file. Read more about error handling in the article "Error Logging".