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: Git and Node

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 git@github.com:tangibleinc/template-system, and pull request from a feature branch.

Develop

Start local dev site

This starts the server for a local development site.

npm run start

Open another terminal tab/window to develop modules with JS and CSS assets.

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.

Test

There is a suite of unit and integration tests included.

The test environment uses wp-now, which runs WordPress on Node and PHP-WASM. It does not require Docker or PHP being installed on the local system.

Run

Run the tests.

npm run test

PHP versions

By default it uses PHP 7.4, the oldest version we support. WordPress itself only has beta support for PHP 8.x. See PHP Compatibility and WordPress versions and Usage Statistics.

Run the tests with PHP 8.3.

npm run test:8.3

Run all PHP versions and E2E

Run the tests with all PHP versions, as well as end-to-end tests.

npm run test:all

Run test file or folder

Run individual test file.

npx roll run tests/loop/taxonomy.ts

Run test folder with index.ts.

npx roll run tests/logic

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