Forms, Bonuses and Smarty Templates

Configuring Forms

User-defined forms allow you to adjust particularly complex forms, such as the registration form, to the requirements of a specific panel in an optimal way.

EFS provides you with user-defined forms for registration, data changes, and profiles of community panels.

  • You can use different forms on different language versions of the same website.
  • For each language version, you can create and use several forms of the same type at the same time. Thus you can, for example, use different registration forms for different ways of entry.
  • Related variables can be assigned to a group and then output in a separate section of the registration form, for example.

In the following Chapters, you learn to manage user-defined forms:

  • It explaines how to manage the forms of a panel.
  • You learn to change the configuration of the variables used in a form.
  • It introduces special features of registration and data change forms.
  • You learn about the special features of profile forms.

Managing Forms

The GUI for creating and managing forms is located in the Website → Standard content → Forms menu.


Information

Read rights for “panel_website_forms” are needed for accessing the Forms menu.

If you want to view forms of another language version which you’re authorized to access in a given installation with several websites and/or language versions, simply change the settings in the upper section of the dialog. You can use the View function to change the number of table columns displayed as well as the number of rows per page. You can browse the overview table.

The following editing options are available:

  • Form name: Opens the overview of variables that belong to the respective form.
  • Edit settings: Opens the properties dialog.
  • Delete: The form will be deleted after a confirmation prompt.

Creating a Form

By clicking on the Create form button you can open the dialog used to configure a new form.

Form Properties

The table lists the properties a form can have.

FieldDescription
Website / Language version

Website and language version to which the form belongs. Cannot be changed subsequently.

Form nameName of the form
DescriptionDescription for internal purposes only
Form type

The form type determines the function module where the form can be used.

You can choose from the following types

  • Registration: Available in the “Registration form” function module.
  • Changing data (logged-in panelists only): Available in the “Change data” function module.
  • Profile: Available in the “Profile search” function module.
Default form

Depending on the form type, the default form is either displayed on the “Registration” or “Change data” page, if they were created with EFS version 5.1 or earlier.

The default form’s “Additionally save in” option is used for the current language/use case when panelists register or change their data per Web service.

Configuring the Variables of a Form

Overview of Form Variables

To view the variables belonging to a form, click on the form name in the overview table. Alternatively, you can also click on the Edit variables button in the form’s properties dialog. This takes you to an overview table that lists the form’s variables along with their key properties.

Configuring Variables

If you wish to change an existing variable configuration, click on the Edit variable x in form y icon in the overview.

Creating a New Variable

If you wish to create a new variable, click on the Add variable icon in the overview.

Outputting Variable Characteristics in a Form

The order in which the variable characteristics are displayed in the form depends on the codes; it starts with the smallest available code. It is not possible to set a divergent order or define different language-dependent orders.

Special Features of Registration and Data Change Forms

Correct collection of registration data and their subsequent maintenance, in particular of panelists’ contact data, is essential for panel operation:

  • Collected data should be as accurate as possible.
  • Registration data should be stored in such a way that they are available later for processes in which they are necessary. Gender, for example, is often required for forming groups and should therefore be available as a master data item. Panelists’ first names, on the other hand, are not needed for forming groups and drawing samples, but are important for establishing contact: They should be stored as address data items.

The form types “Registration” and “Data change” provide you with great flexibility in adjusting the forms to the requirements of a specific panel:

  • As in the past, you can perform plausibility checks on data entered by candidates as soon as on entry. This reduces the risk of erroneous or deliberately false entry of important data, such as names and e-mail addresses. In EFS 6.0 you can define considerably more complex check expressions.
  • You can specify where the queried data are to be stored in the database. Contact data such as name, street and zip code are normally saved in the participant data table. Data that are important for panel operation later on, such as gender and age, are saved in the master data table. Optionally, you can also store data in both tables. (This may be advisable e.g. for “country”.)
  • From EFS 6.0 and later, you can convert the data upon saving. For example, you can merge the values of several variables into a single variable.

Configuration Options

The following table contains all possible configuration options.

FieldDescription
Website / Language version

Website and language version to which the variable belongs. Cannot be changed subsequently.

Form name

This is determined when creating the form. Cannot be changed subsequently.

Form type

This is determined when creating the form. Cannot be changed subsequently.

Variable

The master data item or user variable which the form’s input field refers to.

  • Using the check expressions and transformation formulas described below, you can reformat the data entered, if necessary.
Label in formThe text used to label the form’s input field.
Exclude the following codes

You can hide certain answer characteristics of master data variables. To do so, enter the codes of the answer characteristics you wish to hide. The codes can be entered comma-separated or as a range (e.g. “1,2,3-10”).

Order

Order in which the input fields for the form’s different variables are output.

Group ID

The group ID is available in the templates and can therefore be used in many different ways, for example to group related form fields or to divide the form into different sections. If you assign the same group ID (e.g. 1) to several form fields, for example, you can output these fields next to instead of beneath each other (e.g. day, month und year for three related date fields). In doing so you can apply the label of the first grouped element to the whole line.

Check expression

You can enter a check expression, which is executed prior to saving of the data. If the check expression is correct, the data are not stored; instead, the specified error message is displayed.

  • Move the cursor over the ? icon to obtain an overview of available functions.
  • You can use the pseudo variable “self” to access the current variable.
Error message

Error message, which is displayed if the aforementioned check expression detects a problem.

Additionally save in

You can optionally save an entry in an additional master data item or user variable.

Only in the “Change data” form:

If the panelists use the “Change data” form, skip updating this variable if nothing was entered?

When using the form, panelists often only change a single variable and leave all the other input fields unchanged. By choosing this option you determine that only those values that were actually altered by the panelists will be added when they subsequently save their changes. Default setting: “Yes”.

Transformation formula for saving

You can enter a transformation formula, which is executed upon saving. This allows you to merge the values of several individual variables and store them in the current variable, for example.

  • Move the cursor over the ? icon to obtain an overview of available functions.
  • You can use the pseudo variable “self” to access the current variable.

Functions for Transformation Formulae and Check Expressions

You can use the following functions in transformation formulae and check expressions.

(cont.)FunctionExplanationParameterReturn valueExample
absabs (action: amount)

Returns the amount of a value without an algebraic sign.

$value: The value to be edited

Amount of the value without an algebraic sign

abs(self)

base64_decode

base64_decode (action: decode Base64)

Decodes the value using the Base64 algorithm.

$value: The value to be decoded

Base64 decoded value


base64_encode

base64_encode (action: encode Base64)

Encodes the value using the Base64 algorithm.

$value: The value to be decoded

Base64 decoded value


concat

concat (action: connect)

Connects two or more strings.

$string1 - $stringN: strings to be connected (an unlimited number of strings can be transferred)

concatenated strings

concat(self, u_firstname, md_0077)

get_date_diff

get_date_diff (action: difference between two dates)

Calculates the difference between two dates in days or years (rounded off).

$date1: first date, $date2: second date, $format: "d" (days), "y" (years)

Difference between two transferred dates

get_date_-diff('05.03.1982', '26.08.2008', 'y' ), get_date_-diff('1982-03-05', '26.08.2008', 'd' )

get_gmt_date

get_gmt_date (action: date in GMT)

Returns the current time (GMT) in the desired format.

$format: desired date format

Current, formatted date

get_gmt_- date('d.m.Y H:i:s')

get_timestamp

get_timestamp (action: date in timestamp)

Returns the Unix timestamp (number of seconds that have passed since January 11970 00:00:00 GMT) of the transferred date. Where no date has been transferred, the timestamp of the current date is returned.

$date (optional): date the timestamp of which is required

Unix timestamp

get_timestamp('13.04.2008'), get_timestamp('2008-04-13')

is_date_de

is_date_de (check: German date format)

Checks whether the transferred value is a date in German format (TT.MM.YYYY).

$value: Date to be checked

1, if German date, otherwise 0

is_date_de('05.03.1982')

is_date_int

is_date_int (check: int. date format)

Checks whether the transferred value is a date in international format (TT.MM.YYYY).

$value: Date to be checked

1, if international date, otherwise 0

is_date_de('05.03.1982')

is_email

is_email (check: valid e-mail format)

Checks whether the transferred value is a valid e-mail address format.

$value: E-mail address to be checked

1, if valid e-mail address, otherwise 0

is_email('mustermann
@questback.com')

is_float

is_float (check: floating-point number)

Checks whether the trasnferred value is a floating-point number.

$value: Value to be checked

1, if floatingpoint number, otherwise 0

is_float(10,5)
is_luhn

is_luhn (check: Luhn algorithm)

Checks whether the transferred value corresponds with the Luhn formula.

$value: Value to be checked

1, if Luhn algorithm, otherwise

0

is_luhn(10)
is_md5

is_md5 (check: md5 encoding)

Checks whether the transferred value was encoded using the md5 algorithm.

$value: Value to be checked

1, if md5- encoded, otherwise 0

is_md5('234mklksdf')

is_positive

is_positive (check: positive number)

Checks whether the transferred value is a positive number.

$value: Value to be checked

1, if positive number, otherwise 0

is_positive(5)
is_sha1

is_sha1 (check: SHA1 algorithm)





is_whole

is_whole (check: whole number)





length

length (action: return string length)

Returns the number of characters in a string.

$value: String to be checked

String lengthlength('test')
lowercase

lowercase (action: change to lower case)

Makes all characters in a string lower case.

$value: String to be changed

Changed stringlowercase('Test')
matches

matches (check: apply regular expression)

Checks whether a regular expression applies to a value

$regex: regular expression, $value: string to which the regular expression is applied

1, if regular expression applies, otherwise 0

matches('/^[a-f0-9]{32}$/','test');

md5

md5 (action: md5 encode)

Encodes the value using the md5 algorithm.

$value: Value to be encoded

Encoded value

md5('attack_at_dawn')

replace

replace (action: replace)

Searches the string for matches with regular expression and replaces them with "substitute".

$regex: regular expression, $replace: substitute $value: string

Edited string

replace('/^[a-f0-9]/','replace','7test12')

sha1

sha1 (action: encode SHA1)

Encodes the value using the SHA1 algorithm.

$value: Value to be encoded

Encoded value

sha1('attack_at_dawn')

substr

substr (action: return part of a string)

Returns the part of the string defined by the parameters start and length. If start is not negative, the returned string will commence at the string’s start position, beginning at 0.

$string: string, $start: beginning of the desired partial string $length (optional): length of the partial string

Partial string

substr('hello', 1, 1), returns 'e'

trim

trim (action: removes spaces at the start and the end)

Removes spaces at the start and end of a string.

$str: string, $charlist (optional): characters to be removed at the start and end of the string

Edited string

trim(' hello test ') results "hello test"

uppercase

lowercase (action: change to upper case)

Makes all characters in a string upper case.

$value: String to be changed

Changed string

uppercase('Test') results in "TEST"

whenwhen (query construction)

Checks whether an expression is true or not and returns the corresponding value.

$check: expression, $true: returned value (if expression is true), $false: returned value (if expression is false)

if $check is true, $true, otherwise $false

when('', 'true', 'false')

Nesting

Nesting can be used. If, for example, self = “testing”, the transformation formula yields uppercase(substr(self, 2, 3)) “st”.

Conjunctions

AND and OR can be used. If, for example, you enter a string that is not encrypted with MD5 or SHA1, the check expression

!is_md5(self) AND !is_sha1(self)

will yield an error. If the transferred string were encrypted with MD5 or SHA1, this expression would be false.

!is_positive(self) OR !is_date_de(self)

will yield no error only if both conditions are given, i.e., a positive number and a German date have been entered.

Example: Variables in the Standard Panel’s Forms

The following table lists the variables queried in the standard panel upon registration and changing of data.


VariableDescriptionOrderGroup ID

Check expression

Error message

Form „Registration“

Form „Change data“

u_account

Panelist's login name

1


XX
u_firstnameFirst name2

!matches('/ [^\s]/ ',request.u_firstname)

Please enter your first name.

XX
u_nameName3

!matches('/ [^\s]/ ',request.u_name)

Please enter your last name.

XX
u_streetStreet4

!matches('/[^\s]/ ',request.u_street)

Please enter your street name.

XX
u_zipZip code5

!matches('/^\s*\d{5}\s*$/ ',request.u_zip)

Please enter your zip code.

XX
u_cityCity6

!matches('/[^\s]/ ',request.u_city)

Please enter your city name.

XX
m_0000Country7

!matches('/^[^0]/ ',request.m_0000)

Please enter your country name.

XX
md_0001Day of birth81

!matches('/^[^0]/ ',request.m_0001)

Please choose your day of birth.

XX
md_0002Month of birth91

!matches('/^[^0]/ ',request.m_0002)

Please choose your month of birth.

XX
md_0003Year of birth101

!matches('/^[^0]/ ',request.m_0003)

Please choose your year of birth.

XX
u_genderGender11

!matches('/^[12]$/ ',request.u_gender)

Please choose your gender.

XX
u_emailE-Mail address12

!matches('/[^\s]/ ',request.u_email)

Please enter your email address.

XX
u_passwdPassword13

!matches('/[^\s]/ ',request.u_passwd)

Please enter a valid password.

XX

Ab EFS 9.1: u_sec_quest

Security question14


XX

Ab EFS 9.1: u_sec_quest_answer

Answer to security question

15


XX

Special Features of Profile Forms

The third form type is “Profile”. If you use the community functions of EFS Panel, you can use profile forms to specify which personal data of the panelists may be used for searches, listed in the results list, or displayed on the panelist’s profile.

Configuration Options

The following table contains all possible configuration options.

FieldDescription
Website / Language version

Website and language version to which the variable belongs. Cannot be changed subsequently.

Form name

This is determined when creating the form. Cannot be changed subsequently.

Form type

This is determined when creating the form. Cannot be changed subsequently.

Variable

The master data item or user variable which the form’s input field refers to.

Profile options

There are three options.

  • Field can be searched: The variable is part of the search form.
  • Field is displayed in profiles search results list: The variable is part of the results list.
  • Field is displayed in public profile: The variable is part of the profile.
Label in formThe text used to label the form’s input field.
Exclude the following codes

You can hide certain answer characteristics of master data variables. To do so, enter the codes of the answer characteristics you wish to hide. The codes can be entered comma-separated or as a range (e.g. “1,2,3-10”).

Order

Order in which the input fields for the form’s different variables are output.

Group ID

The group ID is available in the templates and can therefore be used in many different ways, for example to group related form fields or to divide the form into different sections. If you assign the same group ID (e.g. 1) to several form fields, for example, you can output these fields next to instead of beneath each other (e.g. day, month und year for three related date fields). In doing so you can apply the label of the first grouped element to the whole line.

Bonuses

Bonus points are usually exchanged for bonuses on special pages in the password protected, internal panel area. EFS Panel helps you present and manage bonuses:

  • You can create different bonuses and sort them into self-defined categories for easy browsing.
  • You can set the value of a bonus yourself or let the panelist enter a payment amount in a text field.
  • In addition to conventional standard bonuses you can also offer your panelists vouchers from affiliated companies. Optionally, voucher codes can be sent to panelists automatically.

Bonus payment is handled by EFS Panel’s proven bonus system.

Defining and Managing the Assignment of Bonuses

Overview of the Bonus Types

Under Website → Bonus management, you will find the types of bonus that have already been created for the panel. Use the drop-down lists in the head section to display the desired language version.

Creating New Bonus Types

  1. Click on the Create type of bonus button.
  2. Enter the required data into the form.



  3. Choose the type of payment.



  4. Further settings are required if you wish to create a “Voucher” bonus type:

    – You must choose a voucher code list and a mail template. We recommend creating these elements in advance, if possible. When doing so make sure that all elements have been assigned the suitable language version: The bonus dialog only displays lists and templates for the current language version.
    – Optionally, you can activate automatic voucher mail dispatch.

  5. If you wish to make the bonus type available to the panelists online, choose the status “Active”.

  6. Depending on whether you have defined the payment amounts in advance or wish to leave it up to panelists to choose an amount within a certain range, you have the following options:

    – If it is a bonus type where panelists can determine the payment amount themselves by entering a sum in a text field, you should set a minimum and a maximum value of payment. These are the minimum/maximum values that may be entered by panelists.
    – If it is a bonus type with a fixed value or one for which payment amounts were selected in advance from a drop-down list, enter the payment amount(s) in the“Limits of payment” section.

  7. Confirm by clicking on Save.

Configuration Details

Bonus Properties

The table lists all characteristics a bonus can have.

FieldWildcardMeaning

Website / Language version


Website and language version to which the bonus belongs. Cannot be changed subsequently.

Bonus category

Bonus categories allow you to classify bonuses, both in the admin area and on the panel page, according to selfdefined criteria.

Title (internal)

The internal bonus title. For orientation purposes only, it will not be seen by panelists.

Title (on website){$s.item_title}Title displayed on the panel page.
Description

{$s.item_description}

Description of the bonus.
Description 2

{$s.item_description2}

Optional, additional description text.
Image

Optionally, you can use an image, such as a photo of a gift. To do so, insert an image from the media library using HTML.

Image 2
Further optional image field.
Sort order

This field controls the order in which bonuses are listed on the panel page. If the display is limited to one bonus category, bonuses from this category will be displayed according to the order defined.

Manufacturer

Can be used to display the bonus manufacturer on the panel page.

Final description - for confirmation page after bonus points have been redeemed.

{final_desc}

Displayed on the confirmation page when bonus points have been redeemed.

Final description 2{final_desc2}

Can be additionally displayed on the confirmation page when bonus points have been redeemed.

Type of payment
See the following hapter.
Status

Available options are:

  • Inactive
  • Active

Only active bonuses will be displayed.

Minimum / maximum value of payment


If you wish to let the panelists enter the amount themselves in a text field, you can use these thresholds to define the range of the amount. At the same time, defining a minimum value of payment prevents panelists with less points from redeeming the respective bonus.

Limits of payment

Predefined payment amounts that can be determined by the panel administrator in advance.

The following figures illustrate the position of text elements in the standard panel which were inserted using wildcards.

Types of Payment

The following payment types are available:

Payment typesMeaning

Additionally required settings

Standard

The panel administrator calls up the reported payments in the admin area and processes them


Bank payment

This function allows you to use the EFS Panel bonus system for the handling of bank payments. The panelists enter their bank details using specially configured forms. The panel administrator calls up the reported bonus requests in the admin area to process them, usually by payment into a bank account.

  • Configure appropriate options in the "Bonus list and redemption" function module.
  • Optional: Activate the saving of bank details
  • Optional: Create master data for saving of bank details
  • Form configuration.
Voucher

Sending of vouchers with individual code

With vouchers there are no defined limits on payment, instead the amount is set by assigning a voucher code list.

Please note: Bonuses of the type “voucher” will only be shown in the bonus list as long as unused vouchers exist. As soon as the existing vouchers are used, the bonus will no longer be offered. Though only vouchers paid out by the administrator will be regarded as “used”, vouchers requested by panelists but still not paid out are regarded as “unused”. It can occur that more vouchers are requested than are available, because requests for all remaining vouchers have been made, but these were not processed by the administrator yet.

  • Configure appropriate options in the "Bonus list and redemption" function module.
  • Voucher code list
  • Mail template of the type “Voucher mail” for the respective language version.

The panelists can only choose one of these types of payment respectively. The error message which is output when combining different types of payment can be edited using the identifier “msg_different_payment_type”. Furthermore, with vouchers only one payment respectively can be requested with each redeeming process.

Defining and Limiting Amounts for Payment

For the “Standard” type of payment there are two ways of defining payment amounts:

  • The panelists can enter the desired amount themselves in a text field.
  • Predefined payment amounts, the so-called limits of payment, can be determined by the panel administrator in advance.

Panelists enter the desired amount in a text field

If you leave the “Limits of payment” field empty when creating a new bonus, a text field will be displayed on the “Redeem points” page. In this field, panelists can freely enter the number of points to be redeemed.

If you wish to limit the amount redeemable, use the “Minimum value of payment” and “Maximum value of payment” fields. At the same time, the minimum value of payment prevents panelists with less points from redeeming the respective bonus.

Panelists select predefined amounts

If at least one limit of payment is defined, fixed, unchangeable text will be output in the form. If only one limit has been defined, it is a continuous text. If more than one limit for payment has been defined, these can be selected from drop-down lists.

Limits of payment are defined as follows:

  1. Enter the number of required panel points into the “Amount” column.
  2. In the “Display” column you can enter the value as it will be seen by the panelists, i.e. for example with the name of the points or in a currency.
  3. After that, confirm by clicking on Save.


Information

If you wish to ensure that only those panelists who have a certain minimum number of points can redeem bonuses, you can do so in the “Bonus list and redemption” function module for the respective panel page: Enter the desired threshold in the “Minimum number of points for redeeming bonuses” field.

Please note that panelists with less points will then generally not be able to use the respective bonus list: No differentiation is made between new panelists and panelists who had a higher number of points in the past, but who have redeemed points in the meantime.

Handling of Bank Payments

You can use the EFS Panel bonus system for the handling of bank payments. The bank details of the panelists need not be stored on a long-term basis (e.g. via provision upon registration and subsequent storage as part of the master data), rather they are collected in the course of the payment process.

EFS offers the following design options:

  • Various combinations of the following bank details can be used: account holder, SWIFT code, IBAN, bank code, and account number.
  • You can define your own Regex checks to validate bank code and account number.
  • Optionally, you can store the bank details entered by the panelists in selected master data and use them to prefill the forms in future payment processes.

Example

The payment process works as follows:

  • The bonuses of the “bank payment” type are listed with all the other bonuses on the bonus redemption page.
  • If the panelist chooses a bank payment bonus, he will then be asked to enter his bank details in a specially configured form.
  • The administrator then processes the bank payment requests in the People → Incentive management → Bonus system → Payment list menu in just the same way as other bonuses.

Work Steps

In order to create a bank payment, please proceed as follows:

  • Create a bonus of the “bank payment” type for the desired language version as described in Chapter 24.1.2, S. 485. Select “Bank payment” as the payment type. As with other bonuses, there will be a free entry field displayed on the panel page if no limits on payment have been defined. If you do define limits on payment, these will be displayed in a drop-down list.
  • Use the “Bonus list and redemption” function module to create a page for the redemption of bonuses. If such a page already exists in the desired language version of your panel, then the new bonus will be displayed there automatically once it has been activated.
  • Configure the options dedicated to bank payment in the “Bonus list and redemption” function module.
  • If you want to store the entered details and use them to prefill the form for future payments, you need to activate the option “Store entered data for bank payments in selected master data variables and use master data variables for preselection” in the “Bonus list and redemption” function module. Create appropriate master data (data type: text) and select these from the drop-down lists in the field “The following fields should be displayed for bank payments”.


Information

Authentification for PayPal is frequently handled via the e-mail address. In panels which were set up with EFS 8.1 or later, you can realize this based on the account holder field: it allows to store up to 100 characters.

Sending Vouchers

The EFS Panel bonus administration supports the use of voucher codes. With this method you purchase a list of voucher codes from your partner, for example an online shop. You forward these by e-mail to your panelists and the panelists redeem the voucher codes at the partner business.

To manage the voucher lists of your panel, go to the Website->Bonus management menu and click on the Voucher code lists button. Use the drop-down lists in the head section to display the desired language version.

Creating a Voucher Code List

Normally you receive lists from your partner, which respectively contain voucher codes for a particular amount of money. For each of these lists, create a corresponding list in EFS:

  1. Ensure that the website and language version have been correctly configured.
  2. Click on the Create voucher code list button.
  3. Enter the title.

  4. Set the number in bonus points that the voucher code of the list will have.

  5. Optionally, you can enter a description. Using the wildcard #description#, you can later insert this description into the voucher mail. Please mind that you cannot edit this text at a later date. It is also not possible to enter translations into several languages.

  6. Confirm by clicking on Save.


Information

The value of bonuses of the “voucher” payment type is defined by assigning a voucher code list with a pre-set amount. Limits on payments cannot be used with the “voucher” payment type.

Preparing Voucher Codes for Import

  1. For importing you need a list of the voucher codes in the CSV or XLS format. The file is only allowed to have one column in which the codes are listed.

Importing Voucher Codes

  1. Choose either the title or the icon in the overview.
  2. Click on the button Import voucher codes into voucher code list.
  3. Choose the character set and look for the list on your harddrive.
  4. Trigger the import function by clicking on Send.
  5. After carrying out the import you can see the vouchers in the overview table.

  6. You can import the vouchers in blocks, i.e. if a list is almost empty, you can import new vouchers. It isn’t necessary to set up a new list for every import operation.


Information

The voucher codes which are imported into a list must be unique If a code is used twice in the import list or someone tries again to import a code that has already been imported an error message will be the result.

Preparing Mail Templates for Sending Vouchers

A special mail template of the type “Voucher mail” is used to dispatch voucher codes.

  • If you use voucher codes, you need at least one such mail template for every panel site. When setting this up, follow the instructions in “EFS Survey”.
  • You can use the standard mail wildcards for panel projects. These wildcards are particularly important:

    – #code#: is filled with the voucher code. This wildcard must be used.
    – #amount#: can be inserted in order to output the value of the voucher in normal currency.

  • The desired mail template is set when configuring a bonus.

Issuing Vouchers

Requested vouchers can be issued in the People → Incentive management → Bonus system → Issuing of vouchers menu. (Exception: where automatic dispatch has been activated, see following chapter)

  1. Select the panelists whose voucher you would like to issue.
  2. Pay attention that the required vouchers are available: the number is listed in the column “Available”.
  3. Use the Preview icon to view the voucher mail.
  4. Confirm by clicking on Execute.
  5. Dispatching of e-mails with the vouchers is done automatically.

You can check in the panelist’s detail view, whether the e-mail was sent. To do so, click on the Contact history button on the Contacts tab: The sought-after e-mail can be found in the “system mail” section.


Information

A panelist has lost the voucher mail and you want to send the voucher code again? Navigate to the People → Incentive management → Bonus system → Payment list menu and click on the Detail view button. In the table, you can find the dispatched codes.

Sending Vouchers Automatically

Optionally, you can have vouchers automatically issued by the system. This feature reduces your and your colleagues’ workload. However, it also means that voucher requests are no longer monitored by humans. You should therefore weigh up how high the risk of abuse is for your panel. If you choose to use this feature, test the configuration very carefully before activating it and regularly check the accuracy of payments made.

To activate automatic dispatch, click on the “Automatically send voucher confirmation mail” checkbox when creating the bonus type.


Information

The option Offer vouchers only from lists that still have unused voucher codes in the BONUS LIST AND REDEMPTION module is activated by default. If all vouchers of a list have already been redeemed, the bonus types using this voucher list will no longer by displayed. However, if the option is not activated, these bonus types will continue to be displayed and panelists can still redeem their points. In this case, however, the automatic dispatch of the voucher is not triggered. Instead, the redeemed voucher is displayed in the People module under Incentive management > Bonus system > Issuing of vouchers – just as if no automatic voucher dispatch had been configured. A red traffic light symbol and the number 0 are displayed in the Available column indicating that the voucher cannot be issued. The Encash action will only be available again once you upload new voucher codes.


Managing Voucher Code Lists

Monitoring voucher usage

  • When paying out requested vouchers in the People → Incentive management → Bonus system → Issuing of vouchers menu, you can find the number of codes that are still usable in the column “Available”.
  • The overview in the Manage voucher code dialog (see above) lists the complete set and the number of used and unused vouchers for every list.
  • In the detail view of a voucher list (Manage voucher code lists ->{Selected list}) the usage status will be listed for every single voucher.

Filling out a voucher code list

You can use the import function described above to refill codes.

Deleting vouchers that have not been used

Using the detail view of the voucher lists (Manage voucher code lists->{Selected list}) you can delete used vouchers:

  • Deleting a single unused voucher from a list: Mark the voucher to be deleted. Set the drop-down list to “delete” and confirm by clicking on Execute.
  • Deleting all unused vouchers from a list: Select the status “unused” in the Extended search. Trigger the search and mark “all found”. Set the drop-down list to “delete” and confirm by clicking on Execute.


Information

Codes that have been used cannot be deleted.

Deleting an unused voucher code list

Look for the desired list in the Manage voucher code lists menu and confirm by clicking on the Delete button.


Information

Voucher code lists can only be deleted as long as the codes contained in them are still unused. As soon as one or more codes are used, the list can no longer be deleted.

Categorizing Bonuses

Bonus categories allow you to classify bonuses, both in the admin area and on the panel page, according to self-defined criteria, thus improving usability.

The list of categories

To manage the bonus categories of your panel, go to the Website → Bonus management menu and click on the Bonus categories button. Use the drop-down lists in the head section to display the desired language version.

The overview lists all existing bonus categories for the currently-selected language version, each with a sort number and title.

  • You can browse the list.
  • If you want to view bonus categories of another language version in a given installation with several websites and/or language versions, simply change the settings in the upper section of the dialog.

The icons in the “Actions” column provide you with the following editing options:

  • Edit: You can change the title and description of a bonus category.
  • Delete: If you click on the icon and confirm the pop-up message that follows, the respective category will be removed.

Creating a new bonus category

  1. Ensure that the website and language version have been correctly configured.
  2. Click on the Create bonus category button.
  3. Enter the title.
  4. Enter the sort number in the sequence of bonus categories.
  5. Confirm your entries by clicking on Save.

Assigning bonuses to categories and changing assignments

  • When setting up new bonuses you can select the appropriate category from the “Bonus Category” drop-down list.
  • To change the category for an existing bonus, search for the bonus in the bonus list under Website → Bonus management → {Selected language version}, then open the edit dialog and change the selection in the “Bonus category” drop-down list.

Working with Smarty Templates

Templates control how data supplied by the modules are processed and output on panel pages. The present and following chapters describe the Smarty templates used in EFS:

  • The Smarty template engine is presented.
  • Features, tools and auxiliary tools for editing Smarty templates in the website editor are explained.


Information

Please note: No or very little knowledge of HTML was required for the operations introduced in previous chapters of this manual, such as creating new panel pages or maintaining news. However, advanced programming skills are prerequisite for working with Smarty templates and other technologies available in the website editor, such as CSS, JavaScript and mootools.

The Smarty Template Engine

The templates of the CMS are based on the Smarty template engine. Smarty is a proven template engine, which has been successfully used in EFS Survey for many years now. If you are familiar with the EFS Survey questionnaire layout, you will therefore find it easy to work with the CMS templates.

Please refer to http://www.smarty.net for detailed information on Smarty.

Information

Please note: The CMS and questionnaire layouts in EFS Survey are based on the same technology. However, it is not possible to import EFS Survey layout templates into the CMS.

Working with Templates

The “main_default” template is an example of a main template that is responsible for the overall structure of an individual panel page or all pages. In the standard panel, it defines the general structure of the panel pages.

By inserting include commands and wildcards in the main template, various other templates are integrated into this general structure. For a normal panel page as e.g. the “Contact us” page the following elements are integrated, among others:

  1. Language selection: The “tpl_language_selection” template. This field is only displayed for websites with several language versions.
  2. Subnavigation: The “tpl_subnav” template.
  3. Navigation: The “tpl_navigation” template. Depending on whether or not the viewer is logged in, this area contains different functions, which in turn are defined by two different templates.
  4. Messages: The “tpl_error_messages” template.
  5. Login: The “tpl_login_in” and “tpl_login_out” templates for logged-in panelists and visitors who are not logged in.
  6. Breadcrumb: The “tpl_breadcrumb” template.
  7. Actual content area: This is filled for each individual page with the help of content and function modules.

  8. Social bookmarks bar: Template “tpl_bookmarks”. (Social bookmarking is the collective indexing of web pages and other online resources.)

Managing Templates

Template Overview

A language version’s templates are located in the “Templates” tab in the tree view in the menu Website → Website editor.

  • The “Templates” tree view shows all templates and system templates.
  • The Lock icon indicates the respective publishing status.
  • The i icon allows to access detailed information (template name, file name, size, usage, status). The column “Usage” shows how often and on which pages the respective template is used. It considers integration as main template, positioning template or page module template. Integration via Smarty include command cannot be considered, though.

The following actions are available:

  • The + Template button opens the dialog where you can enter the data for a new template.
  • Clicking on a template opens its content in the editor.

  • Copy template: The template is copied, a new template name has to be entered. 

  • Delete template: The template will be deleted following a confirmation prompt.

  • Save: Saves the template. It is subsequently available in the working version. Please note: In the publicly accessible version, the template is only available once it has been published.

  • Save & Publish: The template is published. This means it is not only available in the working version but also in the online version.

Categorizing Templates

Smarty templates are categorized by the task they perform: This categorization allows the dynamic sorting or shortening of long lists of templates when it is clear which type will be required for a certain task. For example, when selecting positioning templates only general and positioning templates will be displayed. This makes it easier to find what you are looking for when working with panels where the website editor contains numerous templates.

Categorizing is performed manually, the names of the templates are not relevant. In the standard panel, the template nomenclature is based on the categories in order to make the structure transparent. However, you do not have to adopt this approach.

Categories

The following categories are used:

  • Main templates: Templates responsible for the general page structure.
    – In the standard panel, the names of these templates start with “main_”.
  • Global templates: These templates usually control overall layout components, such as login or navigation. They are incorporated in a main template.
    – In the standard panel, the names of these templates start with “tpl_”.
  • Templates for function modules: Templates linked to function modules.
    – In the standard panel, the names of these templates start with “func_”.
    – Function module and template are linked on the Edit page tab in the “Module template” field of the desired module.
  • Templates for content modules: Templates linked to content modules.
    – In the standard panel, the names of these templates start with “cont_”.
    – Content module and template are also linked on the Edit page tab in the
  • “Module template” field of the desired module.
  • Positioning templates: If several content modules are placed on a panel page, the contents are listed beneath each other, by default. With the help of positioning templates, however, you can create a different segmentation. On the standard panel homepage, for example, three text columns – each filled using a separate content module – are output next to each other with the help of a positioning template.
    – In the standard panel, the names of these templates start with “pos_”.
    – The positioning template and panel page are linked in the edit dialog of the respective page on the Page configuration tab.

Assigning Categories

The drop-down list for assigning a template to a certain category is located on the editing page of the template in the „Template category“ field.

Editing Templates

The Edit Dialog and its Features in Overview

Open any template, for example the simply structured “cont_headline_text” template that is linked to the “Headline and text” content module.

  • In the head section, you can find the template name. This is the name shown in the tree view, for example. From EFS 10.4, it is identical with the file name. When you create a new template, the name is put together from the user-defined template name and the suffix “.tpl”. It should not contain special characters or blank spaces. It is not possible to change the name.
  • The dialog’s main component is the source code input field. From EFS 10.4, a new comfortable editor is available. The editor is activated and deactivated in the Options → Personal preferences menu via the “Use editor with syntax highlighting for templates” function on the Panel tab.
  • On the History tab, you can view previous versions, compare two particular versions or reset a broken template to an earlier, functioning version.

Working with Includes

Includes are files that are incorporated in templates with the help of HTML. They contain CSS definitions for the layout or provide functionalities, for example.

Examples for includes in the standard panel

There are two types of includes: CSS and JavaScript. In the standard panel, the following files are available in the website editor’s “Includes” folder, among others:

  • “CSS” type:
    – css_default: CSS file primarily responsible for the layout in the standard panel.
  • “JavaScript” type:
    – js_default: Provides various JavaScript functions.
    – several mootools includes: mootools is a JavaScript library that provides various functions, classes and methods. In the standard panel, mootools provides the show and hide functions and the mouse over effects in the navigation, for example. See http://www.mootools.net/, for example, for further information.


Information

Please note: Smarty, CSS, JavaScript etc. are common web technologies that we merely provides.

Managing Includes

You will find the includes of a language version on the “Includes” tab in the tree view in the Website → Website editor menu.

  • All includes and system includes are shown.
  • Clicking on an include opens its content in the editor.
  • The Lock icon indicates the respective publishing status.
  • The i icon allows to access the file name.
  • The actions for editing the includes in the overview are identical to the actions for editing the templates.

CSS-Based Layout Design

You can use CSS classes to control layout properties for the entire panel. For example, you do not need to make changes manually to the font color in each module or template, but can change the appearance of the entire external view by making a one-time change to the respective style sheet template.

When delivered, the CSS file “css_default” is primarily responsible for the standard panel’s layout. You can use this CSS file to perform the following operations:

  • Changing properties of CSS classes.
  • Using existing replacement rules to output status-dependent views.
  • Defining new CSS classes.

You can use “css_custom” to overwrite it, or create additional CSS files as necessary.

If you set up several websites and/or language versions, each version will have its own CSS file(s).


Information

The “Web Developer” Extension for Firefox provides you with support with your practical work with style sheets, and can be downloaded at https://addons.mozilla.org/de/firefox/addon/web-developer/.

Benefiting Automatically From Improvements

Since EFS 8.2, manual corrections of templates and includes after website upgrades and updates are rendered almost completely superfluous thanks to system or default files. These are non-editable templates and includes which are updated automatically during normal installation updates and upgrades.

  • These system files allow you and your web designers to access the latest status of CMS development. Thus, in the long run, the system files will replace the template library.
  • In new panels, TIVIAN may integrate some of these system files directly, if e.g. the layout stays close to the standard panel. This will reduce the effort for manual modifications when updating or upgrading the installation.

In principle, the system templates can be used for the same purposes as the familiar normal templates.


Information

EFS Panel-driven panels show wide variations in terms of appearance and function.

- The system files mirror the functional scope and structure of an up-to-date standard panel.

- To find out if and how time and effort can be saved by using system templates in your existing panel, please get in touch with the support.

The most important characteristics of system files in brief:

  • System files cannot be modified by users.
  • They are automatically added and updated during normal installation updates and upgrades. I.e. their structure may change due to these updates.
  • System files are labelled with (DEFAULT).
  • There’s only one version of each system file.
    – There is no difference between working version and online version.
    – System files do not have a versioning history, i.e. the History tab is deactivated.
  • If a “normal” template and a system template share the same name, e.g. foo.tpl and foo.tpl (DEFAULT), EFS will assume that the “normal” template was created intentionally and that it is to be preferred. In consequence, if you select the system template foo.tpl (DEFAULT) in the drop-down list of a module, EFS will use the “normal” template foo.tpl.
  • The search for template and includes can be restricted to the familiar user-defined contents or to system contents.

Template Library

Prior to the introduction of system files, the template library was used to distribute new templates or sample code. It contains simpified versions or various function templates (i.e. without CSS classes, for example) until EFS 8.2.

Clicking on the Open template library button in the edit dialog opens a pop-up where you can select the desired target EFS version and the desired template. The template is displayed and you can copy the content into the input field of a new template for further editing.


Information

Thanks to the introduction of the system files, the template library is now superfluous. Therefore it will be dropped in EFS 10.4.

Troubleshooting

Viewing and Undoing Changes

The website editor has a versioning system for templates and includes. This means that you can, for example, view previous versions, compare two particular versions or reset a broken template to an earlier, functioning version.

Viewing the change history

To access the versioning system, open the desired template or include and switch to the History tab. It contains a list of all changes saved so far, including revision ID, date, and author.

Comparing and resetting versions

The following actions can be executed using the icons:

  • View: Opens the selected version of the template or include.
  • Compare with current version: Displays a comparison of the selected and the current version. (The revision ID in the header tells you which versions are being compared.)
  • Rollback: Resets the current version to the status of the selected version. This change is performed in the working version only, it is not published automatically.
  • Compare with previous version: Displays a comparison of the selected and the next oldest version. (The revision ID in the header tells you which versions are being compared.)


Information

The history contains the twenty most recent changes made to the respective template or include.

Debugging

You can have different debug information displayed below the proper panel pages, such as the current character set or a panelist’s language version. Furthermore, a Smarty debugging console is available. It contains an overview of all the wildcards that can be used on the respective page.

With EFS 10.3, a new, more comfortable console has been introduced:

  • It is not opened automatically anymore each time you click on the panel page, but only upon explicit request.
  • The smarty objects can be expanded and collapsed.
  • Clicking on a node copies the variable into the clipboard.

If you wish to use these functions, please proceed as follows:

  1. The debug functions are activated under Website → {Selected language version} on the Debugging tab in the field “Show debug information on the website”.
  2. To make sure that the debug mode will not be inadvertently activated for all panelists, the debug function has to be limited to an explicit address range. To do so, enter the desired IP addresses in the field “IP address range”. To have your own IP address available at all times, it is also displayed there.
  3. Optionally, you can also enforce authentication with a combination of user name and password. To do so, enter the desired user name and password into the fields “HTTP authentication (user)” and “HTTP authentication (password)”.
  4. In order to make the Smarty debugging console available (Figure 25.4), in addition to the settings described above, the main template must contain the command {debug}. This is the case in newly set-up standard panels. If the console does not open automatically in your installation, please check whether the command is available. In a newly-set up panel, you will usually find the following line at the end of the main template “main_default”:
    {debug} {* debugging *}


Information

Please note: If you activate the debug function in the online version of the panel site for the entire possible address range, the Smarty debugging console will be visible for all visitors to the panel. This means that the visitors may use it to obtain technical information that might be abused. You should therefore activate the debug function only for your own IP and/or within your working version and immediately deactivate it after you have completed your work.

Topics

© 2024 Tivian XI GmbH