Introduction
The .forms.yml file allows for the creation (or update) of a project via a nice interface, enabling easier and more controlled configuration of stacks. This includes restrictions on provided values, exposed variables, range, etc.
The Stackforms interface simplifies stack creation for all users, with the following documentation primarily addressing stack creators and explaining how the feature works and how to use it for a stack.
How does it work? This feature relies on a configuration file ( .forms.yaml) present in the stack source code. When this file is present, Cycloid switches to stackforms mode and displays stack configuration via an HTML form.
Basically, the .forms.yaml file's goal is to define the mapping between stack parameters (IaC) and a human interface. The file describes each parameter and how they have to be displayed to the user.
Under the hood:
The .forms.yaml is the middle key component. For a user connected to the Cycloid console, during the configuration of a project, an HTML form is displayed. As mentioned above, the definition of this form is contained inside the .forms.yaml file.
Cycloid console exposes parameters to the user, who will have the capacity to change them accordingly. Once everything has been fulfilled, the data will be sent back to the Cycloid API, which will validate the user's input based on the .forms.yaml file definition.
If all user inputs are valid, StackForms reads the defined sample files described in .cycloid.yaml file under config.$technologie.path. StackForms then renders these sample files, adding or updating parameters with the user inputs. Only the elements defined in .forms.yaml will be replaced in the sample file; everything else present in the sample file will remain unchanged.
And render the user's inputs and mapping defined in .forms.yaml.
In the final step, the generated file from user input and sample files is written into the selected Git Config Repository of the project automatically.
If you want to test out your forms configuration before commiting to it fully, you can make use of the stack versioning feature to create a development branch in your stack repository. This way, you can create a component using this branch and see how the forms are rendered without affecting the production version of your stack.
Prerequisites
The only requirement is to create a .forms.yaml file in a stack.
When using Stackforms in a stack containing several use-cases in your .cycloid.yml file, ensure that all the use-cases are defined in the .forms.yaml definition. For details, please refer to the Forms File Format section.