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

# PRODRATING- (Submitting and confirming a rating)

> Build the input form for a product rating, report input errors, resolve the nickname and release the rating via double opt-in by email.

A product rating is created in several steps: the buyer fills in the form, the module checks the entries, resolves the nickname if necessary, and finally the buyer confirms the rating via a link in an email. There is a separate template of the product rating module for each of these steps.

| Template | Role |
| - | - |
| Edit | the input form |
| Confirm | the confirmation page after submission |
| ConfirmMail | the email with the confirmation link |
| MailValidation | the page on which the link from the email lands |

This page describes the tags of these four templates. Displaying existing ratings and changing the nickname have their own pages.

* Guide: Description of the product rating module
* Reference: PRODRATING- (Displaying ratings)
* Reference: PRODRATING- (Changing the nickname)

> [!NOTE]
>
> The product rating module is a separate module with its own templates. These templates run either directly or embedded in the shop via `WS-ExtInclude`. Which of the two operating modes you use changes the behavior of some tags. The affected places are named below in each case.

## Building the form

The input form needs a target and six fields: nickname, email address, heading, comment, score and the submit button.

| Tag | Returns |
| - | - |
| `PRODRATING-LinkSubmitComment` | the target of the form |
| `PRODRATING-Subject_input` | the HTML name of the field for the heading |
| `PRODRATING-Subject_value` | the previous content of the heading |
| `PRODRATING-Comment_input` | the HTML name of the field for the comment |
| `PRODRATING-Comment_value` | the previous content of the comment |
| `PRODRATING-Rating_input` | the HTML name of the field for the score |

The nickname and email address come from the address data prefix.

Reference: `A-NickName_input`, `A-NickName_value`, `A-E-Mail_input` and `A-E-Mail_value` on the page A- (Billing address)

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<form name="bewertung" method="post" action="~PRODRATING-LinkSubmitComment~">
   <input type="text" name="~A-NickName_input~" value="~A-NickName_value~">
   <input type="text" name="~A-E-Mail_input~" value="~A-E-Mail_value~">
   <input type="text" name="~PRODRATING-Subject_input~" value="~PRODRATING-Subject_value~">
   <textarea name="~PRODRATING-Comment_input~">~PRODRATING-Comment_value~</textarea>
   <input type="submit" value="Bewertung abschicken">
</form>
```

> [!WARNING]
>
> `PRODRATING-LinkSubmitComment` behaves differently depending on the operating mode. If the template runs directly, the tag outputs an address that you place in the `action` attribute. If it runs via `WS-ExtInclude`, the same tag instead outputs several hidden form fields. In that case, it belongs **inside** the form and not in the `action` attribute, and you use the shop template as the target.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<form name="bewertung" method="post" action="~FORM-Template(tpl_read_prod_rating.htm)~">
   ~PRODRATING-LinkSubmitComment~
   ...
</form>
```

> [!NOTE]
>
> The heading holds a maximum of 256 characters, the comment a maximum of 10,000 characters.

> [!NOTE]
>
> In include mode, the shop system outputs the two `_value` tags HTML-safe. When run directly, the content appears unchanged. Therefore, do not rely on entered text being masked in every case.

## The score

The rating ranges from one to ten points. For each point value, there is an HTML value and an image, plus the currently selected value in two versions.

| Tag | Returns |
| - | - |
| `PRODRATING-RatingPoint1` … `PRODRATING-RatingPoint10` | the HTML value for one to ten points |
| `PRODRATING-RatingPoint1Image` … `PRODRATING-RatingPoint10Image` | the image address for one to ten points |
| `PRODRATING-Rating_value` | the selected score as a number |
| `PRODRATING-Rating_htmlvalue` | the selected score as an HTML value |
| `PRODRATING-RatingActualPointImage` | the image address for the selected score |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<fieldset>
   <label>
      <img src="~PRODRATING-RatingPoint1Image~" alt="1 Punkt">
      <input type="radio" name="~PRODRATING-Rating_input~" value="~PRODRATING-RatingPoint1~">
   </label>
   <label>
      <img src="~PRODRATING-RatingPoint2Image~" alt="2 Punkte">
      <input type="radio" name="~PRODRATING-Rating_input~" value="~PRODRATING-RatingPoint2~">
   </label>
   ...
</fieldset>
```

> [!NOTE]
>
> `PRODRATING-Rating_value` is the plain number, `PRODRATING-Rating_htmlvalue` is the value that the form submits. For a preselected selection field, you need the HTML value; for a display, the number.

> [!NOTE]
>
> You determine how many points you offer through the number of fields in the template. The module knows ten; a template with five stars simply uses only `PRODRATING-RatingPoint1` to `PRODRATING-RatingPoint5`.

> [!NOTE]
>
> The images for the point values and the image for the average rating are defined in the `ProductRatingImages` and `AdvancedProductRatingImages` sections of the configuration, respectively.

* Reference: `ProductRatingImages` section
* Reference: `AdvancedProductRatingImages` section

## Reporting input errors

If something is wrong with the entries, the module indicates this in three ways: as text, as a list and per field as a flag for styling.

| Tag | Returns |
| - | - |
| `PRODRATING-InputError` | the error text from the configuration |
| `PRODRATING-InputErrorList` | a list of the incorrect entries |
| `PRODRATING-Nickname_error_flag` | `ok` or `err` for the nickname field |
| `PRODRATING-Email_error_flag` | `ok` or `err` for the email field |
| `PRODRATING-Rating_error_flag` | `ok` or `err` for the score |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PRODRATING-InputError}
   <p class="fehler">~PRODRATING-InputError~</p>
   ~PRODRATING-InputErrorList~
{/PRODRATING-InputError}

<div class="feld input_~PRODRATING-Nickname_error_flag~">
   <input type="text" name="~A-NickName_input~" value="~A-NickName_value~">
</div>
```

> [!NOTE]
>
> The three `_error_flag` tags output nothing more than the two strings `ok` and `err`. They are intended as part of a CSS class name, as in the example. You append the flag to a fixed class name and then style `input_ok` and `input_err` differently. For the explanation, the previous documentation refers to a section further down that does not exist on the page.

> [!NOTE]
>
> The range `PRODRATING-InputError` does not depend on whether an error text is stored, but on whether the entry was incorrect. An empty error text in the configuration therefore does not hide the area; it displays it empty.

> [!NOTE]
>
> `PRODRATING-Nickname_error_flag` also reports `err` if the buyer has just requested that their nickname be sent. This is not an input error but an indication that something still needs to be done at this point.

> [!NOTE]
>
> The error text comes from the `Error` parameter of the module configuration.

## Multiple ratings

If only one rating per person and product is allowed in the shop, a range hides the form and explains the reason.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{!PRODRATING-MultipleInput_error}
   <form name="bewertung" method="post" action="~PRODRATING-LinkSubmitComment~">
      ...
   </form>
{/!PRODRATING-MultipleInput_error}

{PRODRATING-MultipleInput_error}
   <p>Sie haben dieses Produkt bereits bewertet.</p>
{/PRODRATING-MultipleInput_error}
```

> [!NOTE]
>
> `PRODRATING-MultipleInput_error` exists only as a range tag. Place the entire form in the negative range; otherwise, the buyer can submit a second rating, which is subsequently rejected.

## The nickname

Ratings appear under a nickname. An email address is always bound to exactly one nickname. If the buyer enters an address that is already registered under a different nickname, the module offers two options: having the existing nickname sent by email or changing it.

| Tag | Task |
| - | - |
| `PRODRATING-SendNicknameButton` | range around the area for sending the nickname |
| `PRODRATING-SendNicknameButton_input` | HTML name of the button for sending the nickname |
| `PRODRATING-NicknameMailRequested` | range, applies after the request |
| `PRODRATING-ChangeNickname_button` | HTML name of the button for changing the nickname |
| `PRODRATING-MinimumNicknameLength` | minimum length of a nickname |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PRODRATING-SendNicknameButton}
   <p>Diese E-Mail-Adresse wird bereits unter einem anderen Nickname verwendet.</p>
   <input type="submit" name="~PRODRATING-SendNicknameButton_input~" value="Nickname zusenden">
   <input type="submit" name="~PRODRATING-ChangeNickname_button~" value="Nickname ändern">
{/PRODRATING-SendNicknameButton}

{PRODRATING-NicknameMailRequested}
   <p>Wir haben Ihnen Ihren Nickname zugeschickt. Bitte tragen Sie ihn oben ein.</p>
{/PRODRATING-NicknameMailRequested}
```

> [!NOTE]
>
> `PRODRATING-SendNicknameButton` only applies if the entered email address is valid **and** does not match the entered nickname. Only then does the notice make sense, not before.

> [!NOTE]
>
> `PRODRATING-MinimumNicknameLength` is permitted in all templates of the module and is suitable for a notice next to the input field.

> [!NOTE]
>
> The button for changing leads to the ChangeNickname template. Its tags are on a separate page.

## Displaying the submitted rating

On the Confirm, ConfirmMail and MailValidation templates, you show the buyer what they submitted.

| Tag | Returns |
| - | - |
| `PRODRATING-ID` | the unique identifier of the rating |
| `PRODRATING-Subject_value` | the heading |
| `PRODRATING-Comment_value` | the comment |
| `PRODRATING-Rating_value` | the score |
| `PRODRATING-RatingActualPointImage` | the image for the score |
| `PRODRATING-Date` | the timestamp of the rating |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<p>Vielen Dank für Ihre Bewertung.</p>

<dl>
   <dt>Überschrift</dt><dd>~PRODRATING-Subject_value~</dd>
   <dt>Kommentar</dt><dd>~PRODRATING-Comment_value~</dd>
   <dt>Bewertung</dt><dd><img src="~PRODRATING-RatingActualPointImage~" alt="~PRODRATING-Rating_value~ von 10"></dd>
</dl>
```

### The date for search engines

For microdata, search engines need the date in individual components.

| Tag | Returns |
| - | - |
| `PRODRATING-Date_day()` | the day of the rating date |
| `PRODRATING-Date_month()` | the month of the rating date |
| `PRODRATING-Date_year` | the year of the rating date |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<meta itemprop="datePublished"
      content="~PRODRATING-Date_year~-~PRODRATING-Date_month(true)~-~PRODRATING-Date_day(true)~">
```

> [!WARNING]
>
> Always use the argument `true` for day and month. Without an argument and with `false`, the module pads single-digit values not with a zero but with a **space**. This is unusable for a date in microdata, and a visible gap also appears in the display. The previous documentation describes output without a leading character for `false`; this is not correct.

> [!NOTE]
>
> `PRODRATING-Date_year` always outputs the year with four digits. An argument is accepted but not evaluated.

Guide: Microdata for search engines and rich snippets

## Confirmation by email

So that nobody can submit a rating under someone else's name, the module sends an email with a confirmation link. Only after clicking it does the rating count.

| Tag | Belongs in | Task |
| - | - | - |
| `PRODRATING-MailConfirmLink` | ConfirmMail | the confirmation link |
| `PRODRATING-RatingAlreadyConfirmed` | MailValidation | range for the second click |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Bitte bestätigen Sie Ihre Bewertung:
~PRODRATING-MailConfirmLink~
```

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{!PRODRATING-RatingAlreadyConfirmed}
   <p>Danke für die Bestätigung Ihrer Bewertung.</p>
{/!PRODRATING-RatingAlreadyConfirmed}

{PRODRATING-RatingAlreadyConfirmed}
   <p>Sie haben diese Bewertung bereits bestätigt.</p>
{/PRODRATING-RatingAlreadyConfirmed}
```

> [!WARNING]
>
> `PRODRATING-MailConfirmLink` must be in the mail template. Without this link, the buyer cannot reach the confirmation, and the rating remains unpublished.

> [!NOTE]
>
> A confirmation link can be clicked several times. `PRODRATING-RatingAlreadyConfirmed` distinguishes the first click from every subsequent one, so that the page does not show the same thank-you twice.

## Back to the shop

| Tag | Leads to |
| - | - |
| `PRODRATING-LinkToWebsale` | the product view in the shop |
| `PRODRATING-ReadComments` | the list of existing ratings |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<a href="~PRODRATING-LinkToWebsale~">Zurück zum Produkt</a>
<a href="~PRODRATING-ReadComments~">Vorhandene Bewertungen lesen</a>
```

> [!NOTE]
>
> The product number and product index are available in all templates on this page via `PR-Number` and `PR-ProdIndex`. You can get further product data with `PR-AdvData()`.

Reference: PR- (Basics and product data)

## General error message

`PRODRATING-Error` outputs the general error message of the module and applies as a range tag if there is one. It is permitted in the Edit and ChangeNickname templates.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PRODRATING-Error}
   <p class="fehler">~PRODRATING-Error~</p>
{/PRODRATING-Error}
```

## The tags at a glance

| Tag | Single tag | Range tag | Negative range tag | Loop tag | Templates |
| - | - | - | - | - | - |
| `PRODRATING-Error` | yes | yes | yes | – | Edit, ChangeNickname |
| `PRODRATING-LinkSubmitComment` | yes | – | – | – | Edit |
| `PRODRATING-Subject_input` | yes | yes | yes | – | Edit |
| `PRODRATING-Subject_value` | yes | yes | yes | – | Edit, Confirm, ConfirmMail, MailValidation, List |
| `PRODRATING-Comment_input` | yes | yes | yes | – | Edit |
| `PRODRATING-Comment_value` | yes | yes | yes | – | Edit, Confirm, ConfirmMail, MailValidation, List |
| `PRODRATING-Rating_input` | yes | yes | yes | – | Edit |
| `PRODRATING-Rating_value` | yes | yes | yes | – | Edit, Confirm, ConfirmMail, MailValidation, List |
| `PRODRATING-Rating_htmlvalue` | yes | yes | yes | – | Edit, Confirm, MailValidation, List |
| `PRODRATING-RatingPoint1` … `10` | yes | yes | yes | – | Edit, Confirm, MailValidation, List |
| `PRODRATING-RatingPoint1Image` … `10Image` | yes | yes | yes | – | Edit, Confirm, MailValidation, List |
| `PRODRATING-RatingActualPointImage` | yes | yes | yes | – | Confirm, MailValidation, List |
| `PRODRATING-InputError` | yes | yes | yes | – | Edit, ChangeNickname |
| `PRODRATING-InputErrorList` | yes | yes | yes | – | Edit, ChangeNickname |
| `PRODRATING-Nickname_error_flag` | yes | – | – | – | Edit |
| `PRODRATING-Email_error_flag` | yes | – | – | – | Edit |
| `PRODRATING-Rating_error_flag` | yes | – | – | – | Edit |
| `PRODRATING-MultipleInput_error` | – | yes | yes | – | Edit |
| `PRODRATING-SendNicknameButton` | – | yes | yes | – | Edit, ChangeNickname |
| `PRODRATING-SendNicknameButton_input` | yes | yes | yes | – | Edit, ChangeNickname |
| `PRODRATING-NicknameMailRequested` | – | yes | yes | – | Edit, ChangeNickname |
| `PRODRATING-ChangeNickname_button` | yes | – | – | – | Edit |
| `PRODRATING-MinimumNicknameLength` | yes | – | – | – | all |
| `PRODRATING-ID` | yes | yes | yes | – | Confirm, ConfirmMail, MailValidation, List |
| `PRODRATING-Date` | yes | yes | yes | – | Confirm, MailValidation, List |
| `PRODRATING-Date_day()` | yes | yes | yes | – | Confirm, MailValidation, List |
| `PRODRATING-Date_month()` | yes | yes | yes | – | Confirm, MailValidation, List |
| `PRODRATING-Date_year` | yes | yes | yes | – | Confirm, MailValidation, List |
| `PRODRATING-MailConfirmLink` | yes | – | – | – | ConfirmMail |
| `PRODRATING-RatingAlreadyConfirmed` | – | yes | yes | – | MailValidation |
| `PRODRATING-LinkToWebsale` | yes | yes | yes | – | Edit, Confirm, MailValidation, List, ChangeNickname |
| `PRODRATING-ReadComments` | yes | – | – | – | Edit, Confirm, MailValidation |

The `_input` tags output fixed HTML names and are therefore never empty. Their range therefore always applies and provides no benefit.

## Related topics

* Guide: Description of the product rating module
* Guide: Configuring the product rating module
* Reference: PRODRATING- (Displaying ratings)
* Reference: PRODRATING- (Changing the nickname)
* Reference: RATEREMINDMAIL- (Rating reminder)


## Related topics

- [RATEREMINDMAIL- (Rating reminder)](https://dokumentation.websale.de/en/v8s/referenz/tags/rateremindmail-bewertungserinnerung.md)
- [Rating configuration prodrating.config](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/bewertungskonfiguration-prodrating-config.md)
- [E-PRODRATING-EKOMI_ (eKomi product rating)](https://dokumentation.websale.de/en/v8s/referenz/tags/e-prodrating-ekomi.md)
- [Materials: eKomi product rating](https://dokumentation.websale.de/en/v8s/materialien/materialien-ekomi-produktbewertung.md)
- [Structured data and rich snippets](https://dokumentation.websale.de/en/v8s/seo/strukturierte-daten-rich-snippets.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.