Tangible Fields

React-based form fields library

Use in a plugin

To use the module inside the plugin, you need to update your composer.json. It's required to add the framework in the repositories list as well even if your project dosen't use it directly, because it's used by the fields module and repositories needs to be defined at the root:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "[email protected]:tangibleinc/fields.git"
    },
    {
      "type": "vcs",
      "url": "[email protected]:tangibleinc/framework.git"
    }
  ],
  "require": {
    "tangible/fields": "dev-main"
  },
  "minimum-stability": "dev"
}

The module can then be installed in your project using:

composer install

The module needs to be manually required in your code:

require_once __DIR__ . '/vendor/tangible/fields/index.php';

You can then access the module from anywhere using this function:

$fields = tangible_fields();

Develop

Prerequisites: Git, Node (version 18 and above)

git clone [email protected]:tangibleinc/fields.git
cd fields

Install dependencies:

npm ci

JS and CSS

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

npm run start

For details see Tests below.

Dev dependencies

Install dev dependencies such as third-party plugins. This is optional.

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

PHPUnit

This module comes with a suite of unit and integration tests.

Method 1: Cloning wordpress-develop.git (Previous)

You will need a copy of https://github.com/WordPress/wordpress-develop.git available. You can run git clone https://github.com/WordPress/wordpress-develop.git in this directory as this is where the bootstrap script expects it to be by default (the WORDPRESS_DEVELOP_DIR environment variable overrides this path).

Bootstrap the WordPress development environment by running npm i; npm run build:dev. Then copy wp-tests-config-sample.php to wp-tests-config.php inside the wordpress-develop directory and set the database credentials as needed. WARNING! This database is dropped everytime the tests run. Do not use a production database.

To install PHPUnit with this method, run composer install. You'll need composer installed globally.

Run vendor/bin/phpunit to launch the tests and hope for all green ;)

Unit and integration tests are mixed together (as is usual in WordPress) and can be found in tests/phpunit/cases and its subdirectories. Every case is in a class extending a TestCase, every test should be a public function starting with "test". We prefer snake case.

The DOING_TANGIBLE_TESTS constant is defined during tests and can be used to modify core behavior as needed.

Coverage can be had using vendor/bin/phpunit --coverage-text (requires the XDebug extension to be available and enabled) or vendor/bin/phpunit --coverage-html=coverage for an HTML version.

https://docs.phpunit.de/en/9.6/ for more information.

Method 2: Using wp-env (Recommended)

Alternatively, you can use the wp-env tool to serve local dev and test sites, optionally switching between multiple PHP versions.

The test environment is started by running:

npm run start

This uses wp-env, which 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 (default user admin with password); 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 in the container.

npm run composer:install

To run the tests:

npm run test:8.2
npm run test:7.4

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.

To stop the Docker process:

npm run stop

To “destroy” and remove cache:

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 start

This repository includes NPM scripts to run the tests with PHP versions 8.2 and 7.4. We need to maintain compatibility with PHP 7.4, as WordPress itself only has “beta support” for PHP 8.x. 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).

Jest

We rely on Jest to test the frontend side of the module:

npm install
npm run jest:test

Playwright

End-to-end tests with Playwright.

npm run e2e

Storybook

Frontend workshop for building UI components and pages in isolation with Storybook

Start Storybook in dev mode, to watch files and rebuild.

npm run storybook

It serves on a random port by default. To specify a port number:

npm run storybook -- -p 6006

Build Storybook for publishing.

npm run storybook:build

Render fields

To render a field, we use $fields->render_field. It takes 2 arguments:

$fields->render_field(
  'field_name',
  $args,
);

The render_field method returns an html div, like this one:

<div id="tangible-field-{{name}}-{{uniqid}}"></div>

It also enqueue our JavaScript dependencies, which will use this span to render the field on the client side.

Render elements

The difference between a field and an element is that the element won't have any value.

To render an element, we use $fields->render_element. It takes 2 arguments:

$fields->render_element(
  'field_name',
  $args,
);

The render_element method returns an html div, like this one:

<div id="tangible-element-{{name}}-{{uniqid}}"></div>

It also enqueue our JavaScript dependencies, which will use this span to render the field on the client side.

References

For the complete list of field types and the associated syntax, see documentation on this site.

This is not ideal and we will try to move back the documentation in the module at some point.