Forms
Just like in every web application, HTML forms are essential in platformOS. Because using plain HTML forms can get difficult to maintain with complex data structures, we provide multiple tools that make working with forms much easier.
To delve into forms, you should be familiar with:
- Liquid Template language
- platformOS Pages
Basic concept
Form configuration is defined as Liquid files and is located within the forms.
If you develop your code as module forms directory should be placed inside public or private directory of your module.
If your code is not a module, forms is placed directly inside app directory.
Each file is divided into two sections: configuration and implementation.
- Configuration section is placed on top of the file marked with three dashes
---at the start and end of the section. It is a definition written in YAML that is telling the platform to create/update the form endpoint with given name and settings. These settings determine where to store and how to validate the data. Head to the Form Configuration Options section for a full list of configuration options.
- Implementation section is an HTML part that accepts Liquid Markup with all goodies from platformOS. This is where you construct the form displayed to users. You can construct the form in HTML but it's much easier to use the
{% form %}tag that will handle many tasks behind the scenes, and will make it easier to write clean code. Learn more about it in the Rendering Form Tutorial.
Minimal form example
Every form configuration is strictly connected with the resource that can be a static class predefined by platformOS or a dynamic record. The very basic example of the Form that enables the possibility to create an object of Table named "Car" and accepts one property called "color", would look like this:
app/forms/car_form.liquid
---
name: car_form
resource: car
fields:
properties:
color: {}
---
{% form %}
<input name="{{ form.fields.properties.color.name }}" />
<button>Save</button>
{% endform %}
As already mentioned the file is split into two sections. In the configuration part, you define name that is later used to include the form in the view, resource that tells the platform which Table is connected with that form and configuration that allows record properties that can be altered with this form endpoint.
In the implementation part the form tag generates the HTML <form> together with all inputs and properties required for successful form submission. The name of the text input, included in the form body, is provided by the form variable.
To display the form within a page, use the include_form tag that accepts the name of the form that you want to display:
app/views/pages/car.liquid
{% include_form "modules/minimal_form/car_form" %}
Now head to the /car page and check the form with text input followed by a submit button.
Live example and source code
To check how it works on a real webpage go to the live example page.
Source code can be found on GitHub.