Generic forms fields

There are many areas in serverboards that can be expanded with user created forms. This are not very complex but just enough for most situations.

They are defined as a list of fields in this form:

fields:
  - label: SMTP Server Address
    name: smtp
    type: text
    validation: empty
    description: FQN of the email server
    placeholder: eg. smtp.google.com
  - label: SMTP Username
    name: smtp_username
    type: text
    only_if: smtp
  - label: SMTP Password
    name: smtp_pw
    type: password
    only_if: smtp
  - label: Description
    type: description
    description: |
      Multiline description.

      It may also contain variables as {{var}} that will be resolved by
      calling a function at a plugin. The function does not receive
      any parameter.
    vars:
      - id: var
        plugin: full.qualified.plugin/daemon
        call: simple_function
Field Description
label Label to show
name Internal name of the field
type Type of the field. Check below for a full list.
default The default value of the field. A list in the case of select. See below.
validation Used on the frontend validation (so if you use this information elsewhere you should not trust it) as defined in Semantic UI validation rules
placeholder Placeholder text
description Long description of the field
button Shows a description and an actionable button
dynamic Will reload remote content on any change of the form, sending all form data to remote end. Used at select call.
subscribe Event to which this field is subscribed to change its value

Field types:

Type Description
button Description with an actionable button. Can use dynamic data.
checkbox Activates or not some option.
description Dynamic description. Uses to set some explanation which may need some dynamic data. Uses moustache templates.
hidden A hidden field that will not be shown in the form, but sent to the user. To set some fixed data.
html Load some HTML snippet and insert it into the form
password A password field that hides whats being written.
select A select. Check below for description.
select call A select that gets data dynamically.
service A select that lets to choose a service that matches a traits field.
text A one line text.
textarea A multiline text.
url An URL.

One of text, password, checkbox, select, service, button, description, serviceselect, select call.

Extra data, dependant of context

Field Description  
card Show at service card resume or not (true false). Default false.
traits Which kind of services to show at type service  
only_if Makes a field dependant on the existence of another field value. For example do not ask for username if the server value is empty.  

Not all fields are required.

By using the description field type it is possible to get some dynamic information from plugins. Check the core-ssh plugin for infor on how it is used to get the public ssh key at id_rsa.pub.

Special considerations

Description and Button variables

Both description and button allow to have dynamic descriptions. They are gathered from the vars field, which is a list of variables, and how to gather them, using a command (a cmd component) and a method to call.

Field Description
vars List of variables to use on dynamic content (description, button).
vars.id Identifier to use at the template text
vars.command Which cmd component will receive the call
vars.call Which method to call. It will receive all the current form data.

For example (from SSH):

- label: SSH Public Key
  type: description
  description: |
    To connect via SSH please ensure that the following SSH public key is
    added to your servers `~/.ssh/authorized_keys`:

    **SSH Public Key:**

    ```
    {{ssh_key}}
    ```
  vars:
    - id: ssh_key
      command: serverboards.core.ssh/mgmt
      call: ssh_public_key

This snippets calls the ssh_public_key method at serverboards.core.ssh/mgmt and the results are set into the ssh_key variable.

This variables can be json objects, and the template can use them as usual.

In the case of buttons, this can be extended to value and className:

- label: Remote SSH Fingerprint
  type: button
  show_if: url
  depends_on: url
  description: |
    The remote fingerprints are:

    ```
    {{status.fingerprint}}
    ```
    Click on "Enable host" to add to your known_hosts.
    This is required to access this server.
  value: "{{status.toggle}}"
  className: "{{status.className}}"
  onclick:
      command: serverboards.core.ssh/mgmt
      call: toggle_remote_fingerprint
  vars:
    - id: status
      command: serverboards.core.ssh/mgmt
      call: remote_fingerprint

Buttons

Buttons have extra optional fields:

Field Description
depends_on Makes a dynamic field (only buttons so far) reload if another field is modified.
button Text to show at the button. Can be a template to be filled with variables.
class Class to use for the button, to be able to change color or enabled. Can be a template.
description Description of the button. Can be a template.
onclick For button fields, what action to execute. Needs command and call.
onclick.command If of cmd component to start, call the method, and stop (which will succeed depending on command strategy)
onclick.call Which function to call, with all the form fields data, plus all the vars from description

select

A field type that is a list of preset options.

Field Description
options List of dicts each with a name and a value
- name: type
  type: select
  options:
    - name: Sum of data
      value: sum
    - name: Evolution of data
      value: evolution

select call

A field of type select call may call a method to gather the data.

Field Description
options An object with the command and call
options.command cmd component that will receive the call
options.call method to call. It will receive all the configuration of the form as parameters.

The full description is something as:

- name: viewid
  label: Property
  type: select call
  options:
    command: serverboards.google.analytics/daemon
    call: get_views
    dynamic: true
    params:
      - name: n1

The method must return a list of objects with value and name:

[
  { "value" : 1, "name": "First option"},
  { "value" : 2, "name": "Second option"},
  { "value" : 3, "name": "Last option"}
]

Instead of name, label can be used.

If dynamic is present, the call will be performed any time that any field in the form changes (including the select call). If there is a list of parameters, only those params will be checked for changes, and passed into the call.

html

It is now possible to add an html and supporting js code directly into the form.

The HTML will be processed to replace `` with the field where the result of this html should be placed using js (from the html or from the js file).

The field definition requires one of:

  • html – the name of the html file at static subdir
  • js – the name of the javascript file at the static subdir
- name: login
  type: html
  html: login.html
  js: login.js

This field type should be anyway avoided as it does not play well with the rest of the data model of Serverboards.

Anyway it may be required to simplify a lot processes as Facebook login.

Subscriptions

Some forms may need another actor changing its value. For example Oauth authentication may use several windows/tabs to provide a token, but this can not be saved before the service is created. This allows to store in a item of the form, and the window sthat receives the data, communicate it via events.

The event can have any free text with letters, numbers dash or slash, and at the end it appends a random UUID for each form. This form_id is passed to the description or button variable generators.

So the final event will be called something like: myevent-name/form_id.

The subscription field at the field definition have to have the myevent-name label.