formtools / api

The Form Tools API.

Form Tools API

This repo contains the Form Tools API, providing some methods to interact with and extend Form Tools, such as:

• Let's you create complex, multi-page forms that integrate well with Form Tools.
• Let's you display Form Tools data on your website publicly
• Provides ways to create user accounts, login to Form Tools programmatically
• Lots more.

The API documentation is pretty thorough. Please refer to one of the following sections:

• API v1.x - current version, but soon to be legacy
• API v2.x - this is coming (very) soon

API v1.x vs. v2.x

Form Tools 3 was a complete rewrite of the application, including changing the codebase from functional code to object-oriented. The API v2.x was updated for Form Tools 3 compatibility, converting the API into a class.

In terms of functionality, v1.x and v2.x of the API are identical: they (currently) provide the same methods. What's changed has the way you call the API methods.

Examples

The documentation links above contains in-page example code for all the methods, but for something more hands-on check out the examples/ folder in this repo. That contains some simple, bare-bones examples (no CSS!) of some of the API methods that can easily be shown. Other methods such as the form integration methods need additional work to configure Form Tools - so couldn't be included. See the tutorials for further info on them.

Thev1/ folder contains the old Form Tools 2.x compatible API methods (version 1.x of the API); the v2/ folder contains Form Tools 3 compatible API methods (version 2.x of the API). For Form Tools 3 users, please use the v2/ folder examples - v1/ is just provided for people upgrading to Form Tools 3 and want to keep compatibility with their existing API forms and usage.

How to view the examples

• Create a form in Form Tools - it doesn't matter if it's an internal, external or Form Builder form. Many of the Form Tools API methods rely on passing form IDs, view IDs and more. As such you may find you will need to edit these examples to pass the IDs/settings that are correct for your installation and forms.
• The Form Tools download packages from formtools.org/download/ all include the API as part of the bundle, but if you're getting the code from the source github repos, be sure to upload the contents of the latest API package version to your [Form Tools root]/global/api/ folder.
• Edit the examples-config.php file in this folder to set the $examples_enabled = true; variable. The examples are all disabled by default to prevent accidentally exposing your Form Tools submission data to the outside world. If you're worried about this, just move the examples folder wherever you want on your server and change the paths to the api.php/API.class.php file.

Getting help

Please create an issue on this repo.

api's Issues

File uploads are lost after failing server-side validation

This is real nuisance, as noted by Jaace here:
http://forums.formtools.org/showthread.php?tid=608

Hmm... will need to rewire the code to actually upload and log the file reference despite failing validation. This will probably require a custom function in order to make it compatible with all existing validation code. Damn... Or could the ft_api_process_form function handle it somehow...? Probably not...

Emails not sent unless next_page populated even if finalize

See spcjak7221's post.
http://forums.formtools.org/showthread.php?tid=652

Should be able to support multiple reCaptcha's in multiple forms in a single page

As described.

File upload module error detection in formtools 2

I still use form tools 2 and I noticed that sometimes file uploading fails while using the API. If I try to upload an invalid file on the back-end I get a detailed error message but via the API the form is submitted regardless without any explanation.

So, I dug around and found the function that processes file uploads, ft_file_api_process_form_hook in modules\field_type_file\library.php, and I can call error_log() on the message it generated but is there a way to have formtools not submit the form and display why the file upload failed on the form page?

Rename ft_api_create_blank_submission to something sane

Really? Weird name... How about:

ft_api_create_submission()

Far more intuitive, I think. "blank" isn't correct because you can set the submission values as part of the first param.

Form Tools 3 reCAPTCHA Form_builder form: Fatal Error when not "logged-in"

Fatal error: Call to a member function prepare() on a non-object in /var/www/forms.buffalonews.com/global/code/Database.class.php on line 65

When not logged in reCAPTCHA can not load.

Is it possible to get all available submissionIDs?

I want to use a loop to get all LastName, FirstName and submissionIDs for a given form. I will use this to create a hyperlink that passes the submissionid on to another page that will display the form.
Pseudocode:
foreach{
$IDs= getAllSubmissions;
$form_id = 1;
$submission_id = ?;
$submission = $api->getSubmission($form_id, $submission_id);
$array = array($submission["LastName"], $submission["FirstName"]);
$comma_separated = implode (", ", $array);
echo "<a href='ViewForm.php?submission_id=$submission_id'target='_blank'>$comma_separated";
}

Add update and delete submission methods to API

See: formtools/core#160

Check if logged in

I am looking to add code to a non FT page that determines if a user is logged in. It most likely won't matter much WHICH user is logged in, just that a valid user is logged in. The other option was to paste my code into one of the pages on the page module but that doesn't really accept html/php combo very well.

I see there is an API function that allows someone to log in programmatically, but is there a way to check to see if someone is logged in already?

EDIT: I played around with it this morning, and tried a few functions such as ft_get_account_info(). What I ended up with is determining if ['is_logged_in'] is set to true within the session. The problem I am having with that is even when I log out of FT, it continues to say I'm logged in, and in another browser it just always says I'm logged out. Am I on the right track here?

require("/path/to/ft/global/session_start.php");

if ($_SESSION['ft']['account']['is_logged_in'] == true) {
echo 'logged in!'; }

else { echo "Not logged in!!"; }

EDIT 2:

My issue seemed to be with FT being https and my script running without https. Sessions seem to be tied pretty tightly to the domain, i.e. with and without https, and www subdomain. All works well when I've got it all the same. If anyone has any suggestions as to any better methods, I'm open to it!

API update for Form Tools 3

Check compatibility with:

• Hooks Manager
• Submission Pre-parser

Expects an API::processFormSubmission method.

getSubmission

I may have raised this before but I cannot see it in the list of issues but apologies if I missed it.

Would it be possible to get submissions via the API using a where clause rather than just ID.

I want to cross reference forms rather than have one big data row.

This is partly because of a lack of update functionality in the API but the ability to search form data through the API would be useful anyway.

Although I suspect I will need the proposed update functionality as well.

Thanks

ft_api_display_captcha has problems with SSL on IE

Easy fix. See:
http://forums.formtools.org/showthread.php?tid=964

API forms should ignore `form_tools_form_id` param if included in the form

As described.

This can cause confusion when upgrading a process.php form to the API.

Update createClientAccount to use core code

This code is duplicated. Needs to use the core code instead.

FT 3.01 - API + Visualization on same PHP page (API 2.x)

Individual ("use in your own pages") visualization code on external PHP page - works OK.

Individual API function code e.g. showSubmissions() on external page - works OK.

Combining both pieces of code on one page causes second element to be ignored and page does not render completely.

MULTIPLE graphs work OK on same page alone
MULTIPLE API functions work OK on same page alone

Cannot get Visualization and API code to work on same page.

Cannot highight field comments for dropdown type

There is no option to "highlight" Field comments as there is in a text box type field.

Steps to reproduce:
Edit form --> Fields --> Edit (DROPDOWN TYPE) field -->

Remove each() method calls

These have been deprecated.

textarea field newline/carriage return characters in the review

So you know though even though the charachters /n and /r show in the verification and finalize pages it does not carry over to the confirmation email and or the database..... weird.

This problem appears to be affecting both my form and your online Registration demo form, all textarea @fields data that has a cr displays "\r\n" in place of the cr, when reviewed and the entry in the database.