Plugin index

Zem Contact Reborn

Please reports bugs and problems with this plugin in this forum thread.

This plugin requires a separate language plugin called zem_contact_lang to be installed and activated to work properly.

Contents

Features

Back to top

Getting started

Contact form

The simplest form is shown below, which produces a default form with Name, Email and Message fields. Email will be delivered to recipient@example.com, with the user’s supplied email as the “From:” address.

<txp:zem_contact to="recipient@example.com" />

To specify fields explicitly, use something like this:

<txp:zem_contact to="recipient@example.com">
  <txp:zem_contact_email />
  <txp:zem_contact_text label="Phone" min=7 max=15/>
  <txp:zem_contact_textarea label="Your question" />
  <txp:zem_contact_submit label="Send" />
</txp:zem_contact>

Alternatively, place the field specifications in a Textpattern form, and call it like this:

<txp:zem_contact to="recipient@example.com" form="mycontactform" />

Back to top

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: 
<txp:zem_contact send_article="1" />
<txp:zem_contact_send_article />

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:

<txp:zem_contact to="you@example.com" send_article="1">
  <txp:zem_contact_email label="Recipient Email" send_article="1" />
  <txp:zem_contact_email label="Your Email" />
  <txp:zem_contact_submit label="Send Article" />
</txp:zem_contact>

<txp:zem_contact_send_article />

Back to top

Tags

<txp:zem_contact /> 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).

<txp:zem_contact_send_article /> 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:zem_contact> … </txp:zem_contact> container tag or in a Textpattern form used as the form attribute in the <txp:zem_contact /> tag.

Back to top

<txp:zem_contact />

May be used as a 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.

Attributes

Examples

See Getting started and Advanced examples.

Back to top

<txp:zem_contact_text />

Creates a text input field and corresponding <label> tag. The input value will be included in the email, preceded by the label.

Attributes

Example

<txp:zem_contact_text label="Your name" />

Back to top

<txp:zem_contact_email />

Input field for user’s email address.

The entered email address will automatically be validated to make sure it is of the form “abc@xxx.yyy[.zzz]”. On non-Windows servers, a test will be done to verify that an A or MX record exists for the domain. Neither test prevents spam, but it does help detecting accidental typing errors.

Attributes

Example

<txp:zem_contact_email label="Your email address" />

Back to top

<txp:zem_contact_textarea />

Creates a textarea.

Attributes

Example

Textarea that is 40 chars wide, 10 lines high, with a customized label:

<txp:zem_contact_textarea cols="40" rows="10" label="Your question" />

Back to top

<txp:zem_contact_submit />

Creates a submit button.
When used as a container tag, a “button” element will be used instead of an “input” element.

Attributes:

Examples

Standard submit button:

<txp:zem_contact_submit />

Submit button with your own text:

<txp:zem_contact_submit label="Send" />

Usage as a container tag, which allows you to use Textpattern tags and HTML markup in the submit button:

<txp:zem_contact_submit><strong>Send</strong> question</txp:zem_contact_submit>
<txp:zem_contact_submit><img src="path/to/img.png" alt="submit"></txp:zem_contact_submit>

Back to top

<txp:zem_contact_select />

Creates a drop-down selection list.

Attributes

Examples

Select list labeled ‘Department’, containing three options and a blank option (due to the comma before ‘Marketing’) shown by default, forcing the user to make a selection.

<txp:zem_contact_select label="Department" list=",Marketing,Sales,Support" />

Select list containing three options with ‘Marketing’ selected by default.

<txp:zem_contact_select list="Marketing,Sales,Support" selected="Marketing" />

Back to top

<txp:zem_contact_checkbox />

Creates a check box.

Attributes

Examples

Shrink-wrap agreement which must be checked by the user before the email will be sent.

<txp:zem_contact_checkbox label="I accept the terms and conditions" />

Optional checkboxes:

Select which operating systems are you familiar with:<br />
<txp:zem_contact_checkbox label="Windows" required="0" /><br />
<txp:zem_contact_checkbox label="Unix/Linux/BSD" required="0" /><br />
<txp:zem_contact_checkbox label="MacOS" required="0" /><br />

Back to top

<txp:zem_contact_radio />

Creates a radio button.

Attributes

Example

Group mutually exclusive radio buttons by setting the group attribute on the first radio button in a group. Only the chosen radio button from each group will be used in the email message. The message will be output in the form group: label for each of the chosen radio buttons.

<txp:zem_contact_radio label="Medium" group="I like my steak" />
<txp:zem_contact_radio label="Rare" />
<txp:zem_contact_radio label="Well done" />

<txp:zem_contact_radio label="Wine" group="With a glass of" />
<txp:zem_contact_radio label="Beer" />
<txp:zem_contact_radio label="Water" />

Back to top

<txp:zem_contact_secret />

This tag has no effect on the form or HTML output, but will include additional information in the email. It can be used as a self-closing tag or as a container tag.

Attributes

Examples

Usage as a self-closing tag

<txp:zem_contact_secret value="The answer is 42" />

Usage as a container tag

<txp:zem_contact_secret label="Dear user">
  Please provide a useful example for this tag!
</txp:zem_contact_secret>

Back to top

<txp:zem_contact_serverinfo />

This tag has no effect on the form or HTML output, but will include additional information in the email based on the PHP $_SERVER variable.

Attributes

Examples

Add the IP address of the visitor to the email

<txp:zem_contact_serverinfo name="REMOTE_ADDR" label="IP number" />

Add the name of the visitor’s browser to the email

<txp:zem_contact_serverinfo name="HTTP_USER_AGENT" label="Browser" />

Back to top

<txp:zem_contact_send_article />

Use this tag in your individual article form, where you want the “send article” link to be displayed.

Attributes:

Examples:

See Getting started

Back to top

Advanced examples

Separate input and error forms

Using show_input and show_error to display the form and error messages on different parts of a page. A form is used to make sure the contents of both forms are identical, otherwise they would be seen as two independent forms. The first form only shows errors (no input), the second form only shows the input fields (no errors).

<div id="error">
  <txp:zem_contact form="contact_form" show_input="0" />
</div>

<div id="inputform">
  <txp:zem_contact form="contact_form" show_error="0" />
</div>

Apart from the show_error and show_input attributes, all other attributes must be 100% identical in both forms, otherwise they would be seen as two unrelated forms.

Back to top

User selectable subject field

Specify the subject_form attribute and create a form which includes a zem_contact_select tag:

<txp:zem_contact to="you@example.com" subject_form="my_subject_form" />
  <txp:zem_contact_text label="Name" /><br />
  <txp:zem_contact_email /><br />
  <txp:zem_contact_select label="Choose Subject" list=",Question,Feedback" /><br />
  <txp:zem_contact_textarea label="Message" /><br />
</txp:zem_contact>

Create a Textpattern form called “my_subject_form”, containing:

<txp:php>
  global $zem_contact_form;
  echo $zem_contact_form['Choose Subject'];
</txp:php>

The label used in the zem_contact_select tag must be identical to the corresponding variable in the subject_form. Here we used Choose subject.

If you’d prefer to add a common prefix for all subjects, use a subject_form containing:

<txp:php>
  global $zem_contact_form;
  echo 'My common prefix - ' . $zem_contact_form['Choose Subject'];
</txp:php>

Back to top

User selectable recipient, without showing email address

Specify the to_form attribute and create a form which includes a zem_contact_select tag:

<txp:zem_contact to_form="my_zem_contact_to_form">
  <txp:zem_contact_text label="Name" /><br />
  <txp:zem_contact_email /><br />
  <txp:zem_contact_select label="Department" list=",Support,Sales" /><br />
  <txp:zem_contact_textarea label="Message" /><br />
</txp:zem_contact>

Create a Textpattern form called “my_zem_contact_to_form”, containing:

<txp:php>
  global $zem_contact_form;
  switch($zem_contact_form['Department'])
  {
    case 'Support':
      echo 'crew@example.com';
      break;
    case 'Sales':
      echo 'showmethemoney@example.com';
      break;
    default:
      echo 'someone@example.com';
  }
</txp:php>

The label used in the zem_contact_select tag must be identical to the corresponsing variable in the to_form. Here we used Department.

A ‘default’ email address in the to_form is specified to ensure that a valid email address is used in cases where you add or change a select/radio option and forget to update the to_form.

Never use tags like zem_contact_text, zem_contact_email or zem_contact_textarea for setting the recipient address, otherwise your form can be abused to send spam to any email address!

Back to top

Styling

The form itself has a class zemContactForm set on the FORM HTML tag.

The list of error messages (if any) has a class zemError set on the UL HTML tag that encloses the list of errors.

All form elements and corresponding labels have the following classes (or ids set):
  1. One of zemText, zemTextarea, zemSelect, zemRadio, zemCheckbox, zemSubmit. It should be obvious which class is used for which form element (and corresponding label).
  2. zemRequired or errorElement or zemRequirederrorElement, depending on whether the form element is required, an error was found in whatever the visitor entered… or both.
  3. An individual “id” or “class” set to the value of the name attribute of the corresponding tag. When styling forms based on this class, you should explicitly set the name attribute because automatically generated names may change in newer zem_contact_reborn versions.

Back to top

History

Only the changes that may affect people who upgrade are detailed below.
To save space, links to forum topics that detail all the changes in each version have been added.

Back to top

Credits

Back to top

Zem Contact Reborn’s API

The plugin API of zem contact, developed by Tranquillo, is similar to the comments API of Textpattern, which is explained in the Textbook Plugin Development Topics and Combat Comment Spam.

Two callback events exist in zem_contact_reborn:

For reference here are the commands that will be interesting to plugin developers:

// This will call your function before the form is submitted
// So you can analyse the submitted data
register_callback('abc_myfunction','zemcontact.submit');

// This will call your function and add the output (use return $mystuff)
// to the contact-form.
register_callback('abc_myotherfunction2','zemcontact.form');

// To get hold of the form-variables you can use
global zem_contact_form;

// With the following two lines you can tell zem_contact if your
// plugin found spam
$evaluator =& get_zemcontact_evaluator();

// The passed value must be non-zero to mark the content as spam.
// Value must be a number between 0 and 1.
$evaluator -> add_zemcontact_status(1);

Multiple plugins can be active at the same time and each of them can mark the submitted content as spam and prevent the form from being submitted.

An example of a plug-in connecting to Zem Contact Reborn’s API:

register_callback('pap_zemcontact_form','zemcontact.form');
register_callback('pap_zemcontact_submit','zemcontact.submit');

function pap_zemcontact_form() {
  $field = '<div style="display:none">'.
    finput('text','phone',ps('phone'),'','','','','','phone').'<br />'.
    finput('text','mail',ps('mail'),'','','','','','mail').'</div>';
  return $field;</code>
}

function pap_zemcontact_submit() {
  $checking_mail_field = trim(ps('mail'));
  $checking_phone_field = trim(ps('phone'));

  $evaluation =& get_zemcontact_evaluator();

  // If the hidden fields are filled out, the contact form won't be submitted!
  if ($checking_mail_field != '' or $checking_phone_field != '') {
    $evaluation -> add_zemcontact_status(1);
  }
  return;
}

Back to top