Skip to content

Forms

Jump to bottom
lorenzoli edited this page Jul 14, 2021 · 24 revisions

Form is a type of page which can contains forms, it's useful to create or edit data.

Configuration

Name Type Required Description
title string no Title displayed in form header
onlyView boolean no To define if the form will be only to view data
isEdit boolean no Required if the form is for edit an entity
putTranslationsFirst boolean no If true, the translatable fields are setted as first one
putFilesOnLanguages boolean no If true, user can choose which language have same files
api Object yes Api configuration
api.endpoint string yes Endpoint where to send/retrieve data
api.filter string no If enabled, form will call endpoint?filter=filter
submit Object no Submit configuration
submit.label string no Submit button label. Default: 'Save'
submit.confirm boolean no If true, a confirmation modal will be opened after submit
submit.refreshAfter boolean no If true, refresh data after submit (makes a GET request to endpoint)
submit.redirectAfter string no Path to redirect after submit (eg: /list)
submit.endpoint string no Endpoint where to send data (if you want to use a different one from api.endpoint)
fields Array yes Please see fields

Fields

Fields defines the structure of the form. Since ngx-backend support multi-language contents, the object fields has the following structure

"fields": {
  "base": [],
  "en": [],
  "it": [],
}

Where base is for non-multi-language fields (eg. select, files ...) and en, it, or another isoCode defined in your content-languages.

As you have noticed, this keys are arrays of fields. Each field has the following structure:

Name Type Required Description
type string yes Field type. Please see field types
label string yes Field label
key string yes Key of the field in the form, must be unique in the form
placeholder string no Placeholder
value any no Default value of the field
description string no Field description (appears under the field)
class string no Custom CSS class of the field
hidden boolean no If true, it will be a hidden field
disabled boolean no If true, it will be a disabled field (readonly)
validators Object no Please see validators
visibleOn Object no Please see visibleOn

Validators

Validators are useful to locally validate fields before submit the form. They are:

  • required
  • minLength (for strings)
  • maxLength (for strings)
  • pattern (for strings)
  • min (for numbers)
  • max (for numbers)

Validators can be set on fields like the following way:

...
"validators" {
  "required": true,
  "minLength": 4,
  "maxLength": 8,
  "pattern": "some_regex_pattern",
  "min": 0,
  "max: 100
}

VisibleOn

It can be used for show or hide field based on value of another form field.

VisibleOn property can be set on fields like the following way:

...
"visibleOn" {
  "fieldKeyName": "value"
}

Field types

Actually, ngx-backend supports the following field-types:

You can also add some "only View" fields:

Text

{
  "key": "name",
  "type": "text",
  "label": "Name"
}

Textarea

{
  "key": "description",
  "type": "textarea",
  "label": "Description",
  "options": {
    "editor": true
  }
}

Email

{
  "key": "email",
  "type": "email",
  "label": "Email"
}

Url

{
  "key": "url",
  "type": "url",
  "label": "Url"
}

Number

{
  "key": "number",
  "type": "number",
  "label": "Number"
}

Password

INFO: future support for confirmation check

{
  "key": "password",
  "type": "password",
  "label": "Password"
}

Checkbox

You can add the checked property to set a default value to the checkbox.

{
  "key": "visible",
  "type": "checkbox",
  "label": "Visible",
  "checked": true
}

Date

You can add the isDateTime property to choose if picker must select also time or only date. If you need your initial value to be some specific time, you can set the value property. You can also define max or min to handle the date selection.

All these strings must be correct for the Date.parse function, or they can be "now".

{
  "key": "date",
  "type": "date",
  "label": "Date",
  "value": "now",
  "min": "now",
  "max": "30 March 2018",
  "isDateTime": true
}

Date range

In this case, key is a fake key, it's just a name that the control need. The real properties will be fromKey and toKey, and they are expected to be DATE or DATE_TIME properties in your database.

{
  "type": "date_range",
  "key": "date_range", 
  "label": "Range",
  "isDateTime": true,
  "fromKey": "createdAt",
  "toKey": "updatedAt",
  "min": "now",
  "max": "30 March 2018",
  "validators": {
    "required": true
  }
}

Time table

Please see #95 for more information

{
  "type": "timetable",
  "key": "hours",
  "label": "Monday",
  "validators": {
    "required": true
  }
}

Select

You must add the options property to define the options of the select. It can be an array or and endpoint, but the data must have the following structure:

[
  {
    "id": 1,
    "text": "Value 1"
  }
]

You can add multiple property to define if the field can allow multiple selection. You can add dependsOn property to define if the field options depend on a form value (only if options are from endpoint) You can add lang property if you need the select to be for multi-lang contents

{
  "type": "select",
  "key": "key",
  "label": "Select values",
  "placeholder": "Select...",
  "options": "endpoint/options",
  "multiple": true,
  "lang": true,
  "dependsOn": ["anotherFieldKey", "anotherOneFieldKey"]
}

File upload

API:

  • Upload: POST request to options.api.upload to upload the file
  • Read: it's based on the field key (in the example is: image). So when the form makes the GET request to retrieve the entity data, the image property must have the following structure:
{
  "id": 1,
  "url": "http://www.examples.com/item.png",
  "type": "image/png"
}

Example:

{
  "key": "image",
  "type": "file",
  "label": "Image",
  "options": {
    "api": {
      "upload": "endoint/upload",
    },
    "multiple": true,
    "canDrag": true,
    "mediaLibrary": {
      "endpoint": "files"
    },
    "maxFiles": 1,
    "allowedContentTypes": [
      ".png",
      ".jpg",
      ".jpeg"
    ]
  }
}

Map

Since you will need two fields, you have to define two grouped fields

{
  "type": "map",
  "lat": {
    "key": "lat",
    "type": "number",
    "label": "Latitude"
  },
  "lng": {
    "key": "lng",
    "type": "number",
    "label": "Longitude"
  }
}

List details

{
  "key": "details",
  "type": "list_details",
  "label": "Details",
  "unique": true,
  "drag": true,
  "max": 7,
  "fields": [
    {
      "type": "select",
      "key": "item",
      "label": "Select item",
      "placeholder": "No item selected",
      "options": "item/options"
    },
    {
      "key": "name",
      "type": "text",
      "label": "Name"
    }
  ]
}

GeoSearch

Example:

{
	"type": "geosearch",
	"key": "geosearch",
	"label": "Cerca indirizzo"
}

Note: please use the string "geosearch" also as key for this type. The following field will be a search field that use Google Geocoding API and the value of the field will be:

{
	"address": "Strada Alvania, 57",
	"city": "Dogana",
	"country": "San Marino",
	"postcode": "47866",
	"lat": 43.986244,
	"lng": 12.986244
}

So for example, you can use this type to auto-complete another fields like address, postcode, city or the location of your map. Check this example to build a complete address form.

Only view fields

Separator

{
  "type": "separator",
  "title": "Some title",
  "icon": "fa fa-test",
  "text": "Some text"
}

Gallery

{
  "type": "gallery",
  "label": "Gallery",
  "options": {
    "endpoint": "documents/list",
    "download": true
  }
}

API

The form will make the following HTTP requests

  • GET /endpoint/:id (if is an edit form, this method will retrieve the current entity data)
  • PATCH /endpoint/:id (if is an edit form, this method will update the entity data)
  • PUT /endpoint (if is a creation form, this method will create a new entity)
Clone this wiki locally