WordPress Plugin – How To Use Forms

Specifying Forms

The plugin allows to select predefined and custom forms. Predefined forms are located inside the plugin folder: „wp-content/plugins/xqueue-maileon/views„. They will be overwritten with each update of the plugin, thus, they should not be changed. Instead they should be copied, renamed and then they should be uploaded to the folder for custom forms, which is inside the uploads folder: „wp-content/uploads/xqueue-maileon/views„. These forms will not be overwritten or changed by the plugin in any case. Since version 2.10 it is also possible to use (child) theme templates as forms. The available forms can be seen in the settings of the plugin:

Please be aware: when loading a template by it’s filename, the plugin will search in the following order:

1. Child theme folder
2. Theme folder
3. Uploads folder
4. Plugin views folder

Forms are specified in the shorttag as attribute „template“. Example: [[maileon-contact template="my-own-template.php"]]

In this example, the file would probably be loaded from „wp-content/uploads/xqueue-maileon/views/my-own-template.php„.

Standard forms

The plugin ships with a set of default forms, which are placed in the folder „wp-content/plugins/xqueue-maileon/views„. They are mainly meant for demonstration purposes, e.g. how to show simple forms, dropdowns, Address Check, or reCaptcha. The currently available files can be seen in the plugin configuration on the API-Settings page:

If no template is specified, the standard form will be used. It provides input fields for the email address, first name and last name.

Custom Forms

If you wish to add a custom form to use more fields in your form or use a different styling, just add your template to „wp-content/uploads/xqueue-maileon/views“ (you might need to create that folder first). A basic template as described above can be found in file ‚maileon-contact-form.php‘, a version extended by gender selection is shipped with the plugin as example in ‚\wp-content\plugins\xqueue-maileon\views\maileon-contact-form-custom-sample.php‘. You can take a copy of those files and edit it according to your wishes.

Again, you can check available templates in the configuration settings:

To extend the standard form, just add new input fields according to the following scheme for the name of the field:

• Standard fields have to start with „standard_“ followed by the standard field name (see previous link). E.g. for the last name use „standard_LASTNAME“.
• Custom fields have to start with „custom_“ followed by the custom field name (capitalization!). E.g. for the field „myCustomField“ use „custom_myCustomField“.
• Contact preferences have to start with „preference_“ followed by the category, a „:“ and the preference name. E.g. category „cars“ and preference „mercedes“ would have to be written as: „preference_cars:mercedes“. The values for preferences must be „true“ or „false“. If not set, nothing will change.

If you are having Space-Characters in your custom field or preference name, please replace them with „_space_“, e.g. if your Variable is not named „myCustomField“ but „my Custom Field“, the field name in the form should be „my_space_Custom_space_Field“.

You can then use the attribute ‚template‘ to select the file:

[[maileon-contact template="maileon-contact-form-custom-sample.php"]]

 

Profile-Update-Forms

Since version 2.7.0 the plugin also supports profile update pages using the shortcode

[[maileon-contact-update]]

The shortcode supports the template attribute with the same naming scheme for fields in the form as the registration pages, including standard, custom form parameters and preferences. As URL parameters the contact ID must be passed as parameter ‚cid‘ and the checksum as ‚cs‘. In Maileon the URL on the profile update page would for example look like „…/profile-update?cid=[[CONTACT|ID]]&cs=[[CONTACT|CHECKSUM]]„.

Prefill Data

In order to prefill a form, the script analyzes the form and collects all fields with names starting with standard_, custom_, or preference_ and requests the corresponding data from Maileon. It then provides the data in the template as PHP array $form_data. To prefill some field make sure to set its value to the matching array value, e.g. for last name use: $form_data[ 'standard_LASTNAME' ]

Example for the whole input field:

<input id="maileon_contact_form_lastname" type="text" class="input et_pb_contact_name" value="<?= (!empty($form_data[ 'standard_LASTNAME' ])?$form_data[ 'standard_LASTNAME' ]:"")?/>" name="standard_LASTNAME">