{"id":17500438,"url":"https://github.com/tripu/performs","last_synced_at":"2025-09-22T02:32:43.215Z","repository":{"id":16033051,"uuid":"18776844","full_name":"tripu/Performs","owner":"tripu","description":"An HTML UI engine written in JavaScript","archived":false,"fork":false,"pushed_at":"2024-09-12T12:24:57.000Z","size":1476,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-09-23T09:18:54.016Z","etag":null,"topics":["declarative","form","html","javascript","language","library","programmatic","ui"],"latest_commit_sha":null,"homepage":"https://tripu.github.io/Performs/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"mttkay/signpost","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tripu.png","metadata":{"files":{"readme":".github/README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-04-14T21:08:26.000Z","updated_at":"2024-09-12T12:24:54.000Z","dependencies_parsed_at":"2023-01-13T18:40:18.914Z","dependency_job_id":"7ad9cfcf-b840-4ef5-bd64-00920e55d5e7","html_url":"https://github.com/tripu/Performs","commit_stats":{"total_commits":175,"total_committers":5,"mean_commits":35.0,"dds":0.5542857142857143,"last_synced_commit":"e16036b723900932b4962c631ed0b34a0a577080"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tripu%2FPerforms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tripu%2FPerforms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tripu%2FPerforms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tripu%2FPerforms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tripu","download_url":"https://codeload.github.com/tripu/Performs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233819580,"owners_count":18735302,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["declarative","form","html","javascript","language","library","programmatic","ui"],"created_at":"2024-10-19T18:11:31.916Z","updated_at":"2025-09-22T02:32:37.828Z","avatar_url":"https://github.com/tripu.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://img.shields.io/npm/v/performs.svg)](https://npmjs.org/package/performs)\n[![Licence](https://img.shields.io/npm/l/performs.svg)](https://github.com/tripu/Performs/blob/master/LICENSE.md)\n[![Build Status](https://app.travis-ci.com/tripu/Performs.svg?branch=master)](https://app.travis-ci.com/tripu/Performs)\n\n# \u003cspan style=\"color: #c00000;\"\u003ePer\u003c/span\u003eforms\n\nAn HTML UI engine written in JavaScript.\n\n* [Intro and examples](https://tripu.github.io/Performs/)\n* [GitHub project](https://github.com/tripu/Performs)\n* [npm package](https://www.npmjs.com/package/performs)\n\n## Installation\n\n\u003cspan style=\"color: #c00000;\"\u003ePer\u003c/span\u003eforms requires jQuery.\n\nServer-side only:\n\n```bash\n$ npm i performs\n```\n\nEither server- or client-side:\n\n```javascript\nvar Performs = require('performs').Performs;\n```\n\n## Usage\n\nLet's assume the HTML document is this:\n\n```html\n\u003chtml\u003e\n  \u003cbody\u003e\n    \u003cp\u003eEnter your details to create your new e-mail account!\u003c/p\u003e\n    \u003cform id=\"userPreferences\"\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nAnd let's assume the URL `https://example.com/options.json` returns this JSON object:\n\n```json\n{\n  \"schema\": \"performs-0.2.0\",\n  \"content\": [\n    {\n      \"id\":       \"givenName\",\n      \"type\":     \"string\",\n      \"label\":    \"Given name\",\n      \"required\": true\n    }, {\n      \"id\":       \"familyName\",\n      \"type\":     \"string\",\n      \"label\":    \"Family name\",\n      \"required\": true\n    }, {\n      \"id\":       \"phone\",\n      \"type\":     \"string\",\n      \"label\":    \"Contact phone number\"\n    }, {\n      \"id\":       \"email\",\n      \"type\":     \"string\",\n      \"label\":    \"Desired e-mail address\",\n      \"required\": true,\n      \"value\":    \"{{$givenName$familyName@example.com}}\"\n    }, {\n      \"id\":       \"subscribe\",\n      \"type\":     \"boolean\",\n      \"label\":    \"Subscribe to the newsletter\",\n      \"value\":    \"true\"\n    }, {\n      \"id\":       \"call\",\n      \"type\":     \"boolean\",\n      \"label\":    \"Get a free call from our marketing departament\",\n      \"enabled\":  \"{{@phone}}\",\n      \"value\":    \"true\"\n    }\n  ]\n}\n```\n\nWe can invoke Performs like this:\n\n```javascript\nvar performs = new Performs();\nperforms.perform('https://example.com/options.json', '#userPreferences');\n```\n\nAfter Performs is done, new elements will created inside the initial (empty) form, and the resulting document will be:\n\n```html\n\u003chtml\u003e\n  \u003cbody\u003e\n    \u003cp\u003eEnter your details to create your new e-mail account!\u003c/p\u003e\n    \u003cform id=\"userPreferences\" class=\"pf-processed\"\u003e\n      \u003clabel for=\"pf-givenName\"\u003eGiven name\u003c/label\u003e\n      \u003cinput id=\"pf-givenName\" type=\"text\" required\u003e\n      \u003clabel for=\"pf-familyName\"\u003eFamily name\u003c/label\u003e\n      \u003cinput id=\"pf-familyName\" type=\"text\" required\u003e\n      \u003clabel for=\"pf-phone\"\u003eContact phone number\u003c/label\u003e\n      \u003cinput id=\"pf-phone\" type=\"text\"\u003e\n      \u003clabel for=\"pf-email\"\u003eDesired e-mail address\u003c/label\u003e\n      \u003cinput id=\"pf-email\" type=\"text\" required\u003e\n      \u003clabel\u003e\n        \u003cinput id=\"pf-subscribe\" type=\"checkbox\" checked\u003e\n        Subscribe to the newsletter\n      \u003c/label\u003e\n      \u003clabel\u003e\n        \u003cinput id=\"pf-call\" type=\"checkbox\" checked disabled\u003e\n        Get a free call from our marketing departament\n      \u003c/label\u003e\n    \u003c/form\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n\u0026hellip;effectively *translating* the JSON object into an HTML form.\n\nHowever, rendering a form programmatically like this wouldn't be that difficult, or particularly useful.\nThe interesting part is that Performs *understands* the relations between fields.\nSo for example, in the JSON above,\n\n```\n{\n  \"id\":       \"email\",\n  \"type\":     \"string\",\n  \"label\":    \"Desired e-mail address\",\n  \"required\": true,\n  \"value\":    \"{{$givenName$familyName@example.com}}\"\n}\n```\n\nmeans:\n\n* \u0026ldquo;Add a field with ID `email`, of type \u0026laquo;string\u0026raquo;, showing this label\u0026rdquo;\n* \u0026ldquo;This field *has to have* a value, or the form can't be submitted\u0026rdquo;\n* **\u0026ldquo;Whenever the value of the field `givenName` or the value of the field `familyName` change, change automatically the value of `email`, according to\nthe expression specified.\u0026rdquo;**\nFor instance, the given name `John` and the family name `Smith` would produce the value `JohnSmith@example.com` for this field.\n\nTo achieve this, Performs adds event listeners to all necessary fields.\nInput-only fields (like `givenName` here) will *notify* other fields whenever their values change.\n\nPerforms detects *cycles* (circular dependencies among fields), which are forbidden for obvious reasons, and alerts the users if there are any.\n\nThere are other useful features, like:\n\n* Read-only fields, useful for output-only data, eg results of computations or informative messages\n* Automatically disabling fields depending on expressions\n* Hidden fields, useful to hold temporary results, or to send extra data along with the visible form\n\nThe 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\npossible.\nThe basic syntax is:\n\n* Curly brackets signal an expression, eg `{{2020 === new Date().getFullYear()}}`\n* An ID prefixed by `@` refers to the *value* of that field, eg `{{@givenName.replace(/\\s/, '') /* Remove spaces */}}`\n\n## API\n\nThe class `Performs` exposes the following properties and methods.\n\n### Property `version`\n\n* Type: `String`\n* Example: `'0.4.1'`\n\n### Method `perform`\n\n* Expects these arguments:\n * `json`: `stream`, `document`, `file`, a `String` containing a URL, or a `String` containing JSON\n * `form`: jQuery-like selector that identifies one (and only one) `\u003cform\u003e` element, eg `'.fields'`, `'form#userInput'`\n* Returns: `0` if everything goes OK\n* Throws:\n * `SyntaxError` if the number of arguments is not 2\n\n## Test suite\n\n```bash\n$ npm t\n```\n\nAt some point, `npm run test-ui` will work, too.\n\n## Documentation\n\nGeneral documentation, introduction to the projects, and some live examples are under `doc/`.\n\nGenerated documentation (ie, the API reference) can be refreshed under `api/` running this command:\n\n```bash\n$ npm run jsdoc\n```\n\n## Credits\n\nCopyright © 2014–2020 tripu ([`t@tripu.info`](mailto:t@tripu.info), [`https://tripu.info`](https://tripu.info/))\n\nThis project is licensed [under the terms of the MIT license](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftripu%2Fperforms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftripu%2Fperforms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftripu%2Fperforms/lists"}