This project started as a CloudFest Hackathon 2024 project. It aims to elevate the possibilities JSON schema offers and utilize it for easier web form and meta fields development.
Project page: https://hackathon.cloudfest.com/project/json-schema-field-form-renderer/
{
"team": {
"name": "Syntax Errors",
"anatem": "If you're happy and you know it - SYNTAX ERROR!",
"leads": [
{"name": "Lars Gersmann", "url": "https://github.com/lgersman"},
{"name": "Daniel Bachhuber", "url": "https://github.com/danielbachhuber"}
],
"collaborators": [
{
"name": "Adam Zielinski",
"url": [
"https://github.com/adamziel",
"https://www.linkedin.com/in/adamziel"
]
},
{"name": "Anja Lang", "url": "https://github.com/AnjaLang"},
{"name": "Michael Schmitz", "url": "https://github.com/Bl4d3s"},
{"name": "Thomas Rose", "url": "https://github.com/codeispoetry"},
{"name": "Marko Feldmann", "url": "https://github.com/DerHerrFeldmann"},
{"name": "Fabian Genes", "url": "https://github.com/genesfa"},
{
"name": "Jan Vogt",
"url": [
"https://www.linkedin.com/in/janvogt",
"https://github.com/janvogt"
]
},
{"name": "Lucisu", "url": ""},
{"name": "Max Andre", "url": "https://github.com/Max-eMundo"},
{"name": "Marcel Schmitz", "url": "https://github.com/schmitzoide"},
{
"name": "Milana Cap",
"url": [
"https://github.com/zzap",
"https://developerka.org"
]
},
{"name": "Julian Haupt", "url": "https://jsonformseditor.io/"},
{"name": "Dennis Snell", "url": "https://github.com/dmsnell"}
]
}
}This Monorepo contains example uses cases of JSON Schema in WordPress.
It demo's the use of JSON Schema as abstraction for user interfaces in WordPress utilizing react-jsonschema-form.
-
see react-jsonschema-form Documentation introducing the concept and usage react-jsonschema-form.
-
see react-jsonschema-form Playground showcasing the capabilities of react-jsonschema-form by man examples.
See What is the idea behind this project? for more explanations.
The sub packages propose just ideas - they are not meant to be implemented as is. I am not going to believe that we can implement all of them. I think it would better better to focus on the most important ones and do them well. If you have any suggestions/improvements/ideas please feel free to start discussing it.
We will use VS Code as our development environment. VS Code is widely used in Web Development due to its sleek developer experience. It comes with preconfigured launch configurations for debugging, required extensions and settings, among other features.
-
Development Tools
-
You will need Git to clone the repository and to push your changes.
-
Docker is a prerequisite of wp-env, a tool for managing WordPress development environments. It is also used to build and run the Docker containers that power the development environment.
I would prefer to use the WordPress Playground over wp-env but it currently lacks a mandatory development feature - PHP debugging support.
-
pnpm is a drop-in replacement for npm. It is fully compatible with the npm registry and can be used with any NodeJS project.
-
exponential faster than npm/yarn & Co. If you once use it, you will never miss it again - i swear 🤞
-
features automatic provisioning of the configured NodeJS version - you don't need to install a specific NodeJS version manually. Say Goodbye to
nvm,voltaand friends ❤️ - you will never need it anymore. -
It is tailored for monorepos first with it's exceptional workspace features.
-
-
It is the default shell on most Linux distributions and macOS. On Windows, we use the Windows Subsystem for Linux (WSL) to run bash.
There are myriads of different other scripting options but we ideally need to pick one where we all together feel comfortable with.
@IMPROVEMENT: Tools could be prepackaged into a vscode dev container.
-
-
Get developer access to the repository by contacting the owner of the repository.
-
Clone the repository :
git clone git@github.com:IONOS-WordPress/workspace/cfhack2024-wp-react-jsonschema-form
the provided .npmrc assumes that the
bashshell is already available at/bin/bash. Ensure that this is the case or adjust the.npmrcfile accordingly (you can get the path to yourbashexecutable usingwhich bash).
-
Run
pnpm installto install the required dependencies.At first start
pnpmwill take a few seconds to download also the configured NodeJS version. Please be patient - it will be much more faster on subsequent runs. -
Run
pnpm buildto build the project. -
Run
pnpm startto start the development environment.This will start a local WordPress using a preconfigured wp-env environment.
The start script will also generate the vscode settings file (
.vscode/settings.json) for PHP Intelephense support and appropriate launch configuration file (.vscode/launch.json) for instant PHP debugging.see
.wp-env-afterStart.shfor the script that generates the vscode settings and launch configuration files. -
Open the WordPress admin dashboard by visiting http://localhost:8888/wp-admin
Use the following credentials to log in:
- Username:
admin - Password:
password
- Username:
Each of the use cases is located in a separate folder in packages/wp-content/plugins/* / packages/wp-content/themes/* directory as a separate sub project. This Monorepo structure allows us to work on multiple use cases in parallel.
Each sub project contains a README.md file with further instructions.
I have participated in coding sessions with people doing Typescript since a year or longer. It took them half an hour to develop a type definition for an event handler (at the extreme).
My opinion : We have limited time to develop the project and we do not need to spend time on this issue. I would tend to use the time to develop functionality and not type definitions. Personally I really like how Rich Harris, maintainer of Svelte thinks about Typescript.
I know there is a lot of discussion going on about this topic.
We should getting things done fast and concentrate on the most important thing : hacking the functionality. Understanding Typescript syntax can be challenging and I would want to avoid locking people out just because they don't-know/have-limited-knowledge about Typescript.
This project has no linting / formatting configured to keep the amount of configuration low.
Be nice to each other and don't use extravagant formatting.
Same reason as for Typescript - not anybody knows about CSS-in-JS.
But anybody is free to use PostCSS since it is everywhere used in the Gutenberg ecosystem.
I used to work with Gitflow for a long time. But I have to admit that it is a bit too complex for small projects. I would prefer to use a trunk based workflow for this project.
I would encourage participants to write commit message according to Conventional Commits to ensure a consistent commit message format.
I am a big fan of changesets for creating human readable changelogs but I would skip it for this project since we do not plan to release anything.
Since the project is a monorepo, we can work on multiple use cases in parallel. These isolated sub packages free us (mostly) from the need to coordinate changes across the whole project.
Anyway, we should follow some best practices to ensure that we don't break the whole project :
-
Don't work directly on the
trunkbranch if possible. -
Create a new branch for each change (feature, bug fix, etc) and merge it back whenever you think it will not break the whole project and is working.
-
I would propose that we don't need to use a pull requests for this project - it costs too much time.
- If you are really unsure if your branch is ready to merge back, you can ask a team mate for a review.
The project is set up to use VS Code as the development environment. It comes with preconfigured launch configurations for debugging, required extensions and settings, among other features.
wp-env is even already preconfigured to support debugging of PHP code.
Plugin/Theme sources are also compiled with debug informations. So you can easily debug into your own sources using the browser.
Gutenberg is compiled with debug informations when wp-env is starting up. This means you can even debug from your own JS/CSS into the Gutenberg sources.
The project setup will always build code including debugging information. Everything is compiled for easy debugging since we are here for hacking :-)
-
pnpm installwill install the required dependencies for the project. -
Have a look at the scripts section of the root package.json for more available scripts
Examples:
-
build all sub packages :
pnpm build -
start wp-env :
pnpm run start -
stop wp-env :
pnpm run stop -
destroy wp-env :
pnpm run destroy -
clean build artifacts :
pnpm run cleanThis interactive script will only remove the build artifacts. It will not remove the
node_modulesdirectory. -
clean every generated / downloaded artifact :
pnpm run distcleanThis interactive script will remove the
node_modules/.pnpm-storedirectories and all build artifacts.Directory
wp-env-homeis managed bywp-env. Executepnpm destroybefore executingpnpm run distclean -
watch and build js/css :
pnpm run devThis command will watch the js/css sources and rebuild them on changes. Perfect when you working on just JS/CSS sources.
The only thing to do is reloading your wordpress tab in the browser.
Why not using HMR ? Because multiple parallel watching wp-scripts start instances are not supported yet by HMR via
wp-scripts -
stop wp-env :
pnpm run stop -
execute individual wp-env commands :
pnpm run wp-env <command>Example :
pnpm run wp-env run cli wp plugin list
-
-
individual package scripts can be executed
-
from the Monorepo root directory using
pnpm --filter "<sub-package-name>" run <sub-package-script>in the package directoryExample:
pnpm --filter "@cfhack2024-wp-react-jsonschema-form/form-block" run build -
by changing to the package directory and running
pnpm run <sub-package-script>Example:
cd packages/form-block && pnpm run build
-
Remember - you only see the last compiles js/css sources.
So whenever you pull or checkout a branch, execute pnpm build to ensure that you are working with the latest sources.
Even if you changed any JS/CSS source locally - you need to built it before seeing any changes
@wordpress/components is a huge library providing a lot of components.
Checkout the Gutenberg Storybook to see all the available components and their options.
By default WordPress provides production ready code which is minified and hard to read. Gutenberg is part of WordPress and is no exception. And so @wordpress/components.
That's why this project is set up with the latest Gutenberg including debug information. This means you can easily debug into the Gutenberg components.
To debug into React you can use the browser's developer tools. You can set breakpoints and debug into JS code.
It's highly recommended to install React Developer Tools in your browser. It will ease React debugging a lot.
Technical documentation can be found in docs folder.
Read the docs!
Ask your team members if you are stuck !
They are here to help you and you are not alone.
Happy coding !
JSON Schema Field/Form Renderer for WordPress is a free software, and complete code inside it is released under the terms of the GNU General Public License version 3 or later. This does not apply to Google fonts and other 3rd party assets - their original license applies.