Tangible Blocks

Tangible Blocks is a system for creating universal dynamic content blocks with HTML-based templates and Sass styling language. It can be integrated with WordPress site and page builders, as well as React applications.

Source code: https://github.com/tangibleinc/blocks

Documentation: https://docs.tangible.one/plugins/blocks/

Website: https://tangibleblocks.com

Plugins

The project consists of a set of plugins.

• Tangible Blocks
• Tangible Blocks Editor - Enable block template editing in the admin
• Tangible Blocks Pro
• Loops & Logic - Basic variant with all template types except blocks. Published in the official plugin directory on wp.org.
• Loops & Logic Pro

Themes

• Tangible Blocks Theme

Modules

Modules are common features shared by plugins.

• BetterDash - Utilities for LearnDash
• BetterLifter - Utilities for LifterLMS
• Fields - React-based form fields library
• Fields Pro
• Framework - Commonly used features like logging, date formatting
• Template System - Template parser, renderer, language definition (dynamic tags), frontend modules (JS & CSS), admin features
• Template System Pro
• Updater - Provide plugin updates from self-hosted update server

Third-party plugins

Blocks and L&L integrate with the following third-party plugins.

• Advanced Custom Fields
• Beaver Builder
• Elementor

The Pro variants add support for more.

• Easy Digital Downloads
• Gravity Forms
• LearnDash
• LifterLMS
• The Events Calendar
• WooCommerce

Develop

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

Clone the repository and install dependencies.

git clone git@github.com:tangibleinc/blocks.git
cd blocks
npm install

JS and CSS

Frontend and admin assets are compiled and bundled using Roller.

Build for development - watch files for changes and rebuild

npm run dev

Build for production

npm run build

Format to code standard

npm run format

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.

Dev dependencies

Optionally, install dev dependencies such as third-party plugins before starting the site.

npm run install:dev

To keep them updated, run:

npm run update:dev

Customize environment

Create a file named .wp-env.override.json to customize the WordPress environment. This file is listed in .gitignore so it's local to your setup.

Mainly it's useful for mounting local folders into the virtual file system. For example, to link another plugin in the parent directory:

{
  "mappings": {
    "wp-content/plugins/example-plugin": "../example-plugin"
  }
}

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 test:7.4
npm run 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.

Run tests for all PHP versions and end-to-end tests (see below).

npm run test:all

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.

---

If you’re on Windows, you might have to use Windows Subsystem for Linux to run the tests (see this comment).

End-to-end tests

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

Prepare

Before the first time you run it, install the browser engine.

npm run e2e:install

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 e2e

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 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 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