Welcome to Simple Email Form’s documentation

_images/logo.png

Project Home Page

What’s new in version 2.3

  • A new Slovenian translation has been added.

New since version 2.2

  • Joomla language overrides now work in Simple Email Form. For more information, see Override strings.

New since version 2.1

  • JForm has become the option by default instead of the deprecated Classic mode.
  • Customizing the rendering of the form is easier. For more details, see Override rendering
  • You can now send an automatic custom message to your user. See Send User a Custom Message

Installation

Here is the installation procedure for Joomla 3.x. The procedure is very similar for Joomla 2.5, but the screens look slightly different.

Download the module on the Simple Email Form page.

Login as the Joomla administrator

_images/installation01.png

Select Extensions - Manage - Install

_images/installation02.png

Click on Browse and locate the Simple Email Form TAR.GZ file you downloaded.

Click Upload & Install

_images/installation03.png

You should see a friendly message indicating success.

Select Extensions - Manage - Manage

_images/installation02.png

Make sure the Simple Email Form’s Status is Published (green check in the Status column).

_images/installation04.png

Click on Extensions - Modules.

_images/installation05.png

Click on Simple Email Form in the Title column to edit the module.

You can edit the Title as desired.

_images/installation06.png

In Position (right column of the Module tab), either select a module position as indicated by your template or enter a custom position (e.g. user99) if you plan to load the module into an article.

_images/installation07.png

In the Menu Assignment tab, make sure the module is assigned to either On all pages or to the pages you choose.

_images/installation08.png

SAVE your changes.

If you plan to load the module into an article, click on Close, then choose Extensions - Plugins

Make sure that the Content - Load Modules plug-in is enabled.

_images/installation09.png

You are now ready to configure the basic options in the Module tab and the advanced options in the Advanced tab.

Basic configuration options

Note

When you move the pointer over a field label, an explanation box pops up to assist you during module configuration.

_images/basic_options01.png

Form type

First, the form type must be chosen.

JForm is the most recent version that integrates new Joomla requirements. This is the default option since version 2.1.

Classic shows the form as it used to be. This option is deprecated and won’t be available in version 3.0 of the module.

_images/basic_options02.png

Language

You can then set the language used in the form. Language files can be found and edited at /path/to/joomla/modules/mod_simpleemailform/language_files.

Thirty languages are available.

_images/basic_options03.png

Note

The module is now integrated with Joomla native language support, so this field has no effect on the JForm type.

Email address

Next to Send Results To, you must enter an email address where information gathered by the simple email form will be sent. If there’s more than one address, separate them with commas or spaces.

_images/basic_options04.png

An empty Email address field will prevent the form from displaying and generate a “SORRY: This email address is invalid! Please re-enter your email address” error.

Label alignment

Choose to have the labels aligned left, right or center.

_images/basic_options05.png

Field options

Eight options can be used to configure each field:

  • Activate Field X
  • Label for Field X
  • Default Value for Field X
  • Display Size of Field X
  • Maximum Length of Field X
  • Field Type
  • Field X Format
  • Field X Before/After
_images/basic_options06.png

Activate Field X

Set this option to Yes to add field X to your form.

No means that field X won’t appear in the form.

Required means that the user won’t be able to submit the form if the field is empty. These fields are marked with an asterisk (*).

_images/basic_options07.png

Hidden fields don’t appear on screen. The value is automatically added in the email that is sent to you.

Label for Field X

Short description of the information to be entered in this field.

Default Value for Field X

With field types Subject, Normal and Textarea, the default value appears automatically in the form.

Note

Since version 1.8.5, default values don’t appear in Textarea fields. The HTML5 placeholder attribute is used instead.

With field types Drop, Radio and Checkbox, this option populates the answers available to the user in this format:

A=Apple,B=Banana,C=Cantelope

In this case, the user will see Apple, Banana and Cantelope on screen. If “Apple” is chosen, “A” is returned.

Note

To set a default for a Drop, Radio or Checkbox field, just make sure the desired default value is the first one specified.

Display Size of Field X

Size, in rows and columns, of a Textarea field. Size is entered in the following format: row,column

With field types Radio and Checkbox, you can enter the width, in pixels, of the labels besides each radio button or box.

Display Size has no effect on other field types.

Note

This option is only available with the Classic form type.

Maximum Length of Field X

Highest number of characters accepted from the user. This field isn’t used with field types Drop, Radio and Checkbox.

Field type

Since version 2.0, available field types are:

  • From
  • Subject
  • Normal (text)
  • Textarea
  • Drop (select)
  • Radio
  • Checkbox

From

This field type is used to get the email address of the user filling out the form. The first field defaults to From.

_images/basic_options10.png

Subject

Whatever the user enters here will become the “Subject” in the email sent to you. The second field defaults to Subject.

_images/basic_options11.png

Normal

This field will appear as one line on your input form.

If you do not wish to enter a default value, make sure to hit the spacebar.

_images/basic_options12.png

Textarea

Creates a text box in which the user can type a message. Label is the only field that is not ignored by this field type.

Note

The new JForm type displays an HTML editor.

_images/basic_options13.png

Drop

In the Default Value field, enter options separated by commas as follows: Return1=Visible1,Return2=Visible2.

ReturnX is the value returned in the email message. VisibleX is the value appearing in the form.

_images/basic_options14.png

Radio

In the Default Value field, enter options separated by commas as follows: Return1=Visible1,Return2=Visible2.

ReturnX is the value returned in the email message sent when that button is selected. VisibleX is the value appearing in the form.

Horizontal format is table/row/col/col/col.

Vertical format is table/row/col/col/row/col/col.

Use CSS (default) assumes you will use your custom CSS.

Before means that the label appears to the left of the button.

After means that the label appears to the right of the button.

_images/basic_options15.png

Checkbox

In the Default Value field, enter options separated by commas as follows: Return1=Visible1,Return2=Visible2.

ReturnX is the value returned in the email message sent when that box is checked. VisibleX is the value appearing in the form.

Horizontal format is table/row/col/col/col.

Vertical format is table/row/col/col/row/col/col.

Use CSS (default) assumes you will use your custom CSS.

Before means that the label appears to the left of the box.

After means that the label appears to the right of the box.

_images/basic_options16.png

Field X Format

Only works with Radio and Checkbox field types.

  • Horizontal means that all radio buttons or checkboxes are on the same row.
_images/basic_options08.png
  • Vertical means that the various button-label pairs are displayed one above the other.
_images/basic_options09.png
  • Use CSS means that you use your custom CSS to display the buttons or boxes.

Field X Before/After

Only used with Radio and Checkbox field types.

  • Before means that labels are displayed to the left of their respective buttons or checkboxes.
  • After means that they are displayed to the right.

Advanced configuration options

Caching

Use global means that this module’s content will be cached according to your Joomla’s global cache settings.

No caching means that no content from this module will be cached.

This option is provided by Joomla.

Form Instance

If you use more than one Classic forms on your website, even on different pages, you need to give each one of them a unique number to differentiate them from each other.

Send Results CC

Enter email addresses here if you want the form to be sent in carbon copy.

Send Results BCC

Enter email addresses here if you want the form to be sent in blind carbon copy.

Reply To this address

Enter email addresses where replies should be sent to.

Activate Reply To

If set to Yes, a “Reply to” field will appear when the email is sent.

Auto Reset Fields

Yes means that all fields will be cleared when the user submits the form.

No means that the values entered by the user will remain after the form is submitted.

Note

With the JForm type, No is automatically used.

Name of CSS Class

Enter the name of the CSS class that will be used with the form.

Space After Labels

Amount of pixels between the labels to the left of the form and their input fields.

Redirect URL

Enter a Website address where the user should be redirected after submitting the form. Make sure you enter a fully formed URL.

Example: http://www.unlikelysource.com/

Use Captcha

With the JForm type:

To be able to use Captcha, you can follow the procedure on the Joomla Website.

This will produce a captcha looking like this:

_images/advanced_options01.png

Note

If you don’t have a Google account and don’t want to create one, you can use a Captcha extension available in the Joomla Extensions Directory.

With the Classic form type:

Set to No Captcha if you don’t want any Captcha protection.

Image Captcha creates an image including a background rectangle, characters the user will have to type and lines blurring the image.

_images/advanced_options02.png

Text Captcha creates a simple character string the user has to type.

_images/advanced_options03.png

Directory to Write Captchas

An absolute path where captchas will be written.

Example : /var/www/application/images

Make sure that the repository is writable.

URL for Captcha Directory

URL matching the directory specified above.

Captcha Word Length

Number of characters the user will need to enter.

Captcha Font Size

Size of the characters in the captcha image.

Captcha Width

Width in pixels of the captcha image.

Captcha Height

Height in pixels of the captcha image.

Captcha Text Color

The color of the characters in the captcha image.

Captcha Lines Color

The color of the lines partially hiding the characters in the captcha image.

Captcha Background Color

The color of the captcha image background.

Error Text Color

The color in which error messages are displayed to the user.

Success Text Color

The color in which success messages are displayed to the user.

Name of Anchor Tag

After submitting the form, the user is redirected to the anchor tag mentioned here. By default, this tag is placed at the beginning of the form.

The name of the tag must start with #. Example : #tag

Number of Upload Fields

Determines the number of attachments users can or must send through the form.

Upload Field Label

The label for the upload fields.

Allowed Attachment Filenames

List of approved filename extensions, separated by commas. For security reasons, Joomla will prevent any user from sending executable content, for instance a .php file.

Are upload fields required?

If set to Yes, submitting the form will fail with an error if an upload field is empty.

Note

This new feature is only available with the JForm type.

Directory to Save Attachments

An absolute path to the directory in which attachments sent by users will be saved.

Send Me an Email Field Label

The label for field Send Me an Email, set below.

Send Me an Email Field

If set to Yes, users can ask to receive a copy of the form that they send.

Send User an Email Automatically

If set to Yes, users will always receive a copy of the form that they send.

Send User a Custom Message

If the Send User an Email Automatically option is set to Yes, you can fill out this section to send your user a custom message.

Email Check

If set to Yes, the data entered in the From field is validated and must follow the format emailaccount@domain.

Note

With the JForm type, this validation occurs automatically.

Include Article Title

If set to Yes, the Joomla article title is automatically included in a hidden field added to the email.

Test Mode

If set to Yes, the form is used in test mode.

Override rendering

Set this option to Yes if you want to use your own template to modify the module’s display. To get you started, you can copy the mod_simpleemailform/tmpl/default_custom.php.dist and name it default_custom.php.

You can also give your custom file another name, but you will have to insert your chosen name on line 7 of the default.php template file.

Override strings

Set this option to Yes if you want to use Joomla’s language overrides feature. Searching for constants with “MOD_SIMPLEEMAILFORM” will give you a list of all the strings that can be overriden in this module.

Thanks to this feature, you won’t lose your changes the next time you update Simple Email Form.

Module Tag

The html tag used for the module. This option is provided by Joomla.

Bootstrap Size

The number of columns used in the module. This option is provided by Joomla.

Header Tag

The HTML tag used for module headers and titles. This option is provided by Joomla.

Header Class

The CSS class used for module headers and titles. This option is provided by Joomla.

Module Style

The option used to override the template style. It is provided by Joomla.

Configuration Example

_images/demo_config01.png _images/demo_config02.png _images/demo_config03.png _images/demo_config04.png _images/demo_config05.png _images/demo_config06.png _images/demo_config07.png _images/demo_config08.png _images/demo_config09.png _images/demo_config10.png _images/demo_config11.png _images/demo_config12.png _images/demo_config13.png _images/demo_config14.png _images/demo_config15.png _images/demo_config16.png

Here’s the result of this configuration with the Classic type:

_images/demo_config17.png

Here’s the result of this configuration with the JForm type:

_images/demo_config18.png _images/demo_config19.png _images/demo_config20.png

Indices and tables