By default, when you create a new project, a theme is no longer installed automatically for your project. If you have followed the installation guide, you must already have a theme installed for your application. If not, please follow the installation step below.
The framework comes with a command line tool at its root directory. If you need to install a fresh theme for your project, you first need to open your terminal and then go to your application root and run the theme:install command like so:
php console theme:install your-theme-nameYou have to provide a name for your theme when calling the command. Spaces are not allowed and we also suggest that you keep your theme name in lowercase.
The theme:install command will download the latest theme boilerplate, install it under the htdocs/content/themes/your-theme-name directory, configure the theme style.css file headers and set it as the default theme for your application.
The theme should be responsible to only handle the views (HTML), its assets like JavaScript and stylesheets files as well as basic templating logic. Here is a look of the default theme structure:
+-- assets/
| +-- js/
| +-- sass/
+-- config/
+-- dist/
| +-- css/
| +-- images/
| +-- js/
+-- inc/
+-- languages/
+-- resources/
| +-- Providers/
+-- views/
+-- functions.php
+-- index.php
+-- package.json
+-- routes.php
+-- style.css
+-- webpack.mix.jsThe assets directory contains all your JavaScript and CSS files. There is a default js/theme.js file as well as default Sass files extracted from the Underscore theme.
The config directory contains the theme configuration files. From this folder, you can control your theme images, menus, sidebars, support features and templates. There is also a theme.php configuration file that handle theme core configuration like the autoloading PSR-4 parameters, the views paths and the list of its service providers. Each configuration file contains comments with explanations about each available option.
The dist directory contains your compiled assets. Compiled assets are then enqueued by the Asset API. Asset compilation is managed by webpack through Laravel Mix tool. You can read more about managing the assets below.
The inc directory is a folder that extends the default functions.php file. You can insert as many PHP files as you want into the folder and all files will be automatically included. You can even nest PHP files within subfolders.
The languages directory contains the PO template file for your theme. You can load it with the PoEdit software and start translating your theme.
The resources directory is the theme namespaced directory. You can organize your theme PHP Class into the folder by following the PSR-4 specification. The \Theme namespace is pointing to the resources directory. By default, it contains a Providers directory that holds the theme RouteServiceProvider class.
The views directory contains all your view files. By default, it contains views extracted from the Underscore theme. Feel free to use, modify or delete default views based on your project.
The theme provides a routes.php file at its root. However, we do not recommend its use. It is now best to define your application routes at project root within the routes/web.php file.
In order to manage your assets, the theme is now bundled with Laravel Mix. Mix is an elegant wrapper around Webpack for the 80% use case.
Laravel Mix is the only front-end dependency defined in the theme package.json file. With Laravel Mix, you'll be able to compile your JavaScript files as well as your stylesheets and any other required assets for your theme.
Before installing Laravel Mix, you need to make sure to have the following tool installed on your machine:
You can handle your node packages using the default npm handler provided by NodeJs or you can also install Yarn for managing them.
Once NodeJs is installed, open a terminal or console and go to your theme root and run the following command:
npm installor if you're using Yarn:
yarn installThe above command will install Laravel Mix and all its dependencies.
In order to configure Laravel Mix, you have to edit the webpack.mix.js file located at theme root. Here is the default configuration provided by the theme:
let mix = require('laravel-mix');
mix.js('assets/js/theme.js', 'dist/js/theme.min.js')
.sass('assets/sass/style.scss', 'dist/css/theme.css')
.sass('assets/sass/woocommerce.scss', 'dist/css');
Webpack is compiling the assets/js/theme.js JavaScript file using the mix.js() method and is also compiling the assets/sass/style.scss and assets/sass/woocommerce.scss Sass files provided by the theme using the sass() method.
Laravel Mix provide multiple methods to compile ReactJs components, VueJs components, Less, Stylus, and many more as well as working with BrowserSync, ...
For more configuration options, please read the official documentation.
The theme package.json file also provides a bunch of scripts/commands in order to help you work with your assets.
For local development, you'll mainly work with a mix of the three following commands: dev, hot and watch:
npm run dev
npm run watch
npm run hotWhen you're ready to publish your application, run the production command in order compile your assets for production:
npm run productionWhen enqueueing assets, it is common to provide a version number in order to provide a browser cache hint. The version number of the default theme assets is set based on the theme Version header defined into the style.css file.
In order to reset browser cache for your assets after a modification, simply update the Version header value from the theme style.css file.
/*
Theme Name: Themosis
...
Version: 1.0.1
...
Text Domain: themosis
*/Theme assets are loaded from the AssetServiceProvider class stored in the resources/Providers directory. If you need to remove or add an asset, simply edit the file:
public function register()
{
/** @var ThemeManager $theme */
$theme = $this->app->make('wp.theme');
Asset::add('theme_styles', 'css/theme.css', [], $theme->getHeader('version'))->to('front');
Asset::add('theme_woo', 'css/woocommerce.css', ['theme_styles'], $theme->getHeader('version'))->to('front');
Asset::add('theme_js', 'js/theme.min.js', [], $theme->getHeader('version'))->to('front');
}The theme is manage by a
ThemeManagerclass. See how the themeversionvalue is retrieved from thestyle.cssheader.
The framework is handling a theme through a ThemeManager class. The manager is responsible to provide utilities in order to work with the current active theme as well as registering it theme configuration.
You can find below a list of methods available in order to work with your theme.
If you need to work inside the theme functions.php file, the ThemeManager class instance is already provided to you through the $theme variable.
The ThemeManager class instance is also registered into the application service container under the abstract name wp.theme. Here is an example on how to retrieve it from a theme service provider:
<?php
namespace \Theme\Providers;
use Illuminate\Support\ServiceProvider;
class MyServiceProvider extends ServiceProvider
{
public function register()
{
$theme = $this->app->make('wp.theme');
}
}It is also possible to retrieve the theme manager instance by using the app() helper function:
$theme = app('wp.theme');Sometimes, you may need to retrieve information from the theme headers defined inside the style.css file. In order to get a header value, use the getHeader method like so:
$theme = app('wp.theme');
$version = $theme->getHeader('version');Here is the list of available headers you can retrieve from the style.css file:
$name = $theme->getHeader('name');
$theme_uri = $theme->getHeader('theme_uri');
$author = $theme->getHeader('author');
$author_uri = $theme->getHeader('author_uri');
$description = $theme->getHeader('description');
$version = $theme->getHeader('version');
$license = $theme->getHeader('license');
$license_uri = $theme->getHeader('license_uri');
$text_domain = $theme->getHeader('text_domain');If you need to get the theme path or a path of a sub-directory of your theme, you can use the getPath method like so:
$theme_root_path = $theme->getPath();
$subdirectory = $theme->getPath('inc/features');If you need to get the theme URL or a URL of a sub-directory of your theme, you can use the getUrl method like so:
$theme_url = $theme->getUrl();
$theme_subdir_url = $theme->getUrl('dist/images/logo.png');The theme is translation ready and provides a languages directory with a .po template file. During development, use the THEME_TD constant, defined by the theme manager, as a text domain value when calling gettext functions.
The constant THEME_TD value is automatically defined based on theme name during installation but you can easily change it by updating the Text Domain header inside the style.css file.
Finally you may use the THEME_TD constant in your views like so:
// From a Blade view
<button>{{ __("Read more", THEME_TD) }}</button>
// From a Twig view
<button>{{ __("Read more", constant('THEME_TD')) }}</button>WordPress themes only need .po files with a locale filename. For example: en_US, fr_BE,...
Based on defined locale from WordPress, the theme is automatically loading the corresponding translation file for you.
We recommend the use of PoEdit in order to update and translate your files. Check the Twig or Blade guides in order to configure PoEdit for your views.
Made in Belgium