Starter Theme – Developers

If you have used the WordPress Installer, you have probably already installed the starter-theme, so maybe skip the 'git clone' part.

Install using git from your WordPress themes directory (replace your-theme-name below with the name of your theme and make sure you specified your SSH key in your bitbucket account ):

# wp-content/themes/ 
$ git clone git@bitbucket.org:magina_fr/starter-theme.git your-theme-name && rm -rf your-theme-name/.git

Init you theme installation

Run npm install from the theme directory to install dependencies
Update webpack.mix.js settings:
- url should reflect your local development hostname
- directory should reflect your WordPress theme folder name)

Theme Structure

themes/your-theme-name/ # → Root of your Sage based theme
├── app/ # → Theme PHP
│ ├── cli/application.php # → PHP file to call from php CLI to run custom commands
│ ├── config/ # → Theme configuration files (Blade, Assets, etc.)
│ ├── data/ # → Files injecting variables into Blade templates. Auto-loaded by body classname.
│ ├── src/ # → App library files. Should follow PSR-4 standard for autoloading to work.
│ │ ├── Command/ # → Custom commands classes to be used by the CLI
│ │ ├── MyPostType/ # → Example of how to handle a custom post type
│ │ ├── Setup/ # → Contains Theme setup files (what you would usually find in functions.php)
│ │ └── Factory.php # → File where you instanciate your singletons for your app to be properly loaded
│ └── index.php # → Loads App main Factory file
├── composer.json # → Autoloading for `app/src` files
├── composer.lock # → Composer lock file (never edit)
├── dist/ # → Built theme assets (never edit)
├── node_modules/ # → Node.js packages (never edit)
├── package.json # → Node.js dependencies and scripts
├── resources/ # → Theme assets and templates
│ ├── assets/ # → Front-end assets
│ │ ├── fonts/ # → Theme fonts
│ │ ├── images/ # → Theme images
│ │ ├── scripts/ # → Theme JS
│ │ └── styles/ # → Theme stylesheets
│ ├── functions.php # → Composer autoloader, theme includes
│ ├── index.php # → Never manually edit
│ ├── languages # → PO/MO files for your theme translation
│ ├── screenshot.png # → Theme screenshot for WP admin
│ ├── style.css # → Theme meta information
│ └── views/ # → Theme templates
│ ├── layouts/ # → Base templates
│ └── partials/ # → Partial templates
├── webpack.mix.js # → Compiled assets configuration
└── vendor/ # → Composer packages (never edit)

Theme Setup

Edit app/setup.php to enable or disable theme features, setup navigation menus, post thumbnail sizes, and sidebars.

Build Command

⚠️ Run these commands outside your VM (so not with ssh maginabox). If not, the watcher with Browsersync will not work properly.

npm run start -- Compile assets when file changes are made, start Browsersync session
npm run build -- Compile and optimize the files in your assets directory
npm run build:production -- Compile assets for production

Back-end / Login Customization

Customize login and back-end is easy and can be done quickly :

On theme customizer, add a theme logo : it will be used on login page,
On resources/assets/styles/common/_variables.scss : adjust the variable $admin-primary to change buttons and links colors.
Dashboard default widgets has been removed. If needed, you can enable them in app/admin.php
Plugins "upgrade to pro" notices has been hidden in resources/assets/styles/layouts-admin/_plugins.scss

SCSS usage with Bulma framework

The main variables used by Bulma have been inserted in resources/assets/styles/common/_variables.scss
Some useful mixins & functions have been added
The main Bulma's mixins & functions have been written on the top of the files as reminders.

About the colors

Bulma has an easy-to-use system with classnames to adjust text colors and backgrounds, see the modifiers section.

To add additionnal colors to this system, you must add them to the variable $addColors defined in _variables.scss file.
(Social Networks colors have been added for example, so you can use classnames "has-text-facebook" or "has-background-facebook")

Assets compiling

Laravel Mix will compile every file that ends with *.compiled.js or *.compiled.scss. You can create as much as compiled files as you need.

in Carlos, you can generate a .profile file using :
echo 'PATH=/opt/plesk/node/15/bin:$PATH' >> ~/.profile && source ~/.profile

Assets autoloading

The Starter theme loads assets for the front-end automatically. On page load, the theme looks for compiled files in the resources/assets/styles/pages folder and compares it with body classes generated by WordPress. If a file name matches a body class, it gets enqueued.

ex.: app.compile.scss will get enqueued on every page since app is added to the body class on every page.

This process ensures that only strictly needed assets are loaded on every page and speeds up assets loading even more if HTTP/2 is enabled on the server.