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.
test
- https://playwright.dev/docs/api/class-testexpect
- https://playwright.dev/docs/api/class-genericassertionsadmin
- https://github.com/WordPress/gutenberg/tree/trunk/packages/e2e-test-utils-playwright/src/adminpage
- https://playwright.dev/docs/api/class-pagerequest
- 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