File size: 14.09Kb
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>eForm example</title>
<style type="text/css">
*{
font-family:arial, helvetica, sans-serif;
font-size:10pt;
border-width:1px;
border-color:#003399;
}
body{
background-color:#a4d1f9;
}
h1, h2, h3{
margin-bottom:0;
color:#003399;
}
h1{
margin-top:0;
margin-bottom:20px;
font-size:20pt;
text-align:center;
border-bottom-style:solid;
border-color:#e78900;
}
h2{
font-size:12pt;
}
hr{
color:#ffffff;
border-style:none none solid none;
border-color:#e78900;
}
p{
margin-top:0;
}
ul{
margin:0 0 0 10px;
padding:0;
list-style-type:square;
}
code{
font-family:monospace;
color:#666666;
}
a{
color:#e78900;
text-decoration:none;
}
a:hover{
border-bottom-style:dashed;
}
#qe_logo{
float:right;
margin:0 57px 20px 57px;
}
#qe_toc{
width:200px;
margin:0 0 20px 20px;
padding:20px;
float:right;
clear:right;
border-style:solid;
background-color:#eaf9ff;
}
#qe_toc h1{
margin-top:0;
font-size:12pt;
text-align:center;
}
div.qe_box{
margin:30px;
padding:30px;
border-style:solid;
background-color:#ffffff;
}
div.qe_level_2{
margin-left:20px;
margin-right:20px;
}
.qe_salutation{
margin-left:30px;
}
.qe_signature{
font-family:cursive;
font-size:14pt;
}
.qe_param_list li{
margin:2px;
color:#333;
}
.qe_param_list li strong{
color:#036;
font-size:1.02em
}
.new{
color:#c00;
font-weight:bold;
}
.codeblock{
margin:10px 0;
padding:5px;
background:#eaeaea;
border:1px solid #999;
font-family:monospace;
white-space: nowrap;
overflow: auto;
max-height: 24em;
clear:right;
}
.qe_param_list li{
margin:2px;
color:#333;
}
.qe_param_list li strong{
color:#036;
font-size:1.02em
}
.new{
color:#c00;
font-weight:bold;
}
.style1 {font-size: smaller}
</style>
</head>
<body>
<div class="qe_box">
<h1>eForm - Examples</h1><img id="qe_logo" src="logo.png" alt="logo" />
<div id="qe_toc">
<h1>Index</h1>
<ul>
<li><a href="eform.htm#top">Main index</a></li>
<li><a href="eform_examples.htm">Examples</a>
<ul>
<li><a href="eform_examples.htm#top">Feedback Form</a></li>
<li><a href="eform_example_multiple_forms.htm">Multiple forms</a></li>
<li><a href="eform_example_events.htm">eForm events</a></li>
</ul>
</li>
</ul>
</div>
<div class='qe_level_1'>
<h2>Creating a general purpose feedback form</h2>
<p>For this example we're creating a feedback form where web site users can send feedback to three different departments or email addresses. This is achieved trough the subject selectbox which will be used by eForm to select the correct email address. All fields will be required and to avoid any spamming by automated submit scripts were also adding a <abbr title="Completely Automated Public Turing Test to Tell Computers and Humans Apart">CAPTCHA</abbr> field. When users succesfully have submitted the form they will be presented with a thank you message which includes a copy of what the user submitted.</p>
<p>To achieve this we firstly need to create the following '<em>templates</em>' either as chunks or in (unplished) MODx documents.</p>
<ul>
<li><a href="#html">The HTML Form</a></li>
<li><a href="#email">The body of the email</a></li>
<li><a href="#thankyou">The thank you page</a></li>
</ul>
<p><br />And offcourse we need to place the <a href="#snippetcall">snippet call</a> on our feedback page. The form will look something like this (after some styling)</p>
</div>
<div class='qe_level_2'>
<h3>The form</h3>
<p><img src="form1.gif" width="404" height="317" alt="Exampel form" border="1" title="" /></p>
<a id="html" name="html"></a>
<h3>The HTML Form Template</h3>
<p>For this example we will create a chunk called '<em>eFeedBackForm</em>' and copy and paste the following form</p>
<div class='codeblock'>
[+validationmessage+]<br />
<form method="post" action="[~[*id*]~]"><br /> <input type="hidden" name="formid" value="feedbackForm" /><br /> <br /> <p><label accesskey="n" for="Name">Your Name</label><br />
<input type="text" name="Name" maxlength="60" eform="Your
Name::1:Expected at least two words:#REGEX /^\w+\s\w+/i" /></p><br />
<br /> <p><label accesskey="e" for="email">Your Email Address</label><br /> <input type="text" name="email" size="40" maxlength="40" eform="Your Email Address:email:1" /></p><br /> <br /> <p><label accesskey="s" for="department">Subject</label><br /> <select name="department"><br /> <option value="1">Website feedback</option><br /> <option value="2">Support request</option><br /> <option value="3">Feature request</option><br /> </select></p><br /> <br /> <p><label accesskey="c" for="comments">Comments</label><br /> <textarea cols="40" rows="10" name="comments" eform="Comments:html:1"></textarea></p><br /><br /> <p><br /> Please enter the anti spam code below:<br /><br /> <img src="[+verimageurl+]" alt="verification code" border="1"/><br /> </p><br /> <p><br /> <label accesskey="c" for="vericode">code</label><br /> <input type="text" name="vericode" size="20" /><br /> </p><br /> <br /> <p><input type="submit" name="submit" value="Send Feedback"></p><br /></form> </div>
<a id="formid" name="formid"></a>
<p>A fairly straight forward html form with some placeholders for error messages and the vericode (CAPTCHA). Note the <code>formid</code> field. This hidden field is required so that eForm can recognize the form. We'll get back to that later at the <a href="#snippetcall">snippet call</a>.</p>
<p>The required fields have formatting and validations options set using the <code>eform</code> pseudo attribute (See the <a href="eform_validation.htm">form validation page</a> for details on setting values for the <code>eform</code> attribute) The eform attribute will be stripped from the form before it is sent to the browser.</p>
<p>The <code>[+validationmessage+]</code> placeholder will be filled with an error message if the form submit was unsuccesful. Below is an example message:</p>
<p style="color:red">Some errors were detected in your form:<br />
The following required field(s) are missing: Your Name, Comments<br />
Your Email Address is not a valid email address</p>
<p><strong>Note!</strong> In the above template we use a hidden field for the formid: <code><input type="hidden" name="formid" value="feedbackForm" /></code><br />
If you are using eForm 1.4+ you can instead use the <strong>id</strong> attribute
of the form tag itself and leave out the hidden field: <code><form id="feedbackForm" method="post" action="[~[*id*]~]"></code>.
Either way will work
</p>
<a id="email" name="email"></a>
<h3>The email template</h3>
<p>We'll create another chunk for the body of the email and call this one '<em>eFeedbackReport</em>'</p>
<div class='codeblock'>
<p>This is a response sent by [+name+] using the feedback form on the website. The details of the message follow below:</p><br /><table><br /><tr valign="top"><td>Name:</td><td>[+name+]</td></tr><br /><tr valign="top"><td>Email:</td><td>[+email+]</td></tr><br /><tr valign="top"><td>comments:</td><td>[+comments+]</td></tr><br /></table><br /><p>You can use this link to reply: <a href="mailto:[+email+]?subject=RE:[+subject+]">[+email+]</a></p><br /><br />
</div>
<p>As you can see you can use HTML markup in your email. Using placeholders for each field we can populate the email with all information from the submitted form. Placeholders must have the same name as the name used for the from field.</p>
<a id="thankyou" name="thankyou"></a>
<h3>The Thank you message</h3>
<p>The same recipe... another chunk, called '<em>eFeedBackThanks</em>' this time</p>
<div class='codeblock'>
<h3>Thank you for your feedback</h3><br /><p>We know how you appreciate our ongoing efforts and thank you for your praise.<br />We will take any suggestions you may have made to heart and will endeavor to <br />respond to you in a timely manner. However as all office staff is attending<br />our 4 week annual company retreat, this year held in the Costa Del Sol, we ask<br />for your patience.</p><br /><p>Below is a copy of your message:</p><br /><table><br /><tr><td>Your name:</td><td>[+name+]</td></tr><br /><tr><td>Your email address</td><td>[+email+]</td></tr><br /><tr valign="top"><td>Your comments</td><td>[+comments+]</td></tr><br /></table><br />
</div>
<p>The thank you template can be used to present the web site user with a more comprehensive follow up after thay have submitted the form and can contain the same placeholders as used in the report template.</p>
<a id="snippetcall" name="snippetcall"></a>
<h3>The Snippet call</h3>
<div class='codeblock'>
[!eForm? &formid=`feedbackForm` &to=`info@some.domain.com,support@some.domain.com,requests@some.domain.com` &tpl=`eFeedBackForm` &report=`eFeedbackReport` &thankyou=`eFeedbackThanks` &mailselector=`department` &vericode=`1` &subject=`Web site feedback`!]<br />
</div>
<p>You should have all paramters on one line but just to make things a bit more readable below is a slightly more verbose printout.</p>
<div class='codeblock'>
[!eForm?<br />
&formid=`feedbackForm` <br />
&to=`info@some.domain.com,support@some.domain.com,requests@some.domain.com` <br />
&tpl=`eFeedBackForm` <br />
&report=`eFeedbackReport` <br />
&thankyou=`eFeedbackThanks` <br />
&mailselector=`department` <br />
&vericode=`1` <br />
&subject=`Web site feedback`<br />
!]
</div>
<p>I'll go through them one by one</p>
<ul>
<li><code>&formid=`feedbackForm</code><br />
This tells eForm which form it should process. The form must contain a hidden <code>formid</code> field with the same value. (You did read that <a href="#formid">note</a> didn't you?)
</li>
<li><code>&to</code><br />
Here we have the three email addresses of which one can be selected in the form using the <code>department</code> select box. See the <code>&mailselector</code> below.
</li>
<li><code>&tpl</code><br />
The name of the chunk with the form template we created</li>
<li><code>&report</code><br />
The name of the chunk with the email template
</li>
<li><code>&thankyou</code><br />
Yes,... you guessed it.
</li>
<li><code>&mailselector</code><br />
This contains the name of the <code>department</code> field which we use to select the email address to use. Note the option values of the <code>department</code> select box in the form. They are 1,2 and 3. The value returned from this field will select one of the addresses we just declared in the <code>&to</code> parameter.1 will select the first address, 2 the second and so on.
</li>
<li><code>&vericode</code><br />
When you add the <code>&vericode=`1`</code> parameter to the snippet call eForm will replace the <code>[+verimageurl+]</code> placeholder in the form with a CAPTCHA generated image. On submitting the form the <code>vericode</code> field is then validated against the text displayed in the image.
</li>
<li><code>&subject</code><br />
This will be used as the subject of the email.
</li>
</ul>
<p><br /><strong>That's it,.. have fun.</strong></p>
<h3>Using chunks, snippets or documents for eForm templates</h3>
<p>Although we have been using chunks for this example you can just as easily
use documentsor even snippets for each template.<br />
In the case of a document
you would pass the document id to eForm, for example <code>&tpl=`31`</code>. <span class="style1">(There is a catch however when you are using the tinyMCE editor. TinyMCE cleans
HTML from what it considers invalid attributes and thus will strip the <code>eform</code> attribute
from your form. If you want to place your form in a document instead of a chunk
make sure you don't use the TinyMCE editor for that document.)<br />
</span>Using a snippet as your template source gives you even more flexibility.
You can dynamically create options and fields, however you must make sure
that the snippet returns the same form template between form submits as otherwise
eForm's validation code may incorrectly evaluate invalid values.<span class="style1"> If for instance
you have a select box with the options values 1,2 & 3 (from a database for
instance) at the first pass and when those values have changed to
2,3 & 4 by the time the form is submitted (and the template retrieved a
second time with the changed values), eform will see a submitted
value of 1 as invalid...</span></p>
<p><em>There is a way to add the eform as a valid attribute to tinyMCE but you'll have to dig into the tinyMCE plugin code to do that. However that's beyond the scope of this article.</em></p>
<hr />
<p ><span class='qe_signature'>Jelle Jager</span><br />
AKA TobyL<br />
(and no,.. don't try to pronounce it)
</p>
</div>
</div>
</body>
</html>