Local Contact Form plugin for Moodle
====================================
[](https://github.com/michael-milette/moodle-local_contact/issues)
[](#contributing)
[](#license)
# Table of Contents
- [Basic Overview](#basic-overview)
- [Requirements](#requirements)
- [Download Contact for Moodle](#download-contact-for-moodle)
- [Installation](#installation)
- [Usage](#usage)
- [Updating](#updating)
- [Uninstallation](#uninstallation)
- [Limitations](#limitations)
- [Language Support](#language-support)
- [Frequently Asked Questions (FAQ)](#faq)
- [Contributing](#contributing)
- [Motivation for this plugin](#motivation-for-this-plugin)
- [Further information](#further-information)
- [License](#license)
# Basic Overview
The Contact Form plugin for Moodle processes information submitted through a web form, sending it by email.
Examples uses for this plugin include:
* Contact us form;
* Support request form;
* Request a course form;
* Information request form;
* Lead generation form;
* Membership application form.
* Quiz question issue report form.
Several pre-configured templates are available when used with the FilterCodes plugin. They include:
* {formquickquestion}
* {formcontactus}
* {formcourserequest}
* {formsupport}
* {formcheckin}
See [The Quick and Easy method](#the-quick-and-easy-method) for details.
[(Back to top)](#table-of-contents)
# Requirements
This plugin requires Moodle 3.0+ from https://moodle.org .
It may work with previous versions of Moodle all the way back to Moodle 2.7 but it has not been tested yet. If it works for you, let us know. Tip: You might need to modify the version.php in order for Moodle to let you install it on earlier versions.
[(Back to top)](#table-of-contents)
# Download Contact for Moodle
The most recent STABLE release of Contact Form for Moodle is available from:
https://moodle.org/plugins/local_contact
The most recent DEVELOPMENT release can be found at:
https://github.com/michael-milette/moodle-local_contact
[(Back to top)](#table-of-contents)
# Installation
Install the plugin, like any other plugin, to the following folder:
/local/contact
See https://docs.moodle.org/en/Installing_plugins for details on installing Moodle plugins.
[(Back to top)](#table-of-contents)
# Usage
Before getting started:
* Ensure email settings are properly configured in Moodle.
* Ensure that you have configured the support name and email address in Moodle.
## Creating a new form
### The Quick and Easy method
By far, The quickest way to get started is to use the [FilterCodes](https://moodle.org/plugins/filter_filtercodes/ Moodle plugin. As of version 1.3.0, it includes several plain text tags that you can easily copy and paste into any Atto editor. The {tags} include:
* {formquickquestion} : Adds a "quick question" form to your course. Form only includes a Subject and Message field. Note: User must be logged in or the form will not be displayed.
* {formcontactus} : Adds a "Contact Us" form to your site (example: in a page). Form includes Name, Email address, Subject and Message fields.
* {formcourserequest} : Adds a "Course Request" form to your site (example: in a page). Unlike Moodle's request-a-course feature where you can request to create your own course, this tag allows users to request that a course they are interested in be created. Could also be used to request to take a course. Form includes Name, Email address, Course name, Course Description.
* {formsupport} : Adds a "Support Request" form to your site (example: in a page). Form includes Name, Email address, pre-determined Subject, specific Subject, URL and Message fields.
* {formcheckin} : Adds a "I'm here!" button to your to your course. Form does not include any other fields. Note: User must be logged in or the button will not be displayed.
### Custom method
This plugin is for administrators with a little knowledge of HTML forms. You can simply copy and paste any of the [examples from the Wiki](https://github.com/michael-milette/moodle-local_contact/wiki/HTML-Form-Templates) to get started.
To create a new web form on your site, start by adding a Moodle page or HTML block. Be sure to switch to the Source Code view button in the Moodle Atto WYSIWYG editor before entering or pasting HTML code similar to the following:
That is it. Just save and you are done.
Note: If you are putting the form into a block, you will need to adjust the "../.." part in the action of the form so that it is relative to the webroot of your Moodle website. If you are using the FilterCodes plugin, you can simply use {wwwroot} and it will work anywhere you put the form whether it is in a page or a block.
Example:
### Require login
The `Require login` setting requires that users be logged-in in order to be able to submit the form. If a form is submitted and the user is not logged-in they will be redirected to the login page. If you require users to be logged-in, it is also highly recommended that you also place your form on a page which is only accessible to logged-in users. Guest users are not considered to be logged-in.
[(Back to top)](#table-of-contents)
# Updating
There are no special considerations required for updating the plugin.
The first public BETA version was released on 2016-12-05. For more information on releases since then, see
[CHANGELOG.md](https://github.com/michael-milette/moodle-local_contact/blob/master/CHANGELOG.md).
[(Back to top)](#table-of-contents)
# Uninstallation
Uninstalling the plugin by going into the following:
Home > Administration > Site Administration > Plugins > Manage plugins > Contact Form
...and click Uninstall. You may also need to manually delete the following folder:
/local/contact
[(Back to top)](#table-of-contents)
# Limitations
This is not a form builder.
The plugin doesn't currently properly support more than one textarea type fields. Additional textareas will still work however they won't be formatted as nice.
Any HTML entered will be escaped. You cannot use any kind of HTML formatting or markup/markdown other than pressing ENTER at the end of a paragraph.
You cannot configure the Contact Form email processor on a per form basis. All contact forms on your site will share:
* The message that is displayed to the user after the message has been sent.
* The footer of the email containing additional user information.
* Enabling/disabling of the autoresponder.
* The autoresponder message (if enabled).
Web forms are limited to 1024 fields including hidden fields and the submit button. Total size of the submission may not exceed 256 KB.
There is no support file attachments type fields or form-data encoded as "multipart/form-data".
[(Back to top)](#table-of-contents)
# Language Support
This plugin includes support for the English language. Additional languages including French are supported if you've installed one or more additional Moodle language packs.
Some core fields will be different if a language pack is available for your language. On a French Moodle site, for example (fielname on English site => fieldname on French site):
* email => courriel
* message => message
* name => nom
* subject => objet
So on a French site, you would need to use the French versions of the field names or Contact Form will not recognize them. For more information, see the section called [Customizing the form](#customizing-the-form).
Pro tip: Creating a multi-language Moodle site? Use the [FilterCodes](https://moodle.org/plugins/filter_filtercodes) {getstring} tag to populate the correct field name. Example:
Note: If no language pack is available for your language, the plugin will default to the English language pack. However, if you need a language that is not yet supported, please contribute translations using the Moodle AMOS Translation Toolkit for Moodle at:
https://lang.moodle.org/
This plugin has not been tested for right-to-left (RTL) language support. If you want to use this plugin with a RTL language and it doesn't work as-is, feel free to prepare a pull request and submit it to the project page at:
https://github.com/michael-milette/moodle-local_contact
[(Back to top)](#table-of-contents)
# FAQ
## Answers to frequently asked questions
### How do I make this form available to everyone, even if they are not logged in?
Assuming you have not enabled "Force users to log in" in Moodle settings, the easiest way is to add a page or block to your Moodle Frontpage (also known as Home page).
1. Login as a Moodle administrator.
2. Go to your Front Page.
3. Turn editing on.
4. Add a **Page** type activity/resource.
5. Insert your HTML form or related FilterCode (if you are using it) into the content field and save. If pasting HTML code, make sure that the WYSIWYG editor is in HTML mode.
Since you don't need to be logged into your Moodle Frontpage to see it, your form will also be accessible to visitors to your site who are logged-out, logged-in as a guest as well as to regular logged-in users. If this option is not available to you, the process is a little more complicated as it involves making a course available to guests and having Moodle automatically logged them in as guests.
### Why isn't my form working?
The quick and easy way to create webforms in Moodle is to simply install [FilterCodes](https://moodle.org/plugins/filter_filtercodes/) and use its tags. Be sure to set the filter to **On** in Moodle's Manage Filter settings and set it to filter **Content and headings**. Built-in forms include {formquickquestion}, {formcontactus}, {formcourserequest}, {formsupport}, {formcheckin}. [More information for FilterCodes method](#the-quick-and-easy-method).
If you are not using FilterCodes, be sure to replace any reference to tags that look like {tagname} that might be found in your HTML form. [More informaiton on HTML method](#custom-method). For example, if your form contains {wwwroot} and the webroot your Moodle site is https://example.com, then replace {wwwroot}/local/contact/ with https://example.com/local/contact/ . Look through your form as there may be others depending on the sample code upon which you based your form.
Anytime your form doesn't work, be sure to try it in a Moodle page or block using the Boost theme with the current language set to English. If it works there, chances are that it is the theme or plugin you are using that is causing the issue, not FilterCodes or Contact for Moodle. As with the Static Pages plugin (see below), you may find that there is a setting that needs to be changed. If not, contact the author/maintainer of the plugin and ask them to add support for filtering in their theme or plugin.
If the form works in English and not in your preferred language, you may need to translate the names of some of your fields. This is required if you want the field names to appear in your language in the email. [More information on Language support](#language-support)
#### Sesskey error
If you are getting an error that mentions *sesskey*, you may have forgot to include the JavaScript snippet in your form:
If you have [FilterCodes](https://moodle.org/plugins/filter_filtercodes/) installed, you can simply replace all of the above code in your form with:
{formsesskey}
If JavaScript does not work in your form, you can replace the above code with the following HTML. Be aware that it will override one of several anti-spam protections built into Contact Form (requires FilterCodes):
#### Static Pages plugin compatibility
The recommended way of using Contact for Moodle is to create your webmail form in a page or block. However, there may be use cases where you might prefer to use the [local_staticpage plugin](https://moodle.org/plugins/local_staticpage). In order for this to work, you will need to configure a couple of its settings:
* Enable the Static Pages plugin's **Process Filters** (processfilters) setting to enable processing of FilterCodes.
* Disable its **Clean HTML code** (cleanhtml) setting to prevent StaticPage from deleting or filtering out some of the required HTML code in your form.
This demonstrates how to use FilterCode Contact Form templates with the Static Pages to create a quick Contact Us form. Start by copying the following code into a text file called contact.html and saving it:
Contact Us
Local Contact Form plugin for Moodle
====================================
[](https://github.com/michael-milette/moodle-local_contact/issues)
[](#contributing)
[](#license)
# Table of Contents
- [Basic Overview](#basic-overview)
- [Requirements](#requirements)
- [Download Contact for Moodle](#download-contact-for-moodle)
- [Installation](#installation)
- [Usage](#usage)
- [Updating](#updating)
- [Uninstallation](#uninstallation)
- [Limitations](#limitations)
- [Language Support](#language-support)
- [Frequently Asked Questions (FAQ)](#faq)
- [Contributing](#contributing)
- [Motivation for this plugin](#motivation-for-this-plugin)
- [Further information](#further-information)
- [License](#license)
# Basic Overview
The Contact Form plugin for Moodle processes information submitted through a web form, sending it by email.
Examples uses for this plugin include:
* Contact us form;
* Support request form;
* Request a course form;
* Information request form;
* Lead generation form;
* Membership application form.
* Quiz question issue report form.
Several pre-configured templates are available when used with the FilterCodes plugin. They include:
* {formquickquestion}
* {formcontactus}
* {formcourserequest}
* {formsupport}
* {formcheckin}
See [The Quick and Easy method](#the-quick-and-easy-method) for details.
[(Back to top)](#table-of-contents)
# Requirements
This plugin requires Moodle 3.0+ from https://moodle.org .
It may work with previous versions of Moodle all the way back to Moodle 2.7 but it has not been tested yet. If it works for you, let us know. Tip: You might need to modify the version.php in order for Moodle to let you install it on earlier versions.
[(Back to top)](#table-of-contents)
# Download Contact for Moodle
The most recent STABLE release of Contact Form for Moodle is available from:
https://moodle.org/plugins/local_contact
The most recent DEVELOPMENT release can be found at:
https://github.com/michael-milette/moodle-local_contact
[(Back to top)](#table-of-contents)
# Installation
Install the plugin, like any other plugin, to the following folder:
/local/contact
See https://docs.moodle.org/en/Installing_plugins for details on installing Moodle plugins.
[(Back to top)](#table-of-contents)
# Usage
Before getting started:
* Ensure email settings are properly configured in Moodle.
* Ensure that you have configured the support name and email address in Moodle.
## Creating a new form
### The Quick and Easy method
By far, The quickest way to get started is to use the [FilterCodes](https://moodle.org/plugins/filter_filtercodes/ Moodle plugin. As of version 1.3.0, it includes several plain text tags that you can easily copy and paste into any Atto editor. The {tags} include:
* {formquickquestion} : Adds a "quick question" form to your course. Form only includes a Subject and Message field. Note: User must be logged in or the form will not be displayed.
* {formcontactus} : Adds a "Contact Us" form to your site (example: in a page). Form includes Name, Email address, Subject and Message fields.
* {formcourserequest} : Adds a "Course Request" form to your site (example: in a page). Unlike Moodle's request-a-course feature where you can request to create your own course, this tag allows users to request that a course they are interested in be created. Could also be used to request to take a course. Form includes Name, Email address, Course name, Course Description.
* {formsupport} : Adds a "Support Request" form to your site (example: in a page). Form includes Name, Email address, pre-determined Subject, specific Subject, URL and Message fields.
* {formcheckin} : Adds a "I'm here!" button to your to your course. Form does not include any other fields. Note: User must be logged in or the button will not be displayed.
### Custom method
This plugin is for administrators with a little knowledge of HTML forms. You can simply copy and paste any of the [examples from the Wiki](https://github.com/michael-milette/moodle-local_contact/wiki/HTML-Form-Templates) to get started.
To create a new web form on your site, start by adding a Moodle page or HTML block. Be sure to switch to the Source Code view button in the Moodle Atto WYSIWYG editor before entering or pasting HTML code similar to the following:
That is it. Just save and you are done.
Note: If you are putting the form into a block, you will need to adjust the "../.." part in the action of the form so that it is relative to the webroot of your Moodle website. If you are using the FilterCodes plugin, you can simply use {wwwroot} and it will work anywhere you put the form whether it is in a page or a block.
Example:
### Require login
The `Require login` setting requires that users be logged-in in order to be able to submit the form. If a form is submitted and the user is not logged-in they will be redirected to the login page. If you require users to be logged-in, it is also highly recommended that you also place your form on a page which is only accessible to logged-in users. Guest users are not considered to be logged-in.
[(Back to top)](#table-of-contents)
# Updating
There are no special considerations required for updating the plugin.
The first public BETA version was released on 2016-12-05. For more information on releases since then, see
[CHANGELOG.md](https://github.com/michael-milette/moodle-local_contact/blob/master/CHANGELOG.md).
[(Back to top)](#table-of-contents)
# Uninstallation
Uninstalling the plugin by going into the following:
Home > Administration > Site Administration > Plugins > Manage plugins > Contact Form
...and click Uninstall. You may also need to manually delete the following folder:
/local/contact
[(Back to top)](#table-of-contents)
# Limitations
This is not a form builder.
The plugin doesn't currently properly support more than one textarea type fields. Additional textareas will still work however they won't be formatted as nice.
Any HTML entered will be escaped. You cannot use any kind of HTML formatting or markup/markdown other than pressing ENTER at the end of a paragraph.
You cannot configure the Contact Form email processor on a per form basis. All contact forms on your site will share:
* The message that is displayed to the user after the message has been sent.
* The footer of the email containing additional user information.
* Enabling/disabling of the autoresponder.
* The autoresponder message (if enabled).
Web forms are limited to 1024 fields including hidden fields and the submit button. Total size of the submission may not exceed 256 KB.
There is no support file attachments type fields or form-data encoded as "multipart/form-data".
[(Back to top)](#table-of-contents)
# Language Support
This plugin includes support for the English language. Additional languages including French are supported if you've installed one or more additional Moodle language packs.
Some core fields will be different if a language pack is available for your language. On a French Moodle site, for example (fielname on English site => fieldname on French site):
* email => courriel
* message => message
* name => nom
* subject => objet
So on a French site, you would need to use the French versions of the field names or Contact Form will not recognize them. For more information, see the section called [Customizing the form](#customizing-the-form).
Pro tip: Creating a multi-language Moodle site? Use the [FilterCodes](https://moodle.org/plugins/filter_filtercodes) {getstring} tag to populate the correct field name. Example:
Note: If no language pack is available for your language, the plugin will default to the English language pack. However, if you need a language that is not yet supported, please contribute translations using the Moodle AMOS Translation Toolkit for Moodle at:
https://lang.moodle.org/
This plugin has not been tested for right-to-left (RTL) language support. If you want to use this plugin with a RTL language and it doesn't work as-is, feel free to prepare a pull request and submit it to the project page at:
https://github.com/michael-milette/moodle-local_contact
[(Back to top)](#table-of-contents)
# FAQ
## Answers to frequently asked questions
### How do I make this form available to everyone, even if they are not logged in?
Assuming you have not enabled "Force users to log in" in Moodle settings, the easiest way is to add a page or block to your Moodle Frontpage (also known as Home page).
1. Login as a Moodle administrator.
2. Go to your Front Page.
3. Turn editing on.
4. Add a **Page** type activity/resource.
5. Insert your HTML form or related FilterCode (if you are using it) into the content field and save. If pasting HTML code, make sure that the WYSIWYG editor is in HTML mode.
Since you don't need to be logged into your Moodle Frontpage to see it, your form will also be accessible to visitors to your site who are logged-out, logged-in as a guest as well as to regular logged-in users. If this option is not available to you, the process is a little more complicated as it involves making a course available to guests and having Moodle automatically logged them in as guests.
### Why isn't my form working?
The quick and easy way to create webforms in Moodle is to simply install [FilterCodes](https://moodle.org/plugins/filter_filtercodes/) and use its tags. Be sure to set the filter to **On** in Moodle's Manage Filter settings and set it to filter **Content and headings**. Built-in forms include {formquickquestion}, {formcontactus}, {formcourserequest}, {formsupport}, {formcheckin}. [More information for FilterCodes method](#the-quick-and-easy-method).
If you are not using FilterCodes, be sure to replace any reference to tags that look like {tagname} that might be found in your HTML form. [More informaiton on HTML method](#custom-method). For example, if your form contains {wwwroot} and the webroot your Moodle site is https://example.com, then replace {wwwroot}/local/contact/ with https://example.com/local/contact/ . Look through your form as there may be others depending on the sample code upon which you based your form.
Anytime your form doesn't work, be sure to try it in a Moodle page or block using the Boost theme with the current language set to English. If it works there, chances are that it is the theme or plugin you are using that is causing the issue, not FilterCodes or Contact for Moodle. As with the Static Pages plugin (see below), you may find that there is a setting that needs to be changed. If not, contact the author/maintainer of the plugin and ask them to add support for filtering in their theme or plugin.
If the form works in English and not in your preferred language, you may need to translate the names of some of your fields. This is required if you want the field names to appear in your language in the email. [More information on Language support](#language-support)
#### Sesskey error
If you are getting an error that mentions *sesskey*, you may have forgot to include the JavaScript snippet in your form:
If you have [FilterCodes](https://moodle.org/plugins/filter_filtercodes/) installed, you can simply replace all of the above code in your form with:
{formsesskey}
If JavaScript does not work in your form, you can replace the above code with the following HTML. Be aware that it will override one of several anti-spam protections built into Contact Form (requires FilterCodes):
#### Static Pages plugin compatibility
The recommended way of using Contact for Moodle is to create your webmail form in a page or block. However, there may be use cases where you might prefer to use the [local_staticpage plugin](https://moodle.org/plugins/local_staticpage). In order for this to work, you will need to configure a couple of its settings:
* Enable the Static Pages plugin's **Process Filters** (processfilters) setting to enable processing of FilterCodes.
* Disable its **Clean HTML code** (cleanhtml) setting to prevent StaticPage from deleting or filtering out some of the required HTML code in your form.
This demonstrates how to use FilterCode Contact Form templates with the Static Pages to create a quick Contact Us form. Start by copying the following code into a text file called contact.html and saving it: