> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# $wsForm - Forms

> Reference for $wsForm: load form fields, render forms and read out submitted form data dynamically in the WEBSALE frontend templates.

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`

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsForm | json }}
```

**JSON output**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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()`.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ foreach $field in $wsForm.loadType("contact").fields }}
    {{ foreach $key in sort(keys($field)) }}
        {{= $key }}: {{= $field[$key] }} 
    {{ /foreach }}
{{ /foreach }}
```

### **Variables of the field objects**

<Info>
  The `$wsForm.loadtype()` method returns an object per field (in this example `$myField`) with the following properties. If a `RuleSet` ([inquiry - Forms](/en/konfiguration/inquiry-formulare#4-inquiry-ruleset-regelbasierte-feldsteuerung)) 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](/en/konfiguration/actions-fehlertexte-e-mails/actions-formulare)). |
  | `$myField.visible`      | bool            | Indicates whether the field should be displayed (`true` / `false`). Is automatically controlled by `inputVisibilityDefinition` in the RuleSet.                  |
</Info>

### \$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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Form inquiry ID: {{= $myInquiry.id }}
```

#### \$myInquiry.formId

Returns the ID of the form used.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Form ID: {{= $myInquiry.formId }}
```

#### \$myInquiry.createdAt

Returns the time of sending.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Form sent: {{= $myInquiry.createdAt }}
```

#### \$myInquiry.submitter

Returns a map with data about the sender.

#### \$myInquiry.submitter.email

Returns the email address of the sender.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Email address: {{= $myInquiry.submitter.email }}
```

#### \$myInquiry.submitter.sessionId

Returns the session ID during which the form was sent.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Session ID: {{= $myInquiry.submitter.sessionId }}
```

#### \$myInquiry.submitter.ipAddress

Returns the IP address of the sender.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
First name label: {{= $myInquiry.form.firstName.label }}
```

#### \$myInquiry.form."fieldName".value

Returns the entered value of the field.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
First name value: {{= $myInquiry.form.firstName.value }}
```

***

## Actions

Actions for this module that trigger changes are documented separately in the "Actions" chapter: [Inquiry](/en/frontend/referenz/aktionen/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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
  {
    "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):

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $action = $wsActions.create('InquirySend') }}
{{ if $action.success }}
    
{{ /if }}
```

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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](/en/frontend/praxisbeispiele/formulare/kontaktformular)

***

## Related links

* [inquiry - Forms](/en/konfiguration/inquiry-formulare)
* [actions - Forms](/en/konfiguration/actions-fehlertexte-e-mails/actions-formulare)