Forms

Overview

To be able to use a form in WM3 you first have to create the form in the Forms Module. In the module you create a name, URL, choose an email adress that will reviece an email when someone is submitting a form and a subject. You may also be able to choose form template which means that you can style the email being sent when someone is submitting a form. This will require that you have created a customized mailer.

Below you can see all required values in the Form object

Name	Description
url	Can be a string or a liquid variable. Needs to be followed by a comma if there are more values

Form structure

The WM3 Form generated a form skeleton which recieves one or more values. The first value is the URL, which is required. You can then add more values to the form like class, id, data etc. These can be separated with comma (,) or an empty space ( ).

Basic structure of form with URL hogwarts-registration

{% wm3form "/forms/hogwarts-registration" %}

   <input name="name" placeholder="Your name" type="text">

   <input type="submit" value="Submit">

{% endwm3form %}

Structure of form with URL hogwarts-registration with class and id

{% wm3form "/forms/hogwarts-registration", class="form", id="mytestform" %}

   <input name="name" placeholder="Your name" type="text">

   <input type="submit" value="Submit">

{% endwm3form %}

Structure of form for customer login to webshop with class and id

{% wm3form customer.login_url, class="form", id="mytestform" %}

   <input name="name" placeholder="Your name" type="text">

   <input type="submit" value="Submit">

{% endwm3form %}

A form created with {% wm3form %} automatically adds a hidden authentication token.

After a form has beeing sent

After a form being submitted, a notification is generated and prepended to the contents of the form. There are two types of notifications, notice and alert, depending on the request being successful or not.

The following code is a skeleton of what will be prepended to the contents of a form, upon its submission.

<div class="wm3-form-notification">

  <div class="_notificationClass_">

    <div class="wm3-form-message">_message_</div>

  </div>

</div>

_notificationClass_ depend on the notification type - it can either be wm3notice or wm3alert

_message_ is the message that is shown to the user. This has a default value that can be configured in the translations with the keys forms.form_sent and forms.not_form_sent. The default value for these keys are "Form was sent successfully!" and "Something went wrong, try again"

Special fields

Sometimes you want to customize the form that is being sent. You may want to change the subject of the email that is being sent, or you may want to send an email to the person who is submitting the form.

Name	Description
subject	If is present, email subject will be `default_form_subject - subject`
wm3_from	If is present and has a valid email syntax, the email "reply to" header will equal the value
wm3_to	If is present and has a valid email syntax, a copy of the email will be sent to its value.

CoffeeScript Notification event

Once the notification is appended to the form, an event 'wm3NotificationsReady' is fired from the document. The following code is an example in coffeescript on how to capture it.

if document.addEventListener

  document.addEventListener 'wm3NotificationsReady', (e)->

    // do something here

else

  // IE8 does not have addEventListner but attachEvent instead

  document.attachEvent 'wm3NotificationsReady', (e)->

    // do something here

Submitted data

Upon a successful submission of a form, the browser gets redirected back to the page. Through liquid, the following information can be retrieved from the form.

Name	Description
flash.form	Standard data. The form url/action
flash.notice	Standard data. Form notice messages
flash.alert	Standard data. Form error messages

User submitted data

User submitted data is not available by default. To access the data, a special input field must be sent with the form.

Input field name: wm3_form_data
Input field value: flash or params.

If it is set to flash the form params that were submitted can be accessed in liquid with flash.form_data. To access the value of a field with name of E-mail the following can be used flash.form_data['E-mail'].

If it is set to params the form params that were submitted can be accessed in liquid with request.params. To access the value of a field with name of E-mail the following can be used request.params['E-mail'].

Flash should NOT BE used if the user can submit a lot of data. Make sure to test it before using. Using params will show all user submitted data in the url, so be careful with sensitive data, for example password fields.

flash data is only available after the redirect. If the page is reloaded, this data will be lost. If you wish to have the data persist upon reload, use params instead.

Handle lists with Forms

You can handle lists and list rows with Forms, e.g. create, update or delete rows

Create row

{% wm3form lists.quidditchapplications.row_create_path, enctype="multipart/form-data" %}

<label for="list_row[values][broomstick]">Broomstick:</label> <input name="list_row[values][broomstick]" type="text" required>

<label for="list_row[values][position]">Position:</label> <textarea name="list_row[values][position]" required></textarea>

{%endwm3form%}

Update row

{% for item in lists.quidditchapplications.current_account_rows %} {% wm3form item.update_path, method="patch", enctype="multipart/form-data" %}

<label for="list_row[values][broomstick]">Broomstick:</label> <input name="list_row[values][broomstick]" type="text" value{{item.broomstick}}" required>

<label for="list_row[values][position]">Position:</label> <textarea name="list_row[values][position]" required>{{item.position}}</textarea> {%endwm3form%}

{%endfor%}

Updated: 2024-11-08

Liqiud basics

Modules

API

Mailer