https://github.com/tripu/performs

An HTML UI engine written in JavaScript
https://github.com/tripu/performs

declarative form html javascript language library programmatic ui

Last synced: 6 months ago
JSON representation

An HTML UI engine written in JavaScript

Host: GitHub
URL: https://github.com/tripu/performs
Owner: tripu
License: mit
Created: 2014-04-14T21:08:26.000Z (almost 12 years ago)
Default Branch: master
Last Pushed: 2024-09-12T12:24:57.000Z (over 1 year ago)
Last Synced: 2024-09-23T09:18:54.016Z (over 1 year ago)
Topics: declarative, form, html, javascript, language, library, programmatic, ui
Language: HTML
Homepage: https://tripu.github.io/Performs/
Size: 1.41 MB
Stars: 2
Watchers: 3
Forks: 2
Open Issues: 0
Metadata Files:
- Readme: .github/README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

[![npm version](https://img.shields.io/npm/v/performs.svg)](https://npmjs.org/package/performs)
[![Licence](https://img.shields.io/npm/l/performs.svg)](https://github.com/tripu/Performs/blob/master/LICENSE.md)
[![Build Status](https://app.travis-ci.com/tripu/Performs.svg?branch=master)](https://app.travis-ci.com/tripu/Performs)

# Performs

An HTML UI engine written in JavaScript.

* [Intro and examples](https://tripu.github.io/Performs/)
* [GitHub project](https://github.com/tripu/Performs)
* [npm package](https://www.npmjs.com/package/performs)

## Installation

Performs requires jQuery.

Server-side only:

```bash
$ npm i performs
```

Either server- or client-side:

```javascript
var Performs = require('performs').Performs;
```

## Usage

Let's assume the HTML document is this:

```html

Enter your details to create your new e-mail account!

```

And let's assume the URL `https://example.com/options.json` returns this JSON object:

```json
{
"schema": "performs-0.2.0",
"content": [
{
"id": "givenName",
"type": "string",
"label": "Given name",
"required": true
}, {
"id": "familyName",
"type": "string",
"label": "Family name",
"required": true
}, {
"id": "phone",
"type": "string",
"label": "Contact phone number"
}, {
"id": "email",
"type": "string",
"label": "Desired e-mail address",
"required": true,
"value": "{{$givenName$familyName@example.com}}"
}, {
"id": "subscribe",
"type": "boolean",
"label": "Subscribe to the newsletter",
"value": "true"
}, {
"id": "call",
"type": "boolean",
"label": "Get a free call from our marketing departament",
"enabled": "{{@phone}}",
"value": "true"
}
]
}
```

We can invoke Performs like this:

```javascript
var performs = new Performs();
performs.perform('https://example.com/options.json', '#userPreferences');
```

After Performs is done, new elements will created inside the initial (empty) form, and the resulting document will be:

```html

Enter your details to create your new e-mail account!

Given name

Family name

Contact phone number

Desired e-mail address

Subscribe to the newsletter

Get a free call from our marketing departament

```

…effectively *translating* the JSON object into an HTML form.

However, rendering a form programmatically like this wouldn't be that difficult, or particularly useful.
The interesting part is that Performs *understands* the relations between fields.
So for example, in the JSON above,

```
{
"id": "email",
"type": "string",
"label": "Desired e-mail address",
"required": true,
"value": "{{$givenName$familyName@example.com}}"
}
```

means:

* “Add a field with ID `email`, of type «string», showing this label”
* “This field *has to have* a value, or the form can't be submitted”
* **“Whenever the value of the field `givenName` or the value of the field `familyName` change, change automatically the value of `email`, according to
the expression specified.”**
For instance, the given name `John` and the family name `Smith` would produce the value `JohnSmith@example.com` for this field.

To achieve this, Performs adds event listeners to all necessary fields.
Input-only fields (like `givenName` here) will *notify* other fields whenever their values change.

Performs detects *cycles* (circular dependencies among fields), which are forbidden for obvious reasons, and alerts the users if there are any.

There are other useful features, like:

* Read-only fields, useful for output-only data, eg results of computations or informative messages
* Automatically disabling fields depending on expressions
* Hidden fields, useful to hold temporary results, or to send extra data along with the visible form

The expressions understood by Performs, like the one above, extend regular JavaScript syntax, so in theory they can get as complex as needed, and anything is
possible.
The basic syntax is:

* Curly brackets signal an expression, eg `{{2020 === new Date().getFullYear()}}`
* An ID prefixed by `@` refers to the *value* of that field, eg `{{@givenName.replace(/\s/, '') /* Remove spaces */}}`

## API

The class `Performs` exposes the following properties and methods.

### Property `version`

* Type: `String`
* Example: `'0.4.1'`

### Method `perform`

* Expects these arguments:
* `json`: `stream`, `document`, `file`, a `String` containing a URL, or a `String` containing JSON
* `form`: jQuery-like selector that identifies one (and only one) `` element, eg `'.fields'`, `'form#userInput'`
* Returns: `0` if everything goes OK
* Throws:
* `SyntaxError` if the number of arguments is not 2

## Test suite

```bash
$ npm t
```

At some point, `npm run test-ui` will work, too.

## Documentation

General documentation, introduction to the projects, and some live examples are under `doc/`.

Generated documentation (ie, the API reference) can be refreshed under `api/` running this command:

```bash
$ npm run jsdoc
```

## Credits

This project is licensed [under the terms of the MIT license](LICENSE.md).

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/tripu/performs

Awesome Lists containing this project

README