Template System

This is the template system shared by Tangible Blocks and Loops & Logic.

Source code: https://github.com/tangibleinc/template-system

Documentation: https://docs.loopsandlogic.com/reference/template-system/

Overview

The codebase is organized by feature areas, which are made up of modules.

• Language - Defines the template language and tags
• Admin - Admin features such as template post types, editor, import/export, assets, locations, layouts, builder integrations
• Modules - Additional template system features, such as Chart, Slider, Table
• Integrations - Integrate with third-party plugins
• Framework - Features shared across plugins, such as AJAX, Date, HJSON

Each module should aim to be generally useful, clarify its dependencies internal and external, and ideally be well-documented and tested. Some are published as NPM (JavaScript) or Composer (PHP) package.

See section Folder Structure for a detailed view.

Getting started

Prerequisites: Linux, macOS, or Windows (WSL); Git, Node (version 20 and above)

Clone the repository, and install dependencies.

git clone https://github.com/tangibleinc/template-system
cd template-system
npm install

Contributing

To contribute to the codebase, create a fork and make a pull request. Tangible team members can clone from [email protected]:tangibleinc/template-system, and pull request from a feature branch.

Develop

Local dev site

Start a local dev site using wp-now.

npm run now

The default user is admin with password. Press CTRL + C to stop.

List modules

The project is composed of modules which can be built individually. See the list of modules with assets.

npm run list-modules

The list is generated from the codebase by finding all config files tangible.config.js, and gathering their folder names relative to the project root. These can be built with the dev, build, and format commands described below.

You can specify one or more modules, for example:

npm run dev editor integrations/gutenberg

Another example, to build all child modules of the admin module.

npm run build admin

Build modules for development

Watch files for changes and rebuild.

npm run dev [module1 module2..]

Press CTRL + C to stop.

Build modules for production

Builds minified bundles with source maps.

npm run build [module1 module2..]

Format code

Format files to code standard with Prettier and PHP Beautify.

npm run format [module1 module2..]

Install third-party plugins

Run npm run install:dev to install optional plugin dependencies such as Advanced Custom Fields, Beaver Builder, Elementor, and WP Fusion.

npm run install:dev

They will be downloaded in the folder vendor/tangible-dev. Existing plugins will be skipped, unless you run the command update:dev to download their newest versions.

npm run update:dev

The dependencies are also listed in the file .wp-env.json to map local folders to the test site environment.

Tests

This plugin comes with a suite of unit and integration tests.

The test environment is started by running:

npm run start

This uses wp-env to quickly spin up a local dev and test environment, optionally switching between multiple PHP versions. It requires Docker to be installed. There are instructions available for installing Docker on Windows, macOS, and Linux.

Visit http://localhost:8888 to see the dev site, and http://localhost:8889 for the test site, whose database is cleared on every run.

Before running tests, install PHPUnit as a dev dependency using Composer inside the container.

npm run composer:install

Composer will add and remove folders in the vendor folder, based on composer.json and composer.lock. If you have any existing Git repositories, ensure they don't have any work in progress before running the above command.

Run the tests:

npm run test

For each PHP version:

npm run env:test:7.4
npm run env:test:8.2

The version-specific commands take a while to start, but afterwards you can run npm run test to re-run tests in the same environment.

To stop the Docker process:

npm run stop

To remove Docker containers, volumes, images associated with the test environment.

npm run env:destroy

Notes

To run more than one instance of wp-env, set different ports for the dev and test sites:

WP_ENV_PORT=3333 WP_ENV_TESTS_PORT=3334 npm run env:start

---

This repository includes NPM scripts to run the tests with PHP versions 7.4 and 8.x. We need to maintain compatibility with PHP 7.4, as WordPress itself only has “beta support” for PHP 8. See https://make.wordpress.org/core/handbook/references/php-compatibility-and-wordpress-versions/ for more information.

End-to-end tests

The folder /tests/e2e contains end-to-end-tests using Playwright and WordPress E2E Testing Utils.

npm run e2e

The first time you run it, it will prompt you to install the browser engine (Chromium).

npx playwright install

Watch mode

There is a "Watch mode", where it will watch the test files for changes and re-run them. This provides a helpful feedback loop when writing tests, as a kind of test-driven development. Press CTRL + C to stop the process.

npm run e2e:watch

A common usage is to have terminal sessions open with npm run dev (build assets and watch to rebuild) and npm run e2e:watch (run tests and watch to re-run).

UI mode

There's also "UI mode" that opens a browser interface to interactively run the tests and view results.

npm run e2e:ui

Utilities

Here are the common utilities used to write the tests.

• test - https://playwright.dev/docs/api/class-test
• expect - https://playwright.dev/docs/api/class-genericassertions
• admin - https://github.com/WordPress/gutenberg/tree/trunk/packages/e2e-test-utils-playwright/src/admin
• page - https://playwright.dev/docs/api/class-page
• request - https://playwright.dev/docs/api/class-apirequestcontext

References

Examples of how to write end-to-end tests:

• WordPress E2E tests - https://github.com/WordPress/wordpress-develop/blob/trunk/tests/e2e
• Gutenberg E2E tests - https://github.com/WordPress/gutenberg/tree/trunk/test/e2e

Folder structure

.
├── admin                      // Admin features
│   │
│   ├── editor                 // Template editor
│   ├── import-export          // Import/export
│   ├── location               // Template location
│   ├── post-types             // Template post types
│   ├── settings               // Plugin settings
│   ├── template-assets        // Template assets
│   ├── template-post          // Template post
│   └── universal-id           // Universal ID
│
├── builder                    // Unified template editor environment
├── content                    // Content structure: post types and fields
├── design                     // Building blocks for design systems
├── form                       // Form
├── editor                     // Template editor core
│
├── elandel                    // Cross-platform template language in TypeScript
│   ├── css                    // CSS engine with extended syntax
│   ├── editor                 // Code editor
│   └── html                   // HTML engine with extended syntax
│
├── framework                  // Framework module shared by plugins
│   │
│   ├── admin                  // Admin features 
│   ├── ajax                   // AJAX
│   ├── api                    // API
│   ├── async-action           // Async action
│   ├── background-queue       // Background queue
│   ├── content                // Content structure
│   ├── date                   // Date module based on Carbon library
│   ├── design                 // Design
│   ├── empty-block-theme      // Empty Block Theme for testing
│   ├── env                    // Local develop and test environment with WordPress Playground
│   ├── format                 // Format methods
│   ├── hjson                  // Human JSON
│   ├── log                    // Logger
│   ├── object                 // Object
│   ├── plugin                 // Plugin utilities: settings page, features list
│   ├── preact                 // Preact
│   └── select                 // Select
│
├── integrations               // Vendor integrations
│   │
│   ├── advanced-custom-fields // Advanced custom fields
│   ├── beaver                 // Beaver Builder
│   ├── elementor              // Elementor
│   ├── gutenberg              // Gutenberg
│   ├── tangible-fields        // Tangible Fields
│   ├── themes                 // Themes
│   ├── third-party            // Third-party extension interface
│   ├── wp-fusion              // WP Fusion
│   └── wp-grid-builder        // WP Grid Builder
│
├── language                   // Template language
│   │
│   ├── format                 // Format methods
│   ├── html                   // HTML parser and renderer
│   ├── logic                  // Logic rules for If tag
│   └── tags                   // Dynamic tags
│
├── logic                      // Logic module
│
├── loop
│   └── types                  // Loop types
│       │
│       ├── attachment         // Attachment
│       ├── base               // Base loop class
│       ├── calendar           // Calendar
│       ├── comment            // Comment
│       ├── field              // Field loop
│       ├── list               // List 
│       ├── map                // Map
│       ├── menu               // Menu
│       ├── post               // Post, page, custom post type
│       ├── taxonomy           // Taxonomy
│       ├── taxonomy-term      // Taxonomy term
│       ├── type               // Post type
│       └── user               // User
│
├── modules                    // Feature modules
│   │
│   ├── async                  // Async
│   ├── cache                  // Cache
│   ├── calendar               // Calendar
│   ├── chart                  // Chart
│   ├── codemirror-v5          // CodeMirror v5 (deprecated)
│   ├── date-picker            // Date picker
│   ├── embed                  // Embed
│   ├── glider                 // Glider image gallery
│   ├── hyperdb                // HyperDB
│   ├── logic-v1               // Logic v1 (deprecated)
│   ├── markdown               // Markdown
│   ├── math                   // Math
│   ├── mermaid                // Mermaid diagram language
│   ├── mobile-detect          // Mobile detect
│   ├── module-loader          // Dynamic module loader
│   ├── pager                  // Pager
│   ├── prism                  // Prism syntax highlighter
│   ├── sass                   // Sass compiler
│   ├── slider                 // Slider
│   ├── sortable               // Sortable
│   └── table                  // Table
│
├── tests
│   ├── e2e                    // End-to-end tests with Playwright
│   ├── empty-block-theme      // Empty block theme for testing
│   ├── html                   // HTML test suite
│   └── integrations           // Integration tests with third-party plugins
│
└── tools
    └── git-subrepo            // Manage Git subrepos

Above reference based on output of tree.

tree -I vendor -I node_modules -I artifacts -I publish --gitignore -d -L 2