Form Rendering

This topic explains form rendering in platformOS.

To understand this topic, you should be familiar with:

Defining form implementation

Form implementation example from Full Form example

<p>{{ form.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.fields.properties.email.name }}"
      value="{{ form.fields.properties.email.value }}"
      id="form_email"
      type="email"
     >

     <p>{{ form.errors['properties.email'] }}</p>
  </div>

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

Rendering form as HTML

In order to generate and display form configuration HTML code use the include_form tag on any page, partial, or layout.
The first argument is the name of the form configuration that you want to display, second is "key: value" list of variables that will be accessible in the form.

Example:

{% include_form 'modules/full_form/full_form_example', id: params.id %}

Form Tag

Using the form tag is the easiest way to generate an HTML form. It uses the context provided by the form configuration to define required attributes and inputs.

  • action is defined based on resource context. It is translated to proper API endpoint

  • method is defined based on the id parameter passed to the include_form tag. When nothing or new is passed, the method will be set to POST, otherwise to PUT. DELETE method needs to be defined explicitly.

    Examples:

    ---
    name: blog_post_delete
    resource: modules/dashboard_blog/blog_post
    resource_owner: anyone
    fields:
    return_to: dashboard/blog
    ---
    {% form method: 'delete' %}
      <button class="btn btn-link">Delete</button>
    {% endform %}
    
    

  • hidden inputs there are multiple inputs generated by form tag.

    <input name="utf8" type="hidden" value="✓">
    <input type="hidden" name="authenticity_token" value="Dl+Oaignq4h7fe577kMJBURm0FaFYRr5qrBx2OngXm28SOqaTGR8vdkReHOevfzNBN9HKebr/z46sHyEjPm9NA==">
    <input type="hidden" name="form_id" value="4099">
    <input type="hidden" name="page_id" value="5492">
    <input type="hidden" name="slug" value="full-form-example">
    <input type="hidden" name="slug2">
    <input type="hidden" name="slug3">
    <input type="hidden" name="resource_id" value="new">
    <input type="hidden" name="parent_resource_id" value="example_model">
    <input type="hidden" name="parent_resource_class" value="CustomModelType">
    

    Make sure to add necessary information if you create your HTML form manually or when you use third-party tools like curl to construct your request. Required request parameters are:

    • form_name or form_id is telling platformOS which form to use when processing request
    • parent_resource_id identifies form object type (which is usually the name of your Model Schema)
    • 'authenticity_token` is required when authorization header is not set, otherwise can be skipped

Form Builder Object

The form object is only accessible within the form configuration file because this configuration defines its state.

List of form properties:

  • action: URL of form configuration API endpoint usually passed as form action
  • errors: list of validation errors raised on failed form submission. For more information about validation errors visit Form Validation Tutorial
  • fields: list of fields that can be altered in the form defined in the form configuration object.
    Every field has the following properties:
    • name is what you pass as a name in the form input field to access the property
    • value is the value assigned to the form object property, this might be different than the value stored in the database when validation is raised
    • validation: validation rules and errors
    • property_options: field property options
  • name: name of form configuration
  • resource: form configuration resource name (usually your Model Schema name)
  • resource_owner: form configuration resource owner
  • system_fields: an object containing data rendered within the form tag

Questions?

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