FormMail Contact - User Guide
Version 1.0.0
================================================

OVERVIEW
--------
FormMail Contact is a simple, lightweight Joomla site module that displays a
contact form on any page or position. It requires no SMTP configuration - it
uses your server's built-in mail function via Joomla's mailer. Spam protection
is provided by a built-in SVG math captcha (no external service required).

This is intended to be used on hosting environments using the build in SENDMAIL not SMTP.  If your server requires the use of SMTP this extension is NOT what you need.

Standard fields included:
- Name (required by default)
- Address
- Email (required by default, validated)
- Phone
- Subject
- Message (required by default)
- Math captcha (always required)

Custom fields (text, textarea, select/dropdown) can be added by editing
helper.php - see the Custom Fields section below.

REQUIREMENTS
------------
- Joomla 5.x or 6.x
- PHP 8 or higher
- Server mail enabled on your hosting account (most hosts enable this
by default - no SMTP setup needed)

INSTALLATION
------------
1. Log in to your Joomla administrator panel.
2. Go to Extensions > Install.
3. Upload mod_formmail_v1.0.0.zip using the Upload Package File tab.
4. Click Upload & Install.
5. Go to Extensions > Modules and find "FormMail Contact" in the list.
6. Click the module title to open its settings.
7. Configure the settings (see below) and assign it to a menu item and
module position.
8. Set Status to Published and save.

CONFIGURATION SETTINGS
-----------------------
All settings are found in the module's Basic tab in the Joomla Module Manager.

Recipient Email (required)
The email address that will receive form submissions.
Default: your@email.com
Change this to your actual email address before publishing.

Email Subject
The subject line used on outgoing notification emails.
Default: Contact Form Submission

From Name
The name that appears in the From header of the outgoing email.
Default: Website Contact Form
Note: The sender address will be the email entered by the visitor.

Required Fields
A comma-separated list of field names that the visitor must fill in.
Default: name,email,message
Available field names: name, address, email, phone, subject, message
Plus any custom field names you have added.
Example to also require phone: name,email,phone,message

Success Message
The message shown to the visitor after a successful submission.
Default: Thank you! Your message has been sent. We will be in touch shortly.

UNINSTALLING
------------
To uninstall, use Extensions > Manage > Manage in the Joomla administrator
and click Uninstall next to FormMail Contact. The module files will be
removed. No database tables are created by this module so nothing else
needs to be cleaned up.

CUSTOM FIELDS
-------------
FormMail Contact supports adding extra fields without modifying the template.
Open modules/mod_formmail/helper.php on your server (or edit before
installing) and find the $custom_fields array near the top of the class.

Three field types are supported:

Text field:
['name' => 'company', 'label' => 'Company', 'type' => 'text'],

Textarea:
['name' => 'details', 'label' => 'Additional Details', 'type' => 'textarea'],

Select (dropdown):
['name' => 'budget', 'label' => 'Budget Range', 'type' => 'select',
'options' => ['Under $1k', '$1k-$5k', 'Over $5k']],

Each custom field is automatically:
- Rendered in the form in the order listed, before the Message field
- Included in the email notification
- Available as a required field by adding its name to the Required Fields
setting in the module configuration

Example with two custom fields enabled:

public $custom_fields = [
['name' => 'company', 'label' => 'Company', 'type' => 'text'],
['name' => 'budget', 'label' => 'Budget Range', 'type' => 'select',
'options' => ['Under $1k', '$1k-$5k', 'Over $5k']],
];

After editing helper.php, save the file and reload the page - no Joomla
cache clearing is needed.

STYLING
-------
The module includes formmail.css with clean, responsive default styles.
All CSS classes are prefixed with fm- to avoid conflicts with your template.

To override styles, add rules to your template's user.css (or custom CSS
field in your Joomla template settings) targeting the fm- classes.

Key classes:
.fm-wrap Outer container
.fm-form The form element
.fm-row Each field row
.fm-row--half Two-column row (email + phone)
.fm-captcha-row Captcha row
.fm-submit-row Submit button row
.fm-success Success message container
.fm-error Inline field error message
.fm-digit SVG captcha digit

SPAM PROTECTION
---------------
FormMail Contact uses a built-in SVG math captcha. Two single-digit numbers
are displayed as pixel-art SVG images (not readable text), and the visitor
must type the sum. Because the numbers are rendered as geometry rather than
text, they are invisible to basic bots that scrape text from HTML.

No external captcha service, API key, or third-party plugin is required.

MULTIPLE INSTANCES
------------------
You can place multiple instances of FormMail Contact on the same site or
even on the same page. Each module instance has a unique ID and its own
captcha session, so they operate independently without conflict.

SUPPORT
-------
For support visit: https://webgoodies.site/index.php/contact-me

This extension is released under the GNU General Public License v2.0 or later.
See LICENSE.txt included in the package or visit https://www.gnu.org/licenses/