@jaspero/form-ui
v0.0.1
Published
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) ![Release](https://github.com/Jaspero/schema-forms/workflows/Release/badge.svg) [![NPM
Downloads
3
Readme
@jaspero/form-builder
Installation
To install this library, run:
$ npm install --save @jaspero/form-builder
Provide services and values
- Provide necessary services
- StorageService - Used for storing files when
FileComponent
,ImageComponent
orGalleryComponent
are used. - DbService - Used for fetching referenced relations from your server in runtime
- Provide necessary values
- STORAGE_URL - Root URL for fetching files from your server
- ROLE - Segments and fields can be conditionally shown/hidden if the value of the role matches what is expected in the schema
Styles
In order to make the generated forms customizable, this library doesn't provide any default styles. This means that the styles need to be loaded in the root of your application. A good starting point are the example styles provided here.
Composing Forms
Definitions
This configuration is used for defining addition field based options. Changing the label or
what component is used to represent the field in the form. The Definitions
interface looks like this:
| Property | Type | Description | Default |
| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| label | string | Label of the field | uses the name of the property |
| hint | string | Shows a hint below the field if defined | - |
| defaultValue | any | What the value of the field should be if empty | - |
| component | object | {type: string, configuration: any}
- The type
defines the field to use and the configuration
is used for any additional component specific options | What ever is the default for the property type |
Component Types
| Name | Selector | Description | Configuration Options |
| ----- | -------- | -------------- | ----------------------------------- |
| Input | input | A simple input | {type: 'text', 'number', 'email'}
|
Example
{
"name": {
"label": "Name",
"defaultValue": "John"
},
"age": {
"label": "Age",
"component": {
"type": "slider"
}
}
}
Adding custom fields
- Create a new component that extends
FieldComponent
. You should injectCOMPONENT_DATA
in order to receiveFieldData
, most importantly the underliningFormControl
. - Map the newly added component through the
CUSTOM_FIELDS
provider e.g.providers: [{ provide: CUSTOM_FIELDS useValue: { 'new-component': NewComponent } }]
- You can now use the new field in a forms
definitions
.
Adding custom components
- Create a new component that extends
CustomComponent
. It receives theCUSTOM_COMPONENT_DATA
which has theform
andid
properties. - Map the newly added component through the
CUSTOM_COMPONENTS
provider e.g.providers: [{ provide: CUSTOM_COMPONENTS, useValue: { example: ExampleComponent } }]
- You can now use the new component in a segment e.g.
"segments": [{ "components": [{"selector": "example"}] }]
Handling Array
The form builder supports both arrays of primitives and object arrays.
Object Arrays
The following is required to render an object array:
- An object array defined in the schema:
{ "addresses": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string" }, "address": { "type": "string" } } } } }
- A dedicated segment with an array property:
{ "segments": [{ "array": "/addresses", "fields": [ "/city", "/address" ] }] }
- You can also optionally define options for each field in the definitions:
{ "definitions": { "addresses/city": { "label": "City" } } }
Primitive Arrays
Primitive arrays can be displayed in two variations as a dedicated segment or as a field.
If the property is defined with out an items
value. It's expected to be used as a field.
In that case the following components can be used:
- select in combination with
{multiple: true}
- chips
- draggable-list
If an items value is defined then it's expected to be rendered as its own segments.
Plugins
Official plugins
TinyMCE WYSIWYG Editor
This plugin registers a field tinymce
for rendering the TinyMCE WYSIWYG Editor.
Set up
- Install the plugin
npm i --save @jaspero/fb-tinymce
- Add the plugin module
TinymceModule
to your module - Install tinymce
npm i --save tinymce
- Add the following to the
assets
array inangular.json
{ "glob": "**/*", "input": "node_modules/tinymce/themes/silver", "output": "/themes/silver" }, { "glob": "**/*", "input": "node_modules/tinymce/skins/ui/oxide", "output": "/skins/ui/oxide" }, { "glob": "**/*", "input": "node_modules/tinymce/skins/content/default", "output": "/skins/content/default" }, { "glob": "**/*", "input": "node_modules/tinymce/plugins", "output": "/plugins" }, { "glob": "**/*", "input": "node_modules/tinymce/icons", "output": "/icons" }
- Add the tinymce script to the
scripts
array inangular.json
"./node_modules/tinymce/tinymce.min.js"
- You can optionally add/extend your commonjs dependencies whitelist to get rid of console warnings
"allowedCommonJsDependencies": [ "json-pointer", "tinymce/plugins/wordcount", "tinymce/plugins/table", "tinymce/plugins/lists", "tinymce/plugins/print", "tinymce/plugins/link", "tinymce/plugins/image", "tinymce/plugins/imagetools", "tinymce/plugins/fullscreen", "tinymce/plugins/code", "tinymce/plugins/autolink", "tinymce/plugins/advlist" ]
Page Builder
Form UI
Set up
- Install the plugin
npm i --save @jaspero/fb-page-builder
- Add the plugin module
PageBuilderModule
to your module
Development
Creating a plugin
- Run
ng g library [plugin-name]
- Add
@jaspero/
prefix in the projectspackage.json
- Add a
release
property as well. Example fromtincymce
plugin."release": { "pkgRoot": "../../dist/@jaspero/fb-tinymce", "branch": "master", "verifyConditions": [ "@semantic-release/changelog", "@semantic-release/npm", "@semantic-release/git" ], "prepare": [ "@semantic-release/changelog", "@semantic-release/npm", "@semantic-release/git" ], "publish": [ "@semantic-release/npm", [ "@semantic-release/github", { "assets": [ "dist/@jaspero/fb-tinymce" ] } ] ], "plugins": [ "@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator" ] }
- Create
ng-package.prod.json
example from tinymce{ "$schema": "../../node_modules/ng-packagr/ng-package.schema.json", "dest": "../../dist/@jaspero/fb-tinymce", "lib": { "entryFile": "src/public-api.ts" } }
- In
angular.json
extend thearchitect.configurations.production
withng-package.prod.json
"configurations": { "production": { "tsConfig": "projects/page-builder/tsconfig.lib.prod.json", "project": "projects/page-builder/ng-package.prod.json" } }
- If you need to register fields do it in the plugins module like this:
export class TinymceModule { constructor( private ctx: FormBuilderContextService ) { this.ctx.registerField( 'tinymce', TinymceComponent ); } }
- Add build scripts for the library in to the root
package.json
- Build the library and publish an initial version manually. This is required because since it's a scoped
package it needs to be explicitly flagged as public. You can do this by running
npm publish --access public
indist/@jaspero/[package-name]
.
License
MIT © Jaspero Ltd