Axio Starter (previously Aucor Starter)

🖥 For developer from developers:
Superior Gutenberg WordPress starter theme with modern build tools by Generaxion. 250+ hours of development over 6 years to make the greatest starting point for WordPress site.
Demo: axio.generax.io
🔌 Required plugins:

• Axio Core: Core functionality that is clever to be centrally updated.
• Advanced Custom Fields Pro: Some custom blocks use ACF. You can do without, but should remove them.

🏷 Buzz-words:
Gutenberg, Gulp, Yarn, SVG, SASS, Browsersync, a11y, l18n, Advanced Custom Fields, Polylang, Schema.org, Native lazyload, BEM, Babel, Responsive images

Table of contents

1. Directory structure
2. Setup
   1. New site setup
   2. Developer setup
   3. Work session setup
3. Components
   1. Base component
   2. Using components
   3. Creating new component
   4. Validating arguments
4. Modules
   1. Default modules
   2. Module loading
   3. Module structure
   4. Creating new modules
   5. Installing new modules
   6. Disabling or deleting modules
   7. Module caveats
5. Assets
   1. Styles
   2. Scripts
   3. SVG
   4. Images
   5. Fonts
   6. Favicon
6. Includes
   1. Functions.php
   2. _conf
   3. Helpers
7. Localization
   1. Registering strings
   2. Using strings
   3. Localizator
8. Workflows
   1. Setting up your code editor
   2. Navigating the code
9. Philosophy
   1. Gutenberg
   2. Scope of starter
   3. Level of detail
   4. Open source

1. Directory structure

Directory
Contents

/acf-json/
automatically saved JSON versions of site specific fields from Advanced Custom Fields

/assets/
global JS, SASS, images, SVG and fonts

/bin/
shell scripts for bulk tasks/automations

/dist/
has processed, combined and optimized assets ready to be included to theme

/modules/
features that are packaged into modules like blocks, template parts, post-types

/inc/
global php files that are not part of template structure/modules

2. Setup

2.1 New site setup

Do these theme installation steps before modifying anything.

Download & Extract

1. Download this repository
2. Extract into /wp-content/themes/ and rename for project like sitename

Run setup

Run setup wizard in theme root with bash sh bin/setup.sh

Field
Meaning
Default

Site name
Name in style.css
Axio by Generaxion

Local development url
Browsersync’s mirror URL. Stored at /assets/manifest.js

https://axio-starter.local

Author name
Author in style.css
Generaxion

Author URL
Author URL in style.css
https://www.generaxion.com

Run localizator (if needed)

Theme strings are by default in English but we do support Finnish and probably Swedish in near future. If you would like to initialize strings in these languages, do the following:

1. Run bin/localizator.sh
2. Input language code
3. Select to remove language packages after running

Install Axio Core

Some of the functionality of Axio by Generaxion require plugin Axio Core. The plugin is centrally updated so that sites using starter will be easier to maintain and there will be less duplicate code from project to project. Axio by Generaxion won’t have fatal errors without it, but for example localization won’t work without it.
Download Axio Core from WordPress.org or Github and activate.
Protip: If you are using composer: composer require wpackagist-plugin/axio-core or WP-CLI: wp plugin install axio-core.

First 15 minutes of your new site

Here’s optional next steps:

1. Go through the /modules/ and remove any unneeded. Just throw them to trash.
2. Save logo at /assets/images/logo.svg
3. Setup colors and fonts at /assets/styles/utils/_variables.scss

2.2 Developer setup

Every developer does this before first time working with the project.

1. Open terminal and navigate to /wp-content/themes/sitename
2. Run yarn install (fetches all node packages for build tools).

Protip: If you don’t have Gulp installed locally run npm install --global gulp-cli. If you are missing Yarn, install Yarn.

2.3 Work session setup

Do this everythime you start to work with the theme.

1. Open terminal and navigate to /wp-content/themes/sitename
2. Run gulp watch to activate build process in background. You’ll get development proxy at http://localhost:3000 where changes to code will be updated automatically to browser (no need to reload).
3. To quit press ctrl + c

Protip: You can also run just gulp to build all the resources or just some resources with gulp styles or gulp scripts. Want to start the watch task but not open the Browsersync in browser? Start watch with quiet mode qulp watch -q.

3. Components

Components are the first unique building blocks of this theme. They are an evolution of WordPress’s get_template_part() function that aim to fix underlying issues of that function:

1. Arguments: Template parts had no legitimate way to pass arguments (until WP 5.5.0).
2. Returning and echoing: All components can be either echoed or HTML markup can be returned.
3. Validation: Template part concept won’t encourage to validate arguments early and end up with highly nested if checks for the code. In components you can exit early and have separated backend and frontend functions to gather and sanitize data.
4. Context free: You can create components to be used in blocks, templates and inside other components. It’s up to you how context aware/independent components you want to build.

3.1 Base component

Components get their power from abstract class Component that keeps in the structure and required functionality for each component. Every component inherits from this class. The component structure is loosely inspired by React component concept.

3.2 Using components

There are two basic ways to use component:

X_Teaser::render();
X_Teaser::get();

The render function prints out the HTML markup of the component and get will return it. You can pass arguments in an array like so:

X_Teaser::render(['id' => 123]);
X_Teaser::render([
  'id'          => 123
  'hide_image'  => true,
]);

All components can be interacted with the same way. It is up to the component to validate the given args and pick what to do with what argument.

3.3 Creating new components

<?php
/**
 * Component: Componet's name
 *
 * @example
 * X_Components_Name::render([
 *   'title'        => 'Title',
 *   'description'  => 'Descriptive text'
 *   'image'        => 123
 * ]);
 */
class X_Components_Name extends X_Component {

  public static function frontend($data) {
    ?>
    <div <?php parent::render_attributes($data['attr']); ?>>

      <?php if (!empty($data['image'])) : ?>

        <div class="components-name__image">
          X_Image::render([
            'id'        => $data['image'],
            'size'      => 'large',
          ]);
        </div>

      <?php endif; ?>

      <h3 class="components-name__title">
        <?php echo $data['title'] ?>
      </h3>

      <p class="components-name__description">
        <?php echo $data['description'] ?>
      </p>

    </div>

    <?php
  }

  public static function backend($args = []) {

    $default = [

      // required
      'title'       => '',
      'description' => '',

      // optional
      'attr'        => [],
      'image'       => '',

    ];

    // overrides defaults with given args
    $args = wp_parse_args($args, $default);

    // validate arguments
    if (empty($args['title']) || empty($args['description'])) {
      return parent::error('Missing title or/and description');
    }

    // set html attributes
    $args['attr']['class'][] = 'components-name';

    // or make conditioning
    if (!empty($args['image'])) {
      $args['attr']['class'][] = 'components-name--has-image';
    }

    // $args should be so pre-chewed that frontend can just use the data with simple empty() checks or foreach() loops
    return $args;
  }

}

3.4 Validating arguments

As in example above the rendering of component starts by passing data to backend function in $args that passes it to frontend function and renames it to $data (just to mentally separate raw input from sanitized).
Here are your validation strategies:

1. Return error in backend: return parent::error('What heppened'); and this error is displayed if WP_DEBUG is activated. In production without…