ft_api_show_submissions

Requirements

1. It requires the Export Manager module to be installed and enabled.
2. To generate the HTML, it uses one of the export types - so you may find you need to create a new one with the appropriate formatting (discussed below).

The general requirements for the Form Tools API also apply.

Overview

This function lets you display your form submissions in your own webpages. By default, it only displays a page-worth of results - but this can be overridden if need be.

The function works by being told which form, View and Export Type you would like to use to render the form information. By specifying the View ID, you can precisely customize what fields you'd like to see published just by adding or editing the Views. You may find it beneficial to create a separate View that displays exactly what you want.

By specifying the export type ID, you customize the manner in which that information is presented (e.g. table format or one-by one). Out the box, Form Tools comes with three HTML-related export types found in the Export Manager module. But you may find you want to create a new one for use with this function. Between the Views and the export types, you have complete control over the appearance of the data in your webpage! Neat, huh?

The function takes the following required parameters:

<?php
ft_api_show_submissions($form_id, $view_id, $export_type_id, $page);
?>

The first three parameters are self-explanatory, and can be found in the Form Tools interface. $page is the current page to display. Here's a simple example. In it, the Form ID is 26, the View ID is 23, the Export Type ID is 2 and the $page value is passed in by the query string.

<?php
// the path will need to be updated!
require("/path/to/global/api/api.php");

$page = ft_api_load_field("page", "page", 1);
ft_api_show_submissions(26, 23, 2, $page);
?>

The ft_load_field function is a really handy helper function, discussed here. Suffice to say that it always returns the appropriate page number - defaulted to 1. If a "page" value is specified in the query string or through a POST submission, it will return that value.

How to find the form, View and export Type IDs

• The form ID can be found in Form Tools. Log in as the administrator and go to the Form List page. The "ID" column is the form ID.
• The View ID is found on the Views tab of the form. That tab lists all available Views, and like the forms contains an ID column for the View ID.
• To find the export type ID, go to the Modules page and select the Export Manager module. Click the Export Group you want to use to determine the results (probably the HTML / Printer-friendly or another custom group), then click on the "Export Types" tab. That lists the IDs of all export types that belong to that group.

The $options parameter

There's one final, optional parameter for the ft_api_show_submissions function: an $options parameter. This lets you override certain default functionality. Here's an example of how it's called:

<?php
$page = (isset($_GET["page"])) ? $_GET["page"] : 1;
$options = array(
	"show_columns_only" => true,
	"num_per_page" => 5,
	"order" => "name-ASC"
);
ft_api_show_submissions(26, 23, 2, $page, $options);
?>

You can set any of the following values:

• num_per_page - (integer) by default, it returns the number of results per page specified by the View. This setting overrides that value.
• submission_ids - (array or integer) this limits the results returned to the submission ID or submission IDs specified in this field. Note: this function will only return those submissions that are within the specified VIEW.
• order - (string) the database column name with a -DESC or -ASC suffix (e.g. col_1-ASC).
• page_num_identifier - (string) passed via the query string to denote what page it's on (default: "page")
• show_columns_only - (boolean) limits the fields that are displayed to those fields marked as "Column" in the View. Defaults to false.
• return_as_string - (boolean) if this value is set to true, instead of outputting the result the function returns the HTML as a string.
• pagination_theme - (string) the pagination links (<< 1 2 3 ...) HTML is generated by the pagination.tpl template, found in each of the theme folders. Generally this file is the same for all themes, but in case it isn't, this setting lets you choose the theme folder with which to render the HTML.
• pagination_location - (string) accepts the values "top" (the default), "bottom", "both" or "none". This determines where (if anywhere) the pagination links should appear. By default it only appears at the top of the page, but you can set this value to either "both" or "bottom" to have it appear there instead / as well.

Return Values

In the examples above, the function just prints the HTML to the screen. This is the normal behaviour. But here's a full list of all the possible return / display values.

1. If error:
   1. if $g_api_debug == true, the error page will be displayed displaying the error code.
   2. if $g_api_debug == false, it returns an array with two indexes: [0] false, [1] the API error code
2. If successful:
   1. if "return_as_string" option key is set, it returns an array with two indexes: [0] true, [1] the HTML content
   2. if "return_as_string" not set, it just prints the HTML to the page (the default behaviour)

Linking to a details page

A common way to organize the form submission is to list a subset of the information in a table, and provide a "More Info" or "Details" link next to each submission. That links to a page which lists the full submission information. You can emulate this behavior by doing the following:

1. In the Export Manager module, create a new export type, with a link for each submission linking to another page called, say, details.php. Make sure the link contains the submission ID as part of the query string.
2. Create the details.php page on your server which will be used to display the submission details. On that page, use the ft_api_show_submission function to display the individual submission data.