Form Configuration

This is an overview of all form configuration options.

Requirements

To understand this topic, you should be familiar with:

• Liquid Template language
• platformOS Forms introduction

Full Form Configuration example

The code below present all possible form configuration options together with the optional form implementation part that comes just after the YAML section. All possible configuration options will be explained in detail in the following section. You can play with the form generated by the example here.

---
name: full_form_example
resource: example_model
resource_owner: anyone
return_to: /full-form-example
flash_alert: This is flash alert (fail)
flash_notice: This is flash notice (success)
spam_protection: "" # e.g. recaptcha - needs to be configured
fields:
  properties:
    email:
      validation:
        presence:
          message: Email cannot be empty
        email: true
    greeting:
      property_options:
        virtual: true
email_notifications:
- welcome_user
api_call_notifications:
- ping_example_com_on_user_sign_up
callback_actions: >
  {% log "Hello from callback actions" %}
async_callback_actions:
  delay: 1
  priority: low
  max_attempts: 2
  content: |-
    {% log "Hello from async callback actions - I am delayed 1 minute!" %}
authorization_policies:
  - valid_example_policy
default_payload: |-
  {
    "properties_attributes": {
      "greeting": "Hello from default payload!"
    }
  }
---
<p>{{ context.flash.notice }}</p>
<p>{{ context.flash.alert }}</p>
<p>{{ form_builder.fields.properties.greeting.value }}</p>

{% form html-class: 'w-50' %}
  <div class="form-group">
    <label for="form_email">Email</label>

    <input
      class="form-control"
      name="{{ form_builder.fields.properties.email.name }}"
      value="{{ form_builder.fields.properties.email.value }}"
      id="form_email"
      type="email"
     >

     {{ form_builder.fields.properties.email.validation.rules.presence.message }}
  </div>

  <button class="btn btn-primary">Save</button>
{% endform %}

The configuration part of the form defines the API endpoint where the server listens to specific requests and invokes all actions defined in the form. The implementation part is what is displayed as HTML to your user. It is optional because sometimes you will only want to configure the server and the request will come from another source like in the example form tutorial: Building a Contact Form with Customization. For more information about the implementation part head to the Rendering Form tutorial.

Required form configuration options

name

The unique identifier of the form. It's how you reference your forms in the include_form tag. This field doesn't depend on the actual FormConfiguration file name, but it's a good practice that the file name corresponds with the value of the name property.

resource

Either the name of your CustomModelType or one of predefined platformOS classes. For the full list of classes visit our REST API reference.

Examples:

• Minimal form example shows the example of dynamic resource based on CustomModelType

• Creating a Sign Up Form shows the predefined class resource example.

Optional form configuration options

api_call_notifications

Array of API call notification names that will be executed after the form is successfully submitted.

Example from Creating an API Call Notification:

api_call_notifications:
  - ping_example_com_on_user_sign_up

async_callback_actions

Accepts the following parameters:

• content: String, Liquid Template code executed asynchronously. There is no timeout set for processing this code so it is the right place for more time-consuming calculations.
• delay: Integer, number of minutes added to the moment of form submission before the code defined in content is executed.
• priority: String, high, default or low, defines priority of execution when executed at the same time with other callbacks.
• max_attempts: Integer, number of executions of callback in case of an error, default is 1.

Example:

async_callback_actions:
  delay: 1
  priority: low
  max_attempts: 2
  content: >
    {% log "Hello from background" %}

The example above prints the "Hello from background" string to the output of marketplace-kit logs staging.

authorization_policies

Array, list of names of Authorization Policies that are protecting the form from unauthorized submission.

callback_actions

String, Liquid Template code that is executed as soon as the form is successfully validated.

fields

Object, whitelist of fields that are allowed to pass to the form object together with the validation rules for each of the defined fields. Every property added to the configuration is accessible in form_builder variable and has the following configuration options:

• validation: see validation tutorial

property_options

• virtual: Virtual fields come in handy when there’s no direct mapping to a model attribute or when you plan on displaying a value without processing.

  Example:

  fields:
    my_first_virtual_property:
      property_options:
        virtual: true
  

default_payload

JSON formatted String that is merged with user data provided in the form submission.
Head to the Default Payload Tutorial to learn more about it.

email_notifications

Array of email notifications names that will be executed after the form is successfully submitted.

flash_alert

String, message that is passed to the context.flash.alert object when the form validation is raised.
Learn more in separate tutorial about Flash Messages.

flash_notice

String, message that is passed to the context.flash.notice object when the form is valid.
Learn more in separate tutorial about Flash Messages.

redirect_to

String, defines path of the page rendered after a successful form submission. Example: /welcome

resource_owner

String, defines form configuration user permissions schema.

Available values are:

• anyone - anyone can modify the object
• creator - only the user that previously created the object can update/delete the object with that form configuration
• self - like owner for User resource

The table below shows all possible resource owners for different resources:

This is very useful when you want to restrict user permissions to modify only records that were previously created by that user.

sms_notifications

Array of short text message notification names that will be executed after the form is successfully submitted.

spam_protection

String, type of spam protection that will be used. Needs to be configured in Partner Portal. A separate topic explains how to add reCaptcha Spam Protection.

Questions?

We are always happy to help with any questions you may have. Check out our Help page, or contact us.