Child Themes

Child themes provide an easy way to add custom assets, override template files or extend YOOtheme Pro with more functionality. All customizations are preserved during updates of YOOtheme Pro.

A child theme is used to make modifications to any part of YOOtheme Pro. It has its own theme directory next to the yootheme directory. This way customizations are separated from YOOtheme Pro which makes them portable, replicable and unaffected by YOOtheme Pro theme updates. Typically, a child theme is used for the following customizations.

  • To add JavaScript, CSS and fonts
  • To add Less styles to the style library
  • To override templates files
  • To add builder elements to the element library
  • To extend YOOtheme Pro with custom PHP code

Note YOOtheme Pro provides custom code settings where you can add custom JavaScript, CSS or Less. This may be sufficient for smaller customizations without the need to create a child theme. They can be found in the Settings → Custom Code panel of YOOtheme Pro. Additionally, each page builder element has an option to apply custom CSS in the Advanced tab of the element settings.


Create a Child Theme

Open the Joomla template directory templates and create a new folder yootheme-NAME for the child theme. The suffix is name of the child theme, for example yootheme-mytheme.

Once the directory is created, the child theme can be activated in the Settings → Advanced panel of YOOtheme Pro. Just select the child theme, click Save and refresh the browser window.

Activate Joomla child theme

Note A YOOtheme Pro child theme does not have its own settings. You can enable or disable the child theme, but the theme settings will stay the same. To have different settings, create a new template style in Joomla and select the child theme there.


JavaScript, CSS and Fonts

YOOtheme Pro automatically loads the custom.js and custom.css files from the respective js and css directory if available in the child theme. Just create one of those files and add your custom code. It's the easiest way to quickly load additional CSS or JavaScript. To load specific JavaScript or CSS files take a look at the modules and events documentation.

/yootheme-NAME
    /css
        custom.css
    /js
        custom.js

To load a custom font, create a fonts directory with all the needed font files. Add a @font-face at-rule to the css/custom.css file and specify the font resources.

@font-face {
    font-family: "Custom Font";
    src: url("../fonts/custom-font.woff2") format("woff2"),
         url("../fonts/custom-font.woff") format("woff");
}

The font Custom Font can now be used in CSS. To set the font in the style customizer, open the font picker and instead of selecting one of the proposed fonts, type in the name Custom Font into the the search field and hit the Enter key.

Set a custom font in the style customizer

Note When a Google font is selected in the style customizer, it's automatically downloaded to the web server and stored locally. There is no round-trip to the Google Fonts server, which is great for page speed and GDPR-compliance. There is no need to add a custom font manually in the child theme if it is already available in the style customizer.


Less Styles

Styles in YOOtheme Pro are built with the UIkit framework. They are basically UIkit themes written in Less and customizable through the style customizer in YOOtheme Pro. Working with UIkit and Less usually involves overwriting Less variables, extending existing CSS rules by using Mixins or adding your own CSS rules. Learn more about customizing UIkit in the UIkit themes documentation.

To add a custom style to the style library, create a less directory in the child theme and add a file theme.NAME.less. The suffix is the name of the style, for example theme.my-style.less. Once the file is created, the style My Style can be selected in the style library.

Add a header comment with additional information at the very top of the file to show a custom preview image and to define under which filter options it is available. Optionally, set a name which will be used instead of the file name in the style library.

/*

Name: My Style
Background: White
Color: Black
Type: Flat
Preview: my-style.jpg

*/

Now you can create your custom style. There are few ways to get started.

Modify a Style

The easiest way is to customize an existing style. Just import it into the Less file and add your customizations.

// Import an existing style, for example `Fuse`
@import "../../yootheme/less/theme.fuse.less";

// Add custom Less code here

There are over 40 styles available in YOOtheme Pro. Their Less files can be found in the less directory in YOOtheme Pro.

Modify a Style Variation

Each YOOtheme Pro style comes in 5 further style variations. To start with a style variation, just import both, the style and its variation, into the Less file.

// Import an existing style, for example `Fuse`
@import "../../yootheme/less/theme.fuse.less";

// Import a style variation, for example `dark-yellow`
@import "../../yootheme/vendor/assets/uikit-themes/master-fuse/styles/dark-yellow.less";

// Add custom Less code here

The available variations of a style can be found in the corresponding style vendor/assets/uikit-themes/master-STYLENAME/styles directory in YOOtheme Pro.

Start from Scratch

To create a style from scratch, import the necessary base styles. This includes files for the Joomla, the UIkit framework, the Master UIkit Theme and the YOOtheme Pro theme.

// Import platform specific styles for Wordpress or Joomla
@import "../../yootheme/less/platform.less";

// Import the UIkit framework
@import "../../yootheme/vendor/assets/uikit/src/less/uikit.less";

// Import the `Master` UIkit Theme which extends the UIkit framework
@import "../../yootheme/vendor/assets/uikit-themes/master/_import.less";

// Import the YOOtheme Pro theme specific styles
@import "../../yootheme/less/theme.less";

// Add custom Less code here

Template Files

Template files like the index, header, menu or module templates can easily be customized. Simply add a template file to the child theme, and it will override the exact same file in YOOtheme Pro. It’s recommended to copy the original file from YOOtheme Pro to the child theme and start modifications from there.

Any Joomla template file can be included in the child theme, not just the ones from YOOtheme Pro. Learn more about how to override the different template files in the Joomla understanding output overrides documentation.

Here is an overview of all template files in YOOtheme Pro.

Theme Templates

The following template files serve as entry points to the Joomla site.

Template Description
index.php The main template file which renders the actual theme layout.
error.php Renders error pages.
offline.php Renders the offline page.

Output Overrides

To override the layout from any Joomla component or module, add the respective template files to the html directory of your child theme. YOOtheme Pro overrides com_content, com_finder, com_search and com_tags template files as well as most modules. These template files are located in yootheme/html and can also be overridden in the child theme.

Since Joomla only has articles and does not differentiate between a single page or a blog post, YOOtheme Pro uses template partials across all component overrides to render articles differently. A simple template hierarchy determines which template partial is loaded.

Template Partial Description
templates/article.php Renders articles if no other matching template file is found.
templates/article-blog.php Renders categorized articles which are used as posts. Included in com_content/category and com_content/article.
templates/article-page.php Renders uncategorized articles which are used as pages. Included in com_content/article.
templates/article-search.php Renders results on search pages. Included in com_finder and com_search.
templates/article-featured.php Renders featured articles. Included in com_content/featured.
templates/article-tag.php Renders tagged articles. Included in com_content/tag.
templates/meta.php Renders the meta information. Included in all article templates.

Section Templates

The following template files render the different sections.

Template Description
templates/section.php Renders the section for the top and bottom positions.
templates/sidebar.php Renders the sidebar for the sidebar position.

Header Templates

The following template files render the different header layouts.

Template Description
templates/header.php Renders the header and its navigation.

The following template partials are included by the header.php.

Template Partial Description
templates/toolbar.php Renders the toolbar.
templates/header-mobile.php Renders the mobile header and its navigation.
templates/header-logo.php Renders the logo.
templates/search.php Renders the search toggle and field.
templates/socials.php Renders the social icons.

Module and Position Templates

The following template files render the module position layouts.

Template Description
templates/position.php Renders the position.
templates/module.php Renders the module.

The following template files render the different menus.

Template Description
templates/menu/menu.php Renders the menu.
templates/menu/nav.php Renders menu items for the vertical nav.
templates/menu/navbar.php Renders menu items for the navbar.
templates/menu/subnav.php Renders menu items for the subnav.
templates/breadcrumbs.php Renders the breadcrumb navigation.
templates/pagination.php Renders the pagination.

Builder Elements

To add a custom element to the page builder, create a builder directory in the child theme and copy the custom element into it. It will be loaded automatically by YOOtheme Pro and will be available in the element library. For more information on how to create a custom element read the custom elements documentation.


Advanced Customizations

To extend YOOtheme Pro with custom functionalities, add a file config.php to the child theme directory. It will be loaded automatically by YOOtheme Pro. Here you can register your own classes with functions that listen to the events. For more information read the modules and events documentation.

YOOtheme Pro Documentation