Ferris Docs: Rephrase "Forms Generator" section in Developer Guide

[fcaprez]

NEW page:

---

title: "Form Generator" linkTitle: "Form Generator" tags: [forms] categories: ["Knowledge Base"] weight: 208 description: >- How to generate Forms that trigger services.

From time to time, you may encounter scenarios in which you need to create a frontend for initiating a service, often to be used by non-technical individuals. Both FX and K8X offer the capability to define forms using a straightforward JSON structure.

These forms are automatically generated by the {{< param replacables.brand_name >}} Management UI, based on the 'parameters.json' file.

When a service directory includes a 'parameters.json' file, the 'Run' button in the Management UI will automatically change its icon to a 'Form' icon.

{{< blocks/screenshot color="white" image="/streamzero/images/developer_guide/run_UI_package_roboto.png">}}

To add the 'parameters.json' file to an existing service directory, ensure that the 'allow_manual_triggering' in the manifest.json file is set to 'true.'

Template parameters.json file

The 'parameters.json' file contains a JSON definition of fields. These fields are presented to the user when manually triggering a package execution to collect the parameter values needed to run the package. This approach allows the same package to be easily adapted and reused for different scenarios or environments simply by providing different parameter values to the same package.

{
  "fields": [
    {
      "type": "text",
      "label": "Some Text",
      "name": "some_text",
      "required": true,
      "description": "This field is required"
    },
    {
      "type": "textarea",
      "label": "Some Textarea",
      "name": "some_textarea"
    },
    {
      "type": "file",
      "label": "Some File",
      "name": "some_file",
      "data": {
        "bucket": "testbucket",
        "async": true
      }
    },
    {
      "type": "int",
      "label": "Some Number",
      "name": "some_number",
      "default": 1,
      "min": 0,
      "max": 10
    },
    {
      "type": "float",
      "label": "Some Float",
      "name": "some_float",
      "placeholder": "0.01",
      "step": 0.01,
      "min": 0,
      "max": 10
    },
    {
      "type": "select",
      "label": "Some Select",
      "name": "some_select",
      "default": "value 2",
      "choices": [
        {
          "title": "Choice 1",
          "value": "value 1"
        },
        {
          "title": "Choice 2",
          "value": "value 2"
        },
        {
          "title": "Choice 3",
          "value": "value 3"
        }
      ]
    },
    {
      "type": "multiselect",
      "label": "Some MultiSelect",
      "name": "some_multiselect",
      "default": ["value 2", "value 3"],
      "choices": [
        {
          "title": "Choice 1",
          "value": "value 1"
        },
        {
          "title": "Choice 2",
          "value": "value 2"
        },
        {
          "title": "Choice 3",
          "value": "value 3"
        }
      ]
    },
    {
      "type": "radio",
      "label": "Some Radio",
      "name": "some_radio",
      "choices": [
        {
          "title": "Choice 1",
          "value": "value 1"
        },
        {
          "title": "Choice 2",
          "value": "value 2"
        },
        {
          "title": "Choice 3",
          "value": "value 3"
        }
      ]
    }
  ]
}

The provided template will display a form as follows:

{{< blocks/screenshot color="white" image="/streamzero/images/developer_guide/run_parameters_UI_roboto.png">}}

When users enter values in the form and click the 'Run' button, the form parameters and values will be sent to the service upon triggering. These parameters will be available to the service as if it were triggered by an event with the same payload as the form values.

Below is a sample script that extracts the parameters (notice that it's not fundamentally different from a script triggered by an event). The only exception is the text areas, which are treated as String data types and may require conversion using the appropriate JSON library.

from fx_ef import context
import json

event_type = context.params.get("sample_event_type")
event_source = context.package.name
data = json.loads(context.params.get("sample_payload"))

context.events.send(event_type, event_source, data=data)