CFDB Plugin

Available in version 2.8. This functionality is an ALPHA version.
Transform introduction

Situation

The saved form data is not formatted or organized the way you want it to be. You want to transform the data coming into the short code. Transforms can be:

Transform Functions:

• Changing one or more fields, such as upper-casing, formatting a date
• Dynamically add fields based on other field data

Transform Classes (Advanced)

• Generate statistics
• Perform custom sorts of the data
• Combinations of the above

1. Transforms Function: Functions that apply to each form entry independently.

To do this, you use the trans short code option.

Examples:

Upper-case the last_name field:

[cfdb-table form="myform" trans="last_name=strtoupper(last_name)"]

Upper-case both the last_name and first_name

[cfdb-table form="myform" trans="last_name=strtoupper(last_name)&&first_name=strtoupper(first_name)"]

Note: use “&&” between different transforms. This is similar to && in the “filter” short code option but there is no “||” for “trans”.

Note: Transforms are evaluated in the order that they appear. So if you had a transform that first upper-cased last_name then lower-cased it, then the end result would be it lower-cased.

Create a “ID” field from the user id part of an email address (text before “@”). To do this we make use of PHP functions strpos and substr. Here we first use strpos to get the position of “@” in the string. We set that as a new form field called “pos”. We then use that field as in input to substring to get the substring from postion 0 to pos. We hide pos from display since it is just a temporary thing.

[cfdb-table form="myform" trans="pos=strpos(email)&&ID=substr(email,0,pos)"]

Same as previous, but instead we write a custom PHP function called “set_ID_field_from_email”. It is better than the above because we don’t have to make the “pos” field and we can handle cases where the email field does not have “@” as we expect.

[cfdb-table form="myform" trans="set_ID_field_from_email" hide="pos"]

Transform Functions vs. Filter Functions

A short code retrieves form data from the DB, transform functions change the data coming into the short code, then the short code uses that data as if it were the actual form data. Thus, short code options such as filter, show, hide, etc. apply to the tranformed data.

Similarly, functions can be used in filters. But in that case, the data is only temporarily changed for the purpose of evaluating the filter expression.

What Functions Can Be Used?

Potentially any PHP function can be used as a Transform Function, including those you create. But there are only a small set that you can use with default settings. These include most string-related PHP functions.

For Transform Classes, any can be used because they are written by you.

Function Security

A user who can create a short code (or export link) could potentially run a PHP function that might harm your installation or data. Therefore security restrictions are in place by default.

This security can be turned off entirely in the administration page Contact Form DB -> Options -> Allow Any Function in Short Codes. If that is set to true then users which role for Can See Submission when using shortcodes can write a short code or compose a URL that can run any PHP function. It is best to keep this option to false.

Alternatively, individual functions that the administrator deems as safe can be registered as being permissible to use.

Permitting a Function and Creating Custom Functions

To permit individual functions, you will need to be able to add PHP code to register function names. First, install the Shortcodes Actions and Filters plugin and activate it. From the administration page, go to the Tools menu -> Shortcodes Actions and Filters. Put your code there and save.

Example: to register a custom function “cfdb_reverse” define the function the call cfdb_register_function.

(Enter code via Shortcodes Actions and Filters)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

require_once(ABSPATH . 'wp-content/plugins/contact-form-7-to-database-extension/CFDBPermittedFunctions.php');
 
function cfdb_reverse($text) {
  return strrev($text);
}
cfdb_register_function('cfdb_reverse');
 
function set_ID_field_from_email(&$entry) {
  // Using "&" in "&$entry" to pass by reference
  if (!$entry['email']) {
    // email field not set
    $entry['ID'] = 'unknown';
  } else {
    $pos = strpos($entry['email'], '@');
    // NOTE: when adding a new field like "ID" always add it in all if-else-elseif cases
    // Set it to '' if it has no value.
    if ($pos === FALSE) {
      // no "@" in the email field
      $entry['ID'] = $entry['email'];
    } else {
      $entry['ID'] = substr($entry['email'], 0, $pos);
    }
  }
}
cfdb_register_function('set_ID_field_from_email');

You can then use the functions as a transform, e.g.

[cfdb-table form="myform" trans="last_name=cfdb_reverse(last_name)"]

and

[cfdb-table form="myform" trans="set_ID_field_from_email"]

Existing PHP and WordPress functions can be added using cfdb_register_function(function_name).

See also: Filter Functions

2. Transforms Function: Functions that apply to a whole form entry.

Instead of a function that operate on a field name, you can make one that works on a whole entry at a time. In this example, we upper-case all the fields the form entries.

NOTE: you can have the entry parameter passed in by reference (above example), or you can have it passed in by copy but then you have to return it or a new one (this example).

[[cfdb-table form="myform" trans="upperall"]

(Enter code via Shortcodes Actions and Filters)

1
2
3
4
5
6
7
8
9
10

require_once(ABSPATH . 'wp-content/plugins/contact-form-7-to-database-extension/CFDBPermittedFunctions.php');
 
function upperall($entry) {
  foreach ($entry as $key => $value) {
    $entry[$key] = strtoupper($value);
  }
  return $entry;
}
 
cfdb_register_function('cfdb_reverse');

Notice that the function takes a parameter but we don’t show a parameter in the short code like we did with strtoupper(name). If the short code detects that “upperall” is a function and there is no parameter passed, then it passes a form entry which is an associative array of field => value.

3. Transforms Classes: PHP Classes that operate on the entire data set, not just each row.

Good for operations across the entire data set like generating statistics and sorting.

[cfdb-table form="myform" trans="AddIndexFieldToSubmissions"]

(Enter code via Shortcodes Actions and Filters)

1
2
3
4
5
6
7
8
9
10
11
12

require_once(ABSPATH . 'wp-content/plugins/contact-form-7-to-database-extension/BaseTransform.php');
 
class AddIndexFieldToSubmissions extends BaseTransform {
 
 public function getTransformedData() {
   $idx = 0;
   foreach ($this->data as &$entry) {
     $entry['index'] = $idx++;
   }
   return $this->data;
 }
}

In this example we extend BaseTransform which captures all the data in $this->data which is an array of associative-arrays of each entry. We implement the getTranformedData() function and return the entire data set.

This simplistic example merely adds an ‘index’ field to each form entry. More complicates examples are sorting the data set or returning an entirely different data set such as a set of statistics about the data.

Classes do not need to be registered.

See Transform Classes.