Find out how to add your own customizations and learn more about file hierarchy in Warp.

To provide as much flexibility as possible, Warp applies a special file cascade. If you include any file like CSS, JS or template PHP files, Warp looks successively in specific folders for the files and the first file found will be loaded. This gives you full flexibility to override any important theme related file.

We will explain the override cascade a bit further. If you just want to know, how to override theme files, jump down to the appropriate examples.

Override cascade

As an example, this is what the override hierarchy for the /layouts folder would look like.

1. Styles folder

The /styles/STYLE-NAME/layouts folder of your theme is at the top of the hierarchy and modifications or additions you make here will override all other theme files. Also this folder will be preserved during updates, so it's the safest place to make your modifications.

2. Theme folder

The theme's /layouts folder is the place where all the theme specific layout files are being stored.

3. Systems folder

The /warp/systems/joomla/layouts or /warp/systems/wordpress/layouts folder provides the individual system implementation needed to integrate with a particular CMS. This layer makes Warp adapt to a certain system to form a consistent API for theme development.

4. Warp folder

The /warp/layouts folder contains basic overrides made by the core framework. Each part of the core framework is universal and designed to work on every supported system.

The cascades for the /js, /css and /layouts folders are defined in the theme's config.php. If you want to register another folder in the cascade, you can do so here.

Layout overrides

To customize the general theme layout, you need to override the /layouts/theme.php. To do so, create the /styles/STYLE-NAME/layouts directory, copy the file in there and start adding your own PHP code.

This way you can also override system files. For example, just take the Joomla article layout /warp/systems/joomla/layouts/com_content/article/default.php and copy it to your style folder /styles/STYLE-NAME/layouts/com_content/article/default.php and modify it. Now your modified article layout file will be used instead of the default system layout. The same applies for WordPress files.

Add your own CSS

There are several ways of adding your own custom CSS to a Warp theme. You can use the Customizer to change most aspects of the theme without having to write any CSS. Keep in mind that your style will only be shown in the Customizer, if there is a style.less file inside the style's folder. When you use the Customizer, changes will be saved in the style.less file. Together with the theme LESS files it will be compiled into the /css/theme.css file and override any customizations you may have done.

Add custom CSS

You can use the Customizer and also add your own CSS by creating a custom.css file inside the /css folder for the related style. That way your CSS won't be overwritten when you save changes in the Customizer.

Add CSS without using LESS and the Customizer

If you are not planning to use the Customizer at all, just duplicate an existing style and delete the style.less file. Now the /css/theme.css will no longer be overwritten when compiling LESS. You can write customizations directly in the the theme.css file.

Add custom JavaScript

The configuration file /layouts/theme.config.php initializes all PHP classes and loads the necessary JavaScript. If you need to load custom JavaScript files, this is the place to do it. Enabled compression and Data URI will be applied automatically to all files you add here.

  1. Create a new file /styles/STYLE-NAME/layouts/theme.config.php.
  2. Load the original file through PHP by using the require function.
  3. Then add your JavaScript file to the asset collection, so it will be added automatically to the template header.
  4. Put your own custom JavaScript file in the /styles/STYLE-NAME/js/MY-JS.js directory.


// add script
$this['asset']->addFile('js', 'js:MY-JS.js');

Custom template files for WordPress

You can use different layouts for template files, for example pages, by creating files in your theme folder with the name prefix page- followed by the ID or page-slug.

  • page-{id}.php
  • page-{slug}.php

Let's say you want custom content for a page with the ID 80. Create a file in your theme folder and name it page-80.php with the following content.

<?php get_header(); ?>

Put your content here...

<?php get_footer(); ?>

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!