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.

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.

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.

Functions for Transformation Formulae and Check Expressions

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

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.

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.

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.

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:

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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