The LEAN Theme
A no-frills WordPress starter theme - Gutenberg Ready!
, (*1)
The Lean Theme is a starter theme for WordPress made by Developers for Developers., (*2)
It focuses on fast development following best development practices., (*3)
Some key features:
* Gutenberg ready
* Easy configuration with Parcel for building development and live environments
* ES6 Javascript
* TailwindCSS
* SASS preprocessor
* MVC coding architecture
* Reusable frontend components (following the Atomic Design methodology)
* Helper functions to create Custom Post Types, Categories and Endpoints easily
* ACF integration
* PHP, JS and SASS linters
* Composer and NPM for managing dependencies, (*4)
Contents
Pre-requisites
You need the following in order to work with this theme:
* PHP 7.1 or higher
* Composer
* Node.js
* Yarn
* Advanced Custom Fields WP Plugin v5.8.1 or higher, (*5)
Composer should be installed globally., (*6)
Installation
Download or clone the theme, (*7)
Go to the theme path and enter, (*8)
composer install
Development and Production Building commands
The theme uses composer as dependency manager for PHP libraries, NPM for the JavaScript libraries and Webpack to build the SASS and JS files., (*9)
Production build command
composer build
This command will install the NPM dependencies and will run the Webpack production configurations which will get the JS and CSS files optimized for a production server., (*10)
Development command
cd frontend
yarn start
This command will run the Webpack development configuration which will start a watcher that compiles the SASS and JS files as soon as you save them., (*11)
It will also enable source maps for easy debugging., (*12)
Best Practices
The Lean Theme encourages you to use best practices by using linters for PHP, JS and CSS. This helps maintain a consistent scode style, leaving it becomes clean and at less risk of bugs or security risks. It will help you to detect errors on your code and give you tips on how to solve them., (*13)
Linter command
The PHP linter uses the WordPress Coding Standards specified on the WordPress handbook. The following command should be run manually before committing change, and also added to your continuous integration build configuration., (*14)
The JS linter uses the ESLint and the SCSS linter uses SCSS Lint., (*15)
composer lint
Codacy
Codacy is a tool that automates code reviews & code analytics., (*16)
If you use this tool you can move the .codacy.yml file to the root of the project.
This will tell Codacy to review only the relevant files of your app.
It will also tell Codacy to grab the PHP, JS and SCSS linter configuration files so that it uses this rules., (*17)
Frontend Components
The Lean Theme follows the Atomic Design methodology for developing a modular frontend., (*18)
Below the frontend/components directories there are 4 directories called Atoms, Molecules, Organisms and Templates to which you can add all the Atomic Elements., (*19)
Atoms
Atoms are the basic building blocks of matter., (*20)
Applied to web interfaces, atoms are our HTML tags, such as a form label, an input or a button., (*21)
Your stylesheet of each atom must be added inside of _style.scss of the atoms directory., (*22)
Molecules
Molecules are groups of atoms bonded together and are the smallest fundamental units of a compound., (*23)
A molecule might be an input that includes a form label and the input error display. They are generally not too useful by themselves, but combine them together as a form and now we have something!, (*24)
Your stylesheet of each molecule must be added inside of _style.scss of the molecules directory., (*25)
Organisms
Organisms are groups of molecules joined together to form a relatively complex, distinct section of an interface., (*26)
For example, a hero is an organism., (*27)
Your stylesheet of each organism must be added inside of _style.scss of the organism directory., (*28)
Templates
Templates consist mostly of groups of organisms stitched together. A template with content in it is a page., (*29)
Your stylesheet of each template must be added inside of _style.scss of the template directory., (*30)
Loading Atomic Elements
The Lean Theme uses the Loader Module to render atomic elements:, (*31)
Load::element_type( ‘element_folder/element_php_file’, element_arguments[] );
To use it first add its namespace at the beginning of the file:, (*32)
<?php
use Lean\Load;
// Example of loading an organism located in patterns/organisms/hero/hero.php
Load::organism(
'hero/hero', [
'bg_image_url' => $bg_image_url,
'show_header' => true,
]
);
// Example of loading an atom located in patterns/atoms/buttons/button.php
Load::atom(
'buttons/button', [
'label' => $label,
'link' => $url,
]
);
Gutenberg Configuration
The Lean Theme comes with preconfigured Gutenberg options for the blocks like Font size and colors setup., (*33)
This settings are changed in Backend/WP/Gutenberg/Editor.php, (*34)
Custom Font Sizes
The font size options in the editor's sidebar can be customized.
Set the styles in frontend/components/atoms/gutenberg/_typography.scss by adding the slugs and font sizes.
The font size selectors option can also be removed completely., (*35)
Custom Colors
To edit the colors that the user can select, add the colors in frontend/components/atoms/gutenberg/_colors.scss.
The color palette options can also be removed completely., (*36)
Allowed Blocks
The blocks that will be allowed to be used in the Gutenberg editor can also be configured.
The discrimination can be done per page or post type., (*37)
Custom Blocks
See the Gutenberg Blocks subsection for information on how to create custom blocks., (*38)
Extending the editor
The Lean Theme comes with a JS building system already setup and ready to use for customizing the Gutenberg editor., (*39)
For example, you could add a custom field to a core block., (*40)
Go to backend/WP/Gutenberg/js and run, (*41)
yarn start
More info on how to extend the Gutenberg editor:
https://developer.wordpress.org/block-editor/, (*42)
Helper functions
TODO: Add Helper functions to the theme, (*43)
Assets
Here you can store anything that is a static file inside the folder frontend/static and respective subfolder:, (*44)
Images
All the images are placed here, usually if there are static images that does not depend change and are from the design can be placed here., (*45)
Web Fonts
This directory is used to place any custom web font that is not available by default as safe web fonts., (*46)
Icons
The SVG icons go here., (*47)
CSS
The Lean Theme comes with TailwindCSS and SASS integrated., (*48)
Styleguide
The Lean Theme comes with its own custom styleguide. More info here: https://github.com/wearenolte/lean-theme-styleguide, (*49)
JavaScript
Adding new JS function / behavior
First of all you need to create a new file where it makes more sense. For example, we want to create a listener for the click event in buttons so every time a button is clicked a class is added to the body., (*50)
In this case it would make sense to create a new atom called inside of atoms/buttons/toggle-button-listener.js such as., (*51)
// Everything inside of this file is going to be local to the scope of this file
const targetButtonClassName = '.js-button';
const toggleClassName = '.button-is-active';
function myMainAction() {
const buttons = searchButtons();
buttons.forEach( attachEvent );
}
function queryTheDOM() {
return Array.from( document.querySelectorAll( targetButtonClassName ) ) ;
}
function attachEvent( node ) {
node.addEventListener( 'click', clickListener );
}
function clickListener() {
document.body.classList.toggle( toggleClassName );
}
export default myMainAction;
As you can see the example has several functions but the one that is exported to the outside world is only the function myMainAction. At this point this JS is not going to be executed unless you explicitly specify so inside of main.js inside of the onReady function. Everything inside of this function is going to be executed once the DOM is ready., (*52)
So following the example aboye you need to add this two lines inside of main.js, (*53)
import myMainAction from './atoms/buttons/toggle-button-listener';
// inside of onReady
function onReady() {
// other functions before
myMainAction();
}
NOTE The code is transpiled so can be executed on browsers where import or export is not supported yet., (*54)
Adding an external package from NPM
Inside of your own modules you can import files from node_modules. You only need to make sure you add the dependency inside of package.json., (*55)
And the syntax is pretty similar to import action from 'package-name';, (*56)
For example to add flatpickr we need to run the following command in to the terminal:, (*57)
yarn add flatpickr
And to usage the package you only need to add:, (*58)
import Flatpickr from 'flatpickr';
// Usage example
function init() {
const node = document.querySelector('.flatpickr');
const instance = new Flatpickr( node );
}
export default init;
Models and Controllers
Modules specific to your project go in the backend directory. We encourage you to follow the Single Responsibility Principle so each module just try to address a single responsibility for instance Widgets/Widgets.php only tries to address the Widget rendering problem., (*59)
The init() method of each class all be called automatically if the class path is set in Backend.php., (*60)
To create a new module:
1 - Create a new directory such as:, (*61)
MyModule/MyModule.php
2 - Check if MyModule path is set in `Backend.php, (*62)
3 - Add the corresponding namespace to the new Class., (*63)
4 - The Lean Theme Loader is going to check for an optional init() method, make sure your this method has the following visibility and variable of scope:, (*64)
public static
The boilerplate for your module should be:, (*65)
<?php
namespace Lean\Backend\MyModule;
class MyModule {
public static function init() {
// This code is executed automatically by the loader.
}
}
You can also create a single class directly in the top-level of the src folder. The same principles apply to the init function. This is useful for simple helper functions or WordPress hook callbacks., (*66)
Creating a Custom Post Type
To create a Custom Post Type, the Lean Theme relies on another PHP library called WP-CPT which comes installed with the theme., (*67)
First create a Module as stated before and add the respective code., (*68)
Example of an Invoice CPT:, (*69)
code in backend/WP/CPT/Invoices/Invoices.php, (*70)
<?php
namespace Lean\Backend\WP\CPT\Invoices;
use Lean\Cpt;
class Invoices {
const TYPE = 'invoices';
public static function init() {
// This code is executed automatically by the loader.
add_action( 'init', [ __CLASS__, 'register_cpt' ] );
}
public static function register_cpt() {
$invoices = new Cpt(
[
'singular' => 'Invoice',
'plural' => 'Invoices',
'post_type' => self::TYPE,
'slug' => 'invoice',
'supports' => [
'title',
],
'args' => [
'menu_icon' => 'dashicons-media-text',
],
]
);
$invoices->init();
}
}
Creating an Endpoint
Create a Class in the folder Backend/WP/Endpoints
and initialize it in Backend/WP/Endpoints/Api.php, (*71)
Endpoint out of the box:, (*72)
http://[site-url]/wp-json/lean/v1/posts
Theme Hooks
Actions
List of hooks and filters availables to be used with this theme., (*73)
lean/before_header
Action executed before the main <header> tag and after the <body> tag, useful if you want to add something before any other tag on the site., (*74)
lean/after_header
Action executed after the main </header> tag. Useful if you want to add something just after the header has been rendered., (*75)
lean/before_footer
Action that is executed before the main <footer> tag. Useful to add something before the last tag of the page is added., (*76)
lean/after_footer
Action that is executed before the closing </body> tag and just after the ` tg. Useful to add something at the end of the site., (*77)
Filters
The following is a collection of filters available to be used to change settings and options from the theme at any point., (*78)
lean/acf_path
With this filter you can change the location of the ACF files, by default saves the ACF Groups into the acf directory located on the theme., (*79)
lean/acf_use_custom_location
By default is set to true, with this filter you can remove the automatic save of ACF Fields into the lean/acf_path., (*80)
Contributing
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us., (*81)
Credits
Thanks goes to:, (*82)
Francisco Giraldo, (*83)
Nelson Amaya, (*84)
Cris Hernandez, (*85)
Daniel López, (*86)
Katia Lira, (*87)
Adam Fenton, (*88)
Oscar Arzola, (*89)
Raul Marrero, (*90)
Changelog
Please read CHANGELOG.md this file is going to keep the changes of the project when a new release is sent to the master branch, (*91)
License
MIT, (*92)
Wallogit.com
