https://github.com/formio/core
The Form.io Core Javascript Framework
https://github.com/formio/core
Last synced: about 1 year ago
JSON representation
The Form.io Core Javascript Framework
- Host: GitHub
- URL: https://github.com/formio/core
- Owner: formio
- License: mit
- Created: 2021-02-25T04:53:28.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-06-25T20:23:34.000Z (about 1 year ago)
- Last Synced: 2025-06-25T21:29:51.026Z (about 1 year ago)
- Language: TypeScript
- Homepage: https://formio.github.io/core
- Size: 8.12 MB
- Stars: 12
- Watchers: 12
- Forks: 10
- Open Issues: 5
-
Metadata Files:
- Readme: Readme.md
- Changelog: Changelog.md
- License: LICENSE.txt
Awesome Lists containing this project
README
## Form.io Core Data Processing Engine
This library is the core data processing engine behind the Form.io platform. It is a set of isomorphic APIs that allow for complex orchestration (e.g. calculated values, conditionally hidden components, complex logic, etc.) of JSON form and submission definitions.
### Usage
@formio/core is available as an npm package. You can install it using the package manager of your choice:
```bash
# npm
npm install --save @formio/core
# yarn
yarn add @formio/core
```
### Development
Processing form and submission data efficiently has two distinct requirements:
1. A form- and data-aware traversal of the form JSON; and
2. A set of processing functions to derive (and occasionally mutate) form state.
The first requirement is accomplished via the `eachComponentData` and `eachComponentDataAsync` functions, which traverse each form component JSON and provide a callback parameter by which to interact with the component and it's corresponding submission data parameter(s).
The second requirement is accomplished via "processors" (e.g. `calculate`, `validate`, or `hideChildren`) which are functions that, given an evaluation `context`, operate on, derive state from, and occasionally mutate the form state and submission values depending on the internal form logic, resulting in a `scope` object that contains the results of each processor keyed by component path.
To run a suite of processor functions on a form and a submission, the `process` family of functions take a form JSON definition, a submission JSON definition, and an array of processor function as an arguments (encapsulated as a `context` object which is passed through to each callback processor function).
```js
import { processSync } from '@formio/core';
const form = {
display: 'form',
components: [
{
type: 'textfield',
key: 'firstName',
label: 'First Name',
input: true,
},
{
type: 'textfield',
key: 'lastName',
label: 'Last Name',
input: true,
},
{
type: 'button',
key: 'submit',
action: 'submit',
label: 'Submit',
},
],
};
const submission = {
data: {
firstName: 'John',
lastName: 'Doe',
},
};
const addExclamationSync = (context) => {
const { component, data, scope, path, value } = context;
if (!scope.addExclamation) scope.addExclamation = {};
let newValue = `${value}!`;
// The scope is a rolling "results" object that tracks which components have been operated on by which processor functions
scope.addExclamation[path] = true;
_.set(data, path, newValue);
return;
};
// The context object is mutated depending on which component is being processed; after `processSync` it will contain the processed components and data
const context = {
components: form.components,
data: submission.data,
processors: [{ processSync: addExclamationSync }],
scope: {},
};
// The `process` family of functions returns the scope object
const resultScope = processSync(context);
console.assert(resultScope['addExclamation']?.firstName === true);
console.assert(resultScope['addExclamation']?.lastName === true);
console.assert(submission.data.firstName === 'John!');
console.assert(submission.data.lastName === 'Doe!');
```
### Debugging
Debugging the Form.io Enterprise Server can be challenging because of the added complexity of the @formio/vm library (which sandboxes the @formio/core processors for safe execution of untrusted JavaScript on the server). [Instructions on how to debug can be found here.](https://formio.atlassian.net/wiki/spaces/SD/pages/184025089/Debugging+formio+core)
### Experimental
This library contains experimental code (found in the `src/experimental` directory or via an import, e.g. `import { Components } from @formio/core/experimental`) that was designed to update and replace the core rendering engine behind the Form.io platform. It is a tiny (12k gzipped) rendering framework that allows for the rendering of complex components as well as managing the data models controlled by each component.
#### Usage
To use this experimental framework, you will first need to install the parent library into your application.
```bash
# npm
npm install --save @formio/core
# yarn
yarn add @formio/core
```
Next, you can create a new component as follows.
```js
import { Components } from '@formio/core/experimental';
Components.addComponent({
type: 'h3',
template: (ctx) => `
${ctx.component.header}
`,
});
```
And now this component will render using the following.
```js
const header = Components.createComponent({
type: 'h3',
header: 'This is a test',
});
console.log(header.render()); // Outputs
This is a test
```
You can also use this library by including it in your webpage scripts by including the following.
```
```
After you do this, you can then do the following to create a Data Table in your website.
```js
FormioCore.render(
document.getElementById('data-table'),
{
type: 'datatable',
key: 'customers',
components: [
{
type: 'datavalue',
key: 'firstName',
label: 'First Name',
},
{
type: 'datavalue',
key: 'lastName',
label: 'First Name',
},
],
},
{},
{
customers: [
{ firstName: 'Joe', lastName: 'Smith' },
{ firstName: 'Sally', lastName: 'Thompson' },
{ firstName: 'Mary', lastName: 'Bono' },
],
},
);
```