Velocity Project Plugin Baseplate Readme

This Wordpress plugin is responsible for all the backend related elements (functions, methods, classes, setup, config and Gutenberg blocks), as well as providing the default markup and styling for components, blocks and modules. These frontend facing foundation elements provide a starting point, and although they are developed to work out the box, they are ultimately overwritten/manipulated by the theme in order to provide a custom theme based experience.

Table of Contents

1. CLI Commands
2. Installation
3. Helpers and Functions
4. Asset Structure
5. Gutenberg Blocks
6. Hierarchy Mode

CLI Commands

The plugin uses gulp to help with task automation throughout development. Here are the available commands.

Build

Running the build command will automatically include minifcation of files (where applicable). This is generally used before deployment. Note: This command will also completely rebuild your build directory from scratch (i.e. deleting the existing directory and any files container within).

Run this command to rebuild your plugin:

gulp build

Watch

The watch command is generally used through development and will change files on an individual basis as modifications are made and saved. All changes are automatically output to your build directory, but non-minified. Note: watch will only work on files that exist before the task is running. If you create any new files you will need to restart the watch process to track any changes.

Run this command to start the watch process:

gulp watch

Optional arguments

| Arg | Result | | --- | ------ | | --nosync | Disables browser-sync refresh on file save |

Installation

Clone this repository into a new folder and run:

npm install

Once complete run the build command (specified in the CLI Commands section) and then symlink the built plugin folder ('/dist/wp-content/plugins/') into your projects built plugin folder, ie:

ln -s /[path to your project folder]/www/wp-content/plugins/[plugin folder]/ /[path to this plugin folder]/dist/wp-content/plugins/

Helpers and Functions

The plugin is configured to be processed after_theme_setup. This means is that all functions, helpers, components, blocks etc... that exist within the theme architecture will be registered first. This allows us to manipulate the functionality of an element by virtue of the if (!function_exists([function name])) { statement, which you will notice wraps all of our functions. Therefore if the function has been registered by the theme already, the plugin function will be bypassed and the theme function will be the one fired when called.

Asset Structure

CSS

All CSS is compiled from SaSS partials using gulp-sass. Any stylesheets defined in the root of the styles working folder ('/src/assets/styles/') will be compiled into its own CSS file.

Compiled SCSS files must not begin with an underscore; underscored files will be ignored by the SaSS compiler, and should only be included as file partials.

JavaScript (excl. frameworks)

Files defined in /src/assets/scripts/main/ will compile to individual JavaScript files. Files defined outside of this directory will not compile to individual files, but may be used for inclusion as ES6 modules.

Gutenberg Blocks

By default the theme runs the allowed_block_types filter which means, for any block that isn't included in this list (via a plugin, or otherwise) it will not be made accessible to the theme. To modify which blocks are accessible to theme you should amend the file: inc/theme/v-allowed-gutenberg-blocks.php. This file controls all Wordpress core blocks, as well as any custom blocks (as defined in the $blocks_custom array).

Theme Blocks

The theme supports its own block registration. With this feature enabled all theme-defined blocks are automatically registered for inclusion via the allowed_block_types filter. To enable theme blocks add/uncomment the following in your wp-config.php file:

define( 'V_THEME_BLOCKS', true );

Most aspect of block registration is handled automatically, but each block requires a small amount of setup. It is crucial you understand and follow these steps carefully. Note: the values of [name] must be the same.

Dependencies

| File | Usage | | --- | ------ | | ./assets/scripts/block/vBlock[Name].jsx | Required for the Gutenberg editor. This should only contain the edit() method for controlling block behaviour in the admin. See below for more information on customisation. | | ./conf/v-block-[name].json | Contains all the configuration settings, attributes and properties that define the block | | ./inc/blocks/v-block-[name].php | Provides the callback for server-side rendering of the block. See below for more information on customisation. |

Block JSON

It is important that the object keys match those as specified within the Gutenberg API documentation. In addition to this there are two further callback parameters which are optional if you wish to go outside of the auto-generated approach:

| Parameter | Info | | --- | ------ | | editor | Specifiy the name of the file you have created for the Gutenberg editor. It must match the file given above. | | callback | Specifiy the function of the file you have created for the server-side rendering of the block. Note: Any specified attributes will automatically be registered for you and will be accessible within this callback function. |

Hierarchy Mode

Under the 'Document' tab, whilst editing a page/post, is a 'Hierarchy Controls' panel. If 'Activate Hierarchy Mode' is active, all the blocks within the page will display placeholder hierarchy styling and provide the user the option to add a label. When deactivated, the blocks will return to their regular configuration.

This is helpful at the start of development to allow us to see the general page structure/hierarchy before a design has been laid out.

Configuration of the heirarchy mode styles can be updated in the each respective block (/src/assets/scripts/blocks/vBlock[Name]) via the JSON const hierarchyModeDetails declared at the top of the page.

Pushing to NPM

to release a new version to NPM, run the following commands: npm version patch followed by npm publish where patch can be patch / minor / major you'll need to be logged into your NPM account on the CLI first, and your account will need to be added to the VP Dev NPM workspace to have permission to publish.

Pipeline Deployment

To deploy to the pipleline, follow the steps below:

1. Merge working branch (development) into pipeline-deploy branch
2. Make sure you're on the pipeline-deploy branch
3. Run the npm command: a. For a patch release: gulp build --release b. For a minor release: gulp build --release --minor c. For a major release: gulp build --release --major
4. On successful completion it will output the new version number with updated files including a new updated zip file
5. Commit files with a message format like: "release v4.42.2 - [description of files changed / actions taken]"
6. Push to pipeline-deploy branch

PHP Linting and Auto-formatting

make sure you've pulled down and installed this repo https://bitbucket.org/velocitypartners/velocityphpcs/src/main/ run gulp phpcs to lint any coding standards issues run gulp phpcbfs to automatically fix any problems identified

Style media query extraction

when wanting to extract media queries from a stylesheet, the syntax is as follows in the gulp.config.json file:

"mediaQueryExtract" : {
    "dist" : "css/",
    "queries" : {
        "(min-width: 576px)"  : "sm",
        "(min-width: 768px)"  : "md",
        "(min-width: 992px)"  : "lg",
        "(min-width: 1200px)" : "xl"
    }
}