Tutorial: Create a summary template

As of version 1.4.0, you can use a template for e-mail notifications.  The mechanism is similar to wordpress theming.  You should first examine the default template, ‘fm-summary-default.php’, located in ‘/templates’ in the plugin’s directory (usually /wp-content/plugins/wordpress-form-manager).

IMPORTANT!!! – Make sure to save your custom template as something other than ‘fm-summary-default.php’ and ‘fm-summary-multi.php’.  Otherwise, you will lose your changes when you update the plugin.

Step 1: To make a new template, make a new file in the ‘/templates’ directory, within the plugin’s main directory.  The first few lines of the template must look like the following:

<?php /*
Template Name: (Template name goes here)
Template Description: (A brief description of the template goes here)
Template Type: (either 'email', 'summary', or 'email, summary', to specifiy what the template should be used for)
*/ ?>

  • Template Name – (required) This is what will appear in the menu to select the template for use by your form.
  • Template Description – This should be a short description of the template.  This won’t show up anywhere, but you should include it anyway.
  • Template Type – (required) This must be the word(s) ’email’ and/or ‘summary’, separated by a comma if both are included.  This specifies whether the template is an e-mail notification template, data summary template, or both.

Step 2: As a bare minimum, you need to output the names of the form elements and the data that was submitted.  The mechanism for doing this is very similar to the way wordpress themes display posts.  Below is an example of how to display the form submission as an unordered list:

<ul>
<?php while(fm_summary_have_items()): fm_summary_the_item(); ?>
<li><?php echo fm_summary_the_label();?>: <?php echo fm_summary_the_value();?></li>
<?php endwhile; ?>
</ul>

If you add the code above below the required code mentioned in step 1, you already have a working summary / e-mail notification template.  Congratulations!

Step 3: Add a formatted timestamp somewhere.  This is especially helpful to give some context to the submitted data.  To add the timestamp, you could simply use:

<?php echo fm_summary_the_timestamp(); ?>

This will display something like “2011-05-19 01:21:03”, which unfortunately is not the most user friendly way to display time and date.  The best way is to use php’s date() and strtotime() functions in conjunction with fm_summary_the_timestamp(), such as the following:

<?php echo date("M j, Y @ g:i A", strtotime(fm_summary_the_timestamp())); ?>

This will look something like “May 19, 2011 @ 1:21 AM”, which is much more user friendly.  If you want to fiddle with the date format, you should look up date() at php.net for information on how the format string works.

Step 4: Display some information about the user.  Of course, this only applies to users that are logged in to your site.  To check if this is the case, you only need to check if fm_summary_the_user() is equal to “”.  Below is an example:

<?php
$userName = fm_summary_the_user();
if($userName != ""){
//stuff to do if there is a logged in user
}
?>

Once you have detected a logged in user, you can use any of wordpress’s functions to extract information about that user, such as get_userdatabylogin().  Below is an example:

$userData = get_userdatabylogin($userName);
echo "Submitted by: <strong>".$userData->last_name.", ".$userData->first_name."</strong>";

You could also add the IP address.  To do so, you would add the following line:

IP: <strong><?php echo fm_summary_the_IP();?></strong>

Step 5: If your forms have notes or separators, you might want to skip those when displaying the form items.  This can be done easily, by modifying the loop set up in step 2 as follows:

<ul>
<?php while(fm_summary_have_items()): fm_summary_the_item(); ?>
<?php if(fm_summary_the_type() == 'separator'): ?>
<hr />
<?php elseif(fm_summary_has_data()): ?>
<li><?php echo fm_summary_the_label();?>: <strong><?php echo fm_summary_the_value();?></strong></li>
<?php endif; ?>
<?php endwhile; ?>
</ul>

This adds a couple new functions, fm_summary_the_type() and fm_summary_has_data().  These two functions work well together.  The first, fm_summary_the_type(), will return the type of the form item: text, textarea, checkbox, custom_list, note, separator, recaptcha, or file.  If you want to isolate a particular kind of form item for special treatment, use this function.  The second, fm_summary_has_data(), will return true only for items that have data associated with them, namely, all types except separator, note, and recaptcha.

Step 6: Add a friendly message, your company logo, or whatever else.  At this point, we have covered everything that happens in the default summary template.  Changes you might want to play with would be converting the unordered list in step 2 to a table, or perhaps add classnames to the HTML to fit with your theme better.  To use your new template, either choose it from the list of templates in the ‘Advanced’ settings to apply the template to all forms, or choose the template within the form editor to apply the template to a single form.

You can also access form elements directly by their nicknames, which you can specify in the ‘Advanced’ part of the form editor.  For example, if your form element’s nickname is ‘the-subject’, then you might do something like the following:

<?php echo fm_summary_get_item_label('the-subject');?>: <?php echo fm_summary_get_item_value('the-subject'); ?>

Below is a complete list of the functions available for use within a summary template:

  • fm_summary_the_title() – the title of the form
  • fm_summary_have_items() – works like have_posts() for wordpress themes.  Returns ‘true’ if there are more items left in the form.
  • fm_summary_the_item() – works like the_item() for wordpress themes.  Initializes the current form item.
  • fm_summary_the_label() – label of the current form item
  • fm_summary_the_nickname() – nickname of the current form item.  If none exists, returns “”.
  • fm_summary_the_type() – type of the current form item (text, textarea, checkbox, custom_list, note, separator, recaptcha, file)
  • fm_summary_has_data() – returns true if the form element is a data element
  • fm_summary_the_value() – submitted value of the current form item
  • fm_summary_the_timestamp() – timestamp for the current submission
  • fm_summary_the_user() – the login name for the current user.  If no user is logged in, this returns an empty string.
  • fm_summary_the_IP() – the IP address of the user who submitted the form.
  • fm_summary_the_parent() – the post ID where the form was submitted from.
  • fm_summary_get_item_label($nickname) – get an item’s label by nickname.
  • fm_summary_get_item_value($nickname) – get an item’s value by nickname.
  • fm_summary_get_form_info() – get the current form’s structure (an associative array).

And the completed code for this tutorial:

 

<?php /*
Template Name: (Template name goes here)
Template Description: (A brief description of the template goes here)
Template Type: (either 'email', 'summary', or 'email, summary', to specifiy what the template should be used for)
*/ ?>
<?php

 

$userName = fm_summary_the_user();
if($userName != ""){
$userData = get_userdatabylogin($userName);
echo "Submitted by: <strong>".$userData->last_name.", ".$userData->first_name."</strong>";
}
?>
On: <?php echo date("M j, Y @ g:i A", strtotime(fm_summary_the_timestamp())); ?>
IP: <strong><?php echo fm_summary_the_IP();?></strong>
<ul>
<?php while(fm_summary_have_items()): fm_summary_the_item(); ?>
<?php if(fm_summary_the_type() == 'separator'): ?>
<hr />
<?php elseif(fm_summary_has_data()): ?>
<li><?php echo fm_summary_the_label();?>: <strong><?php echo fm_summary_the_value();?></strong></li>
<?php endif; ?>
<?php endwhile; ?>
</ul>