npm package: @senx/discovery-plugin-form
Description: Discovery plugin for form
Author: SenX
Latest version: 0.1.0

# Discovery Form

This is a declarative form widget dedicated to [Discovery](https://discovery.warp10.io/). 

## Usage

### In a Web Environment

#### With NPM/Yarn

    $ npm install @senx/discovery-widgets
    $ npm install @senx/discovery-plugin-form

#### With CDN

```html
<script nomodule src="https://unpkg.com/@senx/discovery-widgets/dist/discovery/discovery.js"></script>
<script type="module" src="https://unpkg.com/@senx/discovery-widgets/dist/discovery/discovery.esm.js"></script>


<script type="module" src="https://unpkg.com/@senx/discovery-plugin-form/dist/discovery-plugin-form/discovery-plugin-form.esm.js"></script>
<script nomodule src="https://unpkg.com/@senx/discovery-plugin-form/dist/discovery-plugin-form/discovery-plugin-form.js"></script>

```

#### Usage

```html

<html lang="en">
<head>
  <title>Test</title>
</head>
<body>
<discovery-dashboard url="https://warp.senx.io/api/v0/exec" dashboard-title="Test">
{
  'title' 'Test'
  'description' 'Dashboard test'
  'tiles' [
    {
      'title' 'test'
      'x' 0 'y' 0 'w' 12 'h' 4
      'type' 'form'
      'macro' <%
        {
          'events' [ { 'tags' [ 'test' ] 'type' 'variable' 'selector' 'myVar' } ]
          'data' [
            {
              'name' 'make' 'label' 'Choose a maker'
              'type' 'list'
              'data' [ "Toyota" "BMW" "Honda" "Ford" "Chevy" "VW" ]
              'required' T
              'options' { 'col' 4 }
            }
      %>
    }
  ]
}
</discovery-dashboard>
<script nomodule src="https://unpkg.com/@senx/discovery-widgets/dist/discovery/discovery.js"></script>
<script type="module" src="https://unpkg.com/@senx/discovery-widgets/dist/discovery/discovery.esm.js"></script>
<script type="module" src="https://unpkg.com/@senx/discovery-plugin-form/dist/discovery-plugin-form.esm.js"></script>
<script nomodule src="https://unpkg.com/@senx/discovery-plugin-form/dist/discovery-plugin-form.js"></script>

</body>
</html>
```


## General options

- `options.button.label`: Custom label for the submit button, "Ok" by default.
- `options.input.validation`: Enable form validation
- `options.input.allLabel`: Custom label for "All" button 
- `options.input.noneLabel`: Custom label for "None" button 


## Plugin options

Form plugin options are declared in `extra`:
```
      'options' { 
        'button' { 'label' 'Send' }
        'input' { 'validation' true } 
        'extra' { 'form' { 
          'stickyButton' true 
          'addFormUUID' true
          'diff' true
          } }
      } 
```
- `stickyButton` make the form "Send" button always visible, even if the form is bigger than the tile.
- `addFormUUID` add a uuid in the key `formUUID` of the output variable. It allows to build a logic for tiles listening to multiple events to avoid a replay of the same event, or to miss a new event.
- `diff` remove the untouched keys from the output variable. Each send event only contains modifications since the component load or the previous send.

## Main usage

Your Discovery macro should return a list of controls or a key value map with a field "data" containing a list of controls.

Each control is placed on a 12 columns width grid. By default, each control is 12 columns width. 

Each control is described by:

```warpscript
{
  'name' 'make'                 // Mandatory. Unique control's name  
  'label' 'Choose a maker'      // Optional. Control's label. By default, the control's name is used as label
  'description' 'Bla bla'       // Optional short field description  
  'type' 'list'                 // Mandatory. Type of control (see below)
  'data' [ 'A' 'B' 'C' ]        // Data used by the list
  'default' 'B'                 // Optional default value.
  'required' T                  // Optional, if form validation is enable, mark this control as requiered
  'options' { 
    'col' 4                     // Optional, width of the control over the main grid
    'grid_break' true           // Optional, force a line return in the grid
    'placeholder' 'Choose...'   // Custom input placeholder  
  }         
}
```

The field by field `disabled` is not available for every controls type.

## Available controls

### text (default)

```warpscript
{
  'name' 'myText' 'label' 'Text input sample'  
  'type' 'text'
  'default' 'foo bar' 
  'options' {
    'min' 3         // Optional minimal string length   
    'max' 8         // Optional maximal string length
  }         
  'disabled' true  // cannot edit this field
}
```

### secret

```warpscript
{
  'name' 'mySecret' 'label' 'Password input sample'  
  'type' 'secret'
  'default' 'foo bar' 
  'options' {
    'min' 3         // Optional minimal string length   
    'max' 8         // Optional maximal string length
  }         
}
```

### hidden

```warpscript
{
  'name' 'myHidden' 'label' 'Invisible'  
  'type' 'hidden'
  'default' 'foo bar' 
}
```

### number

```warpscript
{
  'name' 'myNumber' 'label' 'Number input sample'  
  'type' 'number'
  'default' 12 
  'options' {
    'min' 3         // Optional minimal value   
    'max' 80        // Optional maximal value
  }         
  'disabled' true  // cannot edit this field
}
```

### list

Works with a list of strings or a list of numbers

```warpscript
{
  'name' 'myList' 'label' 'List input sample'  
  'type' 'list'
  'data' [ 1995 1996 1997 1998 1999 2000 2001 ] // Use data to set the available values
  'default' 1998
  'disabled' true  // cannot edit this field
}
```

```warpscript
{
  'name' 'myList' 'label' 'List input sample'  
  'type' 'list'
  'macro' <% [ 'A' 'B' 'C' ] %> // or use a macro to set the available values
  'default' 'B'
}
```

### autocomplete

Like lists, works also with a macro.

Works only with a list of strings.

```warpscript
{
  'name' 'myAutocomplete' 'label' 'Autocomplete input sample'  
  'type' 'autocomplete'
  'data' [ "admiring" "adoring" "agitated" "tiny" "trusting" ] // Use data to set the available values
  'default' "adoring"
}
```

### rating

Like lists, works also with a macro. 

```warpscript
{
  'name' 'myRating' 'label' 'Rating input sample'  
  'type' 'rating'
  'data' [ "Beginner" "Skilled" "Experienced" "Advanced" "Expert" ]
  'default' 'Experienced'
}
```

### date, time, datetime

```warpscript
{
  'name' 'myTime' 'label' 'Standard time field'  
  'type' 'time'
  'default' '12:44'
}
```

```warpscript
{
  'name' 'myDate' 'label' 'Standard date field'  
  'type' 'date'
  'default' NOW
}
```

```warpscript
{
  'name' 'myDateTime' 'label' 'Standard datetime field'  
  'type' 'datetime'
  'default' NOW
}
```

### radio group

Like lists, works also with a macro.

```warpscript
{
  'name' 'myRadio' 'label' 'Radio'
  'type' 'radio'
  'default' [ "Work" ]
  'data' [ "Home" "Work" ]
}
```

### checkbox, switch

```warpscript
{
  'name' 'myCheckbox' 'label' 'Checkbox'
  'type' 'checkbox'
  'default' true
}
```

```warpscript
{
  'name' 'mySwitch' 'label' 'Switch'
  'type' 'switch'
  'default' false
}
```

### checkboxes group (multi-cb)

Like lists, works also with a macro.

Your data list can contain either a string or a key/value map.

```warpscript
{
  'name' 'myMultiCb' 'label' 'Multi checkboxes'
  'type' 'multi-cb'
  'default' [ true       false     true       false    false ]
  'data'    [ "admiring" "adoring" "agitated" "tiny" { "name" "opt1" "label" trusting" } ]
}
```

### slider

```warpscript
{
  'name' 'mySlider' 'label' 'Slider sample'
  'type' 'slider'
  'default' 30 
  'options' {
    'min' 10        // Optional minimal value   
    'max' 80        // Optional maximal value
    'step' 10       // Optional increment 
  }  
}
```