Directory structure explained

The Warp framework has HTML, CSS, JavaScript and PHP helper classes to cover all aspects in theme development. It's really portable since all framework related files are kept in a single place, a folder called warp. This folder resides directly in every theme. There are no dependencies on other components or plugins. Nothing needs to be installed or maintained separately.

Warp is separated into three layers. The first layer is the core framework which provides the base CSS, a JavaScript effects library and a collection of PHP helpers. Each part of the core framework is universal and designed to work on every supported system. The second layer is the system dependent layer, which 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. The third layer is the theme specific layer, this is where all the individual theme files go. It's the working place where all the theme's custom HTML, CSS, JavaScript and images are being stored.

To provide as much flexibility as possible we implemented a special file cascade into Warp. 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. Here is the cascade:

  • theme folder
  • specific system folder, for example /warp/systems/joomla
  • warp framework folder

This gives you full flexibility to override any important theme related file. In the following we will give a short overview of the most important files if you want to customize a Warp theme.

Styles

Styles are variations of the default theme and are similar to the concept of child themes in WordPress or sub themes in Drupal. A style defines a layer after the default theme and can inherit or override resources from the parent default theme. Warp walks along the file cascade looking for the resource until it is found. This gives you full flexibility to override any file of the default theme. Each style is placed in its own directory in the theme's /styles folder and can provide its own custom HTML layouts, CSS, JavaScript and images. Our Create a new style tutorial explains how to create your own custom style.

Layouts

The main template file /layouts/template.php is the heart of every theme, it provides the complete HTML markup for the base theme layout. This is different from standard Joomla templates or WordPress themes where the index.php is the main template file. The second important file is the /layouts/template.config.php which includes some layout calculations and defines all the theme's CSS and JavaScripts.

  • Template File: /layouts/template.php
  • Template Configuration File: /layouts/template.config.php

Modules

Modules or widgets can be displayed in different styles with additional icons and badges. The /layouts/module.php takes care of displaying all these module variations. Depending on the selected style the module.php loads the right HTML markup from predefined module templates. Further the framework comes with three commonly used module layouts: equal, double and stacked, which are used to position modules next or above each other. It's also possible to extend them with your own custom module templates and layouts.

  • Module Styles: /layouts/module.php
  • Module Layouts: /warp/layouts/modules/layouts/
  • Module Templates: /warp/layouts/modules/templates/

Stylesheets

The CSS files are divided into three different layers and are placed in their respective folders for theme specific /css, system dependent /warp/systems/joomla/css and framework styles /warp/css. Including these files is really easy because Warp also uses its file helper to locate them across the different folders. Here is an overview on the different files:

  • base.css - Sets baseline defaults to reduce inconsistencies across all browsers.
  • layout.css - Provides a fluid grid and helper classes to create any layout.
  • menus.css - Defines base styles for our mega drop down menu, line menu and accordion menu.
  • modules.css - Defines general module styles, headings, badges and icons.
  • tools.css - Provides a useful set of CSS classes to style your content like lists and boxes.
  • system.css - Defines a base style for the WordPress and Joomla system HTML markup.
  • rtl.css - Used for right-to-left language localizations.
  • print.css - Used when printing.
  • mobile.css - Styles the theme for mobile phones.
  • ie.css, ie7.css, ie8.css - Only loaded by the specific Internet Explorer version.
  • style.css - Defines the main look like colors and backgrounds in one place.
  • custom.css - Use it to style your custom content. It is blank by default.

JavaScript

Warp also provides a library of JavaScript effects used in dropdown and accordion menus, the AJAX search or the mobile theme. The JavaScript files are also structured and stored in their own folders for theme specific /js, system dependent /warp/systems/joomla/js and framework scripts /warp/js. All scripts are configured in a single file /js/template.js. This file is used to enable or disable effects which will be loaded with the theme.

  • Theme JavaScript: /js/template.js

System Markup

Every system has a set of layouts which defines the HTML markup for the core CMS output. For Joomla these are typically the HTML overrides that are used by the theme to render the content component or modules like the login or search. The Joomla 1.7 files are located in /warp/systems/joomla/layouts. In WordPress the layouts provide a HTML markup for the different pages like blog frontpage, the archive or a single post. The WordPress files are located in /warp/systems/wordpress/layouts. To keep things simple, Warp basically uses the same HTML output for all supported systems. Regardless of what you are viewing, articles of a category in Joomla's content component or posts from a category in WordPress, Warp renders the HTML. This allows to create universal CSS rules which apply for both CMS platforms.

  • Joomla 2.5 and Joomla 3.0 System Files: /warp/systems/joomla/layouts
  • WordPress System Files: /warp/systems/wordpress/layouts

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!