Tell-A-Friend Form

The purpose of this tag is to display a form used to share an entry with someone by sending them an email about it. To show your tell-a-friend form use this tag pair:

{exp:email:tell_a_friend}

{/exp:email:tell_a_friend}

The tell-a-friend form is created pretty much like a normal form, only you don't specify the opening and closing form tags; ExpressionEngine takes care of those for you. There are also numerous possible variables that are available in order to auto-fill fields in the form, and also a few tag parameters to specify form handling and hidden recipients. Here's an example of how a tell-a-friend form could be created:

{exp:email:tell_a_friend charset="utf-8" allow_html='n'}

<p><label for="from">Your Email: </label><br />
<input type="text" id="from" name="from" size="40" maxlength="35" value="{member_email}" /></p>

<p><label for="name">Your Name: </label><br />
<input type="text" id="name" name="name" size="40" maxlength="35" value="{member_name}" /></p>

<p><label for="to">To: </label><br />
<input type="text" id="to" name="to" size="40" maxlength="35" /></p>

<p><label for="subject">Subject: </label><br />
<input type="text" id="subject" name="subject" size="40" value="Entry by: {author}" /></p>

<p><label for="message">Message: </label><br />
<textarea id="message" name="message" rows="18" cols="40">
{summary}
{body}
{permalink}
</textarea></p>

<p><input name="submit" type='submit' value='Submit Form' /></p>
{/exp:email:tell_a_friend}

Linking to the Tell-a-Friend page

In order to use the Tell-a-Friend feature, you will need to link to it. First, create a Template and place the Tell-a-Friend form in this Template.

You will then need to add a link to your new Tell-a-Friend Template from within your weblog entry. In your weblog tag {exp:weblog:entries} you can point to it using the permalink variable:

<a href="{permalink=weblog/friend}">Tell-a-Friend</a>

In the above example, the Template "friend" contains the Tell-a-Friend form.

Parameters

allow_html=

allow_html="y" allow_html="<p>,<a>" allow_html="n"

The weblog entry variables (see Weblog Variables below) are formatted according to the formatting specified when the entry was submitted, so there is a possibility of HTML being output. This parameter allows you the choice of whether to keep the HTML in the form fields, allow only certain HTML tags (by specifying the tags as a comma-separated list), or allow no HTML to remain. If HTML is left in, then the email will be automatically sent as an HTML email.

charset=

charset="utf-8"

This allows you to set the character set of the email being sent. Use this if you form's template is using a character set other than iso-8859-1.

recipients=

recipients="admin@example.com"

You may specify hidden recipients for the form. This is who will receive the submitted information. You may specify more than one recipient by separating the email addresses with commas:

recipients="admin@example.com,ceo@example.com,president@example.com"

return=

return="http://www.example.com/index.php"

This parameter lets the admin specify to where the user is directed after the form is submitted. Upon submission, the user is presented with a standard "thank you" message and a link. The return parameter lets the location for the link be specified.

Variables

member_email

{member_email}

If a user is logged in, then it will display their email address as recorded in their member profile.

member_name

{member_name}

If a user is logged in, then it will display their screen name as recorded in their member profile.

Weblog Variables

{title}
{permalink}
{author}
{body}
et cetera...

Many of the Weblog Entries Tag Variables are available for the tell-a-friend form. Notable exceptions are all category related variables and custom member fields.

Note: To ease the useability of this form with multiple weblogs, which will possibly contain different custom fields, all Weblog Variables that are unfillable will be removed from the form.

For example, if you have a weblog with custom fields of summary and body, and then another weblog with custom fields of ingredients and directions, you will be able to put the following in the 'message' textarea: {summary} {body} {ingredients} {directions}. If an entry linking to the tell-a-friend form is from weblog one, then the first two custom fields will be filled and the second two will be ignored. If an entry from weblog 2 is linking to the tell-a-friend form, then the first two will be ignored and the second two will be filled out.

Form Fields

from

<input type="text" name="from" size="40" />

Email address of person who is sending the email.

message

<textarea name="message" rows="10" cols="40"></textarea>

Main message of the email. If you do not wish to have the tell-a-friend message modified then we suggest using a hidden form field or setting the textarea as read only (ex: <textarea readonly="readonly"></textarea>). You must include this form field, even if it is just a hidden field.

name

<input type="text" name="name" size="40" />

Name of person who is sending the email.

required

<textarea name="required" rows="5" cols="40" readonly="readonly"></textarea>

Field allows you to have required information that is included at top of each email message. Useful for support emails where the information can be read only or hidden.

subject

<input type="text" name="subject" size="40" />

Subject of the email that is being sent. You must include this form field, even if it is just a hidden field.

to

<input type="text" name="to" size="40" />

Email address to which the email is being sent. Multiple email addresses may be specified by separating them with a comma. You must include this form field, even if it is just a hidden field. This data may also be specified with the recipients= parameter of the tag.