The pmc-gutenberg Plugin Folder Structure

Below is a breakdown of the pmc-gutenberg (opens in a new tab) folder structure which lives in the pmc-plugins (opens in a new tab) repo.

- bin
- build
- classes
- docs
- src
- template-parts
- tests
- .editorconfig
- .eslintrc
- .npmrc
- .nvmrc
- .stylelintignore
- .stylelintrc.json
- README.md
- babel.config.js
- dependencies.php
- jest.config.js
- jest.setup.js
- package-lock.json
- package.json
- phpunit.xml
- pmc-gutenberg.php
- webpack.config.js

./bin

Contains templates for the scaffolder and related files.

./build

This contains all the built JavaScript files, asset maps, JSON files, and minified stylesheets required for production. This may eventually be part of a post-merge deployment script.

./classes

This directory contains all of the php classes for the blocks, editor, block registration, rest endpoints, and helpers.

./blocks

Contains the class-block-base.php which enables the server-side registration of the blocks along with extra handling for larva (opens in a new tab) and nova elements.

We can improve our process for including assets considerably by leveraging the register_block_type (opens in a new tab) method and avoid unecessary enqueuing of assets. Several other improvmenets in this class could be made.

./editor

👉 class-block-editor-settings.php

Contains various theme overrides (adding or removing theme support) and other editor configuration settings.

👉 class-classic-editor-compat.php

Adds helpers to remove Classic Editor (opens in a new tab) features that may confilct with the block editor.

👉 class-gutenberg-helpers.php

Provides helpers for defining reusable functions and configuration elements localized to the window.

👉 class-gutenberg.php

The main file responsible for reading (optional) configs, enabling Gutenberg features for post types, and supporting various block editor customizations for PMC.

👉 class-heartbeat.php

A class which adds an optional heartbeat modification for some brands to shorten the frequency of reporting. Enabled via Cheezcap option in the brand's "Theme Options" page.

./interfaces/block-base

Contains interfaces (opens in a new tab) that a block's block.php uses requring classes that must be implemented to function.

• Every class that extends the Block_Base class must implement an interface from the PMC\Gutenberg\Interfaces\Block_Base namespace to ensure that the class provides the expected methods needed to render the block.
• Most blocks use the With_Render_Callback interface as they use Larva controllers to render the block, and those controllers render the block output to a string for incorporation in post content.
• Blocks that use the Without_Render_Callback interface are intended to be used when blocks don't require a render callback or only serve as a block to update post meta. This interface has no required class methods.
• If a block does not use a Larva controller, but will render its output using Larva patterns, the class should implement the With_Larva_Data interface and set the template property to the short path of the Larva pattern, such as modules/story-grid.

./traits/block-base

Contains traits (opens in a new tab) that a block's block.php may leverage to extend functionality.

./class-autoloader.php

An autoloader that extends the PMC\Global_Functions\Singleton_Loader functionality, but enables a custom folder stucture. Finds and requires all classes in directories at a defined depth. Used in the pmc-gutenberg.php init file.

This adds a Cheezcap in the "Theme Options" page which allows the ability to turn on Gutenberg at the user level (admins only) and also for all users all at once.

./class-meta.php

This adds our meta registration handler for the pmc-gutenberg plugin. Documentation found here.

./class-story-block-engine.php

Block engines are abstract classes that can be extended to create new blocks using the same base functionality. Documentation found here.

./docs

This directory will be replaced with the pmc-docs docs and will be removed in the future.

./src

This directory contains all of the non-block javascript, reusable components, custom hooks, configurations, and service/util functions.

- blocks
- components
- config
- filters
- hooks
- navbars
- services
- sidebars
- slotfills
- store
- utils

./src/blocks

Contains individual blocks organized by feature or brand and contains all the files necessary to register, create the editor experience, and render the frontend.

For example, a block created to be used ONLY by Variety would look like this:

- blocks
  - variety
    - custom-block-name
      - test
        - __snapshots__
          - index.js.snap
        -index.js
      - block.php
      - edit.js
      - edit.scss
      - index.js
      - meta.json

By default, all blocks are scaffolded to the "global" directory assuming use by all or mulatiple brands or features. The entire block folder can simply be moved to a new or exesting directory.

../src/blocks/brand/block-name

The test, block.php edit.js, and index.js files are automatically created when a new block is scaffolded.

The block.php file contains a block class which contains a constructor and a render_callback method which corresponds to the dynamic block's (opens in a new tab) render callback.

The edit.js contains all of the the JSX required to render the editor experience.

The index.js contains the registration object required to register the block (opens in a new tab) on the client-side and define the various settings and supports (opens in a new tab) values required to do so.

Optionally, a edit.scss can be added, imported into the edit.js file and the block.php constructor can be updated (as well as the matching test) to include the protected variable value $this->_has_stylesheet = true.

./src/config

All block, brand, and feature configurations are stored in this directory. Anything that can be resused should be stored as a config rather than a hardcoded value in a block or component.

The brand directory contains all block configs which can be read about here.

./template-parts

Currently contains the template part for the post-image-content defaults. A template defined in the built-in image block.php (opens in a new tab).

./tests

Contains all PHPUnit (opens in a new tab) tests for all PHP classes in this repository.

./wp-plugins

This directory contains featues that should live in another plugin in the pmc-plugins repo but was added to this plugin in an earlier itteration.

A complete migration of these features is pending a few things:

• A reusable npm package to allow any plugin in the pmc-plugins repo to take advantage of components, hooks, and service/util functions.
• A standardized method of adding, including, registering, and scaffolding blocks in other plugins.

These are the following directories and their corresponding pmc-plugins plugin.

• facebook-instant-articles >>> pmc-facebook-instant-articles
• pmc-gallery-v4 >>> pmc-gallery-v4

./webpack.config.js

The PMC webpack config extends the scripts subset of configs which extends the @wordpress/scripts (opens in a new tab) package and has special handling for all of our block, slotfill, plugin, filter, and wp-plugins features.

In the future we can simplify this to make all features available to the src directory and have blockes registered using the block.json (opens in a new tab) method.