"Advanced examples":#advanced
"Separate input and error forms":#advanced1
"User selectable subject field":#advanced2
** "User selectable recipient, without showing email address":#advanced3
"Styling":#styling
"Plugin API and callback events":#api
"Frequently asked questions":#faq
"Authors/credits":#credits
h2(#introduction). Introduction
A Textpattern CMS form mailer plugin. @@ produces a flexible, customisable email contact form. It is intended for use as an enquiry form for commercial and private sites, and includes several features to help reduce common problems with such forms (invalid email addresses, missing information).
h2(#differences). Migrating from zem_contact_reborn
If upgrading from zem_contact_reborn (the previous incarnation of this plugin), please note these differences:
Tags have been globally renamed from @<txp:zem_contact ... />@ to @<txp:com_connect ... />@ - please adjust your code accordingly.
Classes @zemConnectForm@, @zemError@, @zemRequired@, @zemThanks@, @zemText@, @zemEmail@, @zemTextarea@, @zemSubmit@, @zemSelect@, @zemOption@, @zemCheckbox@ and @zemRadio@ have been renamed to @comConnectForm@, @comError@, @comRequired@, @comThanks@, @comText@, @comEmail@, @comTextarea@, @comSubmit@, @comSelect@, @comOption@, @comCheckbox@ and @comRadio@ respectively - please adjust your code accordingly.
Disable or remove the zem_contact_lang plugin. Language strings are now bundled as part of the plugin itself. If you have a translation Textpack available that is not yet bundled, please submit it for inclusion.
Classes based on the input element @name@ are no longer automatically applied. Only default class names beginning with @com@ are set. To employ custom classes, use the @class@ attribute for each tag, or the global @classes@ attribute to set names for error and information messages.
If your site's 'Doctype' preference is set to @html5@ you may use HTML5 attributes in your tags. Otherwise, they will be ignored.
Validation of required elements and min/max constraints is done by the browser first, and the plugin second. So if you specify a field is required and it is left empty, the browser will usually prevent the form being submitted. To bypass (most of) the browser checks, specify @browser_validate="0"@ in your @@ tag.
h2(#usage). Usage
h3. Contact form
The simplest form is shown below, which produces a default form with 'Name', 'Email' and 'Message' fields. Email will be delivered to code>recipient@example.com</code, with the user's supplied email as the @From:@ address.
bc(language-markup).
To specify fields explicitly, use something like this:
Alternatively, place the field specifications in a Textpattern form, and call it like this:
bc(language-markup).
h3. Send article
Within the context of an individual article, this plugin can be used to send the article (or excerpt, if it exists) to an email address specified by the visitor. This requires at least two tags:
@com_connect@, to create a form that is initially hidden by setting the @send_article@ attribute.
@com_connect_send_article@, to create a 'Send article' link which reveals the aforementioned form when clicked.
bc(language-markup).
By default the form contains fields for your name and email address, the recipient's email address and a personal message, but similar to contact forms you can create your own form layout. Some things you need to know:
Set the @send_article@ attribute to @1@ in the @com_connect@ tag.
Use a @com_connect_email@ tag with the @send_article@ attribute set to @1@. This field will be used as the recipient email address.
@@ can be used to create a 'Send article' link within an article form, connecting it to the contact form.
All other tags provided by this plugin can only be used inside a @@ - @</txp:com_connect>@ container tag or in a Textpattern form used as the @form@ attribute in the @@ tag.
In addition to the tags detailed in the following sections, every tag accepts a core set of common attributes. These are:
; @accesskey="character"@
: Shortcut key to set focus on the field.
; @autofocus="boolean"@
: To automatically focus the cursor in this field on page load. Only one field may have this property.
; @dir="value"@
: Text direction (@ltr@, @rtl@ or @auto@).
; @disabled="boolean"@
: Whether the input control accepts user input. If set, the element does not get submitted with the form, nor is it subject to any @checkValidity()@ JavaScript calls.
; @hidden="boolean"@
: The visibility of the input control.
; @id="id"@
: The HTML identifier for the control.
; @lang="value"@
: The ISO 639 language short code (e.g. @en-gb@, @de-de@) that governs the field.
; @list="id"@
: Used in conjunction with the @
h3(#cc). com_connect tag
bc(language-markup).
May be used as a single (self-closing) or container tag. Place this where you want the input form to go. Status and error messages, if any, will be displayed before the form.
h4. Attributes
; @body_form="form name"@
: Use specified form for the message body text.
; @class="space-separated values"@
: Set the CSS @class@ name of the tag. Default: @comConnectForm@. To remove @class@ attribute from the element entirely, use @class=""@.
; @classes="comma-separated key:value pairs"@
: Set the CSS classes for error / information conditions. Specify each as a pair of values separated by a colon, e.g. @classes="required: req_field, element: warn_field"@. There are up to four available to customise:
: @element@: Set for each form field that fails validation for any reason. Default: @errorElement@.
: @wrapper@: The class to surround the list of errors shown above the form. Default: @comError@.
: @required@: Class assigned when a required element is not completed. Default: @comRequired@.
: @thanks@: Class applied to the wrapper around the @thanks_form@. Default: @comThanks@.
; @copysender="boolean"@
: Whether to send a copy of the email to the sender's address. Available values: @1@ (yes) or @0@ (no). Default is @0@.
; @expire="number"@
: Number of seconds after which the form will expire, thus requiring a page refresh before sending. Default is @600@.
; @form="form name"@
: Use specified form, containing the layout of the contact form fields.
; @from="email address"@
: Email address used in the "From:" field when sending email. Defaults to the sender's email address. If specified, the sender's email address will be placed in the "Reply-To:" field instead.
; @from_form="form name"@
: Use specified form (overrides @from@ attribute).
; @label="text"@
: Label for the contact form. If set to an empty string, display of the fieldset and legend tags will be suppressed. Default is @Contact@.
; @lang="lang-code"@
: Override the language strings that would normally be used from the current admin-side language in force. e.g. @lang="fr-fr"@ would load the French language strings. A Textpack must already exist for the chosen language.
; @browser_validate="boolean"@
: Set to 0 if you wish to stop the browser from validating form field values and 'required' status of input elements. The plugin itself is then solely responsible for validation and will indicate error conditions after submission. Default is @1@.
; @redirect="URL"@
: Redirect to specified URL (overrides @thanks@ and @thanks_form@ attributes). URL must be relative to the Textpattern site URL. Example: @redirect="monkey"@ would redirect to @http://example.com/monkey@.
; @replyto=boolean|email address@
: Governs the email address of who the message reply should go to. Options:
: @true@ (default): Use the email address from the form itself (value from the @@ tag) if the @from@ address has been specified. Blank otherwise.
: @false@: Always use the @from@ email address as reply-to. Note that if the @from@ is omitted the email will be from nobody and may be rejected by the receiving server.
: @email address@: Use the specified email address as the reply-to, if it's a valid address.
; @required="boolean"@
: Whether to require all tags in this contact form to be completed before the form can be submitted. Can be overridden on a field-by-field basis by using the @required@ attribute in the relevant tag. Available values: @1@ (yes) or @0@ (no). Default is @1@.
; @send_article="boolean"@
: Whether to use this form to send an article. Available values: @1@ (yes) or @0@ (no). Default is @0@.
; @show_error="boolean"@
: Whether to display error and status messages. Available values: @1@ (yes) or @0@ (no). Default is @1@.
; @show_input="boolean"@
: Whether to display the form @@ fields. Available values: @1@ (yes) or @0@ (no). Default is @1@.
; @subject="subject text"@
: Subject used when sending an email. Default is the site name.
; @subject_form="form name"@
: Use specified form (overrides @subject@ attribute).
; @thanks="text"@
: Message shown after successfully submitting a message. Default is @Thank you, your message has been sent@.
; @thanks_form="form name"@
: Use specified form (overrides @thanks@ attribute).
; @to="email address"@ %(warning)required%
: Recipient email address. Multiple recipients can be specified, separated by commas.
; @to_form="form name"@
: Use specified form (overrides @to@ attribute).
h4. Examples
h5. Example 1: Built-in contact form
When used as a single tag, produces a default form with 'Name', 'Email' and 'Message' fields. Email will be delivered to code>recipient@example.com</code, with the user's supplied email as the @From:@ address:
bc(language-markup).
h5. Example 2: Building a custom form container
When used as a container tag, much more flexibility is allowed, for example:
Use the @body_form@ attribute to build custom content that is emailed to the recipient:
bc(language-markup).
And the @body_form@ form template named @message-formatting@ is as follows:
bc.. ============
Email received.
: Mr. Nobody wrote:
Nothing much :(
============
h5. Example 4: HTML and plaintext email content
Use the @body_form@ attribute to build custom content in both plaintext and HTML formats that is emailed to the recipient:
bc(language-markup).
Use the @body_form@ form template named @message-formatting@ as follows, and note the @@ tags which indicate that the content of the given @type@ immediately follows. Use the tag with @type="end"@ to signify that the content is complete.
bc.. ============
Fields submitted:
:
============
h3(#cc_text). com_connect_text tag
bc(language-markup).
Creates a text @@ field and corresponding @