Email with Link to Validate/Accept

[jaqy]

I am using FormTools to submit my information collected to the database, then displaying it on the website. I have set up required fields and captcha to try to ward off spam, but I would also like to create one more step to ensure accurate information is being sent. I want for the user, after submitting the form, to get an email with a link to "accept entry" before it goes live. I assume I can just add another field that is yes or no and filter out the displayed results using that... but how do I get the option in an email or go about that without having them log in and get access to the database, etc.? I literally just want "click here to accept" they click it and it marks it or enters in the DB or whatever that it was accepted. I thought I saw information about that somewhere here, but I can't seem to find it! Help? I'm new to FT and MySQL so go easy on me!

[Ben]

Hi jaqy,

Neat idea! Yes, this is very doable. Here's how it would work.

You'd add your form normally - it can be either a POST form or an API form - either is fine. But using the API is probably better. If you use the API you can choose whether or not the submissions show up in the Form Tools user interface by explicitly marking them as "finalized". Only finalized submissions show up. POST form submissions are finalized by default, so there's no choice: they'll always appear in the user interface. However, we can hide them with a little trickery.

But the API approach is better, so I'll explain that one.

1. Add your form using the API. For the test submission, follow all the instructions in the tutorials and documentation and add the "finalize" => true option on the final step. Once the form is added, REMOVE that key-value pair. Now, all submissions will be added to the database but won't show up.

2. Add a new field to your form called "unique_key". We're going to populate that value with a random string for all new submissions using the Submission Pre-Parser module. I've documented this pretty well in this tutorial - see steps 2 and 3:
http://docs.formtools.org/tutorials/post...page=step2

It's exactly the same thing, just re-purposed for your case.

3. Now, when you put through new submissions (a) they won't show up but (b) they WILL have a random string generated for each. We're going to use that random string to

Create an email template for your form. This will contain the link to approve the submission (make it show up). In the email content, just use the placeholders that are listed on the page to construct the string. It would look something like this:

http://www.yoursite.com/finalize.php?id=..._uniquekey}

On your site you'll need to create a page called finalize.php containing the following code:

Code:

<?php
require_once("/path/to/api.php");
if (empty($_GET["id"]) || empty($_GET["key"]))
{
  header("location: /"); // redirect somewhere...
  exit;
}

// here you'll need to replace X with your form ID
$submission_info = ft_api_get_submission(X, $_GET["id"]);

// if the key matches for this submission, finalize it!
if ($submission_info["unique_key"] == $_GET["key"])
{
  // replace X here too
  ft_finalize_submission(X, $_GET["id"]);

  // here you could just redirect to a page that tells the submission
  // has been approved. Alternatively you could show it below
  header("location: approved.php");
  exit;
}
?>

And that's pretty much it. Now, when users click on the link, they'll be taken to that page which parses out the values in the query string and finalizes the submission (if the info is valid).

[Aluwe]

Hi Ben,

Thanks for the FT and all explanations you have been giving. I will like more explanations on this email thread. As I understand it it follows the logic you gave, but where do we trigger the sending of the email, and what what field should be added to the mail templates.

Assuming that at step 1,form was filled and all errors and rules are verified and validated. At step 2, the form was submitted and the unique_key inserted to the mail templates. And at step 3, returned page link is verified against the unique_key. At step 4, the form is finalised and data inserted into database.

Kindly please explain (1)where the trigger should be on form submission and the code for it. (2) How to trigger the email sending and (3) how to use the finalise.

In your example, I am not clear about this on your step 1 "Once the form is added, REMOVE that key-value pair. Now, all submissions will be added to the database but won't show up.".

Thanks.

[Ben]

Hi Aluwe,

Excellent points!

(1) First, I totally forgot to mention how to trigger the emails. When you use the API to submit your form contents, any email templates that have the "on submission" trigger set (on the first tab of the Edit Email Template page in Form Tools) will be sent on the final step of your form when the submission is actually finalized. This is the bit that looks like this:

PHP Code:

$params = array(
  ... 
  "finalize" => true
  ... 
);
ft_api_process_form($param); 


However, in the case I described above, the submission is NOT finalized. So the email will never get sent! Ack!

Instead, add the following key to the $params hash:

PHP Code:

$params = array(
  ... 
  "send_emails" => true
  ... 
);
ft_api_process_form($param); 


That explicitly tells Form Tools to send the emails.

(2) Finalizing the submission

In the example above, I mentioned using ft_finalize_submission($form_id, $submission_id) function, but that will actually re-send the emails (I'll log this as a bug - the emails being sent should be configurable). So instead, replace that section of the code with the following:

PHP Code:

$query = mysql_query("
    UPDATE {$g_table_prefix}form_X
    SET    is_finalized = 'yes'
    WHERE  submission_id = $submission_id
           "); 


(X will need to be the form ID). That should work fine.

In your example, I am not clear about this on your step 1 "Once the form is added, REMOVE that key-value pair. Now, all submissions will be added to the database but won't show up.".

Ah okay, sorry I wasn't clear! Basically, what you need to do is just follow the instructions for adding an API form. Once form submissions are being added properly, edit the form page BEFORE the final page. This page will have some code like this:

PHP Code:

$params = array(
  ... 
  "finalize" => true,
  ...
);
ft_api_process_form($params); 


The important bit is the finalize => true bit. You don't want that any more! Just remove that line.

Hope this info helps... let me know if you have any more questions.

- Ben

[Aluwe]

Hi Ben,

Thanks for the reply, we are getting somewhere with this issue. So far so good the test email works with PhP, and in the actula submission, emails are not sent.

The way I understand this to work is as follows:

1. Registration forms with

PHP Code:

if (empty($errors))
  {
    $params = array(
      "submit_button" => "Submit",
      "next_page" => "newthanks.php",
      "form_data" => $_POST,
      "send_emails" => true
      
    );
    ft_api_process_form($params);
  }
  // it failed validation. Update $fields with the latest contents of the form data
  else 
  {
    $fields = array_merge($_SESSION["form_tools_form"], $_POST);
  }
}
?>

2. The thankyou.php file

Code:

<?php
require_once("/home/content/19/6046519/html/formtools/global/api/api.php");
$fields = ft_api_init_form_page("22");
ft_api_clear_form_sessions();
?>

3. The email configuration in the form tools
Configuration:
Status = enabled
Event trigger = On submission

Recipients:
Custom recipients using the form email field
From:
Custom recipients supply by me

Reply to:
Custom recipients supply by me, save as recipients

Content:

Code:

Submission ID:{$SUBMISSIONID}    Examination: {$ANSWER_Examinations}
  <tr>
    <p>
  Dear  {$ANSWER_title} {$ANSWER_surname},                                                                                                    
Thank you for registering with yoursite.com, your registration has been submitted.

Please click this link to complete your registration http://www.yoursite.com/Prefinalise.html?id={$ANSWER_unique_key}                                                                        

Administration Manager
  
<p>
  
</p>

On submission:
The email is sent to the applicant to click a link. On clinking the link, the finalize.php confirms the header for unique_key. After confirmation redirect to another page.

4. The Finalize php

Code:

<?php
require_once("/home/content/19/6046519/html/formtools/global/api/api.php");
if (empty($_GET["id"]) || empty($_GET["key"]))
{
  header("location: http://www.yoursite.com/anything.html"); // redirect somewhere...
  exit;
}

// here you'll need to replace X with your form ID
$submission_info = ft_api_get_submission(22, $_GET["id"]);

// if the key matches for this submission, finalize it!
if ($submission_info["unique_key"] == $_GET["key"])
{
  // replace X here too
  $query = mysql_query("
    UPDATE {$g_table_prefix}form_22
    SET    is_finalized = 'yes'
    WHERE  submission_id = $submission_id
           ");

  // here you could just redirect to a page that tells the submission
  // has been approved. Alternatively you could show it below
  header("location: http://www.yoursite.com/welcome.html");
  exit;
}
?>

So far, only the test is sending the emails, and with actual submission only the thankyou page and no email is sent.

Is there any event trigger to be added to the emails. I presumed it is not a case of spamming as the test emails are received by the recipients, and clinking the link will open the link page with the unique_key on the header pages.

At what point this function be ft_send_emails("on_submission", $form_id, $submission_id); called and where should it be on submission.php.

Please advised, I know this is painful but this is one of the most important part of the Form Tools, and in fact the killer apps in the system.

Thanks

NB: the link actually is written as unique_key, but showing as nique here.

[Aluwe]

Hi Ben,

Step 3 and 4 of these pages are the same:
http://docs.formtools.org/tutorials/post...page=step3
http://docs.formtools.org/tutorials/post...page=step3

In essence there is no step 4, "Configure your receipt page"

I think this will help as well.

[Ben]

Hi Aluwe,

Sorry - the link on the left nav was incorrect; I tend to use the other nav - next & prev - so I missed it. All fixed now, thanks for mentioning it!

- Ben

[Ben]

Hi Aluwe,

Add the ft_send_emails(...) line after this bit:

PHP Code:

// replace X here too
  $query = mysql_query("
    UPDATE {$g_table_prefix}form_22
    SET    is_finalized = 'yes'
    WHERE  submission_id = $submission_id
           "); 


That will then send any emails that have been assigned to the "on submission" trigger.

Let me know how it goes!

- Ben