Form Rendering

Last edit:  Jan 18, 2019

Contributors:  lemingos diana-lakatos

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 Configuration example

<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 %}

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 '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' %}
      <input type="Submit" class='btn btn-link' value="Delete" data-confirmation='You will delete this post permanently. Are you sure?'>
    {% 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_configuration_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_configuration_name or form_configuration_id is telling platformOS which form to use when processing request
    • parent_resource_id identifies form object type
    • 'authenticity_token` is required when authorization header is not set, otherwise can be skipped

Form Builder Object

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

List of form_builder 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
  • 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. Check out our Help page, or contact us.