Forms

Last edit: Jul 08, 2019

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:

Basic concept

Form configuration is defined as Liquid files and is located within the form_configurations.

If you develop your code as module form_configurations directory should be placed inside public or private directory of your module.

If your code is not a module, form_configurations 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 model. The very basic example of the FormConfiguration that enables the possibility to create an object of CustomModelType named "Car" and accepts one property called "color", would look like this:

---
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 CustomModelType is connected with that form and configuration that whitelists model 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:

---
slug: car
---
{% include_form "modules/minimal_form/car_form" %}

Now head to the /car page and see the form with text input followed by a submit button.

Live example and source code

To see how it works on a real webpage go to the live example page.
Source code can be found on GitHub.

Related topics

Questions?

We are always happy to help with any questions you may have.