Skip to main content

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.

Getting started

Prerequisites: Node.js

Clone the repository, and install dependencies.

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

If you want to contribute to the GitHub repo, 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

Build for production

Builds minified bundles with source maps.

npm run build [module1 module2..]

The Template System is composed of modules which can be built individually. Specify which modules to build, for example:

npm run build editor integrations/gutenberg

Build for development

Watch files for changes and rebuild. Press CTRL + C to stop the process.

npm run dev [module1 module2..]

Format files

Format files to code standard with Prettier and PHP Beautify.

npm run format [module1 module2..]

List all modules with assets

See the complete list of modules with assets.

npm run list

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 and build commands.

For example, npm run build admin will build all child modules of the admin module; or you can build an individual module like npm run build admin/editor.

Test

There is a suite of unit and integration tests included.

Requirements

Prerequisites: Docker

To run the tests, we use wp-env to create a local test environment, optionally switching between PHP versions.

Please note that wp-env requires Docker to be installed. There are instructions available for installing it on Windows, macOS, and Linux. If you're on Windows, you might have to use Windows Subsystem for Linux to run the tests (see this comment).

Prepare

Start the local server environment.

npm run start

After installing everything, it starts a local dev site at http://localhost:8888, and test site at http://localhost:8889. The default user is admin with password.

Note that wp-env can only run one environment at a time. If you have another instance running, it must be stopped first.

Install Composer dependencies for development and testing.

npm run env:composer

This runs composer install in the container.

Run tests

This repository includes NPM scripts to run the tests with PHP versions 7.4 and 8.2.

Note: We need to maintain compatibility with PHP 7.4, as WordPress itself only has beta support for PHP 8.x. See PHP Compatibility and WordPress versions and Usage Statistics.

Ensure a local environment is running, then run tests using a specific PHP version. This will tell wp-env to install it.

npm run env:test:8.2

The version-specific command takes a while to start, but afterwards you can run the following to re-run tests in the same environment.

npm run test

To switch the PHP version, run a different version-specific command.

npm run env:test:7.4

To stop the Docker process:

npm run stop

Usually it's enough to run start and stop. To completely remove the created Docker images and remove cache:

npm run destroy

Reference

Relevant info for writing unit tests:

End-to-end tests

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

Run

Run the tests. This will start the local WordPress environment with wp-env as needed. Then Playwright starts a browser engine to interact with the test site.

npm run test: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 test:e2e:watch  # Shortcut: npm run tdd

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

UI mode

There's also "UI mode" that opens a browser interface to see the tests run.

npm run test:e2e:ui

Utilities

Here are the common utilities used to write the tests.

References

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