Advancedform_XH facilitates to create your own mail forms for integration into CMSimple_XH. Its possible usage ranges from customized contact forms to complex ordering or booking forms. Even complex forms can be constructed by using the form editor, so you do not have to write any HTML, CSS or PHP, if the basic form functionality is enough for your needs. Advanced customization is available through the template and hook system, respectively.
Advancedform_XH is a plugin for CMSimple_XH ≥ 1.7.0 with the Fa and Jquery plugins, which are available by default. It requires PHP ≥ 5.5.4 with the ctype, filter and hash extensions.
The lastest release is available for download on Github.
The installation is done as with many other CMSimple_XH plugins.
- Backup the data on your server.
- Unzip the distribution on your computer.
- Upload the whole directory
advancedform/to your server into theplugins/directory of CMSimple_XH. - Set write permissions to the subdirectories
config/,css/,languages/and to the data folder of the plugin. - Protect the data folder of Advancedform_XH against direct access by any
means your Webserver provides.
.htaccessfiles for Apache servers are already distributed in the default data folder. Note that the subfolderscss/andjs/must not deny public access. - Navigate to
Plugins→Advancedform→Configand save the configuration. - Navigate to
Plugins→Advancedformin the back-end to check if all requirements are fulfilled.
The configuration of the plugin is done as with many other CMSimple_XH
plugins in the back-end of the Website.
Select Plugins → Advancedform.
You can change the default settings of Advancedform_XH under Config.
Hints for the options will be displayed
when hovering over the help icon with your mouse.
The setting php_extension could provide additional
security with regard to the template and the hook system, if enabled.
However, some of the demo forms do not work in this case.
Localization is done under Language.
You can translate the character strings to your own language,
if there is no appropriate language file available,
or customize them according to your needs.
The look of Advancedform_XH can be customized under Stylesheet.
The upper part contains the styling of the forms displayed in the front-end.
The mail form is displayed as a table with two columns.
The left column shows the labels, the right colum the fields.
You can simply adjust the styles for the classes div.advfrm-mailform td.label
and div.advfrm-mailform td.field.
You can style individual forms by selecting form[name=FORM_NAME],
and even individual fields by selecting #advfrm-FORM_NAME-FIELD_NAME.
If you prefer a one column layout,
you have to use the template system.
The lower part of the stylesheet contains the styling of the mail form administration and the form editor. If you want to style the property dialogs to fit to your template, you should consider to add jQueryUI theming support to your template. How this can be done is explained in the CMSimple_XH forum.
Only the first part of the stylesheet above the line
/* END OF MAIL CSS */
will be included inline into the sent HTML mails. So put all style information that is appropriate for the mails at the top of the stylesheet.
In the back-end under Mail Forms there is the list of all defined mail forms.
You can add and import new forms and edit, delete, copy and export existing ones.
To the right of the mail form is the script code needed to show the according form on a page.
Just copy the code and paste it into the desired page.
The mail form editor allows you to construct your mail forms. The details are explained in the following sections.
In the upper part of the form editor you can edit the general form properties.
Name: The name of the form may contain only alphanumeric characters and underscores. It must be unique for all defined forms. It is used to identify the form.Title: The title of the form is used in the mails subject only.To (name): The name of the recipient of the mail.To (e-mail): The address of the recipient of the mail.CC: The addresses of the CC recipients of the mail separated by semicolon.BCC: The addresses of the BCC recipients of the mail separated by semicolon.CAPTCHA: Whether a CAPTCHA should be included in the form.Store data: Whether the submitted data should additionally be stored in a CSV file.Thanks page: If empty, after sending the mail the sent information will be displayed. If set and if a sender email address is entered, after sending the mail visitors will be redirected to this page, and a confirmation mail with the sent information will be sent to them.
In the lower part of the form editor you can edit the fields of the form. Use the tool icons to add, delete or move fields.
Name: The name of the field may contain only alphanumeric characters and underscores. It must be unique for all defined fields of the current form. It is used to identify the field.Label: The label that should be displayed next to the field.Type: The type of the field. Right to the selectbox is the property tool icon. Click it to open a dialog for editing the properties of the selected field type.Req.: Whether the field is required, i.e. must be filled in by the visitor.
Text: A general text field.Sender (name): A field to enter the name of the sender. This information will be included in the mail header. At most one field of typeSender (name)may be used for each form.Sender (e-mail): A field to enter the email address of the sender, which will be validated. This information will be used as Reply-To header field of the mail, and as To header field of the confirmation mail. At most one field of typeSender (e-mail)may be used for each form.E-mail: A field to enter a general email address, which will be validatedDate: A field to enter a date, which will be validated. In contemporary browsers, a datepicker is available.Number: A field to enter a non-negative integer, which will be validated.Textarea: A field to enter multi-line texts.Radiobutton: A field to choose one of several options.Checkbox: A field to choose any of several options.Selectbox: A field to choose one of several options.Multi-Selectbox: A field to choose any of several options.Password: A field to enter a password.File: A field to allow the visitor to upload a file as mail attachment. The attachment will not be sent back to the visitor in the confirmation mail.Hidden: A hidden field. Hidden fields will never be shown to the visitor. They might be useful in combination with the template system and the hooks.Output: A field to output arbitrary HTML.Custom: A field that is validated against a given regular expression.
The field properties are edited in a dialog that is opened by clicking on the property icon. The different field types have different properties that can be set.
Size: For text fields and such, the width of the field measured in characters. For selectboxes the height of the list. Use 1 for a dropdown box.Orientation: For radiobuttons and checkboxes only: whether these should be displayed horizontally or vertically.Max. length: The maximum number of characters that can be entered. For file fields it specifies the maximum file size in bytes.Cols: The width of the textarea in characters.Rows: The height of the textarea in characters.Default: The default value of the field. Fordatefields, this is any of the supported date formats or relative formats. Typical use-cases are fixed dates like "2021-10-31", or relative dates like "today", "tomorrow" or "next saturday".Value: The HTML for output fields.File types: For file fields only: a comma separated list of permissible file extensions, e.g.jpeg,jpg,png,gif,bmpfor images.Constraint: For custom fields only: the regular expression the value should be checked against.Error message: For custom fields only: the error message that should be displayed, if the value does not match the regular expression. Use%sto insert the label of the field into the message.
Radiobuttons, checkboxes and selectboxes allow to enter different options.
Use the tool buttons to add, delete and rearrange them.
The radiobuttons or checkboxes besides the options allow to specify these as default(s).
Use the tool clear defaults to reset them.
Edit the page, that you want to display a mail form, and insert the plugin call:
{{{advancedform('FORM_NAME')}}}
It might be easiest to just copy&paste the necessary code from the mail form administration.
Now the mail form is ready to be used by the visitors of your Website. They can fill out the form and submit it. If they make any mistakes, e.g. leaving empty an required field, entering an invalid email address or number or specifying a file that is larger than allowed, the form will be displayed again with the already entered input, and with the errors shown above, so the visitors can correct the mistakes and submit the form again. It is not necessary that JavaScript is enabled in the browser of the visitor, but if it is, the first erroneous field will be focused. But none of the field validations relies on JavaScript.
After successful submission of the form, an email will be sent
to the receivers (To, CC and BCC) specified in the form editor.
Then the sent information is displayed to the visitors as confirmation,
or, if a thanks page is specified, the visitors will be redirected there,
and a confirmation mail will be sent to them.
The thanks page/confirmation feature will only work,
if a required field of type Sender (e-mail) is specified for the form,
and Mail → Confirmation is enabled in the configuration.
The confirmation mail feature can be abused by anybody,
namely by sending abusive contents to an arbitrary recipient
by using the email address of that recipient.
Therefore it is highly recommended to have
Mail → Confirmation disabled.
Attempts to send an email via Advancedform are logged
in the system log of CMSimple_XH (Settings → Log File).
Note that it is possible to have multiple forms on a single page, which can be sent independent from each other.
It is possible to replace the built-in mail form of CMSimple_XH
with a user defined one.
So just define the desired form, and enter its name
in the language settings of Advancedform_XH as contact form.
Now the mailform link of CMSimple_XH will directly call your custom form.
Note that an email address has to be configured for CMSimple_XH
to display the mailform link,
but its value is completely ignored by Advancedform_XH.
Alternatively create a hidden CMSimple_XH page and insert the required script code to call the form. Then you have to modify your template. Just replace
<?=mailformlink()?>
with
<?=advancedformlink('PAGE_URL')?>
where PAGE_URL should be the part of the URL of the page after the question mark.
It is possible to specify multiple advancedformlink()s this way.
The template system allows to build highly customized mail forms. Power users, who need to create or alter mail forms frequently, might have a look at the Form Mailer by Jerry Jakobsfeld, which is even more versatile than Advancedform_XH.
If a file with the name FORM_NAME.tpl(.php)
(where FORM_NAME has to be replaced with the name of the form,
e.g. for a form named contact, the filename would be contact.tpl(.php))
is found in the data folder of Advancedform_XH,
it will be used as the template file.
Additionally the file css/FORM_NAME.css, if it exists,
will be included as stylesheet in the CMSimple_XH page
and the top of this stylesheet (delimited as for the plugin stylesheet)
will be included in the email.
And if a file js/FORM_NAME.js exists,
it will be included in the page, too.
You can write the template file and its stylesheet manually, but it might be easiest to let Advancedform_XH create a basic one in the mail form administration. By default the generated template files will display the form similar to the one column layout of the original Advancedform. If that is all you want, you are done.
If you want to adjust the styling, have a look at the generated files.
In the template file you can see its simplistic structure.
Everything is encapsulated within <div>s for flexibility.
Have a look at the class of the container-divs.
This is set to break by default, so every field will start in a new row.
Change it to float and the fields will be put right besides each other.
If you want to have the labels to the left of the fields,
just remove the comments in the prepared styles for
div.label and div.field.
A template file is basically a PHP file with one addition to the syntax:
<?field FIELD_NAME?>
will output the field with the name FIELD_NAME.
Do not use any additional characters such as whitespace
except a single space between field and FIELD_NAME.
The template file will be evaluated in the context of CMSimple_XH, so any global variables, constants and functions are available to use. However, it is not possible to alter any global variables (besides the superglobals, what might break the working of the system). And do not call non-existent functions as this will cause the PHP interpreter to fail. Particularly you should be cautious using template files from untrusted sources, as those could contain malicious code that might harm your CMSimple_XH installation.
One particularly useful function is
Advancedform_focusField($form_name, $field_name)
that will set the focus to the given field.
The hooks are provided to give you even more flexibility,
if you are able to write some PHP code.
Define them in a file FORM_NAME.inc(.php)
(where FORM_NAME has to be replaced with the name of the form,
e.g. for a form named contact, the filename would be contact.inc(.php))
in the data folder of Advancedform_XH.
Note that this file will be include()d,
so it has to be a proper PHP file.
The hooks will be called from Advancedform_XH on certain occassions.
They are not tied to the template system.
function advfrm_custom_field_default($form_name, $field_name, $opt, $is_resent)
This will be called before the form is sent to the browser.
It gives the opportunity to dynamically set default values for fields.
Just return the value you want to be used as the default value of the field.
If you do not want to change the default value, just return null.
The third parameter is set for radiobuttons, checkboxes and selects only.
It contains the option, that is currently processed.
Return true to check the option, false to uncheck it,
or null to use whatever was specified in the form editor.
The parameter $is_resent tells whether the form was resent
to the browser after submission, because of validation errors.
If this is the case the values already entered by the user
are sent back instead of the default values specified in the form editor.
You might consider to return null in this case,
to not overwrite the users input.
function advfrm_custom_valid_field($form_name, $field_name, $value)
This will be called after the form was submitted,
and gives the opportunity to add additional validation to the field values.
Return true, if the given $value is valid,
otherwise return an error message,
which will be displayed to the user by Advancedform_XH.
For fields of type file,
$value is the $_FILES[] array of the given field.
function advfrm_custom_mail($form_name, $mail, $is_confirmation)
This will be called after the $mail object is initialized
with all information and just before the mail is sent,
and gives the opportunity to alter the $mail object.
The parameter $form_name specifies the currently processed form,
and the parameter $is_confirmation specifies
whether the $mail object contains the information for the mail
or the confirmation mail (i.e. the response).
If you want to suppress sending of the mail altogether,
just return false.
function advfrm_custom_thanks_page($form_name, $fields)
This is called after the mail is sent,
and can be utilized to switch to a personalized thanks page.
Return the query string
(i.e. the part of the URL of the page after the question mark)
of the page you want to redirect to.
Returning an empty string will redirect
to the thanks page that is defined in the form editor.
If no default thanks page is defined,
the sent information will be displayed.
The parameter $fields is an array
holding the values of all submitted form fields.
For details on the $fields parameter, see Advancedform_fields().
The following functions can be useful for custom hooks:
Advancedform_fields()returns an array which holds the values of all submitted form fields. The format is identical to what is contained in the PHP superglobals$_POSTand$_FILESexcept that the array keys are stripped of theadvfrm-prefixes, i.e. the keys are exactly the names of the respective fields. Also, for historic reasons, the values ofCheckbox,Radiobutton,SelectboxandMulti-Selectboxfields are returned as strings, instead of subarrays. If there are multiple values for these fields, they are separated by broken bar characters (¦). While it is possible to access the superglobals in hooks directly, it is recommended to useAdvancedform_fields()instead, because the names of the keys may change in the future.Advancedform_readCsv()returns an array of records of the data already stored in the CSV file. The records are arrays where each element represents a single field; the key is the name of the field.
You should have a look at the shipped demo forms (see data/README for
further details) to see what can be done, and how it can be done.
Caution: of course you are free to use the demo forms as base for your own forms. But as most of the demo forms use the template and hook system, respectively, the result might not be as expected. Either remove the unwanted template/hook files manually, or make a copy of the form in the form administration and use this copy.
The original AdvancedForm supported different kinds of mailers.
This appears to be a rarely needed feature.
Most Webhosters will provide the possibility to send mail via mail(),
which should be easily configured
and quite acceptable for the purposes of Advancedform_XH.
The original Advancedform offered several features regarding spam protection: IP blacklists, a badword filter, a XSS detection facility. The authors of Advancedform_XH are not convinced that these mechanisms are reasonable ways to prevent spam. So none of these are implemented (besides rendering XSS harmless), but instead a CAPTCHA is available. This is only a minimal text-based solution, but more comprehensive CAPTCHAs can be used by means of an additional conforming CAPTCHA plugin. Currently Cryptographp_XH is available.
Report bugs and ask for support either on Github or in the CMSimple_XH Forum.
Advancedform_XH is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
Advancedform_XH is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantibility or fitness for a particular purpose. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with Advancedform_XH. If not, see https://www.gnu.org/licenses/.
© 2005-2010 Jan Kanters
© 2011-2022 Christoph M. Becker
Czech translation © 2011-2012 Josef Němec
Danish translation © 2012 Jens Maegard
Estonian translation © 2012 Alo Tänavots
French translation © 2014 Patrick Varlet
Slovak translation © 2012 Dr. Martin Sereday
Advancedform_XH is based on AdvancedForm Pro by Jan Kanters. Many thanks to him for giving the permission to use his code for a CMSimple_XH conforming version, and to Holger and johnjdoe who negotiated this permission.
The mail composition and sending is powered by PHPMailer. Many thanks for publishing this advanced mail library under LGPL-2.1.
The regular expression to check for a valid email address is by courtesy of Jan Goyvaerts. Many thanks for the great regular expression tutorial and the examples.
The plugin icon is designed by Jack Cai. Many thanks for publishing it under CC BY-ND.
Many thanks to the community at the CMSimple_XH forum for tips, suggestions and testing. Especially, I want to thank Tata for having the idea to let Advancedform_XH generate a basic template and stylesheet, and manu for requesting the hooks and co-designing their API. And many thanks to maeg, who allowed me to do some debugging on his server, so I was able to find and fix a bug, which caused the sending of mails to fail on several servers. Also special thanks to knollsen and frase for quickly pointing out serious regressions in Advancedform_XH 2.1.
And last but not least many thanks to Peter Harteg, the “father” of CMSimple, and all developers of CMSimple_XH without whom this amazing CMS would not exist.