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 ornew
is passed, the method will be set toPOST
, otherwise toPUT
.DELETE
method needs to be defined explicitly.Examples:
--- name: blog_post_delete resource: modules/dashboard_blog/blog_post resource_owner: anyone fields: redirect_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_record"> <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
orform_id
is telling platformOS which form to use when processing requestparent_resource_id
identifies form object type (which is usually the name of your Table)- '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 Table name)
- resource_owner: form configuration resource owner
- system_fields: an object containing data rendered within the form tag