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.

Install Composer dependencies for development and testing.

composer install --dev

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 env:test # Shortcut: 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 env:stop # Shortcut: npm run stop

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

npm run env: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: