Use of the SmtpPlus Forms Extension


When using SmtpPlus Forms skills in PHP programming and knowledge on the structure of Magento and its Framework are required to make full use of the capabilities of this Extension.



For all of the following documentation you may use the following default template files - being delivered with SmtpPlus Forms as reference, or as starting point for your own form creations:

New Product Question

  • Form Template: app/design/frontend/default/default/smtpplus/forms/productquestion.phtml
  • Email Template (Form Email): app/locale/en_US/template/email/smtpplusforms/new_product_question.html
  • Email Template (Confirmation Email): app/locale/en_US/template/email/smtpplusforms/confirmation_product_question.html



The following shows the related source to this form, for reference and insight. The related template is part of the installation package of this extensions and may get used for any of your own form creations as a starting point or reference:

Template Source Code for this form (as included in the Installation Package)

<?php
/**
 * Smtpplus Forms Block
 *
 * @category    Pisc
 * @package     Pisc_SmtpplusForms
 * @author      PILLWAX Industrial Solutions Consulting <technology.license@pillwax.com>
 * @version	  0.1.0
 */
 
/**
 * @see Pisc_SmtpplusForms_Block_Form
 */
 
// Get prepared data for Form
$data = $this->getFormData();
// Get Product from prepared data
$product = $data->getProduct();
// Get Customer from perpared data
$customer = $data->getCustomer();
// Get Store Email Address for Identity 'general'
$storeEmail = $this->getStoreEmailAddress('general');
 
// This flag is set to TRUE if the previous Form Post has been submitted
if ($this->getOption('form_submit_success', false)) {
	// Clear Form data from previous post
	$this->clearFormPost();
}
// Retrieving form data from the previous post on this form in the current session
$formData = $this->getFormPost('form');
 
/*
 * The following is to set Options for this Form without presenting them in the <FORM> content.
 * These Options are stored in the Session data of the current session.
 */
// Disregard to check the FormKey
$this->setOption('formKey', false);
 
// Setting the URL of the referring page
$this->setOption('referer_url', $this->getFormData()->getReferer());
 
// Where to redirect and what message to show if Form has successfully sent
$this->setOption('success', Array(
	  // Where to redirect in case of sucess, to redirect back to this form set to empty string
	  'url' => $this->getFormData()->getReferer(),
	  // Message to show
	  'message' => 'Thank you, your question has been submitted to us.'
	));
 
// Where to redirect and what message to show in case of error
$this->setOption('error', Array(
	  // Where to redirect in case of sucess, to redirect back to this form set to empty string
	  'url' => '',
	  // Message to show
	  'message' => 'Sorry, there has been a difficulty submitting your question to us. Please try again later.'
	));
 
// REQUIRED: Where to send the Forms content
$this->setOption('email', Array(
	  // REQUIRED: Set the Sender Email for this Form. Use Store Email Address Accounts ONLY: 'general', 'sales', 'support', 'custom1', 'custom2'
	  'sender' => Array('address'=>'general'),
	  // REQUIRED: Set the Recipient Email Address and Name for this Form. Use a Store Email Address Account, fully qualified Email Address, or the Name of the Form field to use
	  'recipient' => Array('address'=>'general', 'name'=>''),
	  // OPTIONAL: Set a Reply-To Address. Use fully qualified Email Address, or the Name of the Form field to use, or a Store Email Address Account as above.
	  'replyto' => Array('address'=>'form[email]'),
	  // Set the ID (or Name) of the Transactional Email Template to use
	  'template' => Array('id'=>null, 'name'=>'smtpplusforms_new_product_question')
	));
 
 
// OPTIONAL: If wanting to send a confirmation email to customer or someone else. Most individual settings are same as for Form Email above
$this->setOption('confirmation', Array(
	  // Set to TRUE to send confirmation Email, FALSE if not
	  'email' => false,
	  // Set to TRUE if to send Attachments also
	  'attachments' => false,
	  'sender' => Array('address'=>'general'),
	  'recipient' => Array('address'=>'form[email]', 'name'=>'form[name]'),
	  'replyto' => Array('address'=>'general'),
	  'template' => Array('id'=>null, 'name'=>'smtpplusforms_confirmation_product_question')
	));
 
?>
 
<?php
	$storeId = Mage::app()->getStore()->getId();
	$visibility = array(
	               Mage_Catalog_Model_Product_Visibility::VISIBILITY_BOTH,
	               Mage_Catalog_Model_Product_Visibility::VISIBILITY_IN_CATALOG
	            );
	$collection = Mage::getModel('catalog/product')
	        ->setStoreId($storeId)
	        ->getCollection()
	        ->addAttributeToFilter('visibility', $visibility)
	        ->addAttributeToSort('name', 'asc');
 
	$products = Array();
	foreach ($collection as $entry) {
	  $products[] = $entry->getName();
	}
 
	$countries = Mage::app()->getHelper('smtpplusforms')->getCountryCallingCodes();
 
?>
 
<?php echo $this->getMessagesBlock()->getGroupedHtml() ?>
 
<div class="page-head">
	  <h3><?php echo $this->__('I have a Question about:')." ".$product->getName();?></h3>
</div>
<form action="<?php echo $this->getFormAction(); ?>" id="productquestionForm" method="post">
	<input type="hidden" name="formName" value="<?php echo $this->getFormName() ?>">
	<input type="hidden" name="formKey" value="<?php echo $this->getFormKey() ?>">
 
	<input type="hidden" name="form[product_id]" value="<?php echo $product->getId() ?>">
 
	<div class="head-alt2">
	    <h4 class="title"><?php echo $this->__('Ask a Question') ?></h4>
	</div>
	<fieldset class="group-select">
	  <ul>
	  <li>
	     <div class="input-box">
	      <label for="form[name]"><?php echo $this->__('Name') ?> <span class="required">*</span></label><br />
	      <?php $value = trim($customer->getName()); if (empty($value)) { $value = $this->getValue($formData,'name',''); } ?>
	      <input name="form[name]" id="name" title="<?php echo $this->__('Name') ?>" value="<?php echo $this->htmlEscape($value) ?>" class="required-entry input-text" type="text" />
	    </div>
 
	    <div class="input-box">
	      <label for="form[email]"><?php echo $this->__('Email') ?> <span class="required">*</span></label><br />
	      <?php $value = $customer->getEmail(); if (empty($value)) { $value = $this->getValue($formData,'email',''); } ?>
	      <input name="form[email]" id="email" title="<?php echo $this->__('Email') ?>" value="<?php echo $this->htmlEscape($value) ?>" class="required-entry input-text validate-email" type="text" />
	    </div>
 
	    <div class="clear" style="margin-bottom:15px"></div>
 
	    <div class="input-box">
	      <label for="form[telephonecountrycode]"><?php echo $this->__('Telephone (Country Code)') ?></label><br />
	      <select name="form[telephonecountrycode]">
	        <option value=""><?php echo $this->__('-- Please select your Country --')?></option>
	        <?php
	          $selected = $this->getValue($formData, 'telephonecountrycode');
	          foreach ($countries as $id=>$value) {
	            $option = $value['name'].' (+'.$value['calling_code'].')';
	            if ($option==$selected) {
	              echo '<option selected="selected">'.$option.'</option>';
	            } else {
	              echo '<option>'.$option.'</option>';
	            }
	          }
	        ?>
	      </select>
	    </div>
 
	    <div class="input-box">
	      <label for="form[telephone]"><?php echo $this->__('Telephone (Number)') ?></label><br />
	      <input name="form[telephone]" id="telephone" title="<?php echo $this->__('Telephone') ?>" value="<?php echo $this->getValue($formData,'telephone',''); ?>" class="input-text" type="text" />
	    </div>
 
	    <div class="clear" style="margin-bottom:15px"></div>
 
	    <div class="input-box">
	      <label for="form[product]"><?php echo $this->__('Product related to this Question') ?> <span class="required">*</span></label><br />
	      <select name="form[product]" class="validate-select">
	        <option value=""><?php echo $this->__('-- Please select the related Product --')?></option>
	        <?php
	          $selected = $this->getValue($formData, 'product', $product->getName());
	          foreach ($products as $value) {
	            if ($value==$selected) {
	              echo '<option selected="selected">'.$value.'</option>';
	            } else {
	              echo '<option>'.$value.'</option>';
	            }
	          }
	        ?>
	      </select>
	    </div>
 
	    <div class="clear" style="margin-bottom:15px"></div>
 
	    <div class="input-box">
	      <label for="form[comment]"><?php echo $this->__('What is your question to us?') ?> <span class="required">*</span></label><br />
	      <textarea name="form[comment]" id="comment" title="<?php echo $this->__('Question') ?>" class="required-entry input-text" style="height:150px;width:525px;" cols="50" rows="5"><?php echo $this->getValue($formData,'comment',''); ?></textarea>
	    </div>
	  </li>
	  </ul>
	</fieldset>
	<div class="button-set">
	  <p class="required"><?php echo $this->__('* Required Fields') ?></p>
	  <input class="button" type="submit" value="<?php echo $this->__('Submit') ?>" />
	</div>
</form>
<script type="text/javascript">
	  var contactForm = new VarienForm('productquestionForm', true);
</script>



For creating a Link to this form in your frontend pages you may:

  • Include the link in your pages template file:

Creating a link to this form in your page templates

<a href="<?php echo $this->helper('smtpplusforms')->getFormUrl('productquestion', Array('product'=>$this->getProduct()->getId())); ?>">
   <?php echo $this->__('I have a Question about this Product'); ?>
</a>


  • Create the link through the Layout definition files:

Using the Link Block in your Layout definition

<block type="smtpplusforms/form" name="smtpplus_forms_link_productquestion" template="smtpplus/forms/links/productquestion.phtml" />


Please also see the Helper Functions for use on the Frontend Pages for a overview of Helper Functions available to all frontend page template files.

The Transactional Email created by this Form may look like this (using the default template):



New Support Question

  • Form Template: app/design/frontend/default/default/smtpplus/forms/gethelp.phtml
  • Email Template (Form Email): app/locale/en_US/template/email/smtpplusforms/new_support_question.html
  • Email Template (Confirmation Email): app/locale/en_US/template/email/smtpplusforms/confirmation_support_question.html


For creating a Link to this form in your frontend pages you may:

  • Include the link in your pages template file:

Creating a link to this form in your page templates

<a href="<?php echo $this->helper('smtpplusforms')->getFormUrl('gethelp', Array('product'=>$this->getProduct()->getId())); ?>">
   <?php echo $this->__('I need help on this Product'); ?>
</a>


  • Create the link through the Layout definition files:

Using the Link Block in your Layout definition

<block type="smtpplusforms/form" name="smtpplus_forms_link_gethelp" template="smtpplus/forms/links/gethelp.phtml" />


Please also see the Helper Functions for use on the Frontend Pages for a overview of Helper Functions available to all frontend page template files.

When using SmtpPlus Forms then there are some naming conventions to be followed:

Give every Form a unique Name

Every Form you create with SmtpPlus Forms has to have a unique name. The following names are already taken by the default Forms coming with the SmtpPlus Forms installation package:

  • productquestion - The form for submitting a Question about a Product
  • gethelp - The form for submitting a Support Request on a Product
  • support - Refrain from using this Form Name. During development of this extension we learned that Magento is not fully loading the layout definitions when using support as a Form Name.


In the following we will refer to this Form Name as form name.

Store URLs for Forms

SmtpPlus Forms does automatically resolve a store URL to the related Form Template:

http://www.yourstore.tlc/contact/form/<formname>

Example URL for Form 'productquestion'

http://www.yourstore.tlc/contact/form/productquestion


<formname> in the URL refers to the Name of the Form to be used. If omitted, or a undefined form name is used, the template page smtpplus/forms/index.phtml will be used.

The default Route for SmtpPlus Forms is contact. To change this modify the extensions config.xml in app/code/local/Pisc/SmtpplusForms/etc:

<frontend>
       <routers>
           <smtpplusforms>
               <use>standard</use>
               <args>
                   <module>Pisc_SmtpplusForms</module>
                   <!-- Default Route is 'contact': http://www.yourstore.tlc/contact/form/<yourform> -->
                   <!-- Modify the FrontName if desired -->
                   <frontName>contact</frontName>
               </args>
           </smtpplusforms>
       </routers>
</frontend>



Template Blocks and Layout directives

Every Form may get used as a Block in the layout definition files, located in your template directory design/frontend/default/…/layout. Important is that the name, assigned to a Form Block, has to include the form name: smtpplus_forms_<formname>

<block type="smtpplusforms/form" name="smtpplus_forms_<formname>" template="smtpplus/forms/<formtemplate>.phtml" />

Example for Form 'productquestion'

<block type="smtpplusforms/form" name="smtpplus_forms_productquestion" template="smtpplus/forms/productquestion.phtml" />



You may put your Forms Block anywhere into the layout definition files of your template.

Alternatively, when using dedicated pages for one or all of your forms, you may create a layout definition file smtpplusforms_local.xml to put your own form layouts into. This layout definition file will not get overwritten by any updates of the extension. See Creating a new Form for a example on this.

Form Fields

Used in the Frontend Form

For any form field, that you want to use in the related Transactional Email, it needs to be in the Array forms[]:

<!-- Example of simple form fields with single values -->
<input name="form[name]" id="name" value="" class="required-entry input-text" type="text" />
<input name="form[email]" id="email" value="" class="required-entry input-text" type="text" />
 
<!-- Example of multiple option select field -->
<select multiple="multiple" name="form[options][]">
<option value="Option 1">Option 1</option>
<option value="Option 2">Option 2</option>
<option value="Option 3">Option 3</option>
<option value="Option 4">Option 4</option>
</select>


For any file attachments, where you want your form users to allow to upload a file, and which you want to have as Attachments in the related Transactional Email, it needs to be in the Array attachments[]:

<input name="attachments[]" id="attachments" type="file" size="70" class="input-text" />



There are some hidden form fields to be required in any of your Form templates:

Required form fields

// This hidden form field holds the current form name
<input type="hidden" name="formName" value="<?php echo $this->getFormName() ?>">
 
// This hidden form fields holds the current form security key
<input type="hidden" name="formKey" value="<?php echo $this->getFormKey() ?>">



Used in the Transactional Emails

For the transactional Emails the Form Fields form[<index>] from the frontend form are accessible as variables with the name of form.<index> in the template of the Transactional Email:

Translation of Form Fields to Email Template variables

Form Name  >>  Email Template Variable
form[name]     {{var form.name}}
form[email]    {{var form.email}}

Example of a template for the Transactional Email

<!-- Form field 'form[name]' -->
<p><u>From:</u>&nbsp;{{var form.name}}</p>
 
<!-- Form field 'form[telephone]' -->
<p><u>Phone:</u>&nbsp;{{var form.telephone}}</p>
 
<!-- Form field 'form[email]' -->
<p><u>Email:</u>&nbsp;<a href="mailto:{{var form.email}}">{{var form.email}}</a></p>
 
<!-- Form field 'form[options]' requires a helper block - see below for more -->
{{layout handle="smtpplusforms_email_multiselect" form=$form}}


Any file uploaded by form fields with the name of attachments[] will be added as Attachment to the Transactional Email automatically.

Option field with multiple select

To add the selected options from multiple select option fields to the transactional email, a helper block is required:

For each multi-select option field there is a helper block required to be defined in the page layout file. You may copy the below default layout block and assign it another unique name to be used in the email template.
You may also need to copy the default template file to a new template file where the related output is being created for the option field to be included into the final email content:

app/design/frontend/...your-template.../layout/smtpplusforms.xml

<!--
   Default Email Block for Multi-Select Options, use the following in the related email template to use:
   {{layout handle="smtpplusforms_email_multiselect" form=$form}}
-->
<smtpplusforms_email_multiselect>
    <block type="smtpplusforms/email" name="smtpplus_forms_email_multiselect" template="smtpplus/forms/email/multiselect.phtml" />
</smtpplusforms_email_multiselect>
 
<!--
   Customized for another multi-select, use the following in the email template to use:
   {{layout handle="smtpplusforms_email_form_option" form=$form}}
-->
<smtpplusforms_email_form_option>
    <block type="smtpplusforms/email" name="smtpplus_forms_email_multiselect" template="smtpplus/forms/email/form_option.phtml" />
</smtpplusforms_email_form_option>


The related template file then is to be used for preparing the related output into the transactional email content:

app/design/frontend/...your-template.../template/smtpplus/forms/email/multiselect.phtml

<?php
// Configure the name of the Multiselect Field here...
$multiSelectFieldName = "options";
 
$options = $this->getForm()->getData($multiSelectFieldName);
 
if (is_array($options)) {
	foreach ($options as $option) {
	  echo '<p>'.$option.'</p>';
	}
}



Defining the Layout

Put the layout definition of your new form into smtpplusforms_local.xml in your frontend layout directory app/design/frontend/default/…/layout:

  • The following shows the definition of a form called 'Example'.
  • The Layout section for this form is therefore per convention <smtpplusforms_form_example>
  • The Layout Name of the form is per convention “smtpplus_forms_example”
  • The Template file for this form is choosen as smtpplus/forms/example.phtml


Example for custom layout definition file 'smtpplusforms_local.xml'

<?xml version="1.0" encoding="UTF-8"?>
<layout version="0.1.0">
 
    <default>
        <reference name="head">
           <!-- Example: Adding a CSS file to Header -->
           <action method="addCss"><stylesheet>css/some.css</stylesheet></action>
	</reference>
    </default>
 
<!-- A Form we name 'example', is accessible via URL http://www.yourstore.tlc/contact/form/example -->
    <smtpplusforms_form_example>
        <remove name="left"/>
        <reference name="root">
            <action method="setHeaderTitle" translate="title" module="smtpplusforms"><title>Example Form</title></action>
            <action method="setTemplate"><template>page/1column.phtml</template></action>
        </reference>
        <reference name="content">
            <block type="smtpplusforms/form" name="smtpplus_forms_example" template="smtpplus/forms/example.phtml" />
        </reference>
    </smtpplusforms_form_example>
 
</layout>



Alternatively you may put the Block smtpplusforms/form anywhere into your other layout definition files, see also Template Blocks and Layout Directives. We suggest to put any full page form into your smtpplusforms_local.xml file.

Creating the Form Template

The template file for any of your forms is to be stored in the template directory of your Frontend Template in app/design/frontend/default/…/template/smtpplus/forms:

  • A Form template is the same as a page template, use the extension .phtml
  • You may access all of the Magento Objects and Models to create your forms appearance and data
  • To control the behavior of your form, set the options for the form as described in Getting and Setting of Form Data and Options
  • Take a view into the forms productquestion.phtml and gethelp.phtml that come with the SmtpPlus Forms installation package as guidance and example for creating your own forms



Creating the Template for the Transactional Email

To create a template for the Transactional Email, that is created from the Form template, you may use one of the default email templates coming with SmtpPlus Forms as your starting point:

  • New Product Question
  • New Support Question
  • Confirmation on new Product Question
  • Confirmation on new Support Question
  • or create a total new one


System » Transactional Emails » Add new Template

Modify the loaded default template to your liking. Or create a fresh new Email Template:

  • Frontend Form fields translate to template variables as described in Form Fields used in the Transactional Emails
  • Attachments defined in the frontend form are handled automatically, if the associated form field name is attachments[]


With your template for the Transactional Email complete, save it. To link the email template to your form page use the ID-Number of the such created template:


SmtpPlus Forms allows to set all options controlling the form behavior within the template file of the Form. With that, there is no other configuration required and the form template and its options are conveniently in the same template file.

The Form Options allow to:

  • Retrieve Form Data from a previous Post of the same form from the current visitor (or customer)
  • Set the Email Sender and Destination Addresses for the Transactional Email that is generated when submitting the form
  • Define if and where another Transactional Email (as confirmation) shall be sent when submitting the form
  • Control where the form shall redirect when being submitted successfully or on failure in the submittal


We suggest to put the code for setting and getting form options into the top part of your form template. This is a example of the template section of a form where all options are set, for details see below:

Example Form Options controlling the form behavior

// Get prepared data for Form
$data = $this->getFormData();
// Get Product from prepared data
$product = $data->getProduct();
// Get Customer from perpared data
$customer = $data->getCustomer();
// Get Store Email Address for Identity 'general'
$storeEmail = $this->getStoreEmailAddress('general');
 
// This flag is set to TRUE if the previous Form Post has been submitted
if ($this->getOption('form_submit_success', false)) {
	// Clear Form data from previous post
	$this->clearFormPost();
}
// Retrieving form data from the previous post on this form in the current session
$formData = $this->getFormPost('form');
 
/*
 * The following is to set Options for this Form without presenting them in the <FORM> content.
 * These Options are stored in the Session data of the current session.
 */
// Disregard to check the FormKey
$this->setOption('formKey', false);
 
// Setting the URL of the referring page
$this->setOption('referer_url', $this->getFormData()->getReferer());
 
// Where to redirect and what message to show if Form has successfully sent
$this->setOption('success', Array(
	  // Where to redirect in case of sucess, to redirect back to this form set to empty string
	  'url' => $this->getFormData()->getReferer(),
	  // Message to show
	  'message' => 'Thank you, your question has been submitted to us.'
	));
 
// Where to redirect and what message to show in case of error
$this->setOption('error', Array(
	  // Where to redirect in case of sucess, to redirect back to this form set to empty string
	  'url' => '',
	  // Message to show
	  'message' => 'Sorry, there has been a difficulty submitting your question to us. Please try again later.'
	));
 
// REQUIRED: Where to send the Forms content
$this->setOption('email', Array(
	  // REQUIRED: Set the Sender Email for this Form. Use Store Email Address Accounts ONLY: 'general', 'sales', 'support', 'custom1', 'custom2'
	  'sender' => Array('address'=>'general'),
	  // REQUIRED: Set the Recipient Email Address and Name for this Form. Use a Store Email Address Account, fully qualified Email Address, or the Name of the Form field to use
	  'recipient' => Array('address'=>'general', 'name'=>''),
	  // OPTIONAL: Set a Reply-To Address. Use fully qualified Email Address, or the Name of the Form field to use, or a Store Email Address Account as above.
	  'replyto' => Array('address'=>'form[email]'),
	  // Set the ID (or Name) of the Transactional Email Template to use
	  'template' => Array('id'=>null, 'name'=>'smtpplusforms_new_product_question')
	));
 
 
// OPTIONAL: If wanting to send a confirmation email to customer or someone else. Most individual settings are same as for Form Email above
$this->setOption('confirmation', Array(
	  // Set to TRUE to send confirmation Email, FALSE if not
	  'email' => false,
	  'sender' => Array('address'=>'general'),
	  'recipient' => Array('address'=>'form[email]', 'name'=>'form[name]'),
	  'replyto' => Array('address'=>'general'),
	  'template' => Array('id'=>null, 'name'=>'smtpplusforms_confirmation_product_question')
	));



Get prepared Form Data

The form data of the Form (including POST Data from a previous form submit of the visitor) is stored in the visitors session data. This allows to have form data prepared with using the SmtpPlus Forms Events. And to have form fields filled with the original data when having a failure on submitting the form. To retrieve this data in the form template use:

$data = $this->getFormData();



Clear Form POST Data from previous submit

To clear any data stored from a previous POST of the form by the visitor in his session, use:

$this->clearFormPost();



Get current Store's Email Address

Use this function to get one of the Store Email Addresses. Use 'general', 'sales', 'support', 'custom1', 'custom2' as argument for the Store Email Address to retrieve:

$storeEmail = $this->getStoreEmailAddress('general');



Do not check the Form Key when submitting

For each visitor session a unique form key is being produced, and checked if present in the form post data as security measure. To disable this security check use this option set to false (use true to enable it):

$this->setOption('formKey', false);



Set the URL of the referring page

To set the referring URL for the form page. By default SmtpPlus Forms uses the last known page url from the Store, to override the referring URL to any other URL use:

$this->setOption('referer_url', 'http://www.domain.tlc./some/page');



Set where to redirect on successful form submittal

Was a form submitted successfully as Transactional Email, the form page will redirect to the URL defined. You may add a message, that will get shown as part of the store messages, as feedback to the user of the form:



// In this example the URL for the redirection is to be the referring page:
$this->setOption('success', Array(
	  // Where to redirect in case of success, to redirect back to this form set to empty string
	  'url' => $this->getFormData()->getReferer(),
	  // Message to show
	  'message' => 'Thank you, your question has been submitted to us.'
	));
 
// In this example the URL for the redirection is a specific one:
$this->setOption('success', Array(
	  // Where to redirect in case of success, to redirect back to this form set to empty string
	  'url' => 'http://www.yourstore.tlc/some/page',
	  // Message to show
	  'message' => 'Thank you, your question has been submitted to us.'
	));



Set where to redirect on failed form submittal

Has a form failed to submit as Transactional Email, the form page will redirect to the URL defined in this option. You may add a message, that will get shown as part of the store messages, as feedback to the user of the form:

// In this example the URL is left blank to redirect back to the form page:
$this->setOption('error', Array(
	  // Where to redirect in case of sucess, to redirect back to this form set to empty string
	  'url' => '',
	  // Message to show
	  'message' => 'Sorry, there has been a difficulty submitting your question to us. Please try again later.'
	));
 
// In this example the URL for the redirection is a specific one:
$this->setOption('error', Array(
	  // Where to redirect in case of sucess, to redirect back to this form set to empty string
	  'url' => 'http://www.yourstore.tlc/some/page',
	  // Message to show
	  'message' => 'Sorry, there has been a difficulty submitting your question to us. Please try again later.'
	));



Where to send the Form Email

Each form will be sent as Transactional Email, use this option to set Sender and Destination data for the Transactional Email created by this form template:

$this->setOption('email', Array(
	  // REQUIRED: Set the Sender Email for this Form. Use Store Email Address Accounts ONLY: 'general', 'sales', 'support', 'custom1', 'custom2'
	  'sender' => Array('address'=>'general'),
	  // REQUIRED: Set the Recipient Email Address and Name for this Form. Use a Store Email Address Account, fully qualified Email Address, or the Name of the Form field to use
	  'recipient' => Array('address'=>'general', 'name'=>''),
	  // OPTIONAL: Set a Reply-To Address. Use fully qualified Email Address, or the Name of the Form field to use, or a Store Email Address Account as above.
	  'replyto' => Array('address'=>'form[email]'),
	  // Set the ID (or Name) of the Transactional Email Template to use
	  'template' => Array('id'=>null, 'name'=>'smtpplusforms_new_support_question')
	));


Setting Email Addresses

Email Addresses may get set from various sources:

  • Using a Store Email Address (required to be used for 'sender' and optional for 'recipient' and 'replyto') titled: 'general', 'sales', 'support', 'custom1', 'custom2'
$this->setOption('email', Array(
	  'sender' => Array('address'=>'general')
	));


  • Defining a fully qualified email address as ('sender' is required to be a Store Email Address): 'email@domain.tlc'
$this->setOption('email', Array(
	  'recipient' => Array('address'=>'email@domain.tlc', 'name'=>'Some optional Recipients Name')
	));


  • Using a Form field to get the Email Address from: form[email]
$this->setOption('email', Array(
	  'replyto' => Array('address'=>'form[email]')
	));


Email Addresses always will be validated to be a qualified email address before the Transactional Email will be sent. In case a email address used fails this validation the form submittal to the Transactional Email will fail. A corresponding store message will be created by the extension.

Defining the Email Template to use

To define the Email Tempalte to use for the related Transactional Email:

Either use the Name of one of the default templates:

  • smtpplusforms_new_product_question
  • smtpplusforms_new_support_question
  • smtpplusforms_confirmation_product_question
  • smtpplusforms_confirmation_support_question
$this->setOption('email', Array(
	  // Set the ID (or Name) of the Transactional Email Template to use
	  'template' => Array('id'=>null, 'name'=>'smtpplusforms_new_support_question')
	));


Or create your own Email Template as described in Creating the Template for the Transactional Email and use the ID-Number of the email template

$this->setOption('email', Array(
	  // Set the ID (or Name) of the Transactional Email Template to use
	  'template' => Array('id'=>20, 'name'=>null)
	));



Sending a Confirmation Email

Each form allows to create another Transactional Email as a “Confirmation Message”, use this option to set Sender and Destination data for this Transactional Email created by the form template:

$this->setOption('confirmation', Array(
	  // Set to TRUE to send confirmation Email, FALSE if not
	  'email' => false,
	  // Set to TRUE if to send Attachments also
	  'attachments' => false,
	  // All following option are the same as for Option 'email'
	  'sender' => Array('address'=>'general'),
	  'recipient' => Array('address'=>'form[email]', 'name'=>'form[name]'),
	  'replyto' => Array('address'=>'general'),
	  'template' => Array('id'=>null, 'name'=>'smtpplusforms_confirmation_support_question')
	));


The structure of this configuration option is the same as for Where to send the Form Email above.

Enabling the Confirmation Email

To enable the sending of a confirmation email, which will only get sent if the main form email has been sent successfully, set 'email' to true:

$this->setOption('confirmation', Array(
	  // Set to TRUE to send confirmation Email, FALSE if not
	  'email' => true
	));



Enabling File Attachments for the Confirmation Email

Per default any file attachments are excluded from the Confirmation Email. To include these set following Option:

$this->setOption('confirmation', Array(
	  // Set to TRUE if to send Attachments also
	  'attachments' => true
	));



Getting the URL of a specific Form

To get the URL of a specific form use:

$this->helper('smtpplusforms')->getFormUrl(<formname>, <options>);

Example to get the URL for the form 'productquestion'

// This will result in the URL: http://www.yourstore.tlc/contact/form/productquestion/
$this->helper('smtpplusforms')->getFormUrl('productquestion');


You may add URL options to transport a Product ID (or Customer ID or any other data) to the form template, via the URL, and for further use in the template code:

Example to pass a Product ID with the Form URL

// This will result in the URL: http://www.yourstore.tlc/contact/form/productquestion/product/<the Product ID>/
$this->helper('smtpplusforms')->getFormUrl('productquestion', Array('product'=>$this->getProduct()->getId()));



Getting the Route Name for all Forms

To get the URL route for all SmtpPlus Forms:

// Per default configuration this will result in: http://www.yourstore.tlc/contact/
$this->helper('smtpplusforms')->getFrontName();



Getting the Form Action URL

To get the URL for submitting any form handled by SmtpPlus Forms:

// Per default configuration this will result in: http://www.yourstore.tlc/contact/submit?SID=<The current Session-ID>
$this->helper('smtpplusforms')->getFormAction();

The Form Action URL does always include the current Session-ID as URL parameter, this to ensure that the form submit action uses the same Session as the Form page itself. If not using the Session-ID it may occur that Form Options get inaccessible, as the visitors Browser may submit the Form data under a different session than the Form Page.

Getting the Form Name of the current shown form

To get the form name of the currently shown form:

// This will result in the form name of the current form: e.g. 'productquestion'
$this->helper('smtpplusforms')->getFormName();