 <style>
   li code {font-weight: bold;}
   pre {padding: 0.5em 1em; background: #eee; border: 1px dashed #ccc;}
   h1, h2, h3, h3 code {font-family: sans-serif; font-weight: bold;}
   h1, h2, h3 {margin-left: -1em;}
   h2, h3 {margin-top: 2em;}
   h1 {font-size: 3em;}
   h2 {font-size: 2em;}
   h3 {font-size: 1.5em;}
   li a code {font-weight: normal;}
   .required, .warning {color:red;}
 </style>

	<h1 id="top">Zem Contact Reborn</h1>

	<p>Please reports bugs and problems with this plugin in <a href="http://forum.textpattern.com/viewtopic.php?id=23728">this forum thread</a>.</p>

	<p class="required">This plugin requires a separate language plugin called <code>zem_contact_lang</code> to be installed and activated to work properly.</p>

	<h2 id="contents">Contents</h2>

	<ul>
		<li><a href="#features">Features</a></li>
		<li><a href="#start">Getting started</a>
	<ul>
		<li><a href="#contactform">Contact form</a></li>
		<li><a href="#sendarticle">Send article</a></li>
	</ul></li>
		<li><a href="#tags">Tags</a>
	<ul>
		<li><a href="#zc"> <code>&lt;txp:zem_contact /&gt;</code> </a></li>
		<li><a href="#zc_text"> <code>&lt;txp:zem_contact_text /&gt;</code> </a></li>
		<li><a href="#zc_email"> <code>&lt;txp:zem_contact_email /&gt;</code> </a></li>
		<li><a href="#zc_textarea"> <code>&lt;txp:zem_contact_textarea /&gt;</code> </a></li>
		<li><a href="#zc_submit"> <code>&lt;txp:zem_contact_submit /&gt;</code> </a></li>
		<li><a href="#zc_select"> <code>&lt;txp:zem_contact_select /&gt;</code> </a></li>
		<li><a href="#zc_checkbox"> <code>&lt;txp:zem_contact_checkbox /&gt;</code> </a></li>
		<li><a href="#zc_radio"> <code>&lt;txp:zem_contact_radio /&gt;</code> </a></li>
		<li><a href="#zc_secret"> <code>&lt;txp:zem_contact_secret /&gt;</code> </a></li>
		<li><a href="#zc_server_info"> <code>&lt;txp:zem_contact_serverinfo /&gt;</code> </a></li>
		<li><a href="#zc_send_article"> <code>&lt;txp:zem_contact_send_article /&gt;</code> </a></li>
	</ul></li>
		<li><a href="#advanced">Advanced examples</a>
	<ul>
		<li><a href="#show_error">Separate input and error forms</a></li>
		<li><a href="#subject_form">User selectable subject field</a></li>
		<li><a href="#to_form">User selectable recipient, without showing email addresses</a></li>
	</ul></li>
		<li><a href="#styling">Styling</a></li>
		<li><a href="#history">History</a></li>
		<li><a href="#credits">Credits</a></li>
		<li><a href="#api">Plugin <span class="caps">API</span> and callback events</a></li>
	</ul>

	<h2 id="features">Features</h2>

	<ul>
		<li>Arbitrary text fields can be specified, with min/max/required settings for validation.</li>
		<li>Email address validation, including a check for a valid MX record (Unix only).</li>
		<li>Safe escaping of input data.</li>
		<li><span class="caps">UTF</span>-8 safe.</li>
		<li>Accessible form layout, including <code>&lt;label&gt;</code>, <code>&lt;legend&gt;</code> and <code>&lt;fieldset&gt;</code> tags.</li>
		<li>Various classes and ids to allow easy styling of all parts of the form.</li>
		<li>A separate language plug-in to enable easy localisation.</li>
		<li>Spam prevention <span class="caps">API</span> (used by Tranquillo&#8217;s <code>pap_contact_cleaner</code> plugin).</li>
	</ul>

	<p><a href="#top">Back to top</a></p>

	<h2 id="start">Getting started</h2>

	<h3 id="contactform">Contact form</h3>

	<p>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&#8217;s supplied email as the &#8220;From:&#8221; address.</p>

<pre><code>&lt;txp:zem_contact to=&quot;recipient@example.com&quot; /&gt;
</code></pre>

	<p>To specify fields explicitly, use something like this:</p>

<pre><code>&lt;txp:zem_contact to=&quot;recipient@example.com&quot;&gt;
  &lt;txp:zem_contact_email /&gt;
  &lt;txp:zem_contact_text label=&quot;Phone&quot; min=7 max=15/&gt;
  &lt;txp:zem_contact_textarea label=&quot;Your question&quot; /&gt;
  &lt;txp:zem_contact_submit label=&quot;Send&quot; /&gt;
&lt;/txp:zem_contact&gt;
</code></pre>

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

<pre><code>&lt;txp:zem_contact to=&quot;recipient@example.com&quot; form=&quot;mycontactform&quot; /&gt;
</code></pre>

	<p><a href="#top">Back to top</a></p>

	<h3 id="sendarticle">Send article</h3>

	<p>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:
	<ul>
		<li><code>zem_contact</code>, to create form that is initially hidden by setting the <code>send_article</code> attribute.</li>
		<li><code>zem_contact_send_article</code>, to create a &#8216;send article&#8217; link which reveals the aforementioned form when clicked.</li>
	</ul></p>

<pre><code>&lt;txp:zem_contact send_article=&quot;1&quot; /&gt;
&lt;txp:zem_contact_send_article /&gt;
</code></pre>

	<p>By default the form contains fields for your name and email address, the recipient&#8217;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:
	<ul>
		<li>Set the <code>send_article</code> attribute to <code>1</code> in the <code>zem_contact</code> tag.</li>
		<li>Use a <code>zem_contact_email</code> tag with the <code>send_article</code> attribute set to <code>1</code>. This field will be used as the recipient email address.</li>
	</ul></p>

<pre><code>&lt;txp:zem_contact to=&quot;you@example.com&quot; send_article=&quot;1&quot;&gt;
  &lt;txp:zem_contact_email label=&quot;Recipient Email&quot; send_article=&quot;1&quot; /&gt;
  &lt;txp:zem_contact_email label=&quot;Your Email&quot; /&gt;
  &lt;txp:zem_contact_submit label=&quot;Send Article&quot; /&gt;
&lt;/txp:zem_contact&gt;
</code>
<code>&lt;txp:zem_contact_send_article /&gt;
</code></pre>

	<p><a href="#top">Back to top</a></p>

	<h2 id="tags">Tags</h2>

	<p><a href="#zc"><code>&lt;txp:zem_contact /&gt;</code></a> 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).</p>

	<p><a href="#zc_send_article"><code>&lt;txp:zem_contact_send_article /&gt;</code></a> can be used to create a &#8220;send article&#8221; link within an article form, connecting it to the contact form.</p>

	<p>All other tags provided by this plugin can only be used inside a <code>&lt;txp:zem_contact&gt;</code> &#8230; <code>&lt;/txp:zem_contact&gt;</code> container tag or in a Textpattern form used as the <code>form</code> attribute in the <code>&lt;txp:zem_contact /&gt;</code> tag.</p>

	<p><a href="#top">Back to top</a></p>

	<h3 id="zc"><code>&lt;txp:zem_contact /&gt;</code></h3>

	<p>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.</p>

	<h4>Attributes</h4>

	<ul>
		<li><code>to=&quot;email address&quot;</code> <span class="required">required</span><br />
Recipient email address.</li>
		<li><code>to_form=&quot;form name&quot;</code><br />
Use specified form (overrides <strong>to</strong> attribute).</li>
	</ul>

	<ul>
		<li><code>from=&quot;email address&quot;</code><br />
Email address used in the &#8220;From:&#8221; field when sending email. Defaults to the sender&#8217;s email address. If specified, the sender&#8217;s email address will be placed in the &#8220;Reply-To:&#8221; field instead.</li>
		<li><code>from_form=&quot;form name&quot;</code><br />
Use specified form (overrides <strong>from</strong> attribute).</li>
	</ul>

	<ul>
		<li><code>subject=&quot;subject text&quot;</code><br />
Subject used when sending an email. Default is the site name.</li>
		<li><code>subject_form=&quot;form name&quot;</code><br />
Use specified form (overrides <strong>subject</strong> attribute).</li>
	</ul>

	<ul>
		<li><code>thanks=&quot;text&quot;</code><br />
Message shown after successfully submitting a message. Default is <strong>Thank you, your message has been sent</strong>.</li>
		<li><code>thanks_form=&quot;form name&quot;</code><br />
Use specified form (overrides <strong>thanks</strong> attribute).</li>
		<li><code>redirect=&quot;URL&quot;</code><br />
Redirect to specified <span class="caps">URL</span> (overrides <strong>thanks</strong> and <strong>thanks_form</strong> attributes). <span class="caps">URL</span> must be relative to the Textpattern Site <span class="caps">URL</span>. Example: <em>redirect=&#8220;monkey&#8221;</em> would redirect to http://example.com/monkey.</li>
	</ul>

	<ul>
		<li><code>label=&quot;text&quot;</code><br />
Label for the contact form. If set to an empty string, display of the fieldset and legend tags will be suppressed. Default is <strong>Contact</strong>.</li>
		<li><code>send_article=&quot;boolean&quot;</code><br />
Whether to use this form to <a href="#article">send an article</a>. Available values: <strong>1</strong> (yes), <strong>0</strong> (no). Default is <strong>0</strong> (no).</li>
		<li><code>copysender=&quot;boolean&quot;</code><br />
Whether to send a copy of the email to the sender&#8217;s address. Available values: <strong>1</strong> (yes), <strong>0</strong> (no). Default is <strong>0</strong> (no).</li>
	</ul>

	<ul>
		<li><code>form=&quot;form name&quot;</code><br />
Use specified form, containing the layout of the contact form fields.</li>
		<li><code>show_input=&quot;boolean&quot;</code><br />
 Whether to display the form input fields. Available values: <strong>1</strong> (yes), <strong>0</strong> (no). Default is <strong>1</strong> (yes).</li>
		<li><code>show_error=&quot;boolean&quot;</code><br />
 Whether to display error and status messages. Available values: <strong>1</strong> (yes), <strong>0</strong> (no). Default is <strong>1</strong> (yes).</li>
	</ul>

	<h4>Examples</h4>

	<p>See <a href="#contactform">Getting started</a> and <a href="#advanced">Advanced examples</a>.</p>

	<p><a href="#top">Back to top</a></p>

	<h3 id="zc_text"><code>&lt;txp:zem_contact_text /&gt;</code></h3>

	<p>Creates a text input field and corresponding <code>&lt;label&gt;</code> tag. The input value will be included in the email, preceded by the label.</p>

	<h4>Attributes</h4>

	<ul>
		<li><code>label=&quot;text&quot;</code><br />
Text label displayed to the user. Default is <strong>Text</strong>.</li>
		<li><code>name=&quot;value&quot;</code><br />
Field name, as used in the <span class="caps">HTML</span> input tag.</li>
		<li><code>break=&quot;tag&quot;</code><br />
Break tag between the label and input field. Default is <code>&lt;br /&gt;</code>. Use <code>break=&quot;&quot;</code> to put the label and input field on the same line.</li>
		<li><code>default=&quot;value&quot;</code><br />
Default value when no input is provided.</li>
		<li><code>min=&quot;integer&quot;</code><br />
Minimum input length in characters. Default is <strong>0</strong>.</li>
		<li><code>max=&quot;integer&quot;</code><br />
Maximum input length in characters. Default is <strong>100</strong>.</li>
		<li><code>size=&quot;integer&quot;</code><br />
Size of the input field as displayed to the user.</li>
		<li><code>required=&quot;boolean&quot;</code><br />
Whether this text field must be filled out. Available values: <strong>1</strong> (yes), <strong>0</strong> (no). Default is <strong>1</strong> (yes).</li>
	</ul>

	<h4>Example</h4>

<pre><code>&lt;txp:zem_contact_text label=&quot;Your name&quot; /&gt;
</code></pre>

	<p><a href="#top">Back to top</a></p>

	<h3 id="zc_email"><code>&lt;txp:zem_contact_email /&gt;</code></h3>

	<p>Input field for user&#8217;s email address.</p>

	<p>The entered email address will automatically be validated to make sure it is of the form &#8220;abc@xxx.yyy[.zzz]&#8221;. 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.</p>

	<h4>Attributes</h4>

	<ul>
		<li><code>label=&quot;text&quot;</code><br />
Text label displayed to the user. Default is <strong>Email</strong>.</li>
		<li><code>name=&quot;value&quot;</code><br />
Field name, as used in the <span class="caps">HTML</span> input tag.</li>
		<li><code>break=&quot;tag&quot;</code><br />
Break tag between the label and input field. Default is <code>&lt;br /&gt;</code>. Use <code>break=&quot;&quot;</code> to put the label and input field on the same line.</li>
		<li><code>default=&quot;value&quot;</code><br />
Default value when no input is provided.</li>
		<li><code>min=&quot;integer&quot;</code><br />
Minimum input length in characters. Default is <strong>0</strong>.</li>
		<li><code>max=&quot;integer&quot;</code><br />
Maximum input length in characters. Default is <strong>100</strong>.</li>
		<li><code>size=&quot;integer&quot;</code><br />
Size of the input field as displayed to the user.</li>
		<li><code>required=&quot;boolean&quot;</code><br />
Whether this text field must be filled out. Available values: <strong>1</strong> (yes), <strong>0</strong> (no). Default is <strong>1</strong> (yes).</li>
		<li><code>send_article=&quot;boolean&quot;</code><br />
Whether this field is used as the recipient email address when using the send_article function. Available values: <strong>1</strong> (yes), <strong>0</strong> (no). Default is <strong>0</strong> (no).</li>
	</ul>

	<h4>Example</h4>

<pre><code>&lt;txp:zem_contact_email label=&quot;Your email address&quot; /&gt;
</code></pre>

	<p><a href="#top">Back to top</a></p>

	<h3 id="zc_textarea"><code>&lt;txp:zem_contact_textarea /&gt;</code></h3>

	<p>Creates a textarea.</p>

	<h4>Attributes</h4>

	<ul>
		<li><code>label=&quot;text&quot;</code><br />
Text label displayed to the user. Default is <strong>Message</strong>.</li>
		<li><code>name=&quot;value&quot;</code><br />
Field name, as used in the <span class="caps">HTML</span> input tag.</li>
		<li><code>break=&quot;tag&quot;</code><br />
Break tag between the label and input field. Default is <code>&lt;br /&gt;</code>. Use <code>break=&quot;&quot;</code> to put the label and input field on the same line.</li>
		<li><code>default=&quot;value&quot;</code><br />
Default value when no input is provided.</li>
		<li><code>cols=&quot;integer&quot;</code><br />
Column width. Default is <strong>58</strong>.</li>
		<li><code>rows=&quot;integer&quot;</code><br />
Row height. Default is <strong>8</strong>.</li>
		<li><code>min=&quot;integer&quot;</code><br />
Minimum input length in characters. Default is <strong>0</strong>.</li>
		<li><code>max=&quot;integer&quot;</code><br />
Maximum input length in characters. Default is <strong>10000</strong>.</li>
		<li><code>required=&quot;boolean&quot;</code><br />
Whether this text field must be filled out. Available values: <strong>1</strong> (yes), <strong>0</strong> (no). Default is <strong>1</strong> (yes).</li>
	</ul>

	<h4>Example</h4>

	<p>Textarea that is 40 chars wide, 10 lines high, with a customized label:</p>

<pre><code>&lt;txp:zem_contact_textarea cols=&quot;40&quot; rows=&quot;10&quot; label=&quot;Your question&quot; /&gt;
</code></pre>

	<p><a href="#top">Back to top</a></p>

	<h3 id="zc_submit"><code>&lt;txp:zem_contact_submit /&gt;</code></h3>

	<p>Creates a submit button.<br />
When used as a container tag, a &#8220;button&#8221; element will be used instead of an &#8220;input&#8221; element.</p>

	<h4>Attributes:</h4>

	<ul>
		<li><code>label=&quot;text&quot;</code><br />
Text shown on the submit button. Default is &#8220;Send&#8221;.</li>
		<li><code>button=&quot;boolean&quot;</code><br />
<em>Deprecated. Use a container tag if you want a button element.</em></li>
	</ul>

	<h4>Examples</h4>

	<p>Standard submit button:</p>

<pre><code>&lt;txp:zem_contact_submit /&gt;
</code></pre>

	<p>Submit button with your own text:</p>

<pre><code>&lt;txp:zem_contact_submit label=&quot;Send&quot; /&gt;
</code></pre>

	<p>Usage as a container tag, which allows you to use Textpattern tags and <span class="caps">HTML</span> markup in the submit button:</p>

<pre><code>&lt;txp:zem_contact_submit&gt;&lt;strong&gt;Send&lt;/strong&gt; question&lt;/txp:zem_contact_submit&gt;
</code></pre>

<pre><code>&lt;txp:zem_contact_submit&gt;&lt;img src=&quot;path/to/img.png&quot; alt=&quot;submit&quot;&gt;&lt;/txp:zem_contact_submit&gt;
</code></pre>

	<p><a href="#top">Back to top</a></p>

	<h3 id="zc_select"><code>&lt;txp:zem_contact_select /&gt;</code></h3>

	<p>Creates a drop-down selection list.</p>

	<h4>Attributes</h4>

	<ul>
		<li><code>list=&quot;comma-separated values&quot;</code> <span class="required">required</span><br />
List of items to show in the select box.</li>
		<li><code>selected=&quot;value&quot;</code><br />
List item that is selected by default.</li>
		<li><code>label=&quot;text&quot;</code><br />
Text label displayed to the user. Default is <strong>Option</strong>.</li>
		<li><code>name=&quot;value&quot;</code><br />
Field name, as used in the <span class="caps">HTML</span> input tag.</li>
		<li><code>break=&quot;tag&quot;</code><br />
Break tag between the label and input field. Default is <code>&lt;br /&gt;</code>. Use <code>break=&quot;&quot;</code> to put the label and input field on the same line.</li>
		<li><code>delimiter=&quot;character&quot;</code><br />
Separator character used in the <strong>list</strong> attribute. Default is <strong>,</strong> (comma).</li>
		<li><code>required=&quot;boolean&quot;</code><br />
Whether a non-empty option must be selected. Available values: <strong>1</strong> (yes), <strong>0</strong> (no). Default is <strong>1</strong> (yes).</li>
	</ul>

	<h4>Examples</h4>

	<p>Select list labeled &#8216;Department&#8217;, containing three options and a blank option (due to the comma before &#8216;Marketing&#8217;) shown by default, forcing the user to make a selection.</p>

<pre><code>&lt;txp:zem_contact_select label=&quot;Department&quot; list=&quot;,Marketing,Sales,Support&quot; /&gt;
</code></pre>

	<p>Select list containing three options with &#8216;Marketing&#8217; selected by default.</p>

<pre><code>&lt;txp:zem_contact_select list=&quot;Marketing,Sales,Support&quot; selected=&quot;Marketing&quot; /&gt;
</code></pre>

	<p><a href="#top">Back to top</a></p>

	<h3 id="zc_checkbox"><code>&lt;txp:zem_contact_checkbox /&gt;</code></h3>

	<p>Creates a check box.</p>

	<h4>Attributes</h4>

	<ul>
		<li><code>label=&quot;text&quot;</code><br />
Text label displayed to the user. Default is <strong>Checkbox</strong>.</li>
		<li><code>name=&quot;value&quot;</code><br />
Field name, as used in the <span class="caps">HTML</span> input tag.</li>
		<li><code>break=&quot;tag&quot;</code><br />
Break tag between the label and input field. Default is <code>&lt;br /&gt;</code>. Use <code>break=&quot;&quot;</code> to put the label and input field on the same line.</li>
		<li><code>checked=&quot;boolean&quot;</code><br />
Whether this box is checked when first displayed. Available values: <strong>1</strong> (yes), <strong>0</strong> (no). Default is &#8220;0&#8221; (no).</li>
		<li><code>required=&quot;boolean&quot;</code><br />
Whether this checkbox must be filled out. Available values: <strong>1</strong> (yes), <strong>0</strong> (no). Default is <strong>1</strong> (yes).</li>
	</ul>

	<h4>Examples</h4>

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

<pre><code>&lt;txp:zem_contact_checkbox label=&quot;I accept the terms and conditions&quot; /&gt;
</code></pre>

	<p>Optional checkboxes:</p>

<pre><code>Select which operating systems are you familiar with:&lt;br /&gt;
&lt;txp:zem_contact_checkbox label=&quot;Windows&quot; required=&quot;0&quot; /&gt;&lt;br /&gt;
&lt;txp:zem_contact_checkbox label=&quot;Unix/Linux/BSD&quot; required=&quot;0&quot; /&gt;&lt;br /&gt;
&lt;txp:zem_contact_checkbox label=&quot;MacOS&quot; required=&quot;0&quot; /&gt;&lt;br /&gt;
</code></pre>

	<p><a href="#top">Back to top</a></p>

	<h3 id="zc_radio"><code>&lt;txp:zem_contact_radio /&gt;</code></h3>

	<p>Creates a radio button.</p>

	<h4>Attributes</h4>

	<ul>
		<li><code>group=&quot;text&quot;</code> <span class="required">required</span><br />
Text used in the email to describe this group of radio buttons. This attribute value is remembered for subsequent radio buttons, so you only have to set it on the first radio button of a group. Default is <strong>Radio</strong>.</li>
		<li><code>label=&quot;text&quot;</code> <span class="required">required</span><br />
Text label displayed to the user as radio button option.</li>
		<li><code>name=&quot;value&quot;</code><br />
Field name, as used in the <span class="caps">HTML</span> input tag. This attribute value is remembered for subsequent radio buttons, so you only have to set it on the first radio button of a group. If it hasn&#8217;t been set at all, it will be derived from the <code>group</code> attribute.</li>
		<li><code>break=&quot;tag&quot;</code><br />
Break tag between the label and field. Default is a space.</li>
		<li><code>checked=&quot;boolean&quot;</code><br />
Whether this radio option is checked when the form is first displayed. Available values: <strong>1</strong> (yes), <strong>0</strong> (no). Default is <strong>0</strong> (no).</li>
	</ul>

	<h4>Example</h4>

	<p>Group mutually exclusive radio buttons by setting the <code>group</code> 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 <strong>group: label</strong> for each of the chosen radio buttons.</p>

<pre><code>&lt;txp:zem_contact_radio label=&quot;Medium&quot; group=&quot;I like my steak&quot; /&gt;
&lt;txp:zem_contact_radio label=&quot;Rare&quot; /&gt;
&lt;txp:zem_contact_radio label=&quot;Well done&quot; /&gt;
</code>
<code>&lt;txp:zem_contact_radio label=&quot;Wine&quot; group=&quot;With a glass of&quot; /&gt;
&lt;txp:zem_contact_radio label=&quot;Beer&quot; /&gt;
&lt;txp:zem_contact_radio label=&quot;Water&quot; /&gt;
</code></pre>

	<p><a href="#top">Back to top</a></p>

	<h3 id="zc_secret"><code>&lt;txp:zem_contact_secret /&gt;</code></h3>

	<p>This tag has no effect on the form or <span class="caps">HTML</span> output, but will include additional information in the email. It can be used as a self-closing tag or as a container tag.</p>

	<h4>Attributes</h4>

	<ul>
		<li><code>name=&quot;text&quot;</code><br />
Used internally. Set this only if you have multiple &#8216;secret&#8217; form elements with identical labels.</li>
		<li><code>label=&quot;text&quot;</code><br />
Used to identify the field in the email. Default is <strong>Secret</strong>.</li>
		<li><code>value=&quot;value&quot;</code><br />
Some text you want to add to the email.</li>
	</ul>

	<h4>Examples</h4>

	<p>Usage as a self-closing tag</p>

<pre><code>&lt;txp:zem_contact_secret value=&quot;The answer is 42&quot; /&gt;
</code></pre>

	<p>Usage as a container tag</p>

<pre><code>&lt;txp:zem_contact_secret label=&quot;Dear user&quot;&gt;
  Please provide a useful example for this tag!
&lt;/txp:zem_contact_secret&gt;
</code></pre>

	<p><a href="#top">Back to top</a></p>

	<h3 id="zc_serverinfo"><code>&lt;txp:zem_contact_serverinfo /&gt;</code></h3>

	<p>This tag has no effect on the form or <span class="caps">HTML</span> output, but will include additional information in the email based on the <span class="caps">PHP</span> $_SERVER variable.</p>

	<h4>Attributes</h4>

	<ul>
		<li><code>name=&quot;value&quot;</code> <span class="required">required</span><br />
Name of the server variable. See the <a href="http://php.net/manual/reserved.variables.php#reserved.variables.server"><span class="caps">PHP</span> manual</a> for a full list.</li>
		<li><code>label=&quot;text&quot;</code><br />
Used to identify the field in the email. Defaults to the value of the <strong>name</strong> attribute.</li>
	</ul>

	<h4>Examples</h4>

	<p>Add the IP address of the visitor to the email</p>

<pre><code>&lt;txp:zem_contact_serverinfo name=&quot;REMOTE_ADDR&quot; label=&quot;IP number&quot; /&gt;
</code></pre>

	<p>Add the name of the visitor&#8217;s browser to the email</p>

<pre><code>&lt;txp:zem_contact_serverinfo name=&quot;HTTP_USER_AGENT&quot; label=&quot;Browser&quot; /&gt;
</code></pre>

	<p><a href="#top">Back to top</a></p>

	<h3 id="zc_send_article"><code>&lt;txp:zem_contact_send_article /&gt;</code></h3>

	<p>Use this tag in your individual article form, where you want the &#8220;send article&#8221; link to be displayed.</p>

	<h4>Attributes:</h4>

	<ul>
		<li><code>linktext=&quot;text&quot;</code><br />
Text displayed for the link. Default is <strong>send article</strong></li>
	</ul>

	<h4>Examples:</h4>

	<p>See <a href="#sendarticle">Getting started</a></p>

	<p><a href="#top">Back to top</a></p>

	<h2 id="advanced">Advanced examples</h2>

	<h3 id="show_error">Separate input and error forms</h3>

	<p>Using <code>show_input</code> and <code>show_error</code> 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).</p>

<pre><code>&lt;div id=&quot;error&quot;&gt;
  &lt;txp:zem_contact form=&quot;contact_form&quot; show_input=&quot;0&quot; /&gt;
&lt;/div&gt;
</code>
<code>&lt;div id=&quot;inputform&quot;&gt;
  &lt;txp:zem_contact form=&quot;contact_form&quot; show_error=&quot;0&quot; /&gt;
&lt;/div&gt;
</code></pre>

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

	<p><a href="#top">Back to top</a></p>

	<h3 id="subject_form">User selectable subject field</h3>

	<p>Specify the <code>subject_form</code> attribute and create a form which includes a <code>zem_contact_select</code> tag:</p>

<pre><code>&lt;txp:zem_contact to=&quot;you@example.com&quot; subject_form=&quot;my_subject_form&quot; /&gt;
  &lt;txp:zem_contact_text label=&quot;Name&quot; /&gt;&lt;br /&gt;
  &lt;txp:zem_contact_email /&gt;&lt;br /&gt;
  &lt;txp:zem_contact_select label=&quot;Choose Subject&quot; list=&quot;,Question,Feedback&quot; /&gt;&lt;br /&gt;
  &lt;txp:zem_contact_textarea label=&quot;Message&quot; /&gt;&lt;br /&gt;
&lt;/txp:zem_contact&gt;
</code></pre>

	<p>Create a Textpattern form called &#8220;my_subject_form&#8221;, containing:</p>

<pre><code>&lt;txp:php&gt;
  global $zem_contact_form;
  echo $zem_contact_form[&#39;Choose Subject&#39;];
&lt;/txp:php&gt;
</code></pre>

	<p>The <code>label</code> used in the <code>zem_contact_select</code> tag must be identical to the corresponding variable in the <code>subject_form</code>. Here we used <code>Choose subject</code>.</p>

	<p>If you&#8217;d prefer to add a common prefix for all subjects, use a <code>subject_form</code> containing:</p>

<pre><code>&lt;txp:php&gt;
  global $zem_contact_form;
  echo &#39;My common prefix - &#39; . $zem_contact_form[&#39;Choose Subject&#39;];
&lt;/txp:php&gt;
</code></pre>

	<p><a href="#top">Back to top</a></p>

	<h3 id="to_form">User selectable recipient, without showing email address</h3>

	<p>Specify the <code>to_form</code> attribute and create a form which includes a <code>zem_contact_select</code> tag:</p>

<pre><code>&lt;txp:zem_contact to_form=&quot;my_zem_contact_to_form&quot;&gt;
  &lt;txp:zem_contact_text label=&quot;Name&quot; /&gt;&lt;br /&gt;
  &lt;txp:zem_contact_email /&gt;&lt;br /&gt;
  &lt;txp:zem_contact_select label=&quot;Department&quot; list=&quot;,Support,Sales&quot; /&gt;&lt;br /&gt;
  &lt;txp:zem_contact_textarea label=&quot;Message&quot; /&gt;&lt;br /&gt;
&lt;/txp:zem_contact&gt;
</code></pre>

	<p>Create a Textpattern form called &#8220;my_zem_contact_to_form&#8221;, containing:</p>

<pre><code>&lt;txp:php&gt;
  global $zem_contact_form;
  switch($zem_contact_form[&#39;Department&#39;])
  {
    case &#39;Support&#39;:
      echo &#39;crew@example.com&#39;;
      break;
    case &#39;Sales&#39;:
      echo &#39;showmethemoney@example.com&#39;;
      break;
    default:
      echo &#39;someone@example.com&#39;;
  }
&lt;/txp:php&gt;
</code></pre>

	<p>The <code>label</code> used in the <code>zem_contact_select</code> tag must be identical to the corresponsing variable in the <code>to_form</code>. Here we used <code>Department</code>.</p>

	<p>A &#8216;default&#8217; email address in the <code>to_form</code> 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 <code>to_form</code>.</p>

	<p class="warning">Never use tags like <code>zem_contact_text</code>, <code>zem_contact_email</code> or <code>zem_contact_textarea</code> for setting the recipient address, otherwise your form can be abused to send spam to any email address!</p>

	<p><a href="#top">Back to top</a></p>

	<h2 id="styling">Styling</h2>

	<p>The form itself has a class <strong>zemContactForm</strong> set on the <code>FORM</code> <span class="caps">HTML</span> tag.</p>

	<p>The list of error messages (if any) has a class <strong>zemError</strong> set on the <code>UL</code> <span class="caps">HTML</span> tag that encloses the list of errors.</p>

	<p>All form elements and corresponding labels have the following classes (or ids set):
	<ol>
		<li>One of <strong>zemText</strong>, <strong>zemTextarea</strong>, <strong>zemSelect</strong>, <strong>zemRadio</strong>, <strong>zemCheckbox</strong>, <strong>zemSubmit</strong>. It should be obvious which class is used for which form element (and corresponding label).</li>
		<li><strong>zemRequired</strong> or <strong>errorElement</strong> or <strong>zemRequirederrorElement</strong>, depending on whether the form element is required, an error was found in whatever the visitor entered&#8230; or both.</li>
		<li>An individual &#8220;id&#8221; or &#8220;class&#8221; set to the value of the <code>name</code> attribute of the corresponding tag. When styling forms based on this class, you should explicitly set the <code>name</code> attribute because automatically generated names may change in newer zem_contact_reborn versions.</li>
	</ol></p>

	<p><a href="#top">Back to top</a></p>

	<h2 id="history">History</h2>

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

	<ul>
		<li>14 feb 2007: <strong>version 4.0.3.19</strong> <a href="http://forum.textpattern.com/viewtopic.php?id=21144">changelog</a>
	<ul>
		<li><a href="#sendarticle">send_article</a> functionality revised, requiring changes when upgrading from earlier versions</li>
		<li>New language strings: &#8216;send_article&#8217; and &#8216;recipient&#8217; (replaces &#8216;receiver&#8217;)</li>
		<li>Sets of radio buttons require the new <a href="#zc_radio">group</a> attribute</li>
		<li>Yes/No values deprecated in favor for the <span class="caps">TXP</span> standard 1/0 values (yes/no still work in this version)</li>
	</ul></li>
		<li>20 nov 2006: <strong>version 4.0.3.18</strong> <a href="http://forum.textpattern.com/viewtopic.php?id=19823">changelog</a>
	<ul>
		<li>IDs &#8216;zemContactForm&#8217; and &#8216;zemSubmit&#8217; have changed to classes to allow multiple forms per page</li>
		<li>New language strings: &#8216;form_used&#8217;, &#8216;invalid_utf8&#8217;, &#8216;max_warning&#8217;, &#8216;name&#8217;, &#8216;refresh&#8217;, &#8216;secret&#8217;</li>
	</ul></li>
		<li>12 mar 2006: <strong>version 4.0.3.17</strong> <a href="http://forum.textpattern.com/viewtopic.php?id=13416">changelog</a></li>
		<li>11 feb 2006: <strong>version .16</strong></li>
		<li>06 feb 2006: <strong>version .15</strong></li>
		<li>03 feb 2006: <strong>version .14</strong>
	<ul>
		<li>Requires separate zem_contact_lang plugin</li>
	</ul></li>
		<li>29 jan 2006: <strong>version .12</strong></li>
		<li>27 jan 2006: <strong>version .11</strong></li>
		<li>23 jan 2006: <strong>version .09 and .10</strong></li>
		<li>23 jan 2006: <strong>version .08</strong></li>
		<li>17 jan 2006: <strong>version .07</strong></li>
		<li>16 jan 2006: <strong>version .05 and .06</strong></li>
		<li>15 jan 2006: <strong>version .04</strong></li>
		<li>10 jan 2006: <strong>version .03</strong></li>
		<li>19 dec 2005: <strong>version .02</strong></li>
	</ul>

	<p><a href="#top">Back to top</a></p>

	<h2 id="credits">Credits</h2>

	<ul>
		<li><strong>zem</strong> wrote the zem_contact 0.6 plugin on which this plugin was initially based.</li>
		<li><strong>Mary</strong> completely revised the plugin code.</li>
		<li><strong>Stuart</strong> Turned it into a plugin, added a revised help text and additional code. Maintained all plugin versions till 4.0.3.17.</li>
		<li><strong>wet</strong> added the zem_contact_radio tag.</li>
		<li><strong>Tranquillo</strong> added the anti-spam <span class="caps">API</span> and zem_contact_send_article functionality.</li>
		<li><strong>aslsw66</strong>, <strong>jdykast</strong> and others (?) provided additional code</li>
		<li><strong>Ruud</strong> cleaned up and audited the code to weed out bugs and completely revised the help text. Maintainer of versions 4.0.3.18 and up.</li>
		<li>Supported and tested to destruction by the Textpattern community.</li>
	</ul>

	<p><a href="#top">Back to top</a></p>

	<h2 id="api">Zem Contact Reborn&#8217;s <span class="caps">API</span></h2>

	<p>The plugin <span class="caps">API</span> of zem contact, developed by Tranquillo, is similar to the comments <span class="caps">API</span> of Textpattern, which is explained in the Textbook <a href="http://textpattern.net/wiki/index.php?title=Plugin_Development_Topics">Plugin Development Topics</a> and <a href="http://textpattern.net/wiki/index.php?title=Combat_Comment_Spam">Combat Comment Spam</a>.</p>

	<p>Two callback events exist in zem_contact_reborn:
	<ul>
		<li><code>zemcontact.submit</code> is called after the form is submitted and the values are checked if empty or valid email addresses, but before the mail is sent.</li>
		<li><code>zemcontact.form</code> let&#8217;s you insert content in the contact form as displayed to the visitor.</li>
	</ul></p>

	<p>For reference here are the commands that will be interesting to plugin developers:</p>

<pre><code>// This will call your function before the form is submitted
// So you can analyse the submitted data
register_callback(&#39;abc_myfunction&#39;,&#39;zemcontact.submit&#39;);
</code>
<code>// This will call your function and add the output (use return $mystuff)
// to the contact-form.
register_callback(&#39;abc_myotherfunction2&#39;,&#39;zemcontact.form&#39;);
</code>
<code>// To get hold of the form-variables you can use
global zem_contact_form;
</code>
<code>// With the following two lines you can tell zem_contact if your
// plugin found spam
$evaluator =&amp; get_zemcontact_evaluator();
</code>
<code>// The passed value must be non-zero to mark the content as spam.
// Value must be a number between 0 and 1.
$evaluator -&gt; add_zemcontact_status(1);
</code></pre>

	<p>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.</p>

	<p><strong>An example of a plug-in connecting to Zem Contact Reborn&#8217;s <span class="caps">API</span>:</strong></p>

<pre><code>register_callback(&#39;pap_zemcontact_form&#39;,&#39;zemcontact.form&#39;);
register_callback(&#39;pap_zemcontact_submit&#39;,&#39;zemcontact.submit&#39;);
</code>
<code>function pap_zemcontact_form() {
  $field = &#39;&lt;div style=&quot;display:none&quot;&gt;&#39;.
    finput(&#39;text&#39;,&#39;phone&#39;,ps(&#39;phone&#39;),&#39;&#39;,&#39;&#39;,&#39;&#39;,&#39;&#39;,&#39;&#39;,&#39;phone&#39;).&#39;&lt;br /&gt;&#39;.
    finput(&#39;text&#39;,&#39;mail&#39;,ps(&#39;mail&#39;),&#39;&#39;,&#39;&#39;,&#39;&#39;,&#39;&#39;,&#39;&#39;,&#39;mail&#39;).&#39;&lt;/div&gt;&#39;;
  return $field;&lt;/code&gt;
}
</code>
<code>function pap_zemcontact_submit() {
  $checking_mail_field = trim(ps(&#39;mail&#39;));
  $checking_phone_field = trim(ps(&#39;phone&#39;));
</code>
<code>  $evaluation =&amp; get_zemcontact_evaluator();
</code>
<code>  // If the hidden fields are filled out, the contact form won&#39;t be submitted!
  if ($checking_mail_field != &#39;&#39; or $checking_phone_field != &#39;&#39;) {
    $evaluation -&gt; add_zemcontact_status(1);
  }
  return;
}
</code></pre>

	<p><a href="#top">Back to top</a></p>