PRODRATING- (Submitting and confirming a rating)

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)

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)

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

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.

<form name="bewertung" method="post" action="~FORM-Template(tpl_read_prod_rating.htm)~">
   ~PRODRATING-LinkSubmitComment~
   ...
</form>

The heading holds a maximum of 256 characters, the comment a maximum of 10,000 characters.

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

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

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.

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.

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

{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>

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.

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.

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.

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.

{!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}

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

{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}

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.

PRODRATING-MinimumNicknameLength is permitted in all templates of the module and is suitable for a notice next to the input field.

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

<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

<meta itemprop="datePublished"
      content="~PRODRATING-Date_year~-~PRODRATING-Date_month(true)~-~PRODRATING-Date_day(true)~">

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.

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

Bitte bestätigen Sie Ihre Bewertung:
~PRODRATING-MailConfirmLink~

{!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}

PRODRATING-MailConfirmLink must be in the mail template. Without this link, the buyer cannot reach the confirmation, and the rating remains unpublished.

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

<a href="~PRODRATING-LinkToWebsale~">Zurück zum Produkt</a>
<a href="~PRODRATING-ReadComments~">Vorhandene Bewertungen lesen</a>

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.

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

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)

​Building the form

​The score

​Reporting input errors

​Multiple ratings

​The nickname

​Displaying the submitted rating

​The date for search engines

​Confirmation by email

​Back to the shop

​General error message

​The tags at a glance

​Related topics

Building the form

The score

Reporting input errors

Multiple ratings

The nickname

Displaying the submitted rating

The date for search engines

Confirmation by email

Back to the shop

General error message

The tags at a glance

Related topics