Plugin Documentation

Detailed documentation about all features and settings of CFF.

How it works?

From the dashboard/configuration area the process is as follows:

  1. Insert data fields into the form
  2. Insert a calculated field and define the calculation rule on it to store the calculated value
  3. Configure the general form processing, email and PayPal settings if needed
  4. Publish the form from a post or page (go to edit posts or pages).

From the end user (visitor) point of view, the process is as follows:

  1. The user fills the data fields
  2. The calculated fields (if any) will automatically show the calculated value
  3. If the form Processing is enabled:
    • If PayPal integration isn't enabled:
      1. The user clicks "submit" and you (the website owner or administrator) receive a notification email with the data posted by the user.
      2. The user receives an automatic "confirmation/thank you" email.
      3. The user is redirected to a "confirmation/thank you" page into your WordPress website
    • If PayPal integration is enabled:
      1. The user clicks "submit" and is automatically sent to PayPal for the payment
      2. In background (transparent to the user): The request is saved into the local database and mark as "un-paid"
      3. The user completes the payment at PayPal
      4. In background (transparent to the user): Upon completed the payment, you (the website owner or administrator) receive a notification email with the data posted by the user.
      5. In background (transparent to the user): The request is marked as "paid".
      6. The user receives an automatic "confirmation/thank you" email.
      7. The user returns to a "confirmation/thank you" page into your WordPress website

Installation

To install the WordPress plugin follow these steps:

  1. Download the plugin to your computer.
  2. Go to the plugins section in WordPress
  3. If has been installed another version of the plugin, deactivate it, and then press the corresponding "Delete" button.
  4. Press the "Add New" button at top of section.
  5. Press the "Upload Plugin" button, and select the zipped file downloaded in the first step.
  6. Finally, install and activate the plugin.

Inserting the CFF on Page

  1. Configure the settings at the administration menu >> Settings >> Calculated Fields Form.
  2. To insert a form into some pages or posts, uses the icon that will appear when editing contents:

    Insert Calculated Form

  3. After doing that, the tag [CP_CALCULATED_FIELDS id="1"] will be inserted into your content. The "id" is optional, if not specified the first form will be used. When you preview the content in the public website that tag will be replaced by the reservation form:

    Calculated Form

  4. The Claculated Fields Form includes multiple predefined designs.

    Calculated Form

Register the plugin

The "CFF" is completely functional even without be registered. But after registering the plugin, the updates are received directly into WordPress.

For registering the plugin follows the steps below:

  1. Go to the settings page of the plugin through the menu option: "Settings/Calculated Fields Form"
  2. Enter the email address used to purchase the plugin, in the attribute: "Enter the email address of buyer"
  3. Press the "Register" button.

Registering the plugin

After registering the plugin the updates are notified in the "Updates" section of WordPress.

Managing Forms

After going to the WordPress administration menu >> Settings >> Calculated Fields Form you will see the list of forms like in the following image:

Calculated Forms List

For each form you will see the following options:

  • ID: Identification number of the form, useful when publishing an specific contact form.
  • Form Name: Name to identify the form. Visible only from the admin area.
  • Update: Updates the form name.
  • Settings: For managing the form settings.
  • Clone: Duplicate/clone a form.
  • Messages: Printable list of messages (both paid and unpaid).
  • Delete: Deletes the form and all its messages and settings.
  • Shortcode: An alternative way for publishing the form.

After clicking the "Settings" button you will jump to a new page with the form builder a other configuration options as explained below.

Check the submissions

Press the "Messages" button, corresponding to the form. The messages screen displays the list of submissions, and a filtering section to reduce the submissions by form, a time interval, or a text in the data

From the messages screen it is possible remove a submission, or submissions group, change its status to paid/unpaid, but from this screen is possible export all submissions to a CSV file

Export the submissions to a CSV File

For exporting the submitted information to a CSV file, press the "Messages" button corresponding to the form, and press the "Export to CSV" button, select the location where will be saved the CSV and that's all. The first row of CSV file allows identify each of fields, the text used to identify the field will be the short label, defined in the field, or the label in case that the short label is not defined.

Import/Export Forms

The "Calculated Fields Form" allows exporting the forms created in a WordPress website to be imported in other websites(*). The feature is really thankfully for owners or developers of multiple websites to avoid implementing the same form once and once again.

Note(*): Both websites must be using the same version of the plugin to have a compatible exported file.

To export a form:

  1. Go to the settings page of the plugin through the menu option: "Settings/Calculated Fields Form"
  2. Select the form from the list: "Export this form structure and settings" (in the "Import/Export Area"), and press the "Export" button.
  3. Finally, select a location in your computer to save the exported file.

To import a form:

  1. Go to the same area mentioned in the previous section.
  2. Choose the previously exported file (.cpfm) that contains the form's structure and settings.
  3. Finally, press the "Import" button.
  4. The new form will appear in the list of forms. To modify it use the related "Settings" button.

The Form Builder

The Form Builder lets you to add/edit/remove fields into the form and also to specify the validation rules for your form (required fields, email fields, etc...).

Form Builder

Form title and predefined designs

The "Form Settings" tab allows define the form's title and description, as the placement of labels respect the fields (at top, at left, aligned to the right). In the "Form Settings" tab is possible to enable the autocompletion of fields, evaluate dynamically the equations (or evaluate the equations through a "Calculate" button), or decide the form's design. The plugin includes multiple predefined designs.

Form Settings Tab

The following field types are currently available:
  • Single Line Text: Classic text input.
  • Number: This field can validate if only digits or a valid number was entered.
  • Slider: Numeric field whose value is modified sliding a handle.
  • Currency: A classic input field for currency values, that allows separator for thousands, and currency symbols.
  • Hidden: A hidden field.
  • Email: This field validates that the email address has a valid format.
  • Date/Time: Date-picker. Can be setup also to show also a selectable year and month, for example for birth date fields, and time fields.
  • Checkboxes: Classic checkboxes, select one or more on a group.
  • Multiple Choice: Radio buttons, select one of many.
  • Dropdown: Classic select / dropdown field.
  • Upload File: For uploading files.
  • Password: A field that shows * instead the typed letters. You can also add a confirm password validation.
  • Phone field: Supports international formats line ###-###-#####. The format is configurable.
  • Comment area: It's a comment to introduce to a section of the form or give instructions to the user.
  • Summary: Displays a summary of form fields with the values entered.
  • Section Break: It's a line for separating areas group of fields
  • Page Break: Useful for creating multi-page forms. The "page break" marks the start of a new page in the form builder
  • Instruct. Text: Text field to display instructions for users.
  • HTML Content: Field for general purpose, to include HTML tags in the form.
  • Media: Allows insert images, audios or videos.
  • Button: Insert a button in the form. The buttons supported are: common button, calculate button, or reset (the submit button is inserted from the form settings).
  • Calculated field: It's highlighted with a different color since it's a special field that can calculate its value from the data entered in other fields. This field is explained in detail below.
Container Fields

The form builder includes some container controls. The container controls allow to insert another controls in them:

  • Fieldset Container: Allows insert a fieldset control in the form, with a legend.
  • Div Container: Inserts a container very useful for grouping related controls, and not modifies the appearance of the form.
DataSource Fields

In addition to the above, the following fields are available only in the Developer and Platinum versions of the plugin:

  • RecordSet DS: A hidden field that gets its values from one of following datasources - Database, or CSV file. The "RecordSet DS" fields are used as intermediary to populate other fields in the form, reducing the number of connections to server side to get the records.
  • Line Text DS: An input field that gets its default values from one of following datasources - Database, Posts information, Taxonomies information or Users information.
  • Number DS: An input field that gets its default values from one of following datasources - Database, Posts information, Taxonomies information or Users information.
  • Email DS: An input field for Email address that gets its default values from one of following datasources - Database or Users information.
  • Text Area DS: A text area field that gets its default values from one of following datasources - Database, Posts information.
  • Checkboxes DS: Checkboxes for selecting one or more options into the same field that gets its options from one of following datasources - Database, CSV, Posts information, Taxonomies information or Users information.
  • Radio Btns DS: Radiobuttons for selecting one option between the options available for the field that gets its options from one of following datasources - Database, CSV, Posts information, Taxonomies information or Users information.
  • Drop-down DS: A select / drop down list for selecting one of the values listed that gets its options from one of following datasources - Database, CSV, Posts information, Taxonomies information or Users information.
  • Hidden DS: A hidden field that gets its value from one of following datasources - Database, Posts information, Taxonomies information, or Users information.
Editing the field settings in the Form Builder

Field Settings

When you click a field already added, you can edit its details and validation rules. The following properties are useful:

  • Field Label: Label for the field in the public form and into the email.
  • Field tag for the message: In addition to the general <%INFO%> tag, you can use this tag to show the field value into a specific tag of the email.
  • Specific settings: The settings depends of the field type, for example the format of the phone number, the date format, etc...
  • Validation rule: The validation rules depends of the field type, example: required, only digits, valid email, valid number, etc...
  • Predefined value: Pre-filled value for the field, if any.
  • Instructions for user: This text will appear in a smaller form below the field. It's useful for giving instructions to the user.
  • Add CSS layout keywords: Customize the look & feel. If used, this field must contain the name of the CSS class and not the styles rules directly.
Other features in the form builder:
  • Equal fields validation: Use it for example to confirm if the email or password typed in two different fields are the same. This is valid for "Single Line Text", "Password" and "Email" fields.
  • Dependent fields: Use this feature for show/hide fields (any field type) based in the selection made on other fields (checkboxes, radiobuttons or select/drop-down fields).
calculated fields settings:

When clicking over a calculated field in the form builder the following settings will appear:

Calculated Field

In addition to the general fields settings there are three additional settings:

  • Set Equation: To enter the equation/formula used for the calculation.
  • Operands: To select the fields from the form that will be used in the calculations. Click the "+" button for adding a field into the equation/formula.
  • Operators: Operators and functions supported for the formula...

Note for advanced users: The JavaScript ternary operator is also supported: (condition ? value_if_true : value_if_false). See the "Ideal Weight Calculator" for a sample.

For DataSource controls (only available in the Developer and Platinum versions of the plugin)

This is a step by step about the use of datasource controls

  1. Insert in the form the control with access to external datasources (these controls are represented with the DS at the end of its names)
  2. Select the control in the form, and pays attention to the "Define Datasource" section.

    There are different datasources: Database, CSV file, Recordset, Post Type, Taxonomy, and User Data.

    • Database, allows populate the field with the data stored in database.
    • CSV, allows populate the field with the data stored in a CSV file (Datasource available only in fields with multiple entries: DropDown DS, Checkbox DS, Radio Button DS).
    • Recordset, allows populate the fields from the records stored in a "RecordSet DS" field.
    • Post Type, allows populate the field with the information associated to a specific post type (like the products names in a Woocommerce, etc.)
    • Taxonomy, allows populate the field with the information of taxonomies.
    • And finally the User Data, with the data of users in WordPress.

    Note: Depending of control selected will be available all available datasources, or not.

So, suppose we want populate the field with the data stored in a database table.

  1. Select Database, from the list of datasources.
  2. If the database is different that used by WordPress, will be required enter the Host's address, the authentication data to connect to the database (username and password), and the name of database(a host can include multiple databases). There is a button for testing the database connection.

    Note: If the database is the same used by WordPress, leave empty the fields above.

Now its time to define the query to database

  1. Enter the name of table's column, that store the control's values. If you are using the Drop-down DS control, it has multiple options; each option of drop-down list includes a value and text; in this option you determine the column in the table that includes the values of options.
  2. Enter the column's name that stores the control's texts. Similar to the previous step, but in this case the column stores the texts of the options (in case of checkbox or radio buttons, this column contain the label of options)
  3. Type the table name, a database can include multiple tables, you should identify the table you are using.
  4. Type a condition if required. If you want filtering the values to display in the control, type the condition in this attribute. For example, suppose you want load the data of posts that are public, the condition in this case would be: post_status='publish', where post_status is the name of column, and publish is the value for filtering.
  5. The "Order by" is used to order the query results by the values in columns, and not by the order that data were stored in database. For example, suppose you want populate the control with the users names of WordPress, and you want order the results alphabetically, in this case the "order by" would be: display_name ASC, where display_name is the column's name, and will be ordered in ascending way.
  6. Limit, enter an integer number to reduce the number of query results.

If your query is very complex, and you prefer create it manually; selects the option "Custom Query", but in this case you should type all the query. Pay attention because you should use alias in the "SELECT" clause, to indicate the colum used to get the values, and the column used to get the texts. For example, a hypothetical query:

SELECT column1 AS value, column2 AS text FROM tablename WHERE column3 > 5 ORDER BY column2 ASC LIMIT 5

The use of database as datasource, allows filtering the information to populate the fields with the values on other fields in the form, or javascript variable. The use of variables are only accepted in the "Condition" section ("WHERE" clause), and requires the format: <%varname%>. For example, to get the title of a post, filtering by its ID, if the id is defined through the fieldname3 field, the "Condition" attribute of the query would be: ID=<%fieldname3%>

How to use CSV files as datasource?

The CSV files can be used as data sources for fields with multiple choices (DropDown DS, Radio Btns DS, Checkboxes DS). The initial steps are similar to the previous section, but selecting the "CSV" option as data-source instead of selecting "Database".

A comma-separated values (CSV) file stores tabular data (numbers and text) in plain text. Each line of the file is a data record. Each record consists of one or more fields, separated by commas. The use of the comma as a field separator is the source of the name for this file format.

For CSV files, the plugin includes the attributes:

Select CSV file: allows to select between a local or online file. For local files, the field displays a file field for selecting the CSV file. For online files the field displays a text field for entering the URL to the CSV file.

Use headline: tick the checkbox if the first line of CSV file is a headline to identify the data in the next records.

Delimiter: enter the delimiter symbol used as the field separator on each record.

Press the "Import CSV" button to import the records into the form. This action will feed the lists "Select column for texts" and "Select column for values", that are used for selecting which fields will be used texts and values of the choices in the DS field.

Where the value is equal to: allows filtering the rows to include in the field. The value entered in the attribute must be equal to the value in the column selected for the field's values. It is possible to use the values in other fields in the form, or variables, for filtering the rows, similar to the "Database" datasource.

Using Recordset as datasource.

  1. Select the recordset option from the list of data sources.
  2. Select the "RecordSet DS" field from the list of recordsets.
  3. Type the property in the record to be used as the value of the DS field.
  4. Type the property in the record to be used as the value of the DS field.
  5. Enter the conditions for filtering.

    This clause require additional instructions, that are explained with an example:

    Assuming the values in the "RecordSet DS" fields, selected as datasource, is a list of records with the structure:

    {
    	'First Name' : 'John',
    	'Last Name' : 'Smith',
    	'Birth Date' : '1th Jan, 2001'
    }
    

    and you want populate a "Line Text DS" field with the "Birth Name" of the user "John Smith"

    Type the property name: Birth Date in the "value" attribute.

    Enter the properties for filtering in the condition field (pay attention to the use of the reserved word "record" in the conditions):

    record['First Name']=='John'&&record['Last Name']=='Smith'

Tips: Javascript is casesensitive, please, be careful with the properties names.

In the conditions can be used the following comparison operators:
equal to: ==
non equal to: !=
less than: <
less than or equal to: <=
bigger than: >=
bigger than or equal to: >=

And the logical operators:
and: &&
or: ||

Create dependencies between fields

Some fields, like radio groups, checkboxes and drop-down menu, allow dependencies in function to the option selected.

For example, suppose your form includes a radio-group control with multiple choices: - House, - Car, - Electrodomestics, and each of them, uses different attributes. The house requires fields for address, number of rooms, etc; the car requires a field for trademark, model, etc. and finally the electrodomestics, will need type of electrodomestic,and more. So, if you want display the fields, depending of choice selected:

  1. Select the radio group fied in the form editor.
  2. Press the "Show dependencies" link, in the choices area.
  3. and select the field to display if the choice is selected. If you need associate multiple fields to the choice, press the plus button and select the new fields.

The calculated fields allow dependencies too, but in function to its value. For example, if you are designing a form for selling electrodomestics, and you want display additional fields for finance the purchase, if the amount is bigger than or equal to $1000usd. In this case:

  1. Select the calculated field.
  2. In the "Define dependencies" section, select a rule in the "if the value is" dropdown, and enter the value in the input box.
  3. Select the field to display in case that the rule be valid. Using the "plus" buttons it is possible define multiple rules, or associate more than one field to the same rule.

Create dependencies with other fields. It is possible create dependencies with Dropdown fields, checkboxes, radio buttons, and calculated fields. To define dependencies with other fields, would be necessary to use Calculated Fields as auxiliary fields. Simply, should to use the field as part of the equation associated with the calculated field, and create dependencies rules in function to the equation's result. The auxiliary fields are not relevant in the form's interface, to hide them, tick the checkbox: "Hide Field From Public Page"

Settings area of the forms

For each form you will be able to edit the following settings:

Form Builder: Already explained in the previous sections (see above).

Define Texts

Texts Section

Area were define the texts for the general elements in the form

  • Submit button label: The caption of submit button.
  • Previous button label: The caption of the previous button.
  • Next button label: The caption of next button.
  • Captcha label: The title of Captcha section.
  • Refresh captcha: The message to refresh the Captcha code.
  • Security code label: Label to recommend entering the Captcha code.
  • Captcha required: Error message if the Captcha is empty.
  • Captcha error: Error message if the Captcha is wrong.
  • Payment options: Payment option text.
  • Coupon code label: Label used in the coupon section.
  • Page X of Y: Label of pages in a multi-page form. Uses the format: Page {0} of {0}
Validation Settings:

Validation Settings

This area contains the "texts" used for the validations. You can easily translate them to other languages.

  • is required: Error message for required field.
  • is email: Error message for email format.
  • is valid date (mm/dd/yyyy): Error message for date format.
  • is valid date (dd/mm/yyyy): Error message for date format.
  • is number: Error message if the value is not a number.
  • only digits: Error message if the value has not only digits.
  • under maximum: Error message if the value is not in the correct interval.
  • over minimum: Error message if the value is not in the correct interval.
Submit button and thank you page:

Submit button and thank you page

  • Display submit button?: Adds a submit button to the form.
  • Thank you page (after sending the message): After the completing the payment (or after submit the form if the payment option is disabled) the user may be redirected to a page into your website (usually a "thank you" page). Type the page address into this field.
PayPal Payment Configuration:

PayPal Payment Configuration

  • Enable Paypal Payments: Allows to enable/disable the PayPal payment option.
  • PayPal mode: Select here if you want to process real payments (production mode) or you want to test the form with the PayPal Sandbox.
  • PayPal email: The email of the PayPal that will receive the payments.
  • Request cost: Select the field on the form that contains the amount to be paid. In most cases it will be a calculated field but it can be also a classic field.
  • Currency: The currency, example: USD, EUR, GBP, etc...
  • A $0 amount to pay means: Select "skip payment" for accepting 100% discount codes or select "let the user enter any amount" for accepting donations or open payment amounts. The "Base Amount" attribute has precedence over this attribute.
  • Base Amount: Allows to define a minimum amount to be charged through the form.
  • PayPal product name: The name that will appear to the customer at PayPal. It is possible to define the name of the product through a field in the form. For example, for defining the product name with the value entered in the fieldname3 field, should be entered the special tag <fieldname3> as the value of this attribute.
  • PayPal language: The language that will be used for the PayPal payment. It's any PayPal supported language.
  • Payment frequency: Select here if you will be requesting a one-time payment or a recurrent/subscription payment.

    For recurring payments it is possible define a first payment different to the recurring payments, and delay the first payment to offer a trial period.

  • Discount Codes: Use this section to define the accepted discount codes and the discount percent. A 100% discount means that the payment isn't required.
Form Processing / Email Settings:

Form Processing/Email Settings

  • "from" email: The email used as from in the notifications.

    It is strongly recommended the use of an email address in the website's domain. The main emails services (as Gmail, Hotmail, Yahoo, MSN, etc.) check the correspondence between the email address in the "Sender" header on emails, and the domains that send the emails. If the correspondence fails, the emails can be managed as Spam or as a "Phishing" email, in whose case would be deleted for security reasons.

  • Destination emails (comma separated): List of administrators that will receive the email notification.
  • Email subject: Subject of the notification email sent after completing the payment.
  • Include additional information?: Optional information about the user IP and browser.
  • Email format? Select if the email will be sent as plain-text or HTML-formatted.
  • Message: Content of the notification email that you will receive. Keep the tag <%INFO%>, it will be replaced automatically with the form data send by the user.
Email Copy to User:

Email Copy to User

  • Send confirmation/thank you message to user?: Select if you want to sent the "confirmation/thank you" message to the user.
  • Email field on the form: Select here the field that contains the user's email on the form.
  • Email subject: Subject of the email sent to the user after payment
  • Email format? Select if the email will be sent as plain-text or HTML-formatted.
  • Message: Content of the email sent to the user after payment. The tag <%INFO%> will be replaced by the information sent using the form, if needed.
Captcha Settings:

Captcha Settings

  • Use Captcha Verification?: Select if the captcha image will be used.
  • Width: Width of the captcha image.
  • Height: Height of the captcha image.
  • Chars: How many characters will appear in the captcha image.
  • Min font size: Minimum size used for the font (randomized).
  • Max font size: Maximum size used for the font (randomized).
  • Preview: Preview for checking how the captcha image will look.
  • Noise: Amount of noise to make it stronger.
  • Noise Length: Length of the noise to modify its look.
  • Background: Background color.
  • Border: Border color.
  • Font: Base font used to render the text. Four options already included.

Displaying Form Summary in the Thanks Page

  • Go to the thanks page
  • Press the icon indicated in the next image, to insert a shortcode with format [CP_CALCULATED_FIELDS_RESULT]

Insert Form Summary

The shortcode to insert in the thanks page allows a total control over the content to display with it.

In case to display all fields submitted with the form, is as simple as insert the shortcode: [CP_CALCULATED_FIELDS_RESULT]. But what to do if you want include in the thanks page only some of submitted fields, and not all?

The shortcode allows define the "fields" attribute, to select the fields names to include in the thanks page, separated by the comma symbol. For example, suppose the form has three fields: fieldname1, fieldname2, and fieldname3, but we want include only the fieldname1, and fieldname3, and exclude the fieldname2, in this case the shortcode would be:

[CP_CALCULATED_FIELDS_RESULT fields="fieldname1,fieldname3"]

But in some cases, we need more control over the content to display. By default, the shortcode is replaced by pairs of label-value for each field included in the thanks page. But what happen if you want display the label of fieldname1 in bold, or use a different label for the fieldname2, that the label used in the form?. In this case you should use the shortcode like a tag: [CP_CALCULATED_FIELDS_RESULT]...[/CP_CALCULATED_FIELDS_RESULT], and its content would be common HTML tags, with the field names using the same format that in the notification emails: <%fieldname#%>, to display only the label <%fieldname#_label%>, and to display only the value <%fieldname#_value%>. So, in this case the shortcode would be:

[CP_CALCULATED_FIELDS_RESULT]
<p><%fieldname1_label%>:<%fieldname1_value%></p>
<p>New Label: <%fieldname2_value%></p>
<p><%fieldname3%></p>
[/CP_CALCULATED_FIELDS_RESULT]

To get a complete list of the tags to use in the thank you page, read the section "SPECIAL TAGS IN THE NOTIFICATION EMAILS", in the "Settings & Add-Ons" tab.

Special tags in the notification emails and the thank you pages

There are special tags that can be used in the notification emails to display the forms information:

<%INFO%>, the tag <%INFO%> is replaced by the labels and values of fields that are submitted from the form.

To insert only specific fields, use the format <%fieldname#%>, for example, if you want include the fieldname1 and fieldname3 in the notification email, use the tags <%fieldname1%>, and <%fieldname3%>, the tag will be replace by the pair: label-value of field.

To insert only the field's label, use the format <%fieldname#_label%>, for example <%fieldname1_label%>

To insert only the shortlabel (that is used too in the CSV files), use the format <%fieldname#_shortlabel%>, for example <%fieldname1_shortlabel%>

To insert only the field's value, use the format <%fieldname#_value%>, for example <%fieldname3_value%>

To display all previous tags only if the fields have been filled by the users, you should use the attribute if_not_empty in the tags:

<%INFO if_not_empty%>
<%fieldname# if_not_empty%>
<%fieldname#_label if_not_empty%>
<%fieldname#_value if_not_empty%>

There are other special attributes to use in the tags. The values of the attributes are closed between the symbols {{...}}:

before: The attribute allows to define a symbol, or a HTML tag, to display before the field in the notification email <%fieldname# before={{<strong>}} after={{</strong>}}%>

after: The attribute allows to define a symbol, or a HTML tag, to display after the field in the notification email <%fieldname# after={{<br />}}%>

These attributes give a big control over the information included in the notification emails. For example, inserting a tag like:

<p><%fieldname1 if_not_empty%></p>

Inserts in the notification email, the pair of tags: <p></p>, if the value of the "fieldname1" field is empty. But if you inserts the previous tag with the attributes: before and after, like follow:

<%fieldname1 if_not_empty before={{<p>}} after={{</p>}} %>

The pair of tags <p></p> won't be inserted in the notification email, if the value of the fieldname1 field is empty.

separator: Allows to define a separator symbol to insert between the field's label, and its value. For example, if you insert the tag like: <%fieldname1 separator={{:}}%>, it would be replaced by field label : field value

There are some special tags to define dependencies in the notification emails: <%fieldname#_block%><%fieldname#_endblock%>

For example, to insert the fields: fieldname2 and fieldname3 in the email, only if the fieldname1 field was submitted, should be inserted the following tags in the email:

<%fieldname1_block%>
<%fieldname2%>
<%fieldname3%>
<%fieldname1_endblock%>

To include the URL to the uploaded file, if the file field is the fieldname1, the tag to insert in the email and thank you page would be: <%fieldname1_url%>, but if the fieldname1 supports multiple files, the corresponding tag would be: <%fieldname1_urls%>

To display the final price, after apply the discount if was defined, use the tag <%final_price%>

To display the coupon/discount applied, if was applied a discount, uses the tag <%coupon%>

To display the payment option selected, in case that PayPal has been set as optional, use the tag <%payment_option%>

To include an unique number that identifies the submitted data into the system, uses the tag <%itemnumber%>. This number allows to identify easier the PayPal transference, and could be used as an order reference.

To include the ip address of the user, <%ipaddress%>

To include the date in the format: mm/dd/yyyy, <%currentdate_mmddyyyy%>

To include the date in the format: dd/mm/yyyy, <%currentdate_ddmmyyyy%>

Create JavaScript variables to be used in the equations

- From GET, or POST parameters, SESSION variables, or COOKIES

JavaScript Variable

The icon with the "X" symbol, that appears when editing the contents of pages or posts, inserts a shortcode in the content with the structure:

[CP_CALCULATED_FIELDS_VAR name="..."]

The ... symbol should be replaced by the parameter or variable name, and will be the same name of the javascript variable. For example: [CP_CALCULATED_FIELDS_VAR name="varname"]

To restrict the source of variable, define the attribute "from" in the shortcode with any of following values: get, post, session, or cookie. For example, to create the javascript variable: varname, only if exist a session variable with the same name, insert the shortcode: [CP_CALCULATED_FIELDS_VAR name="varname" from="session"]

The shortcode: [CP_CALCULATED_FIELDS_VAR] accepts two other attributes:

Definig default values

The "default_value" attribute allows to define the value used by default if there is not a parameter with the specified name, or session variable or cookie:

[CP_CALCULATED_FIELDS_VAR name="varname" default_value="mydefault"]

If there is not a parameter, or session variable, or cookie, with the name "varname", the plugin will create a global javascript variable with the name: "varname", and value: "mydefault".

Create direct variables

The attribute: "value", allows to create a javascript variable with the name defined as attribute, and the value in the attribute: "value".

[CP_CALCULATED_FIELDS_VAR name="varname" value="myvalue"]

After insert the shortcode to create the javascript variable, a valid equation would be: fieldname1*varname

Create a direct variable through the Forms Shortcode

There is another way to create global variables to be used in the equations, directly from the form's shortcode. All attributes in the shortcode, except the "id" that identifies the form, are converted in javascript variables with global scope, whose names correspond to the variable name, and their values, the attributes' values:

[CP_CALCULATED_FIELDS id="1" varname="varvalue"]

It is possible create multiple variables, defining multiple attributes.

The variables created through the form's shortcode have a particularity, for each global variable will be created another one with the structure: <variable name>_arr, for example: if the shortcode is:

[CP_CALCULATED_FIELDS id="1" varname="varvalue"]

The plugin will create two varaibles, the global variable: varname whose value would be varvalue, and the varname_arr variable, whose value is a hash with the varvalue as one of their items.

How to access to the value of the varname_arr?

Simply should be called the varname_arr variable, using as the index, the form_identifier constant: fieldname1*varname_arr[ form_identifier]

Pay attention to this way to access to the variables generated through the form shortcode. If there are multiple shortcodes inserted in the same page, and all of them define a same variable, accessing to the variable name through the scheme: <variable name>_arr[ form_identifier], each form will have its own value for the variable, because the global variable <variable name> will have only the latest value defined.

Add-Ons

The list of add-ons available in the plugin, appear in the "Add-ons area" of settings page of the plugin. For enabling the add-ons, simply should tick the corresponding checkboxes, and press the "Activate/Deactivate Addons" button.

Add-ons

WooCommerce add-on

The developer version of the plugin includes the WooCommerce add-on, to integrate the forms created by the "Calculated Fields Form" with the WooCommerce products. The add-on inserts an additional metabox in the WooCommerce products, with multiple settings fields:

  • Enter the ID of the form: Allows select the form that will be associated to the product.
  • Calculate the product price through the form: Allows calculate the price of the products through the form.
  • Minimum price allowed: The minimum price applied to a product.
  • Activate the summary: Allows customize the fields included in the cart page of WooCommerce.
  • Summary title: Enter the summary title.
  • Summary: Define the summary, are accepted all special tags supported by the notification emails and the thank you page.

Note: If you want calculate the price of products through the form, will be required that you select the field of the price in the attribute: "Request cost" in the form's settings.

WooCommerce Add-on

Google Analytics add-on

Google Analytics Add-on

The platinum version of the plugin includes the "Google Analytics" add-on to generate the usage reports in "Google Analytics" about the interactions of users with the form. The add-on adds a new metabox in the forms settings, to configure the events and exceptions that are sent to "Google Analytics" and when:

Google Analytics Settings

  • Enter the property ID: property ID generated in Google Analytics.
  • Send Fields section: enter the form's fields (fieldname#), and select the information to be sent to Google Analytics, and when.

Sends a hit of "Event" type for every onfocus event triggered by the field. The hits can include the field's label, and it is possible to decide if send only one hit by field, or for each "onfocus" event in the field. The hits are sent with the event's category: "form", and the event action: "focus", the label of the event includes the form's id, the field's name, and the field's label, if the corresponding option was ticked.

  • Send Events section: tick the checkbox corresponding to each event to be reported to Google Analytics.

Sends a hit of "Event" type if the form is loaded, or for every action: "Next Page", "Previous Page", or "Submit". The hits are sent with the event's category: "form", and the events' actions: "load", "next page", "previous page", and "submit", respectively. Each event includes a label with the form's id, and in case of next and previous page events, the page number. The events "next page" and "previous page" allow to know the pages that are reached by the users, and identify problems in the form's structure. The "submit" event allows to know how many users complete the form, comparing the amount of "submit" events with the "load" events.

  • Send Exceptions section: tick the checkbox corresponding to the exceptions to be reported to Google Analytics.

Sends a hit of "Exception" type in every failed submission by an incorrect "CAPTCHA" code. It allows to know if the "CAPTCHA" images are difficult to read, and modify its settings to solve the issue.

SalesForce add-on

The add-on allows create new leads in the SalesForce account with the data submitted by the forms.

To create new leads in SalesForce with the data submitted by a form, be sure that the SalesForce account has enabled the Web-to-lead option, and then go to the form's settings:

  • Enter the OID (Organization ID)
  • For debugging the lead creation, tick the "Enabling debug" option, and enter the email address where receive the information. For production, untick the debugging option.
  • Press the "Add attribute" button, select the Lead attribute, and enter a fixed text, or the name of the field in the form (fieldname#)

Note: The Add-on includes the list of predefined attributes of Leads, but it is possible to enter custom attributes too.

SalesForce Add-on

WebHook add-on

The add-on allows posting the submitted information by the forms to WebHooks URLs. With the WebHook add-on it is possible integrate the forms created by the plugin with services like Zapier. The Zapier connects services as important and popular as Zoho CRM, Dropbox, Mailchimp, Evernote, Google Drive, Facebook, Twitter, and more than 300 services(Zapier apps)

Use this add-on is as simple as entering the WebHooks URLs, through the CFF-WebHook section in the forms settings. To associate a form with multiple WebHooks, simply press the "Add new url" button, to add a new input field.

Note: About Zapier service, select Webhook as the Trigger app, and "Catch Hook" as the trigger for this app.

WebHook Add-on

Users Permissions add-on

The new add-on: "Users Permissions", allows restrict the access to the forms, and associate the submitted information to the submitter.

The options to restrict the access to the form are: Only for registered users, for registered users with specific roles, or allow the access to the form only to specific users.

With the "Users Permissions" add-on it is possible restrict the number of submissions to only one by user.

The add-on includes a new shortcode: [CP_CALCULATED_FIELDS_USER_SUBMISSIONS_LIST], to display the list of submissions belonging to an user. If the shortcode is inserted without attributes, the list of submissions will include those entries associated to the logged user. This shortcode accepts two attributes: id, for the user's id, and login, for the username (the id attribute has precedence over the login), in whose case the addon will list the submissions of the user selected. The add-on allows to define the summary of the submitted data that will displayed in the list of submissions. Enter the summary's structure in the "Summary" attribute. In the summary can be use all the special tags, available for the notification emails, and the thank you pages.

The add-on allows to assign permissions for "edit" or "delete" the entries. Actually, the submissions are not deleted, or its data modified from these actions, the real control over the data is only for the website's administrator. In the first case, the submission will be disabled, and will be hidden from the list of user's submissions, but the submission is always accessed by the website administrator through the messages section, and if the data are edited, the original entry will be disabled, and a new entry is generated and associated to the user.

There are other features included by this add-on, the "Messages" section is modified to include in the list of submissions the name of the submitter, furthermore, includes a new input field for filtering the events by users.

Users Permissions Add-on

reCAPTCHA add-on

The add-on allows to protect the forms using the Google reCAPTCHA instead of the captcha distributed with the plugin. reCAPTCHA is more visual and intuitive than the traditional captcha, with just a single click the users confirm they are not a robot.

reCAPTCHA (its official name is No CAPTCHA reCAPTCHA) as they define themselves:

reCAPTCHA is a free service that protects your website from spam and abuse. reCAPTCHA uses an advanced risk analysis engine and adaptive CAPTCHAs to keep automated software from engaging in abusive activities on your site. It does this while letting your valid users pass through with ease.

reCAPTCHA offers more than just spam protection. Every time our CAPTCHAs are solved, that human effort helps digitize text, annotate images, and build machine learning datasets. This in turn helps preserve books, improve maps, and solve hard AI problems.

To use reCAPTCHA in your forms, activate the add-on in the the settings page of the plugin, through the menu option: "Settings/Calculated Fields Form", tick the checkbox: "CFF - reCAPTCHA", and press the "Update" button.

The activation of reCAPTCHA displays a new section for entering the site key, and the secret key, two keys provided by Google reCAPTCHA to protect the website, and validate the forms submissions respectively.

reCAPTCHA Add-on

PayPal Pro add-on

PayPal Pro Add-on

With Payment Form for PayPal Pro you can insert a form into a WordPress website and use it to process credit card payments directly into your website without navigating to an external payment page.

You can check the differences betwen PayPal Pro and PayPal Standard at https://www.paypal.com/webapps/mpp/compare-business-products

For integrating PayPal Pro you must have a PayPal Pro account. In addition to that a SSL connection is also needed, the SSL connection isn't a technical requirement since the plugin can work without it but anyway it is strongly recommended for accepting credit cards into your website, otherwise the transactions won't be secure.

In the settings area the following information is needed to activate and link the PayPal Pro account to the form:

  • Enable PayPal Pro: Select "Yes" to enable PayPal Pro. This selection will disable automatically the PayPal Standard option.
  • PayPal Pro - API UserName: The API Username provided by PayPal into your account.
  • PayPal Pro - API Password: The API Password provided by PayPal into your account.
  • PayPal Pro - API Signature: The API Signature provided by PayPal into your account.
  • PayPal Pro - Currency: The currency for the payments, a valid PayPal currency code, example: USD, CAD, AUD, GBP, ...
  • Paypal Mode: Select "Sandbox" for testing purposes and "Production" for charging real payments.

When enabled, the form on the public website will display an additional set of fields to request the data needed to process the payment, like for example the billing address, credit card details. This info is only for the payment processing, as mentioned it won't be stored into the website for security reasons.

After the submission Once the payment is processed and the posted data (excluding the credit card related information) is saved into the WordPress database.

Upload add-on

The "Upload Files" add-on allows to add the uploaded files through the forms to the Media Library, and access to them from the pages and posts of website.

Furthermore, it allows to include the support of new mime types, than files format supported by default by WordPress.

Upload Files Add-on

To add the uploaded files to the "Media Library" ticks the checkbox: "Add the uploaded files to the media library".

WordPress supports some specific mime types, for supporting new mime types, you simply should enter the files' extensions separated by comma.

DropBox Integration add-on

The "DropBox Integration" add-on allows to copy or move the uploaded files through the forms to a DropBox.

DropBox Add-on

Enter the Token Access to access the DropBox account.

To remove the copies of files from the WordPress website, tick the checkbox: "Delete the local copy of file".

Note: To copy the files to the DropBox account is required create a DropBox App, and generate a token access.

Access your account, to the reserved area where configure an App: https://www.dropbox.com/developers/apps/create

  1. Select the "Dropbox API" option.
  2. Select the "App folder" option.
  3. Enter the application name.
  4. Press the "Create app" button.

In the next screen press the "Generate" button to generate an access token

Finally, copy the generated access token to be used with the add-on.

ip2location add-on

The add on integrates the Calculated Fields Form with the ip2location databases to identify additional information of users based on their IP, as: Country, City Name, Coordinates, Weather Station, Time Zone, ZIP Code, etc...

Note: Requires PHP 5.3 and over.

ip2location Add-on

Uplods the ip2location database's file to the correct location in the webserver (/wp-content/uploads/), and then, enters the file's name in the add on settings

Tick the checkboxes of the information you want get of users.

If has been selected the option to include the users information in the notification emails, and the add-on is enabled, the notification email will include all extracted data.

Google Places add-on

Google Places Add-on

The add-on integrates the input fields in the form with the Google Places API to autocomplete the address entered by the users. The user only need to start typing the address, and the add-on displays a list of addresses matching with the typed text.

Google Places Add-on

To activate the add-on, simply visit the plugin page through the menu option: "Settings/Calculated Fields Form", tick the checkbox: "CFF-Google Places", and press the "Update" button...

Google Places Add-on

...the plugin displays a new dialog for entering the Google API Key. The Key is not required, but it allows searching by more places than the use of the free API.

Google Places Add-on

From the form's settings, selects the fields to associate with the Google Places API. It is possible apply the Google Places API to multiple fields in the form.

Signature add-on

Signature Add-on

The add-on converts the form fields selected in "Signature" fields, allowing the users to sign with the mouse or directly in the touchscreens.

Signature Add-on

To activate the add-on, simply visit the plugin page through the menu option: "Settings/Calculated Fields Form", tick the checkbox: "CFF-Signature", and press the "Update" button.

Signature Add-on

From the form's settings, selects the fields to convert in Signature fields. It is possible convert multiple fields in the form in signature fields.

Signature settings:

Color: the color code for signatures. For example: #000000

Line thickness: an integer number defining the line thickness of the signature.

Show guideline: checkbox to include or not a guideline in the signature fields.

Guideline color: the color code for guideline. For example: #000000

WebMerge add-on

WebMerge Document

The add-on sends the information collected by the form to the WebMerge service to generate a PDF file or Office document at runtime. Furthermore the generated document can be send to the user.

WebMerge Add-on

To activate the add-on, simply visit the plugin page through the menu option: "Settings/Calculated Fields Form", tick the checkbox: "CFF-WebMerge", and press the "Update" button...

WebMerge form settings

After activate the WebMerge add on, the form settings will include a new section for entering the URL to the WebMerge document, and the correspondence between the variables in the document, and fields in the form.

Pressing the "Add a New Document" button it is possible to associate multiple documents to a same form, and pressing the "Add Field" button it is possible associate multiple variables and form fields to a document.

WebMerge Document URL

Each document in WebMerge has its own URL with the corresponding ID and Key code.

MailChimp add-on

MailChimp Logo

The add-on creates new members in the MailChimp service with the information collected by the forms in the website: www.mailchimp.com.

MailChimp is an online email marketing solution to manage subscribers, send emails, and track results.

MailChimp Subscribers

To activate the add-on, simply visit the plugin page through the menu option: "Settings/Calculated Fields Form", tick the checkbox: "CFF-MailChimp", and press the "Update" button...

MailChimp Add-On

After activate the MailChimp add-on, the form settings will include a new section to create the correspondence between the signup form associated to a list in MailChimp, and the form fields in the form created with the "Calculated Fields Form" plugin.

MailChimp Settings

  1. Enter the API Key.
  2. Press the "Get Lists" button. The action generates a list with all "Lists" associated to the MailChimp account.
  3. Select the list and press the "Get Fields and Groups" button. The action displays multiple input fields, for connecting the fields in the form with the fields in the signup form of to the list, and the interests groups defined in MailChimp, that are displayed in the public form too to be selected by the users.

Authorize.Net Server Integration Method (www.authorize.net) add-on

Authorize.Net

The Authorize.net Server Server Integration Method (Authorize.net SIM) is a hosted payment processing solution that handles all of the steps in processing a transaction, including:

  • Collecting customer payment information through a secure, hosted form
  • Generating a receipt to the customer
  • Securely transmitting to the payment processing networks for settlement
  • Funding of proceeds to the merchant's bank account
  • Securely storing cardholder information

Authorize.net SIM is an ideal integration solution because merchants are not required to collect, transmit, or store sensitive cardholder information to process transactions. Additionally, Authorize.net SIM does not require merchants to purchase and install a SSL or TLS digital certificate, reducing the complexity of securely handling and storing cardholder information, simplifying compliance with the Payment Card Industry (PCI) Data Security Standard. For more information go to www.authorize.net

Authorize.Net Add-On

To activate the add-on, simply visit the plugin page through the menu option: "Settings/Calculated Fields Form", tick the checkbox: "CFF-Authorize.net Server Integration Method", and press the "Activate/Deactivate addons" button

Authorize.Net settings

In the settings area the following information is needed to activate and link the Authorize.net Server Integration Method account to the form:

Enable Authorize.net SIM?: Select "Yes" to enable the Authorize.net Server Integration Method payment.

Mode: Change the mode between "test" for testing purposes and "production" for accepting real payments.

API Username: Change this value with API Username received from Authorize.net.

API Key: Change this value with API Key received from Authorize.net.

Receipt URL: User will return here after a successfull payment. Important!: You must also configure the receipt link URL in the Merchant Interface.

Cancel URL: User will return here if payment fails.

In addition to the above required setting fields there are other fields to link the form fields to the Authorize.net payment form, like for example the client name, address, phone, email, ... These fields are optional. To link the fields you can indicate the ID of the field on the form that contains the related info. Sample values: fieldname1, fieldname2, ..

When enabled, the customer will be redirected to the Authorize.net Server Integration Method payment form after the submision. The process will be similar to the way PayPal Standard works.

Skrill (www.Skrill.com) add-on

Skrill

The Skrill Payments addon provides a secure interface for accepting payments through a secure page. You can accept cards, more than 20 local payment methods and over 80 direct bank transfer connections with a single integration. Form more information go to https://www.skrill.com/en/merchants/

Skrill Add-On

To activate the add-on, simply visit the plugin page through the menu option: "Settings/Calculated Fields Form", tick the checkbox: "CFF-Skrill Payment Integration", and press the "Activate/Deactivate addons" button.

Skrill settings

In the settings area the following information is needed to activate and link the Skrill account to the form:

Enable Skrill Payments?: Select "Yes" to enable the Skrill Payments Integration.

Skrill Email?: Emai linked to the Skrill merchant account, this will be the account that will receive the payments.

Receipt URL: User will return here after a successfull payment.

Cancel URL: User will return here if payment fails.

Currency: Currency code for the received payment. example: USD, EUR, CAD, GBP ....

When enabled, the customer will be redirected to the Skrill hosted payment form payment form after the submision. The process will be similar to the way PayPal Standard works.

TargetPay (iDeal) add-on

TargetPay (iDeal)

The TargetPay addon provides integration with iDeal, the most popular Dutch payment method. The integration is made via TargetPay: https://www.targetpay.com/info/ideal?setlang=en

With TargetPay you can set up iDEAL payments for your website easily. Acting as a "Payment Service Provider" it aggregates payments for a large number of webstores. The iDEAL platform combines the online banking systems of 10 of the largest Dutch banks (ABN AMRO, ASN Bank, Bunq, ING, Knab, Rabobank, RegioBank, SNS Bank, Triodos Bank and van Lanschot) into one payment method.

After the consumer selects the iDEAL payment method the consumer's bank is selected. The actual payment then takes place in the bank's trusted online banking environment for which security is guaranteed by the bank. Through iDEAL buyer and seller are guaranteed a transparent transaction without hidden fees or other unpleasant surprises.

TargetPay (iDeal) Add-On

To activate the add-on, simply visit the plugin page through the menu option: "Settings/Calculated Fields Form", tick the checkbox: "CFF-iDeal TargetPay", and press the "Activate/Deactivate Addons" button.

TargetPay (iDeal) settings

In the settings area the following information is needed to activate and link the iDeal-TargetPay account to the form:

Enable iDeal-TargetPay?: Select "Yes" to enable the iDeal-TargetPay payment option for the form.

RTLO Subaccount ID: Change this value with the account ID received from iDeal-TargetPay.

If payment fails return to this page: Return page if the payment fails or is cancelled before completing it.

Payments Mode: Change the mode between "test" for testing purposes and "production" for accepting real payments.

When enabled, the customer will be redirected to the iDeal-TargetPay payment form after the submision. The process will be similar to the way PayPal Standard works.

Mollie (iDeal) add-on

iDeal

The Mollie addon provides integration with iDeal, the most popular Dutch payment method. The integration is made via Mollie: www.mollie.com.

You're easily connected to iDEAL through Mollie without the dreaded technical and administrative hassle. The iDEAL platform combines the online banking systems of 10 of the largest Dutch banks (ABN AMRO, ASN Bank, Bunq, ING, Knab, Rabobank, RegioBank, SNS Bank, Triodos Bank and van Lanschot) into one payment method.

After the consumer selects the iDEAL payment method the consumer's bank is selected. The actual payment then takes place in the bank's trusted online banking environment for which security is guaranteed by the bank. Through iDEAL buyer and seller are guaranteed a transparent transaction without hidden fees or other unpleasant surprises.

Mollie (iDeal) Add-On

To activate the add-on, simply visit the plugin page through the menu option: "Settings/Calculated Fields Form", tick the checkbox: "CFF-iDeal Mollie", and press the "Update" button...

Mollie (iDeal) form settings

In the settings area the following information is needed to activate and link the Mollie - iDeal account to the form:

Enable iDeal-Mollie?: Select "Yes" to enable the Mollie - iDeal addon. This selection will disable automatically the PayPal Standard option.
Mollie API Key: The API Username provided by Mollie for your account, it may be the test key or the production key.
If payment fails return to this page: If the payment fails the customer is redirected to the page indicated in this field.

When enabled, the customer will be redirected to the Mollie - iDeal payment form after the submision. The process will be similar to the way PayPal Standard works.

RedSys / Servired / Sermepa add-on

RedSys Document

The RedSys / Servired / Sermepa addon provides a secure interface for accepting credit card payments through most banks in Spain (Sabadell, Banco Popular, BBVA, Santander, Bankia, Caixa, Bankinter, etc...). You can read more about RedSys at www.redsys.es.

RedSys TPV Add-On

To activate the add-on, simply visit the plugin page through the menu option: "Settings/Calculated Fields Form", tick the checkbox: "CFF-RedSys TPV", and press the "Update" button...

RedSys TPV form settings

In the settings area the following information is needed to activate and link the RedSys account to the form:

Enable TPV: Select "Yes" to enable the RedSys TPV. If "Pay Later" or "PayPal" are also selected in this option, a radiobutton will appear in the form to select if the payment will be made with RedSys, with PayPal or if the form will be submitted without payment.
CÓDIGO COMERCIO: The API Username provided by RedSys or your bank.
CLAVE SECRETA: The API Password provided by RedSys or your bank.
Mode: Select "Sandbox" for testing purposes and "Production" for charging real payments.

When enabled, the customer will be redirected to the RedSys payment form after the submision. The process will be similar to the way PayPal Standard works.

PayTM add-on

PayTM

The PayTM addon provides a secure interface for accepting payments through credit card, debir cards, net banking, wallet and EMI. With over 100mn Paytm users in India, your customers will love the option to pay with their trusted Paytm Wallet. You can read more about PayTM at paywithpaytm.com.

PayTM Add-On

To activate the add-on, simply visit the plugin page through the menu option: "Settings/Calculated Fields Form", tick the checkbox: "CFF-PayTM", and press the "Update" button...

PayTM form settings

In the settings area the following information is needed to activate and link the PayTM account to the form:

Enable PayTM?: Select "Yes" to enable the PayTM payment gateway. This selection will disable automatically the PayPal Standard option.
Merchant ID: The Merchant ID provided by PayTM.
Merchant Key: The Merchant Key provided by PayTM.
Website Name: The Website Name provided by PayTM.
Industry Type ID: The Industry Type ID provided by PayTM.
Mode: Select "Sandbox" for testing purposes and "Production" for charging real payments.

When enabled, the customer will be redirected to the PayTM payment form after the submision. The process will be similar to the way PayPal Standard works.

SagePay add-on

SagePay

The SagePay addon provides a secure interface for accepting payments through SagePay. You can read more about SagePay at www.sagepay.co.uk.

SagePay Add-On

To activate the add-on, simply visit the plugin page through the menu option: "Settings/Calculated Fields Form", tick the checkbox: "CFF-SagePay", and press the "Update" button...

SagePay form settings

In the settings area the following information is needed to activate and link the SagePay account to the form:

Enable SagePay?: Select "Yes" to enable the SagePay payment gateway. This selection will disable automatically the PayPal Standard option.
Vendor ID: The Vendor ID provided by SagePay.
SagePay Encrypt Password: The SagePay Encrypt Password provided by PayTM.
Mode: Select "Sandbox" for testing purposes and "Production" for charging real payments.

When enabled, the customer will be redirected to the SagePay payment form after the submision. The process will be similar to the way PayPal Standard works.

Sage Payment add-on

Sage Payment

The SagePayments addon provides a secure interface for accepting payments through a secure SSL checkout system for both bankcard and virtual check transactions. All authorized and approved transactions will be delivered into your current bankcard and/or virtual check batches viewable within the Virtual Terminal for order processing and settlement. You can read more about Sage Payment Solutions at http://www.sage.com/us/sage-payment-solutions/accept-payments. The integration implemented in this addon is for Sage Payment Solutions >> Shopping ExpressPay

Sage Payment Add-On

To activate the add-on, simply visit the plugin page through the menu option: "Settings/Calculated Fields Form", "CFF-SagePayments Payment Gateway", and press the "Update" button.

Sage Payment form settings

In the settings area the following information is needed to activate and link the Sage Payment Solutions >> Shopping ExpressPay account to the form:

Enable SagePayments?: Select "Yes" to enable the SagePayments TPV. This selection will disable automatically the PayPal Standard option.

Merchant ID (M_id): Change this value with M_id received from SagePayments.

In addition to the mentioned two required setting field there are other fields to link the form fields to the Sage Payment Solutions payment form, like for example the client name, address, phone, email, tax and shipping cost. These fields are optionals and to link the fields you can indicate the ID of the field on the form that contains the related info. Sample values: fieldname1, fieldname2, ...

When enabled, the customer will be redirected to the Sage Payment Solutions payment form after the submision. The process will be similar to the way PayPal Standard works.

Equations Format for Calculated Fields

The equations allowed by the plugin "Calculated Fields Form" are really powerful tools.

It is possible create simple equations like follow:

With simple mathematical operations:

fieldname1+fieldname2

fieldname1*fieldname2

fieldname1/fieldname2

fieldname1-fieldname2

or mathematical equations with multiple fields and fields grouping included.

fieldname1*(fieldname2+fieldname3)

The equations may include a group of more specific operations

some of them available as buttons in the plugin's interface, the other operations should be typed manually in the equation's editor:

Operation Description Demo
abs(x) Returns the absolute value of x

If the value of fieldname1 is -7.25, the result of: abs(fieldname1) would be 7.25

acos(x) Returns the arccosine of x, in radians

If the value of fieldname1 is 0.5, the result of: acos(fieldname1) would be 1.0471975511965979

asin(x) Returns the arcsine of x, in radians If the value of fieldname1 is 0.5, the result of: asin(fieldname1) would be 0.5235987755982989
atan(x) Returns the arctangent of x as a numeric value between -PI/2 and PI/2 radians If the value of fieldname1 is 2, the result of: atan(fieldname1) would be 1.1071487177940904
atan2(x,y) Returns the arctangent of the quotient of its arguments If the value of fieldname1 is 8 and fieldname2 is 4, the result of: atan2(fieldname1,fieldname2) would be 1.1071487177940904
ceil(x) Returns x, rounded upwards to the nearest integer If the value of fieldname1 is 1.4, the result of: ceil(fieldname1) would be 2
cos(x) Returns the cosine of x (x is in radians) If the value of fieldname1 is 3, the result of: cos(fieldname1) would be -0.9899924966004454
exp(x) Returns the value of E^x If the value of fieldname1 is 1, the result of: exp(fieldname1) would be 2.718281828459045
floor(x) Returns x, rounded downwards to the nearest integer If the value of fieldname1 is 1.6, the result of: floor(fieldname1) would be 1
log(x) Returns the natural logarithm (base E) of x If the value of fieldname1 is 2, the result of: log(fieldname1) would be 0.6931471805599453
logab(x,y) Returns the logarithm of x base y If the value of fieldname1 is 2, and the value of fieldname2 is 10, the result of: logab(fieldname1,fieldname2) would be 0.30102999566398114
max(x,y,z,...,n) Returns the number with the highest value If the value of fieldname1 is 5 and fieldname2 is 10, the result of: max(fieldname1, fieldname2) would be 10
min(x,y,z,...,n) Returns the number with the lowest value If the value of fieldname1 is 5 and fieldname2 is 10, the result of: min(fieldname1, fieldname2) would be 5
pow(x,y) Returns the value of x to the power of y If the value of fieldname1 is 4 and fieldname2 is 3, the result of: pow(fieldname1, fieldname2) would be 64
random() Returns a random number between 0 and 1  
round(x) Rounds x to the nearest integer If the value of fieldname1 is 2.5, the result of: round(fieldname1) would be 3
sin(x) Returns the sine of x (x is in radians) If the value of fieldname1 is 3, the result of: sin(fieldname1) would be 0.1411200080598672
sqrt(x) Returns the square root of x If the value of fieldname1 is 9, the result of: sqrt(fieldname1) would be 3
tan(x) Returns the tangent of an angle If the value of fieldname1 is 90, the result of: tan(fieldname1) would be -1.995200412208242
gcd(x,y) Returns the greatest common divisor between x and y If the value of fieldname1 is 16, and the value of the fieldname2 is 12 the result of: gcd(fieldname1,fieldname2) would be 4

Pay special attention to the next two operations. The first of them, very extended its use in equations for calculations the cost of products and services, and the other one to obtain a date.

Operation Description Demo
prec(x,y) Return the x number with y decimal digits

If the value of fieldname1 is 10.33323, the result of: prec(fieldname1,2) would be 10.33

If the value of fieldname1 is 10.3365, the result of: prec(fieldname1,2) would be 10.34

If the value of fieldname1 is 10, the result of: prec(fieldname1,2) would be 10.00

cdate(x, format) Returns the number x formatted like a Date, the second parameter defines the format of the output date ('mm/dd/yyyy', 'dd/mm/yyyy'). The number represents the number of days from Jan 1, 1970

If fieldname1 is a date field, and its value is 3/11/2013: cdate(fieldname1+10) would be 13/11/2013

Sample valid equations:

To calculate the monthly payment in a lease calculator:

The fields implied are:

Load amount: fieldname1

Residual value: fieldname2

Interest rate %: fieldname3

Number of months: fieldname4

The corresponding equation for monthly payment is:

prec((fieldname1*fieldname3/1200*pow(1+fieldname3/1200,fieldname4)-fieldname2*fieldname3/1200)/(pow(1+fieldname3/1200,fieldname8)-1),2)

There is a huge number of equations that can't be recreated with simple mathematical operators, or the operations listed above.

Operation Description Demo

Pay attention to the following sample:

In your form there are four fields: fieldname1, fieldname2, fieldname3 and the calculated field: fieldname4, but the value of fieldname4 is dependent of fieldname3 value, that is:

The value of fieldname4 will be: fieldname1+fieldname2, if the value of fieldname3 is greater than 100, or will be: fieldname1*fieldname2, if the value of fieldname3 is less than or equal to 100. Neither of previous operations, by itself, can calculate the value of fieldname4.

To solve complex cases like this, the "Calculated Fields Form" plugin allows entering javascript code directly in the equation editor, like the following sample:

(function(){

if(fieldname3 > 100) return fieldname1+fieldname2;

if(fieldname3 <= 100) return fieldname1*fieldname2;

})();

For complex equations where is required to define blocks of javascript code, you must use the following format:

(function(){

//Your code here

})();

and the return the value of that function will be the value assigned to the calculated field:

return fieldname1+fieldname2;

Pay attention, the plugin removes the changes of lines from the equations at runtime. So, if the equation is defined with the "function" format:

(function(){

//Your code here

})();

It is really important to include the semicolon symbols (;) at the end of the code lines, furthermore, if the equation is really complex, and you want to include comments for future references, should be used the format for multiple lines comments: /* comment here */, but never the format for single line of comments: // comment here

Logical Module

The logical module include the following functions:

Function Description Demo
IF(condition, value if true, value if false) Checks whether a condition is met, and returns one value if true, and another if false.IF(logical_test, value_if_true, value_if_false)

If the value of fieldname1 is 10 and the value of fieldname2 is 20, the result of:

IF(fieldname1 < fieldname2, fieldname1, fieldname2)
would be 10

AND(x,y,z,....) Checks whether all arguments are true, and return true if all values are true, and false in another way. AND(logical1,logical2,...)

Suppose there are three fields, fieldname1, fieldname2 and fieldname3, with values: 10, 20 and 30 respectively, so:

AND( fieldname1<100, fieldname2<100, fieldname3<100)
would be true

but

AND( fieldname1<100, fieldname2<100, fieldname3<25)
is false, because the fieldname3 is bigger than 25

OR(x,y,z,....) Checks whether any of arguments is true, and return true if any of values is true, and false if all values are false. OR(logical1,logical2,...)

Suppose there are three fields, fieldname1, fieldname2 and fieldname3, with values: 10, 20 and 30 respectively, so:

OR( fieldname1<100, fieldname2<100, fieldname3<25)
is true, because at least the two initial conditions are true, inclusive if the third condition fails.

but

OR( fieldname1<5, fieldname2<5, fieldname3<25)
is false, because the three conditions fail

NOT(x) Changes false to true, or true to false.NOT(logical)

NOT(true)
return false

NOT(false)
return true

IN(x,[x,y,z,....]) Checks whether the term is included in the second argument, the second argument may be a string or strings array. IN(term, string/array)

IN(10,[10,20,30,40])
Return true

IN('world', 'hello world')
Return true

Financial Module

The module includes a pack of functions to improve the implementation of financial equations.

Operation Description Demo
CALCULATEPAYMENT(x,y,z)

Calculates the Financed Payment Amount
Three parameters: amount, months, interest rate (percent)

Ex: CALCULATEPAYMENT(25000, 60, 5.25)
Result: 474.65

CALCULATEAMOUNT(x,y,z)

Calculates the Financed Amount
Three parameters: months, interest rate (percent), payment

Ex: CALCULATEAMOUNT(60, 5.25, 474.65)
Result: 25000.02

CALCULATEMONTHS(x,y,z)

Calculates the Months Financed
Three parameters: amount, interest rate (percent), payment

Ex: CALCULATEMONTHS(25000, 5.25, 474.65)
Result: 60

CALCULATEINTEREST(x,y,z)

Calculates the Financed Interest Rate
Three parameters: amount, months, payment

Ex: CALCULATEINTEREST(25000, 60, 474.65)
Result: 5.25

CALCULATEACCRUEDINTEREST(x,y,z)

Calculates the Accrued Interest
If your money is in a bank account accruing interest, how much does it earn over x months? Three parameters: principle amount, months, interest rate (percent)

Ex: CALCULATEACCRUEDINTEREST(25000, 60, 5.25)
Result: 7485.806648756854

CALCULATEAMORTIZATION(x,y,z,date)

Creates an amortization Schedule
Create an amortization schedule. The result should be an array whose length in the number of months. Each entry is an object. Four parameters: principle amount, months, interest rate (percent), start date (optional Date object)

Ex: CALCULATEAMORTIZATION(25000, 60, 5.25, new Date(2011,11,20) )
Result:
[
{
principle: 24634.725
interest: 109.375
payment: 474.65
paymentToPrinciple: 365.275
paymentToInterest: 109.375
date: Tue Dec 20 2011 00:00:00 GMT+0100 (Romance Daylight Time)
},
{
principle: 24267.851921874997
interest: 217.151921875
payment: 474.65
paymentToPrinciple: 366.873078125
paymentToInterest: 107.776921875
date: Fri Jan 20 2012 00:00:00 GMT+0100 (Romance Daylight Time)
},
...
]

The CALCULATEAMORTIZATION is the operation with most complexity in the "Calculated Fields Form" and requires its own section.

The CALCULATEAMORTIZATION operation returns a list of objects. For example:

CALCULATEAMORTIZATION(25000, 60, 5.25, new Date(2011,11,20) )
Result: [ { principle: 24634.725 interest: 109.375 payment: 474.65 paymentToPrinciple: 365.275 paymentToInterest: 109.375 date: Tue Dec 20 2011 00:00:00 GMT+0100 (Romance Daylight Time) }, { principle: 24267.851921874997 interest: 217.151921875 payment: 474.65 paymentToPrinciple: 366.873078125 paymentToInterest: 107.776921875 date: Fri Jan 20 2012 00:00:00 GMT+0100 (Romance Daylight Time) }, ... ]
  • principle: how much remains to pay.
  • interest: is the accumulated of interest paid until this date.
  • payment: is the monthly payment (payment of interests and payment of principle).
  • paymentToPrinciple: is the part of payment that is considered as payment of principle.
  • paymentToInterest: is the part of payment that is considered as payment of interest.
  • date: is the date of payment.

In the following example, we explain the use of the CALCULATEAMORTIZATION operation: the fieldname1 represents the principle amount, fieldname3 the number of months, and the fieldname2 the interest rate.

So, the value returned by CALCULATEAMORTIZATION(fieldname1,fieldname3,fieldname2) cannot by assigned directly to the calculated field, or will be displayed a text like: [object],[object],...... Therefore, we'll need to create a formatted string, with HTML tags, to display the CALCULATEAMORTIZATION results in an understandable format.

(function(){
var r = CALCULATEAMORTIZATION(fieldname1,fieldname3,fieldname2),
str = '';

if(r.length)
{
str = '<table cellpadding=" 10" >';
str += '<tr>';
str += '<td>Date</td>';
str += '<td>Interest</td>';
str += '<td>Payment</td>';
str += '<td>Payment to Interest</td>';
str += '<td>Payment to Principle</td>';
str += '<td>Principle</td>';
str += '</tr>';
for(var i = 0, h = r.length; i < h; i++)
{
str += '<tr>';
str += '<td>'+GETDATETIMESTRING( new Date(r[i]['date']), 'yyyy-mm-dd')+'</td>';
str += '<td>'+PREC(r[i]['interest'],2)+'</td>';
str += '<td>'+PREC(r[i]['payment'],2)+'</td>';
str += '<td>'+PREC(r[i]['paymentToInterest'],2)+'</td>';
str += '<td>'+PREC(r[i]['paymentToPrinciple'],2)+'</td>';
str += '<td>'+PREC(r[i]['principle'],2)+'</td>';
str += '</tr>';
}
str += '</table>';
}
jQuery('.comment_area .uh').html( str );
})()

The first step will be store the list of objects returned by the CALCULATEAMORTIZATION operation, in a local variable, and create another variable to store the amortization data, but with an HTML format:

var r = CALCULATEAMORTIZATION(fieldname1,fieldname3,fieldname2),
str = '';

The equation validates if the previous operation returns a value, because if the CALCULATEAMORTIZATION was called with wrong values can return an empty array:

if(r.length)
{
...
}

I've decided display the results of CALCULATEAMORTIZATION operation in a tabular format because is easier to understand. The first element in the result is the tag to open the table: <table>, and the row with the column names:

str = '<table cellpadding=" 10" >';
str += '<tr>';
str += '<td>Date</td>';
str += '<td>Interest</td>';
str += '<td>Payment</td>';
str += '<td>Payment to Interest</td>';
str += '<td>Payment to Principle</td>';
str += '<td>Principle</td>';
str += '</tr>';

Now, it is the moment to create each row of the table with the values of monthly amortization.

for(var i = 0, h = r.length; i < h; i++)
{
    str += '<tr>';
    str += '<td>'+GETDATETIMESTRING( new Date(r[i]['date']), 'yyyy-mm-dd')+'</td>';
    str += '<td>'+PREC(r[i]['interest'],2)+'</td>';
    str += '<td>'+PREC(r[i]['payment'],2)+'</td>';
    str += '<td>'+PREC(r[i]['paymentToInterest'],2)+'</td>';
    str += '<td>'+PREC(r[i]['paymentToPrinciple'],2)+'</td>';
    str += '<td>'+PREC(r[i]['principle'],2)+'</td>';
    str += '</tr>';
}

The previous code has its particularities. By default the dates returned by the CALCULATEAMORTIZATION operation have the complete format including hours and seconds, In this form the information about hours and seconds is not relevant, so, it is preferred to use a short date format: yyyy-mm-dd. The date string will be formatted with the GETDATETIMESTRING operation, included in the Date module of developers version of the plugin (the second parameter is the format to use):

str += '<td>'+GETDATETIMESTRING( new Date(r[i]['date']), 'yyyy-mm-dd')+'</td>';

Another particularity is the use of the PREC operation. By default the CALCULATEAMORTIZATION returns the numeric values with all its decimals digits, for example: 366.873078125, but for humans it is common to identify the money representation with two decimal digits. So, I've used the PREC operation with the number 2 as the second parameter.

str += '<td>'+PREC(r[i]['interest'],2)+'</td>';

After creating all table rows, it is time to close the table, and print the results:

str += '</table>';

If you display the result directly in the calculated field, you will see a weird text (or very hard to understand) because the input fields in HTML are not able to display tables, in this case I've preferred to show the result in an "Instruct Text" field. I've inserted an "Instruct Text" field in the form, this type of field uses the class name "comment_are", and includes an <span> tag with the class "uh". Then, using jQuery to select the correct field, I've inserted the formatted result of the CALCULATEAMORTIZATION in the <span> tag included in the "Instruct Text" field:

jQuery('.comment_area .uh').html( str );

The complete equation is:

(function(){
var r = CALCULATEAMORTIZATION(fieldname1,fieldname3,fieldname2),
str = '';

if(r.length)
{
str = '<table cellpadding=" 10" >';
str += '<tr>';
str += '<td>Date</td>';
str += '<td>Interest</td>';
str += '<td>Payment</td>';
str += '<td>Payment to Interest</td>';
str += '<td>Payment to Principle</td>';
str += '<td>Principle</td>';
str += '</tr>';
for(var i = 0, h = r.length; i < h; i++)
{
str += '<tr>';
str += '<td>'+GETDATETIMESTRING( new Date(r[i]['date']), 'yyyy-mm-dd')+'</td>';
str += '<td>'+PREC(r[i]['interest'],2)+'</td>';
str += '<td>'+PREC(r[i]['payment'],2)+'</td>';
str += '<td>'+PREC(r[i]['paymentToInterest'],2)+'</td>';
str += '<td>'+PREC(r[i]['paymentToPrinciple'],2)+'</td>';
str += '<td>'+PREC(r[i]['principle'],2)+'</td>';
str += '</tr>';
}
str += '</table>';
}
jQuery('.comment_area .uh').html( str );
})()
Operation Description Demo
PRESENTVALUE(x,y,z)

Returns the present value of an investment
The present value is the total amount that a series of future payments is worth now. Three parameters: The interest rate per period, the total number of payment periods in an annuity, the payment made each period and cannot change over the life of the annuity

Ex: PRESENTVALUE(0.08,5,100)
Result: 399.27

FUTUREVALUE(v,w,x,y,z)

Returns an investment based on an interest rate and a constant payment schedule. Five parameters: The interest rate for the investment, the number of payments for the annuity, the amount of the payment made each period, the present value of the payments (if this parameter is omitted, it assumes to be 0), parameter that indicates when the payments are due (if this parameter is omitted, it assumes to be 0. The possible values are: 0 - Payments are due at the end of the period, 1 - Payments are due at the beginning of the period)

Ex: FUTUREVALUE(7.5/12,24,-250,-5000,1)

PMT(Rate,NPer,PV,FV,TYPE)

Returns the periodic payment for an annuity with constant interest rates

Rate is the periodic interest rate.
NPer is the number of periods in which annuity is paid.
PV is the present value (cash value) in a sequence of payments.
FV (optional) is the desired value (future value) to be reached at the end of the periodic payments.
Type (optional) is the due date for the periodic payments. Type=1 is payment at the beginning and Type=0 is payment at the end of each period.

Ex: PMT(1.99/12,36,25000)
Result: -715.96
IPMT(Rate,Period,NPer,PV,FV,TYPE)

Calculates the periodic amortizement for an investment with regular payments and a constant interest rate

Rate is the periodic interest rate (%).
Period is the period, for which the compound interest is calculated.
NPer is the number of periods in which annuity is paid.
PV is the present value (cash value) in a sequence of payments.
FV (optional) is the desired value (future value) to be reached at the end of the periods.
Type (optional) is the due date for the periodic payments. Type=1 is payment at the beginning and Type=0 is payment at the end of each period.

Ex: IPMT(5,5,7,15000)
Result: -352.9735
PPMT(Rate,Period,NPer,PV,FV,TYPE)

Returns for a given period the payment on the principal for an investment that is based on periodic and constant payments and a constant interest rate

Rate is the periodic interest rate (%).
Period is the amortizement period. P = 1 for the first and P = NPer for the last period.
NPer is the number of periods in which annuity is paid.
PV is the present value (cash value) in a sequence of payments.
FV (optional) is the desired value (future value) to be reached at the end of the periods.
Type (optional) is the due date for the periodic payments. Type=1 is payment at the beginning and Type=0 is payment at the end of each period.

Ex: PPMT(8.75/12,1,36,5000,8000,1)
Result: -350.99
PVIF(Rate,Periods)

Calculates the today value per currency received at a future date

Rate is interest rate per period (%).
Periods is the number of periods.

Ex: PVIF(5,10)
Result: 0.6139
FVIFA(Rate,Periods)

Calculates the future value interest factor of annuity

Rate is interest rate per period (%).
Periods is the number of periods.

Ex: FVIFA(5,17)
Result: 25.8404
NPV(Rate,Values)

Calculates the net present value of an investment based on a discount rate and a series of periodic cash flows.

Rate is the discount rate of the investment over one period (%).
Values is the array of values representing payments and income.

Ex: NPV(10,[-10000,3000,4200,6800])
Result: 1188.44
XNPV(Rate,Values,Dates)

Calculates the capital value (net present value)for a list of payments which take place on different dates

Rate is the internal rate of return for the payments (%).
Values and Dates refer to a series of payments and the series of associated date values. The first pair of dates defines the start of the payment plan. All other date values must be later, but need not be in any order. The series of values must contain at least one negative and one positive value (receipts and deposits).

Ex: XNPV(9,[-10000,2750,4250,3250,2750],['1/1/2008', '3/1/2008', '10/30/2008', '2/15/2009', '4/1/2009'])
Result: 2068.65
XIRR(Values,Dates,Guess)

Calculates the internal rate of return for a list of payments which take place on different dates

The calculation is based on a 365 days per year basis, ignoring leap years.

Values and Dates refer to a series of payments and the series of associated date values. The first pair of dates defines the start of the payment plan. All other date values must be later, but need not be in any order. The series of values must contain at least one negative and one positive value (receipts and deposits).
Guess (optional) is a guess that can be input for the internal rate of return (%). The default is 10.

Ex: XIRR([-10000,2000,2500,5000,1000],['01/01/2001', '01/02/2001', '03/15/2001', '05/12/2001', '08/10/2001'],10)
Result: 0.1948184751
MIRR(Values,Dates,Guess)

Calculates the modified internal rate of return on an investment based on a series of periodic cash flows and the difference between the interest rate paid on financing versus the return received on reinvested income.

Values is the array of values containing the income or payments associated with the investment.
Financing Rate is the interest rate paid on funds invested (%).
Reinvestiment Return Rate is the return (as a percentage) earned on reinvestment of income received from the investment (%).

Ex: MIRR([-120000, 39000, 30000, 21000, 37000, 46000], 10, 12)
Result: 12.61

Formats a Number

One parameters: number

Ex:NUMBERFORMAT(-2530023420269.123456)
Result: -2,530,023,420,269

Ex: NUMBERFORMAT(25000.123456, {precision:2})
Result: 25,000.12

Format Currency

Formats a number to a certain currency. Two parameters: number, settings (optional). If settings option is a string it is treated as a currency name. If it is an object it is used as currency settings.

Ex: NUMBERFORMAT(25000.123456, 'USD')
Result: $25,000.12

The settings of format can be overridden with the "options" parameter.

Ex: NUMBERFORMAT(-25000.123456, 'GBP', { negative: '()', precision: 3, thousand: '' })
Result: £(25000.123)

Format a Percent

Formats a number with a certain precision. Two parameters: number, settings ("percent" is a format)

Ex: NUMBERFORMAT(25000.123456, 'percent')
Result: 25,000%

Create a Currency

You may create a currency. The library comes with "USD", "GBP", and "EUR" currency formats and "number" and "percent" numeric formats. Two parameters: key, settings

Ex: ADDFORMAT('Dollars', { before: '', after: ' Dollars', precision: 0, thousand: ',', group: 3, decimal: '.', negative: '-' })
Result: true

Ex: NUMBERFORMAT(25000.123456, 'Dollars')
Result: 25,000 Dollars

REMOVEFORMAT(x)

Removes a Currency
To remove a currency. One parameter: key

Ex: REMOVEFORMAT('Dollars')
Result: true

Date Time module

The Date Time module includes a group of operations to manage dates and times.

Operation Description Demo
DATEOBJ(x,y)

Gets the date object from a string representation of date. DATEOBJ( date_string, format )

DATEOBJ('2013-05-21', 'yyyy-mm-dd')
Result: date object

YEAR(x,y)

Gets the year from an string representation of date. YEAR( date_string, format )

YEAR('2013-05-21', 'yyyy-mm-dd')
Result: 2013

MONTH(x,y)

Gets the month from a string representation of date. MONTH( date_string, format )

MONTH('2013-05-21', 'yyyy-mm-dd')
Result: 5

DAY(x,y)

Gets the days from a string representation of date. DAY( date_string, format )

DAY('2013-05-21', 'yyyy-mm-dd')
Result: 21

WEEKDAY(x,y)

Gets the week day from a string representation of date. WEEKDAY( date_string, format )

WEEKDAY('2013-10-27', 'yyyy-mm-dd')
Result: 1 Sunday is the day number one

WEEKNUM(x,y)

Gets the week number from a string representation of date, a year has 53 weeks.WEEKNUM( date_string, format )

WEEKNUM('2013-10-27', 'yyyy-mm-dd')
Result: 43

HOURS(x,y)

Gets hours from a string representation of datetime. HOURS( datetime_string, format )

HOURS('2013-10-27 01:21', 'yyyy-mm-dd hh:ii')
Result: 1

MINUTES(x,y)

Gets minutes from a string representation of datetime. MINUTES( datetime_string, format )

MINUTES('2013-10-27 01:22', 'yyyy-mm-dd hh:ii')
Result: 22

SECONDS(x,y)

Gets seconds from a string representation of datetime. SECONDS( datetime_string, format )

SECONDS('2013-10-27 01:22:56', 'yyyy-mm-dd hh:ii:ss')
Result: 56

NOW()

Gets a date object with the current day-time information. NOW()

NOW()
Result: 2013-10-27 01:42:19

TODAY() Gets a date object with the current day information, without the time part.TODAY()

 

DATEDIFF(date_one, date_two, date_format, return)

Gets the difference between two dates strings representation

DATEDIFF(date_one, date_two, date_format, return)

The function returns an object, whose value depends on the 'return' argument

Possible values of return argument:
d - returns the number of days between two dates
m - returns the number of months between two dates, and remaining days
y - returns the number of years between two dates, remaining months, and remaining days

DATEDIFF('2013-10-27', '2012-06-22', 'yyyy-mm-dd', 'y')['months']
Result: 4

DATETIMESUM(date_string, format, number, to_increase)

Increases the date-time string representation in the number of seconds, minutes, hours, days, months, or years, passed as parameter.

DATETIMESUM( date_string, format, number, to_increase )

DATETIMESUM('2013-10-27', 'yyyy-mm-dd', 5, 'd')

Result: The date object representation of 2013/11/01

GETDATETIMESTRING(datetime_object, format)

Returns the string representation of a date object

GETDATETIMESTRING( datetime_object, format )

GETDATETIMESTRING(TODAY(), 'yyyy-mm-dd')
Result: 2013-10-27

DISTANCE MODULE

The distance module integrates the Calculated Fields Form with the Google Maps:

Operation Description Demo
DISTANCE(Address A, Address B, Unit System, Travel Mode)

Returns the distance between two addresses, in the unit system passed as parameter, and with the travel mode selected. Returns the FAIL text if at least one of addresses is invalid, or it is not possible access to Google.

The addresses A and B are posts addresses, or post codes.

The allowed values for Unit System are: km for kilometters, or mi for miles, km is the value by default.

The allowed values for Travel Mode are: DRIVIN, BICYCLING, TRANSIT, or WALKING, DRIVING is the value by default.

DISTANCE( '33122', '32801', 'mi', 'DRIVING') would be 240

TRAVELTIME( Address A, Address B, Return as Text, Travel Mode, Avoid Highways, Avoid Tolls )

Returns the distance between two addresses, in the unit system passed as parameter, and with the travel mode selected. Returns the FAIL text if at least one of addresses is invalid, or it is not possible access to Google.

The addresses A and B are posts addresses, or post codes.

The allowed values for Return as Text are: 1 to get values in text format as 11 min, or 0 to get the value in seconds, zero is the default value.

The allowed values for Travel Mode are: DRIVIN, BICYCLING, TRANSIT, or WALKING, DRIVING is the value by default.

The allowed values for Avoid Highways and Avoid Tolls are: 1 or 0, zero as the default value.

TRAVELTIME('Murray BMCC, 70 Murray St, New York, NY 10007, USA', '384-386 Broadway, New York, NY 10013, USA',1,'WALKING') Result: 13 min

Tip: To use your personal key for Google API, insert a shortcode for the variable: "google_api_key" in the webpage as: [CP_CALCULATED_FIELDS_VAR name="google_api_key" value="<your key>"]

The API Key can be defined directly in the form's shortcode, as follows: [CP_CALCULATED_FIELDS id="1" google_api_key="<your key>"]

Troubleshoot Area & General Settings

Throubleshoot Area

The "Troubleshoot Area & General Settings" section, allows correct some possible issues, or conflicts with third party plugins, and define the general settings.

  • Script load method: Changes the script load method if the form doesn't appear in the public website.
  • Character encoding: Updates the charset, if you are getting problems displaying special/non-latin characters. After updated you need to edit the special characters again.
  • Activate Javascript Cache: Allows caching the javascript files of the plugin.
  • Activate Forms Cache: Stores the forms in cache to improve the website's performance.
  • Modify the eMails Headers: If the notification emails are not send to the users, tries checking this checkbox, but if it is not sufficient, install and activate a SMTP plugin.
  • Do not loading the forms with crawlers: The forms are not loaded when website is being indexed by search engine crawlers.
  • Enter an unique field name: The name of the field that will be created to protect the forms against the spam bots. Adds a hidden text field to the forms to trap the spam bots.

Filters and Actions

The plugin calls the following list of filters and actions:

  • cpcff_pre_form: Filters applied before generate the form, is passed as parameter an array with the forms attributes, and return the list of attributes, modified or not.
  • cpcff_the_form: Filters applied after generate the form, is passed as parameter the HTML code of the form with the corresponding <LINK> and <SCRIPT> tags, and returns the HTML code to include in the webpage.
  • cpcff_valid_submission: Filters applied for checking if the form's submission is valid or not, returns a boolean.
  • cpcff_redirect: Filters applied to decide if the website should be redirected to the thank you page after submissions, passes a boolean as parameter, and returns a boolean too.
  • cpcff_csv_query: Allows modify the query of messages, passing the query as parameter, returns the new query.
  • cpcff_get_option: Filters applied before returning a form option. Passes three parameters to the filter: The value of option, the name of option and the form's id, returns the new option's value.
  • cpcff_messages_query: Allows modify the query of messages, passing the query as parameter, returns the new query.
  • cpcff_process_data: Action called after be submitted the form, and processed the information in the server side.
  • cpcff_payment_processed: Action called after receive the payment confirmation, passing as parameter the information collected by the form.
  • cpcff_file_uploaded: Action called after upload a file through the form. It is passed as parameter the object returned by the wp_handle_upload function.
  • cpcff_update_submission: Action called when a submission is updated, the submission ID is passed as parameter.
  • cpcff_delete_submission: Action called when a submission is deleted, the submission ID is passed as parameter.
  • cpcff_messages_filters: Additional filtering options, allows to add new fields for filtering the events in the messages screen.
  • cpcff_messages_list_header: Action called to include new headers in the table of events in the messages screen.
  • cpcff_message_row_data: Action called to add related data to the events in the messages screen, the row is passed as parameter.
  • cpcff_script_after_validation: Action called in the generation of javascript code to validate the forms data before submission.
  • cpcff_summary: Filters applied after generate the summary in the thank you pages. Passes the summary as parameter.

Tips and Tricks

Set the value to a slider control programmatically
  1. Assign a class name to the slider field, for example: my-field (the class names are assigned to the fields through the attribute: "Add Css Layout Keywords")
  2. Insert a "HTML Content" field in the form with the piece of code below as its content:
    <SCRIPT>
    function setSliderValue( clss, value )
    {
    var id = fbuilderjQuery('.'+clss+' input').attr( 'id' );
    var fId = id.match(/_\d+$/);
    fbuilderjQuery.fbuilder.forms[fId].getItem(id).setVal(value);
    }
    </SCRIPT>
    
  3. Finally, if the equation associated to the calculated field is for example: fieldname1+fieldname2, modify it as follows:
    (function(){
    var v = fieldname1+fieldname2;
    setSliderValue('my-field', v);
    return v;
    })()
    
Create new validation rules

In some situations is required that the fields values have a specif format, or maybe allow to enter only a list of values. In these cases the current validation rules (digits, numbers, max value, min value, text length, required) are not sufficient, and would be needed new rules. This section describes how to create a new validation rule, and assing it to a field.

Assuming you need restricts the values of the fieldname1 field as US Zipcode, with the formats: #####-#### or #########, the regular expression used to validate the field's value is: /^\d{5}([\-]?\d{4})?$/

Insert a "HTML Content" field in the form, with the piece of code below as its content:

<SCRIPT>
fbuilderjQuery(document).one('showHideDepEvent', function(){
	fbuilderjQuery
	.validator
	.addMethod(
		"zipcode", 
		function(v,e)
		{
			return this.optional(e) || /^\d{5}([\-]?\d{4})?$/.test(v);
		}
	);
	fbuilderjQuery.validator.messages['zipcode'] = 'The  zipcode is invalid';
	fbuilderjQuery('[id*="fieldname1_"]').addClass('zipcode');
});
</SCRIPT>

The previous code adds a new method to the "validator" object, applied to all input fields with the class name "zipcode", the method returns true if the input field is optional, or its value satisfies the format of an US zipcode. With the instruction: fbuilderjQuery.validator.messages['zipcode'] = 'The zipcode is invalid'; is defined the error message to display when the validation rule fails. The last instruction assign the class name: zipcode to the fieldname1 field, to apply on it the new validation rule.

Storing Data in a Different Database

The Developers version of the "Calculated Fields Form" plugin, allows storing the data submitted in a database different to the own plugin database.

To use this feature are required some basic skills, because should be edited the "cp_calculatedfieldsf_insert_in_database.php" file included in the code of plugin.

This file is a mockup to integrate the plugin with other MySQL database. The file should be modified manually because each database has its own structure, and gives to the users a total control on the process.

The file's edition:

Open the file with the text editor your choice. There are some text editors, widely recommended for code editing, like: Notepad++, Sublime Text, Vim, Atom, UEditor.

The first section of file allows defining the constants needed for connecting with the database, and its authentication:

define( 'DATABASE_HOST', '' );
define( 'DATABASE_USER', '' );
define( 'DATABASE_PASS', '' );
define( 'DATABASE_NAME', '' );
define( 'DATABASE_TABLE', '' );

The name of constants are auto-descriptives:

  • DATABASE_HOST: hosname or IP of database server.
  • DATABASE_USER: username for database's authentication.
  • DATABASE_PASS: password for database's authentication.
  • DATABASE_NAME: database name.
  • DATABASE_TABLE: table name.

The plugin checks if the constants have been defined, before for running the insertion queries.

The second section to be edited by the developers, is the creation of the variables to use in the queries. The file includes some variables as a guide of section:

$field1 = mysqli_escape_string( $db_link, $params[ 'fieldname%' ] );
$field2 = mysqli_escape_string( $db_link, $params[ 'fieldname%' ] );
$field3 = mysqli_escape_string( $db_link, $params[ 'fieldname%' ] );

I'll explain this section with an example. Suppose you want store in the "my_users" table, the firstname, lastname, and email of the user, submitted through the form, and the corresponding fields in the form for these information are: fieldname1, fieldname2, and fieldname3, respectively. So, the variables are created like follow:

$field1 = mysqli_escape_string( $db_link, $params[ 'fieldname1' ] );
$field2 = mysqli_escape_string( $db_link, $params[ 'fieldname2' ] );
$field3 = mysqli_escape_string( $db_link, $params[ 'fieldname3' ] );

In the previous code has been created a varaible for each field in the form. All fields are included in the $params array.

After create the variables, is time to generate the insertion queries. The plugin includes a mockup for a hypotetical insertion query, that must be replaced with the structure of your database and the fields created previously.

mysqli_query( $db_link, "INSERT INTO `".DATABASE_TABLE."` (field1, field2, field3) VALUES ('$field1', '$field2', '$field3');" );

Returning to the previous example. If the columns of the table are: firstname, lastname, and email, respectively, the query should be modified like follow:

mysqli_query( $db_link, "INSERT INTO `".DATABASE_TABLE."` (firstname, lastname, email) VALUES ('$field1', '$field2', '$field3');" );

Pay attention, if the type of data in a column of table is a numeric value, should be removed the quotes around the variable name. For example, suppose the form includes a DropDown field for the year of birth, that evidently is a numeric value, I will assume this is the fieldname4. So, you should create a new variable for the new field:

$field4 = mysqli_escape_string( $db_link, $params[ 'fieldname4' ] );

and modify the insertion query too:

mysqli_query( $db_link, "INSERT INTO `".DATABASE_TABLE."` (firstname, lastname, email, year) VALUES ('$field1', '$field2', '$field3',$field4);" );

The $field4 variable is not closed between quotes.

A last tip: It is possible create as many insertion queries as needed, even can use the table name directly without use the constant defined in the first section.

Populate a Form by Default

The plugin adds a consecutive number to each form inserted in a webpage to prevent conflicts between different copies of a same form, starting in "1". The process will be explained in an example. I will suppose your form includes only one form created with the "Caculated Fields Form", and the form includes three fields: - a numeric field (fieldname1), a DropDown field (fieldname2), a checkbox field (fieldname3), and a single text field (fieldname4). Furthermore, the form fields should be prefilled with the values: 3 for the fieldname1, the choice with the value 4 in the fieldname2, tick the choices with the values: 1, and 2 for the fieldname3, and the "qwerty" text in the fieldname4, follows the steps below:

  1. Enable the text tab in the content's editor of your webpage. If are inserted HTML tags with the "Visual" tab enabled, the symbols "<" and ">" are encoded as "&lt;" and "&gt" respectively.
  2. Inserts a pair of <SCRIPT>...</SCRIPT>, with the piece of code:
    <SCRIPT>
    cpcff_default = { 1 : {} };
    cpcff_default[1][ 'fieldname1' ] = 3;
    cpcff_default[1][ 'fieldname2' ] = 4;
    cpcff_default[1][ 'fieldname3' ] = [1,2];
    cpcff_default[1][ 'fieldname4' ] = "qwerty";
    </SCRIPT>
    

Pay attention to the values of the fieldname3 and fieldname4. The fieldname3 is a checkbox, as it is possible select multiple choices, should be assigned an array of values. For the fieldname4, whose value is a text, it should be closed with quotes or double quotes.

This process can be used to pre-populate the Form B, inserted in the thank page of the Form A, with the information submitted by the Form A.

Create New Predefined Template

The "Caculated Fields Form" plugin includes multiple predefined templates to be used in the forms. The template is selected from the "Form Settings" tab, in the toolbar of the form builder, but can occur that the predefined templates are not sufficient to create a form with the look and feel you want.

The template's module in our plugin, can be extended easily to create new designs, to be used in the forms of website.

Into the "/wp-content/plugins/calculated-fields-form/templates" directory there are multiple folders, a folder for each template. The folders names have not restrictions, you simply should create a new folder for the custom template, with the name you want.

The only one required file in a template is the "config.ini" file, whose structure is:

prefix="cp_cff_custom"
file="style.css"
title="Custom Template"
thumbnail="thumbnail.jpg"
description="This is my custom template"

The description of attributes:

  • prefix: Classname, applied to the form's container. Its value should be unique for all templates on website (required attribute).
  • file: Name to the CSS file with the styles to define the appearance of form.
  • title: Name of the template, displayed in the dropdown list on form settings.
  • thumbnail: Name of image file, displayed when the template is selected (the image file should be stored in the template directory).
  • description: Description to display when the template is selected.

To implement a specific design to your forms, creates a CSS file, in the template directory (uses the file's name you prefers, but assings the file name to the file attribute in the config.ini file)

The stylepublic.css file defines the default appearance to all forms on website. The classes definitions start with #fbuilder, the ID value assigned to the form, to prevent conflicts with styles defined by other plugins or themes in the website. For extending and modify the styles from the custom template, should redefine the styles in your own CSS file, but prefixing the styles definitions, with the value entered in the prefix attribute of config.ini file.

I'll explain the process with an example. Suppose you want apply to the forms titles, the style rule font-size:1.5em, and you have defined the text: cp_cff_custom as the value of the prefix attribute, in this case the style's definition in the CSS file would be:

.cp_cff_custom #fbuilder .fform h1{font-size:1.5em;}

Apply this logic for the rest of classes in the CSS file.

After complete the template, you simply should select it from the settings page of the forms.