Theme Structure

File Structure

The organization of the theme is very similar to modern PHP Frameworks. All code is split into five main folders:

• app/ – contains theme Components and Models definition (object-oriented code for all theme features and data providers);
• inc/ – contains simple functions, which are required inside the theme (like helpers or template functions);
• views/ – theme templates ;
• assets/ – public theme files like CSS and JavaScript;
• config/ (optional) – various configuration data.

Theme root looks like this:

├── app/                    # → Main theme code should be added here
├── assets/                 # → Public assets should be placed here
├── config/                 # → Specific configuration files for 3rd-party plugins/libraries
├── inc/                    # → Simple functions not related to a specific component
├── views/                  # → Templates
│
├── .htaccess               # → Security: deny access to a theme codebase
├── style.css               # → Theme declaration file
├── index.php               # → Theme Wrapper launcher
├── functions.php           # → Theme features loader, only requires all theme features
├── requirements.php        # → Requirements checker 
└── woocommerce.php         # → WooCommerce plugin compatibility (loads from /views/woocommerce/*)

assets folder

Assets are downloadable public resources such as CSS, JavaScript, fonts and images.

Theme doesn't have any gulp/webpack json settings here because we prefer to keep theme assets clean and do not overload it with source SCSS files or a lot of javascript libraries.

We usually develop nice, responsive HTML/CSS code separately based on our web starter kit. It has a lot of tools inside, and we don't see any reasons to merge this web starter kit with WordPress theme. This allows to speed up theme development using several developers to create high-quality HTML/CSS and WordPress code/template.

Example of assets folder structure:

│
├── assets/                 # → Public assets should be placed here
│   ├── css/
│   ├── js/
│   ├── images/
│   ├── fonts/
│   └── .htaccess           # → Security: allow access to public files
│

app code base

app folder contains all theme custom features and data-related logic code. Each theme component is represented by an independent class object, one class definition per file. We group classes based on their type (Post type, taxonomy, model, widget) or logical meaning (Supports, Web, Admin). So default app structure looks as follows:

│
├── app/                    # → Main theme code should be added here
│   ├── Admin/              # → Custom Dashboard features
│   │   └── ThemeSettings.php       # → Theme Settings page based on Titan Admin Panels
│   ├── Models/             # → Page/Section data providers
│   │   └── {Some_Data_Object}.php      # → Section-based data models
│   ├── Post_Type/          # → Registration of Custom Post Types
│   │   └── {Some_Post_Type}.php        # → List of Custom Post Types
│   ├── Taxonomy/           # → Registration of custom Taxonomies
│   │   └── {Some_Taxonomy}.php         # → List of Taxonomies
│   ├── Widgets/            # → Custom theme widgets
│   │   └── {Some_Widget}.php           # → List of custom Widgets
│   ├── Supports/           # → 3d-party plugins support hooks/feautres
│   │   └── Autoptimize.php         # → CSS/JS cache/combine advanced configuration
│   └── Theme.php           # → Main theme class, which registers all other components
│

The theme is loaded inside functions.php. During the code execution, we create a singleton instance of a Theme class object, which is defined inside app/Theme.php. This class does pretty standard things, like describing sidebars, widgets, post types, image sizes, etc.

Also Theme defines other Components (like Load More, Contact Form 7 support, etc.).

inc folder

In some cases, you will still require simple functions like helpers, generic hooks registration, or some HTML-related template print functions. We moved them to a separate folder called inc:

│
├── inc/                    # → Simple functions not related to a specific component
│   ├── helpers.php         # → Helper functions like data formatters or adapter functions
│   ├── hooks.php           # → Registering some template related hooks (like body class logic, etc.) 
│   └── template-funcs.php  # → "The"-loop related functions (like posted_on(), etc.)
│

views templates

All templates have been moved to a separate folder called views (modern name of PHP templates used inside PHP Frameworks). Views templates can inherit each other.

Default views folder has such required folders:

│
├── views/                  # → Templates
│   ├── layouts/            # → Template wrapper templates
│   │   ├── html.php            # → Base <html> tags wrapper
│   │   └── main.php            # → Default layout with header, footer and sidebar
│   ├── partials/           # → Generic templates similar for several templates, section-independent 
│   │   ├── header.php          # → Usual header template
│   │   ├── footer.php          # → Usual footer template
│   │   └── sidebar.php         # → Usual sidebar template
│   ├── page/               # → Page templates (like front-page, page-*, etc.)
│   ├── post/               # → Post templates (like index, archive, single, etc.)
│   └── search/             # → Search templates
│

You can read more in Templates Hierarchy and Templates Layouts topics.

Loading process

On WordPress load, it includes theme functions.php file. We tried to keep this file as simple as possible and do the following inside it:

• Check theme requirements (framework plugin installed and activated).
• Include theme helper functions (/inc/*).
• Register Autoloader to load classes automatically from /app/ folder.
• Launch Theme Setup by creating a Theme class instance.
• Register Theme Options page by creating a Theme_Settings class instance.

All other classes are included "on demand", based on PSR-4 Autoloader.

functions.php

<?php
/**
 * JustCoded Theme Boilerplate functions and definitions.
 */

/**
 * We need to make sure the required plugins are active and installed
 */
require_once get_template_directory() . '/requirements.php';
if ( ! Just_Theme_Framework_Checker::single()->check_requirements() ) {
	// terminate if titan plugin is not activated.
	return;
}

require_once get_template_directory() . '/inc/helpers.php';
require_once get_template_directory() . '/inc/hooks.php';
require_once get_template_directory() . '/inc/template-funcs.php';

/**
 * Wrap theme start code into a function to be able to use child theme.
 * this code will be executed inside child theme.
 */
if ( ! function_exists( 'boilerplate_theme_starter' ) ) {
	/**
	 * Theme launcher function
	 */
	function boilerplate_theme_starter() {
		new \JustCoded\WP\Framework\Autoload( 'Boilerplate\Theme', get_template_directory() . '/app' );

		$theme    = \Boilerplate\Theme\Theme::instance();
		$settings = \Boilerplate\Theme\Admin\Theme_Settings::instance();
	}
}

/**
 * Finally run our Theme setup
 * and ThemeOptions setup
 */
boilerplate_theme_starter();

---

Next: Theme Setup