Modularity Documentation

Intro

Modularity provides a simple but effective methodology to empower any WordPress-Developer to develop clean, modular, maintainable, shareable and extendable code even on larger projects.

Modularity does not force you to work with a specific frontend-framework and will not lock you in a complex library.

Modularity helps you and your team to share the same way of writing code for WordPress-Projects.

You can start working modular on every existing or new project. Modularity loads, compiles and enqueues your theme-modules automatically. No local transpiling needed. Start coding straight away!

Notice: The code examples below will encourage everyone to write lightweight code, which is easy to write and to understand. Let’s keep things simple.

Get started

1. Download and install the free and Open Source Modularity Plugin here
2. Create a folder called /modules in your theme’s root folder
3. Thats it! You can now start to develop your own modules

01 . Anatomy of a module

• modules inside the /modules folder can have every name. We recommend to use - as a name-separator for readability
• a modules folder name is the modules basename
• main module files are named with the basename
• mark template file with a *.template.php or place template parts in a templates folder if you have more than one
• place assets in an assets folder
• structure a complex module with submodules below a submodules folder

Example 1 (simple)

/your-theme-folder
  /modules
    /module-xyz
      module-xyz.php - main module file - is loaded automatically
      module-xyz.template.php - a template file - can be included
      module-xyz.scss - module styles - compiled and enqueued automatically
      module-xyz.js - module scripts - compiled and enqueued automatically

Example 2 (complex)

/your-theme-folder
  /modules
    /module-xyz
      /assets - assets like static images, fonts, media
      /submodules - can hold submodules that extend the main module
      /templates - holds the multiple template files of a module
      module-xyz.php - main module file - is loaded automatically
      module-xyz.scss - module styles - compiled and enqueued automatically
      module-xyz.js - module scripts - compiled and enqueued automatically
      readme.md - module infos on how to use it and changelog

Hints

• start thinking modular: create all code for a specific feature in a specific module
• use short and simple module names like header , frontend , theme-settings or hero-slider
• you can use modules for every type of functionality or just for styling/scripts
• you do not need to have all files in a module. You can just have a basename.php or a basename.scss

02 . PHP code structure and naming

• create and use namespaces for every module. We recommend this structure in camelcase letters: YourMainNamespace\ModuleXy
• name your functions simple with verb first like register_blocks or load_template (no worries you will not collision with WordPress functions if you use namespaces)
• use actions and filters to apply your code. More about the WordPress hook-system here.

Example module-xyz.php

<?php 

namespace YourMainNamespace\ModuleXyz;

defined("ABSPATH") or die;

add_action('init', 'YourMainNamespace\ModuleXyz\register_blocks');
add_action('modulexyz/email', 'YourMainNamespace\ModuleXyz\send_email');

function register_blocks()
{
 // your code to register blocks here
}

function send_email()
{
  // do some functionality
}

Hints

• If you need to prioritise the load order of your different modules’ code, use the priority parameter of WordPress’ hook-system
• create your own hooks to load a modules functionality in another module f.e. in module: add_action('modulexy/show_something', 'YourMainNamespace\ModuleXyz\show_something'); and in other module do_action('modulexy/show_something');
• structure complex modules below /submodules and use also a sub-namespace f.e. YourMainNamespace\ModuleXyz\SubmoduleXyz
• use \ in front of WordPress internal functions while in namespace

03 . SCSS structure and naming

• write your clean SCSS code into the module’s main scss-file
• try to use the simple naming-conventions of SMACSS which structures styling in base, layout, module, states and theme parts
• BEM is also a good method to create and maintain complex styling-architectures but has some class-name-writing-overhead

Example module-xy.scss

.module-xyz {
  // modules styles
}

Hints

• if your scss code has changed Modularity regenerates all css-files automatically
• add // generate_editor_styles in your scss to generate and enqueue a css-file for the block-editor
• we recommend to not use SCSS-variables but CSS-variables (custom properties) cause these are way more flexible and can be changed at runtime

04 . JS structure and naming

The modular architecture of your further websites will lead to clear code over several modules. As main WordPress development is still done via serverside PHP-scripts, the JavaScript part of Websites and Web-Applications is comprehensible. Because of that we do not need (so far) a way to transpile ES5 (or later) JavaScript.

We recommend to just start with simple VanillaJS and/or jQuery for frontend-scripting. A typical structure for your module`s JS could be:

Example module-xy.js

function($) {
  $(document).ready(function(){
    // function calls here
  });
  
  // functions here
}

Hints

• Modularity enqueues all module-scripts in the site footer. An anonymous function to wrap jQuery is enough

05 . Loading, compiling and enqueing

Ok nice but what is the Modularity Plugin doing for me?

If modules are present in the given structure (01), Modularity will:

1. load all modules+submodules main .php files
2. compile every SCSS file to a CSS with same name in same folder
3. enqueue all module styles and scripts the right way

Modularity is doing all this for you! Automagically!

Footnote

This documentation is a basic start. We will go on to provide more info about Modular Development.

Modularity is not new. We are now at v5 so we already had some iteration rounds. 🙂