JavaScript API

The Tap Forms JavaScript Application Programming Interface (API) provides you with specific extensions to the JavaScript virtual machine that lets you create, update, and delete various objects within your Tap Forms database document.

Here are a list of objects and the functions you can call on each.

document

Function/Property	Parameters	Returns	Description	Example
createNewFormNamed()	text	form	Call this to create a new form with the specified name.	document.createNewFormNamed('My New Form');
getFormIdsByName()	text	array	Returns the list of form IDs for the specified form name.	document.getFormIdsByName('Movies');
getFormNamed()	text	form	Call this to fetch a form with the specified name.	document.getFormNamed('My Movie Library');
getForms()	none	array of forms	Call this to fetch an array of all the forms in your database document.	document.getForms();
getFormWithId()	form ID	form	Call this to get a form with the specified form ID.	document.getFormWithId('frm-1234567890abcdef');
getId()	none	text	Returns the ID of the current document	document.getId();
getPickListNamed()	text	Pick List	Call this to fetch a Pick List with the specified name.	document.getPickListNamed('Priorities');
getPickLists()	none	array of Pick List	Call this to fetch the list of Pick Lists in the database.	document.getPickLists();
name	none	text	Returns the name of the document.	document.name;
saveAllChanges()	none	Bool	Call this to save any changes your script has made to the database document.	document.saveAllChanges();
selectFormLayout()	form ID, layout ID	none	Selects a form and a specific layout. Pass null for the layout ID to select the Default Layout	document.selectFormLayout(form_id, layout_id);

form

Function/Property	Parameters	Returns	Description	Example
addField()	Field	none	Adds the specified Field to the form.	form.addField(field);
addNewFieldNamedWithType()	name, type (text, number, calc, location, photo)	Field	Adds a new field to the form with the specified name and field type.	var field = form.addNewFieldNamedWithType('Quantity', 'number');
addNewRecord()	none	record	Adds a new record to the form.	var newRecord = form.addNewRecord();
addNewScriptNamed()	text	Script	Adds a new Script to the form.	var newScript = form.addNewScriptNamed("My Script");
deleteRecord()	record	error string	Deletes the specified record from the form.	form.deleteRecord(someRecord);
deleteScriptNamed()	text	error string	Deletes the first Script with the specified name from the form.	form.deleteScriptNamed("My Script");
deleteScriptWithId()	text	error string	Deletes the Script with the specified ID from the form.	form.deleteScriptWithId("scr-blahblah");
getAvgOfField()	field ID	number	Returns the average value of all the records in the form for the specified field.	form.getAvgOfField(fieldID);
getFieldIds()	none	array	Returns an array of all the field IDs in the form.	form.getFieldIds();
getFields()	none	array	Returns an array of all the TFField objects in the form.	form.getFields();
getFieldsForType()	type (text, number, check_mark, date, time, date_time, calc, note, etc.)	array	Returns an array of all the TFField objects in the form for the specified type.	form.getFieldsForType('text');
getFieldNamed()	text	Field	Returns the TFField object for the specified field name.	form.getFieldNamed('Movie Title');
getFieldWithId()	field ID	Field	Returns the TFField object for the specified field ID.	form.getFieldWithId('fld-abcde1234');
getId()	none	form ID	Returns the internal unique ID of the form.	form.getId();
getLayoutNamed()	text	Layout	Returns the TFFormLayout object for the specified layout name.	form.getLayoutNamed('Print Layout');
getLayoutWithId()	layout ID	Layout	Returns the TFFormLayout object for the specified layout ID.	form.getLayoutWithId(layout_id);
getLayouts()	none	array of layouts	Returns all the layouts for the form.	form.getLayouts();
getMaxOfField()	field ID	number	Returns the maximum value of all the records in the form for the specified field.	form.getMaxOfField(fieldID);
getMinOfField()	field ID	number	Returns the minimum value of all the records in the form for the specified field.	form.getMinOfField(fieldID);
getRecords()	none	array	Returns an array of record objects for the specified form.	var records = form.getRecords();
getRecordWithId()	record ID	record	Returns the record for the specified record ID.	form.getRecordWithId('rec-123456789abcdef');
getRecordsForSearchTerm()	text	array	Returns an array of record objects for the specified search term.	var records = form.getRecordsForSearchTerm("search term");
getScriptNamed()	text	Script	Returns the first Form Script with the specified name.	form.getScriptNamed("My Script");
getScripts()	none	array of Script	Returns the array of Script objects in the form.	form.getScripts();
getSearchNamed()	text	Search	Returns a search object given the name of a search.	form.getSearchNamed('Genre: Action & Adventure');
getTotalOfField()	field ID	number	Returns the total sum of all the records in the form for the specified field.	form.getTotalOfField(fieldID);
name	none	text	Returns the name of the form.	form.name;
runScriptNamed()	text	none	Runs the Form Script with the specified name. Used for including scripts inside other scripts.	form.runScriptNamed('Common Functions');
saveAllChanges()	none	Bool	Call this to save any changes your script has made to the database document.	form.saveAllChanges();
selectRecord()	record	none	Selects the specified record on the form.	form.selectRecord(someRecord);

field

Function/Property	Parameters	Returns	Description	Example
defaultValue	none	text	Get or sets the field’s default value.	field.defaultValue = 'some value';
fieldDescription	none	text	Returns the description of the field.	field.fieldDescription;
fieldType	none	text	Returns the type of the field.	field.fieldType;
form	none	Form	Returns the form the field belongs to.	field.form;
getId()	none	field ID	Returns the internal unique ID of the field.	field.getId();
hideField	none	none	Sets the field to be hidden or not.	field.hideField = true;
isCollapsed	none	none	Sets the Section field to be collapsed or not.	field.isCollapsed = true;
name	none	text	Returns the name of the field.	field.name;
script	none	text	Returns the JavaScript code for the specified field.	field.script;
sortOrder	none	number	Get or set the field sort order.	field.sortOrder = 2;

layout

Function/Property	Parameters	Returns	Description	Example
getId()	none	layout ID	Returns the internal unique ID of the layout.	layout.getId();
name	none	text	Returns the name of the layout.	layout.name;

pick lists

Function/Property	Parameters	Returns	Description	Example
getId()	none	pick list ID	Returns the internal unique ID of the pick list.	pick_list.getId();
name	none	text	Returns the name of the Pick List.	pick_list.name;
values	none	Array of Dictionary	Returns an array of dictionaries for the Pick List. The dictionary keys are value and valueColour	pick_list.values;

record

Function/Property	Parameters	Returns	Description	Example
addNewRecordToField()	field_id	record	Used for adding a new record to a Link to Form or Table field.	var newRecord = record.addNewRecordToField(field_id);
addFileFromUrlToField()	url, field_id	none	Fetches a file from the specified URL and adds it to the File Attachment field specified by field_id. The file can be a local file URL on disk in the Mac version when you have the Script Folder specified on the General Preferences window.	record.addFileFromUrlToField(file_url, file_field_id)
addPhotoFromUrlToField()	url, field_id	none	Fetches a photo from the specified URL and adds it to the Photo field specified by field_id	record.addPhotoFromUrlToField(image_url, case_cover_id)
addRecordToField()	record, field_id	none	Used for adding an existing record to a Link to Form or Table field.	record.addRecordToField(someRecord, field_id);
dateCreated	none	date	Returns the date the record was created.	var created = record.dateCreated;
dateModified	none	date	Returns the date the record was modified.	var modified = record.dateModified;
deviceName	none	text	Returns the name of the device that modified the record last.	var device = record.deviceName;
duplicate()	none	record	Returns a new copy of the record.	var copyOfRecord = record.duplicate();
form	none	Form	Returns the form this record belongs to.	record.form;
getAvgOfLinkedFieldForField()	linked field ID, field ID	number	Returns the average of all the records in the linked field for the specified field.	record.getAvgOfLinkedFieldForField(linkedFieldID, fieldID);
getFieldValue()	field_id	object	Gets the value for the specified field from the record. The return type depends on the field you’re getting the value from.	var barcode = record.getFieldValue(barcode_id);
getId()	none	record ID	Returns the internal unique ID of the record.	record.getId();
getMaxOfLinkedFieldForField()	linked field ID, field ID	number	Returns the maximum value of all the records in the linked field for the specified field.	record.getMaxOfLinkedFieldForField(linkedFieldID, fieldID);
getMinOfLinkedFieldForField()	linked field ID, field ID	number	Returns the minimum value of all the records in the linked field for the specified field.	record.getMinOfLinkedFieldForField(linkedFieldID, fieldID);
getNoteFieldValue()	field_id	note value	Gets the rich text note field value from the specified Note field.	record.getNoteFieldValue(field_id');
getRecordColor()	none	web hex color	Gets the web hex colour value for the record.	var color = record.getRecordColor();
getTotalOfLinkedFieldForField()	linked field ID, field ID	number	Returns the total sum of all the records in the linked field for the specified field.	record.getTotalOfLinkedFieldForField(linkedFieldID, fieldID);
getUrl()	none	url	Gets the URL for the record. This is the same URL as the Copy Record Link function under the Edit menu.	record.getUrl();
removeRecordFromField()	record, field_id	none	Removes a record from a Link to Form or Table field.	record.removeRecordFromField(childRecord, field_id');
recordExistsInField()	record, field_id	boolean	Returns true if the record exists in the Link to Form or Table field.	record.recordExistsInField(field_id');
setFieldValue()	field_id, value	none	Sets the value on the specified field.	record.setFieldValue(movie_title_id, 'The Terminator');
setFieldValue()	field_id, value, boolean	none	Sets the value on the specified field and optionally disables scripts that would run by default when the field value changes if the third parameter is false.	record.setFieldValue(movie_title_id, 'The Terminator', false);
setFieldValues()	dictionary, boolean	none	Sets the values on multiple fields at once given a dictionary of field ids and values. Second boolean parameter optionally disables scripts that would run by default if the parameter is false.	record.setFieldValues({ [field1_id]: "value1", [field2_id]: "value2", [field3_id]: "value3" }, false);
setNoteFieldValue()	field_id, value	none	Sets the rich text note field value on the specified Note field.	record.setNoteFieldValue(field_id, 'note_value');
setRecordColor()	web color	none	Sets the color for the record to the specified web hex color.	record.setRecordColor('#cc9900');
values	none	dictionary	Returns the values in dictionary format that are associated with this record. The key in the dictionary is the field ID.	record.values;

script

Function/Property	Parameters	Returns	Description	Example
getId()	none	script ID	Returns the internal unique ID of the script.	script.getId();
isFavourite	none	boolean	Gets or sets the script to be a favourite or not.	script.isFavourite = true;
name	none	text	Returns the name of the Script.	var scriptName = script.name;
code	none	text	Returns the source code of the Script.	var code = script.code;
scriptDescription	none	text	Returns the description of the Script.	var description = script.scriptDescription;

search

Function/Property	Parameters	Returns	Description	Example
getAvgOfField()	field ID	number	Returns the average value of all the records in the search for the specified field.	search.getAvgOfField(fieldID);
getMaxOfField()	field ID	number	Returns the maximum value of all the records in the search for the specified field.	search.getMaxOfField(fieldID);
getMinOfField()	field ID	number	Returns the minimum value of all the records in the search for the specified field.	search.getMinOfField(fieldID);
getRecords()	none	array	Returns an array of record objects for the specified search.	var records = search.getRecords();
getTotalOfField()	field ID	number	Returns the total sum of all the records in the search for the specified field.	search.getTotalOfField(fieldID);
name	none	text	Returns the name of the Search.	search.name;

Utils

Function/Property	Parameters	Returns	Description	Example
addToCalendar()	dictionary, start date, end date	event identifier	Adds an event given the specified start date, end date, and event info dictionary.	See example below
addToReminders()	dictionary, due date	none	Adds a reminder to the Apple Reminders for the specified reminder dictionary and due date.	See example below
alertWithMessage()	title, message	none	Displays an alert with the specified title and message	Utils.alertWithMessage('Script Run Complete!', 'Cool!!!!!');
copyTextFromClipboard()	none	text	Returns whatever text is on the clipboard.	Utils.copyTextFromClipboard()
copyTextToClipboard()	text	none	Copies the specified text to the clipboard.	Utils.copyTextToClipboard('Some text')
getDataFromUrl()	url	binary data	For the specified URL, returns a binary data response.	var photo_data = Utils.getDataFromUrl(url);
getDeviceName()	text	none	Returns the name of the device.	var device_name = Utils.getDeviceName();
getJsonFromUrl()	url	JSON	For the specified URL, returns a JSON response that you can get values from.	var product_info = Utils.getJsonFromUrl(url);
getTextFromUrl()	url	text	For the specified URL, returns a text response.	var product_info = Utils.getTextFromUrl(url);
getUserName()	text	none	Returns the name of the user logged in to the device. For iOS, returns “Mobile User”	var user_name = Utils.getUserName();
openUrl()	url	none	For the specified URL, calls the operating system to open it.	Utils.openUrl(url);
postContentToUrlWithContentType()	text, url, content type	dictionary	For the specified URL, posts the text content using the specified content type.	Utils.postContentToUrlWithContentType(some_string, url, 'application/json');
postJsonToUrl()	JSON, url	dictionary	For the specified URL, posts the JSON content.	Utils.postJsonToUrl(json_string, url);
printRecordsShowPanel()	boolean	none	When true passed in, shows the print panel before printing records. When false is passed in, prints the current view without showing the print panel.	Utils.printRecordsShowPanel(true);
updateCalendarEvent()	string, dictionary, start date, end date	none	Given an event identifier previously provided when adding an event, update the event information.	See example below
updateReminder()	string, dictionary, due date	none	Given a reminder identifier previously provided when adding a reminder, update the reminder information.	See example below

Prompter class – for prompting for input.

You can also prompt a user for input parameters, then take the input and use it for populating fields. Here’s an example:

var output = function printOut(continued) {
       if (continued == true) {
	   console.log(username + ", " + password + ", " + email_address + ", " + other_field + ", " + genre);
       } else {
          console.log("Cancel button pressed.");
       }
}


var username = 'test username';
var password;
var email_address;
var other_field;
var genre;
var genres = ['Action & Adventure', 'Comedy', 'Drama', 'Horror', 'Science Fiction'];

let prompter = Prompter.new();
prompter.cancelButtonTitle = 'No Thanks';
prompter.continueButtonTitle = 'Go For It!';
prompter.addParameter('Username: ', 'username', '', '', username)
.addParameter('Password: ', 'password', 'secure')
.addParameter('Email Address: ', 'email_address')
.addParameter('Other: ', 'other_field')
.addParameter('Genre: ', 'genre', 'popup', genres)
.addParameter('Media Type: ', 'media_type', 'picklist', 'Media Types List')
.show('Enter a Username and Password and Stuff', output);

*Note: the following parameters are valid .addParameter(label, field_name, control type, values_list, default_value)

Progress class – for monitoring the progress of long running scripts.

You can ask Tap Forms to display a progress indicator while you run scripts that might take a while to run. For example:

var progress = Progress.new();
function ProcessRecords(records) {
	for (index in records) {

		if (progress.cancelled) {
			console.log('Cancelled operation');
			break;
		}

		var aRec = records[index];
		// do something with the record.

		// update the progress indicator.
		progress.updateProgress(index);
	}
}

var records = form.getRecords();
progress.totalCount = records.length;
progress.currentCount = 1;
console.log('Begin');

// show the progress sheet
progress.show('Processing Records...');

ProcessRecords(records);

// dismiss the progress sheet when done.
progress.dismissProgress();

// save your changes 
form.saveAllChanges();

console.log('End');

Utils.addToCalendar()

You can ask Tap Forms to add an event to your Apple Calendar programatically. When you add an event, Tap Forms will return an event identifier which you could store somewhere, perhaps in another field that you could then retrieve at a later date and then update the event.

function Add_And_Update_Event() {

	var event_info = {"calendar_name" : "Work",
			"title" : "Test Event 1",
			"location" : "Big Ben, London, UK",
			"notes" : "This is a note",
			"url" : "https://www.tapforms.com",
			"all_day" : true};

	var start_date = new Date();
	// Create new Date instance
	var end_date = new Date();

	// Add a day
	end_date.setDate(end_date.getDate() + 1);

	var identifier = Utils.addToCalendar(event_info, start_date, end_date);
	console.log(identifier);

       // Update the calendar if you want. But you don't need to update right after you've added.
       // You'll want to store the identifier obtained from above somewhere (in another field) so
       // later on you can update the calendar entry if you wish.

	event_info["title"] = "Hello Event 2";
	Utils.updateCalendarEvent(identifier, event_info, start_date, end_date);

}

Add_And_Update_Event();

Utils.addToReminders()

You can ask Tap Forms to add an reminder to your Apple Reminders programatically.

function Add_And_Update_Reminder() {

	// Create new Date instance
	var due_date = new Date();

	// Add a day
	due_date.setDate(due_date.getDate() + 1);

	var event_info = {"list_name" : "Work",
					"title" : "Test Event",
					"priority" : 1,
					"notes" : "test note",
					"repeat_option" : 2};

	var identifier = Utils.addToReminders(event_info, due_date);
	console.log(identifier);
	event_info["title"] = "Hello Reminder 2";
	Utils.updateReminder(identifier, event_info, due_date);

}

Add_And_Update_Reminder();

Calling a script from a URL

You can call a Form Script from a URL when the URL is of the following format:

tapformz://script/[document ID]/[form ID]/[form script name]?key1=value1&key2=value2...

tapformz://script/db-xxxx/frm-xxxx/Test+Script?option1=A&option2=B

You can click the link button on the Script Editor window to get a copy of the script URL.

Notes:

• Tap Forms documents must be within the Tap Forms Container to receive and act upon URLs. If your document is visible on the main Database Documents window then you’re good.
• The query component of the URL must have spaces and double-quotes escaped.
• The =, &, and # characters within query values should also be percent-escaped. If this requirement is not followed, Tap Forms may not be able to identify the target script of the URL, listing it as (null) in the Console.
  

You will also have access to a special property in the Script editor called parameters.

To reference a parameter you would use this code:

var value_1 = parameters["key1"];

The parameters property will only be available when calling the script from a URL.

Here’s an example script:

function Test_Script() {
	var hello_world = "Hello World!"; 
	console.log(hello_world);
	var parms = parameters;
	console.log(parms["option1"]);
	var prompt = Prompter.new();
	prompt.show('Does this work?');
}

Test_Script();

Console Logging.

You can log your output to the console log view with the following code:

console.log("Colour Me This!", "#c90000");

The second parameter is optional and allows you to provide a hexadecimal web colour for your output.

Testing Tap Forms script code with an incoming URL.

Call the URL from the external app once. Tap Forms will remember the parameters. You can then edit and re-run the script within Tap Forms without resending the URL from the external app unless you make changes to the URL. The script editor can be open while an incoming URL is received. The script will run as usual, and output will be recorded in the Console.

The parameters global variable will contain query keys/values for the pairs specified within the URL. Although a query pair may have existed within the previous URL action, it will not exist within the parameters variable if the new URL does not include that pair.

The parameters global variable will revert between test runs of the Tap Forms script; i.e., if your script changes the contents of the variable, the next time the script is run, those changes will have been reverted to the values specified by the URL.

Copyright 2016, Tap Zapp Software Inc. All Rights Reserved.