checkSubmissionIsUnique()

API v2.x

This function lets you check that a submission is unique, based on whatever criteria is required for your form. For example, a common usage of this function is to check that a submission currently being placed has NOT already been placed by someone with the same email address.

The function can be called like so:

$api = new FormTools\API();
if ($api->checkSubmissionIsUnique($form_id, $criteria, $submission_id)) {
    echo "oh it's unique all right!";
}

The $form_id parameter is self-explanatory; you can find this value in your Form Tools interface. $criteria is a hash/associative array where the keys are the database column names and the values are the values being examined. This field can contain any number keys. The third $submission_id parameter is OPTIONAL, and was added in version 20090905 of the API. This lets you tell the function to ignore a particular submission when doing to the comparison. In other words, it ensures that it doesn't run the test for uniqueness against itself - because that would always fail!

To return to our example, imagine you want to check that a submission hasn't already been placed by a user with a particular email address. You could check like this (where "email" is the database column name and the form ID is 10):

<?php
$api = new FormTools\API();

$criteria = array(
    "email" => $_POST["email"]
);
// note the the $fields variable should be named to whatever your initFormPage() function
// call returns
if (!$api->checkSubmissionIsUnique(10, $criteria, $fields["form_tools_submission_id"])) {
    // uh-oh! A submission already exists with this email address!
    // Abort, abort! here, you could do something like set a
    // variable like: $already_exists = true
    // and in the webpage do a little test to see if it's set.
    // If so, let the user know what's going on
} else {
    // call processFormSubmission() function here to continue processing
    // the form submission
}
?>

We chose to use database column names rather than form field names to allow you to also use the system fields (is finalized, IP address) to check for uniqueness. You can find the database column names on the Edit Form » Fields tab.

DOCUMENTATION

API v2.x