Forms in Order Process

Introduction

PepperShop offers an easily integrable, dynamically designable, and multilingual form generator with the order form system. Currently, one form is fixed as a template – after checkout and before the order overview.

To use this module, HTML and PHP knowledge is required.

Files and Integration

Files

Integration into Order Process

The only form that exists so far, the ‘nach_kasse’ form, is integrated in the file shop/USER_BESTELLUNG_1.php. After checkout and before the order overview. The integration takes place in the area darstellen == 2. At the beginning of the area, it is checked whether you come from checkout or from the form, and further down, the control of the display of the form or the order overview is inserted. The display control is done via the constant NACH_KASSE_FORM defined in shop/util.php. By default, this is set to false (Boolean).

Form Template(s)

General

As described in the chapter Files and Integration, there is the file shop/bestellformular/nach_kasse_form.php, which contains the HTML template of the form. Actually not just one template, but several:

The template definitions are each in a PHP string, which usually extends over several lines.

Variables

The variables that are replaced by the form template system are enclosed in curly braces. Some examples: | Variables | Description | | ——— | ——— | |{get_localized_text[formulartitel]}| Read localized variable (here formulartitel) | |{selection}| within an element definition there are no prefixes| |{special:name}| ‘special:’ = prefix for distinction|

Hidden Elements

There are three hidden HTML input elements that are used for display control and must therefore always be present:

<input type="hidden" name="von_bestellformular" value="true">
<input type="hidden" name="lang" value="'.$lang.'">
<input type="hidden" name="javascript_enabled" value="'.$javascript_enabled.'">

<form>-Tag

Something special is of course always the <form ... > HTML tag, because this represents the connection of the form with the order process from the form’s perspective.

<form name="Bestellformular" action="'.$link_zum_check.'" method="post">

Important here is the PHP variable $link_zum_check. This variable contains the location where the form sends the entered customer data for verification. In the form template file, you can see PHP variable definitions at the very beginning, one of which is this link. The link back is realized via HTML link, this variable is also defined at the beginning of the file.

Element Definition

An element, or its definition, consists of two parts: A language-dependent and an independent part. The name of the form, the label (what is shown to the shop customer), the type of input validation (text, exact, nothing, …) and options are defined…

Language-Independent Data

This data is defined in the file shop/bestellformular/nach_kasse_elements.php. An example entry looks like this:

$form_elements[0]['name']       = 'keine_medikamente_einnehmen';
$form_elements[0]['type']       = 'dropdown';

It is important that you increase the number ([0]) per element, there must be no gaps in the numbering.

As you can see, the element definition is realized via PHP arrays.

• 'name' This refers to an internal name, best to use only [a-zA-Z0-9_]
• 'type' What type is the element: dropdown, text, radio, checkbox, textarea

The text field options are also language-independent, but are explained in the language-dependent part, since the types of input fields are described there. All further settings are language-dependent and are located in the corresponding files.

Language-Dependent Data

The definitions of an element that depend on a language are located in a separate file for each language. The names of the files can easily be assigned to a language, the postfix is the ISO-639-1 code of the language, format: Formularname_ISO-Code.php. Here are some examples:

• nach_kasse_de.php German
• nach_kasse_en.php English
• nach_kasse_fr.php French
• nach_kasse_it.php Italian

The language-dependent data are the following, partly type-dependent data:

Info: The order forms use an independent language control in PepperShop by default.

check_type – what should be checked?

What is the accepted value/value range for this element. If a different value is given by the shop customer, PepperShop shows him the error message specified in error_msg and he is sent back to the form. | Types of Checks | Description | | ——— | ——— | |irgendwas| = exactly this text is required | |–irgendwas| = everything is allowed, except empty string and the specified string| |@text| = any text can be entered, an empty string is recognized as false | |@email| = Only an email address is accepted (syntactic check only) | |= If you don’t specify anything, the element is not checked|

Now follow the element definitions that depend on the type of element, there is an example for each type in the language-dependent definition file.

dropdown

A dropdown menu consists of options. The selection of these options is displayed to the shop customer. The dropdown values (dropdown_values) are again arranged in an array from 0-n. Since a dropdown value itself consists of several definitions, the value itself is also defined in an array (array(…)). The ‘value’ contains the value transmitted via POST, ‘label’ the displayed name. The optional definition ‘option_color_style’ contains a hex-encoded color value, as is common on the web, with a preceding #. The color value assignment only works correctly in Internet Explorer.

$form_elements[0]['dropdown_values'][0] = array('value'=>'Ja','label'=>'Ja'  ,'option_color_style'=>'#33CC33');
$form_elements[0]['dropdown_values'][1] = array('value'=>'Nein','label'=>'Nein', 'option_color_style'=>'#FF0000');

text

A text field must also know how long the input field should be ‘size’ and what its maximum length should look like – ‘maxlength’. Since the text field does not contain language-dependent data, the definition is made in the file nach_kasse_elements.php:

$form_elements[0]['options']    = array('size'=>10,'maxlength'=>30);

radio

So that you don’t have to query further field name definitions in the program code, the dropdown_values were used here in the v.1.0 API. You have ‘name’ and ‘label’ again, but then a new definition ‘default’. This field contains a boolean value. If it = true, this field serves as the preselected default field in the radio button group. Per radio button group, there should always be only one field that has ‘default’ = true. All other fields in the group must have ‘default’ = false.

In the following example, you can see how you can integrate color information for the label using a simple <span> tag, for example.

$form_elements[0]['dropdown_values'][0] = array('value'=>'Ja' ,'label'=>'<span 
style="color:#33CC33">Ja</span>'  ,'default'=>true);
$form_elements[0]['dropdown_values'][1] = array('value'=>'Nein','label'=>'<span 
style="color:#FF0000">Nein</span>','default'=>false);

checkbox

The same syntax applies here as for the radio button group. The ‘default’ definition here means that the checkbox is preselected. The checkbox has the property that it only transmits its value when it is activated. If this is not the case, no POST value is generated and transmitted, this is just for information.

$form_elements[0]['dropdown_values'] = array('value'=>'Ja','label'=>'<span
style="color:#33CC33">Ja</span>','default'=>true);

textarea

With a textarea, larger text can also be queried. Here you must define the number of rows (‘rows’) and columns (‘cols’), as well as the type of line break (‘wrap’). The values possible here are the same as in the HTML 4.01 specification.

$form_elements[0]['dropdown_values'] = array('rows'=>10,'cols'=>3,'wrap'=>'physical','default_value'=>'Mein Text');

Process Flow in Order Process

Theoretically, forms can be integrated at any location in the order process. The respective controllers would have to be inserted at the corresponding locations in the handler of the order process: shop/USER_BESTELLUNG_1.php.

How are Check Results Evaluated?

In the file shop/bestellformular/nach_kasse_elements.php, two variables can be defined at the beginning of the file: $form_check_commit (how should the errors be interpreted) and the array $form_check_begruendung, in which the details are described if the interpretation ‘begruendung’ is chosen.

Interpretation Types

The variable $form_check_commit can be given two different values:

1. einzeln: The check of each individual element must be fulfilled. If even one is not successfully passed, the customer cannot proceed. This is the standard form evaluation method.
2. begruendung: If the choice falls on ‘begruendung’, the customer is asked for a justification as to why he chose this way for the failed checks. If the shop customer does not violate any checks of the elements entered in the array $form_check_begruendung['exclude'], he can pass. After so much prose, the check flow again in a list: 2.1 Is at least one check not fulfilled, if yes: 2.2 Display error messages and the justification field. 2.3 If the shop customer does not provide a justification and at least one check is still faulty, the customer is prevented from proceeding. 2.4 If the customer passes all checks or has at least provided a justification, another check is started: 2.5 Does the shop customer still violate a check that is excluded from the justification clause (element contained in exclude array). If yes, the ‘einzeln’ interpretation described in 1) applies to this element – he must pass this check.

Further Help

Do you have questions or need assistance? Do you have special requirements or desire a custom solution for your system? Our support team is happy to help. Support services are charged based on time and material at CHF 195.- / hour. Here is how to reach us:

• Email: support@glarotech.ch
• Phone: +41 (0)71 923 08 58
• Opening Hours: Monday – Friday I 8:00 a.m. – 12:00 p.m. I 1:30 p.m. – 5:00 p.m.

Other Useful Pages

• FAQ (Frequently Asked Questions)
• Modules & Functions
• Interfaces