$wsForm - Forms - WEBSALE Dokumentation

With the $wsForm module, you can use form data dynamically in the frontend, load form fields, and read out submitted form data.

Module overview

Example / excerpt of $wsForm

{{= $wsForm | json }}

JSON output

{
  "inquiryId": "...",
  "load": "ƒ()",
  "loadAllTypes": "ƒ()",
  "loadType": "ƒ()"
}

Note: ƒ() denotes a function. Variables overview

Name	Return type	Description
`inquiryId`	string	Contains the ID after sending a form.
`loadType()`	map	Loads the structure of a form by the form name.
`loadAllTypes()`	array	Loads all available form types of the shop.
`load()`	map	Loads the submitted data of a sent form.

Templates

Forms are used everywhere in the shop and on all templates. These forms are, for example:

Contact form
Withdrawal form
Question about the product
Password reset

Variables

$wsForm.inquiryId

Contains the unique ID of a form inquiry after successful sending. With this ID, the form data can be retrieved via load().

Inquiry ID: {{= $wsForm.inquiryId }}

Methods

$wsForm.loadType()

Loads the structure of a form (fields, labels, validations) by the form ID. Signature
$wsForm.loadType(inquiryId) Return value
map - Map with the form properties and fields. Parameters

Name	Type	Required	Description
`inquiryId`	string	yes	ID of the form (e.g. “`contact`”).

Example that outputs all properties of each form field:

{{ foreach $field in $wsForm.loadType("contact").fields }}
    {{ foreach $key in sort(keys($field)) }}
        {{= $key }}: {{= $field[$key] }} 
    {{ /foreach }}
{{ /foreach }}

Variables of the field objects

The $wsForm.loadtype() method returns an object per field (in this example $myField) with the following properties. If a RuleSet (inquiry - Forms) is assigned to the form, the attributes required and label are automatically adjusted by the rules defined there.

Variable	Return type	Description
`$myField.name`	string	Technical field name.
`$myField.label`	string	Display name of the field. Is automatically updated by `customLabelDefinition` in the RuleSet if a RuleSet is linked.
`$myField.required`	bool	Required-field flag (`true` / `false`). Is automatically updated by `requiredDefinition` in the RuleSet.
`$myField.validations`	array	List of validation rules for the field.
`$myField.defaultValue`	string	Default value of the field (set by `defaultValuesDefinition` in the RuleSet). Can be used in the template to pre-populate the field value when it is empty.
`$myField.value`	string	Current value of the field. Is populated by the `inquiryCheck` action (see actions - Forms).
`$myField.visible`	bool	Indicates whether the field should be displayed (`true` / `false`). Is automatically controlled by `inputVisibilityDefinition` in the RuleSet.

$wsForm.loadAllTypes()

Loads all available form types of the shop Signature
$wsForm.loadAllTypes() Return value
array - List of all available form types. Example that iterates over all available form types.

{{ foreach $formType in $wsForm.loadAllTypes() }}
  Form: {{= $formType.name }}
{{ /foreach }}

$wsForm.load()

Loads the submitted data of a sent form. Signature
$wsForm.load(inquiryId) Return value
map - Map with the inquiry data. Parameters

Name	Type	Required	Description
`inquiryId`	string	yes	ID of the sent form.

Example that checks whether the form was successfully sent and loads the data.

{{ var $myAction = $wsActions.create('InquirySend') }}
{{ if $myAction.success }}
    {{ var $myInquiry = $wsForm.load($myAction.successInfo.inquiryId) }}
{{ /if }}

Procedure:

Create action “InquirySend”
Check whether sending was successful
Load form data via the Inquiry ID

The following variables are available after the inquiry data has been loaded with load():

Variable	Return type	Description
`id`	string	Unique ID of the form inquiry.
`formId`	string	ID of the form used.
`createdAt`	string	Time of sending.
`submitter`	map	Data of the sender.
`email`	string	Email address of the sender.
`sessionId`	string	Session ID during which the form was sent.
`ipAddress`	string	IP address of the sender.
`form`	map	Data of the form that the customer entered in the shop.
`"fieldName".label`	string	Display name of the field.
`"fieldName".value`	string	Entered value of the field.

Variables of the inquiry data

$myInquiry.id

Returns the unique ID of the form inquiry.

Form inquiry ID: {{= $myInquiry.id }}

$myInquiry.formId

Returns the ID of the form used.

Form ID: {{= $myInquiry.formId }}

$myInquiry.createdAt

Returns the time of sending.

Form sent: {{= $myInquiry.createdAt }}

$myInquiry.submitter

Returns a map with data about the sender.

$myInquiry.submitter.email

Returns the email address of the sender.

Email address: {{= $myInquiry.submitter.email }}

$myInquiry.submitter.sessionId

Returns the session ID during which the form was sent.

Session ID: {{= $myInquiry.submitter.sessionId }}

$myInquiry.submitter.ipAddress

Returns the IP address of the sender.

IP address: {{= $myInquiry.submitter.ipAddress }}

$myInquiry.form

Returns the data of the form inquiry that the customer entered in the shop as a map.

$myInquiry.form.”fieldName”.label

Returns the display name of the field.

First name label: {{= $myInquiry.form.firstName.label }}

$myInquiry.form.”fieldName”.value

Returns the entered value of the field.

First name value: {{= $myInquiry.form.firstName.value }}

Actions

Actions for this module that trigger changes are documented separately in the “Actions” chapter: Inquiry

Example for displaying form fields

Function - loadType

The function $wsForm.loadType() takes the name of the form as an argument and is used to access the properties and fields of the form. The fields and associated properties of the contact form can then be loaded and read as follows.

{{ foreach $field in $wsForm.loadType("contact").fields }}
   {{ foreach $key in sort(keys($field)) }}
      {{= $key }}: {{= $field[$key] }} 
   {{ /foreach }}
{{ /foreach }} 

The output could then look like this:

[
  {
    "defaultValue": "",
    "label": "First name",
    "name": "firstName",
    "required": false,
    "validations": [
      { "type": "formCheck", "name": "minlen" },
      { "type": "formCheck", "name": "maxlen" }
    ],
    "value": "",
    "visible": true
  },
  {
    "defaultValue": "",
    "label": "Last name",
    "name": "lastName",
    "required": false,
    "validations": [
      { "type": "formCheck", "name": "minlen" },
      { "type": "formCheck", "name": "maxlen" }
    ],
    "value": "",
    "visible": true
  },
  {
    "defaultValue": "",
    "label": "Subject",
    "name": "subject",
    "required": true,
    "validations": [
      { "type": "formCheck", "name": "maxlen" }
    ],
    "value": "",
    "visible": true
  },
  {
    "defaultValue": "",
    "label": "Customer number",
    "name": "customerNumber",
    "required": false,
    "validations": [
      { "type": "formCheck", "name": "maxlen" }
    ],
    "value": "",
    "visible": true
  },
  {
    "defaultValue": "",
    "label": "Text",
    "name": "text",
    "required": true,
    "validations": [
      { "type": "formCheck", "name": "minlen" },
      { "type": "formCheck", "name": "maxlen" }
    ],
    "value": "",
    "visible": true
  }
]

Function - load

The function $wsForm.load() is used to access the submitted data of a sent form. This can be used, for example, to show the user the submitted information in the frontend or via email. This example checks whether the form was successfully sent and loads the inquiry data. This is done as follows (commented out so that the output is not displayed directly in the frontend):

{{ var $action = $wsActions.create('InquirySend') }}
{{ if $action.success }}
    
{{ /if }}

The output in the browser’s developer console could then look like this:

{
  "createdAt": "2025-04-14T06:43:57Z",
  "form": {
    "customerNumber": {
      "label": "Customer number",
      "value": "10011"
    },
    "firstName": {
      "label": "First name",
      "value": "VX"
    },
    "lastName": {
      "label": "Last name",
      "value": "Buyer"
    },
    "subject": {
      "label": "Subject",
      "value": "Test inquiry"
    },
    "text": {
      "label": "Text",
      "value": "Please send more info"
    }
  },
  "formId": "contact",
  "id": "52ad06427c68738c",
  "submitter": {
    "email": "vx-kauefer@beispiel.de",
    "ipAddress": "95.90.217.XXX",
    "sessionId": "c5a37018627bf18e2f0b151ee5fa19b77b1ed64794fa710b45e17613460ba60a"
  }
}

Example: display data in the frontend

This example loads and displays the data of a sent form using the $wsForm.load() function.

{{ var $action = $wsActions.create('InquirySend') }}
{{ if $action.success }}
   {{ var $inquiry = $wsForm.load($action.successInfo.inquiryId) }}
   Thank you for your inquiry.
   Here is your data:
   Your email address: {{= $inquiry.submitter.email }}
   Your IP address: {{= $inquiry.submitter.ipAddress }}
   Inquiry ID: {{= $inquiry.id }}
   Inquiry type: {{= $inquiry.formId }}
   First name: {{= $inquiry.form.firstName.value }}
   Last name: {{= $inquiry.form.lastName.value }}
   Your customer number: {{= $inquiry.form.customerNumber.value }}
   Subject: {{= $inquiry.form.subject.value }}
   Your message: {{= $inquiry.form.text.value }}
{{ /if }}

You can find more examples of displaying and loading form data here:
→ Practical examples: forms

Frontend

The basics

Getting started

Feature overview

Examples

Reference – Actions

Reference – Language

Reference – Modules

$wsForm - Forms

Module overview

Templates

Variables

$wsForm.inquiryId

Methods

$wsForm.loadType()

Variables of the field objects

$wsForm.loadAllTypes()

$wsForm.load()

Variables of the inquiry data

$myInquiry.id

$myInquiry.formId

$myInquiry.createdAt

$myInquiry.submitter

$myInquiry.submitter.email

$myInquiry.submitter.sessionId

$myInquiry.submitter.ipAddress

$myInquiry.form

$myInquiry.form.”fieldName”.label

$myInquiry.form.”fieldName”.value

Actions

Example for displaying form fields

Function - loadType

Function - load

Example: display data in the frontend

​Module overview

​Templates

​Variables

​$wsForm.inquiryId

​Methods

​$wsForm.loadType()

​Variables of the field objects

​$wsForm.loadAllTypes()

​$wsForm.load()

​Variables of the inquiry data

​$myInquiry.id

​$myInquiry.formId

​$myInquiry.createdAt

​$myInquiry.submitter

​$myInquiry.submitter.email

​$myInquiry.submitter.sessionId

​$myInquiry.submitter.ipAddress

​$myInquiry.form

​$myInquiry.form.”fieldName”.label

​$myInquiry.form.”fieldName”.value

​Actions

​Example for displaying form fields

​Function - loadType

​Function - load

​Example: display data in the frontend

​Related links

Module overview

Templates

Variables

$wsForm.inquiryId

Methods

$wsForm.loadType()

Variables of the field objects

$wsForm.loadAllTypes()

$wsForm.load()

Variables of the inquiry data

$myInquiry.id

$myInquiry.formId

$myInquiry.createdAt

$myInquiry.submitter

$myInquiry.submitter.email

$myInquiry.submitter.sessionId

$myInquiry.submitter.ipAddress

$myInquiry.form

$myInquiry.form.”fieldName”.label

$myInquiry.form.”fieldName”.value

Actions

Example for displaying form fields

Function - loadType

Function - load

Example: display data in the frontend

Related links