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
createFormNamed() text form Call this to create a new form with the specified name. document.createFormNamed('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();
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. document.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);
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;
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();
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();
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 executes scripts that would run by default when the field value changes. record.setFieldValue(movie_title_id, 'The Terminator', false);
setFieldValues() dictionary none Sets the values on multiple fields at once given a dictionary of field ids and values. record.setFieldValues({ [field1_id]: "value1", [field2_id]: "value2", [field3_id]: "value3" });
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);

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;
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')
.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);

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);
	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 new button on the Script Editor window to get a copy of the script URL.

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.

Need more help with this?
Don’t hesitate to contact us here.

Was this helpful?

Yes No
You indicated this topic was not helpful to you ...
Could you please leave a comment telling us why? Thank you!
Thanks for your feedback.