Scripts

New to Tap Forms 5.3 are Scripts both at the Form level and Field level. Scripts allow you to write code that can perform complex actions on your data.

*Scripts must be written in the JavaScript programming language. Please see this link for more information about what JavaScript syntax is supported: https://tc39.github.io/ecma262/

*For a getting started tutorial on scripting, please see Tap Forms Scripting 101 This is useful even if you have no prior programming experience.

Field Level Scripts

The Script field is similar to the Calculation Field in that it gets executed when any field the script references changes. The mechanism that triggers the script to be executed is when you have a reference to a field in your script via the record.getFieldValue(field_id) function and that field changes in the record. Scripts can often be more efficient and easier to understand when dealing with complex formulas. So if your formula starts to get complex, you might consider using a Script field instead.

To create a Script field:

1. Open the Forms sidebar and click “Fields”
2. Click the + button to add a new field
3. In the dropdown menu, choose the Script field type
4. Scroll down to find the Edit Script… button and click on it. You can also double-click on a Script field to quickly open the Script Edit window

After you’ve clicked the Edit Script… button, you’ll be able to input your own custom scripts, as well as use snippets and available fields to help you in the process. As you work, you can choose how you’d like the result to be returned to the field (number, date, text, etc.). You can also adjust the text size of the script you’re written with the font size slider. When you’ve finished, clicking Save will save the script to your field.

*If you don’t want to have your script update all the records in your form, uncheck the Update records when saving checkbox button. Saving will now simply save the script and will not loop through your records executing the script for each record.

Form Level Scripts

In addition to field scripts, Tap Forms 5.3 also supports form level scripts, which can be used to create new records and update existing records within your forms. Form scripts are executed manually by you.

To create and modify these scripts, visit the Scripts tab in the form inspector panel. You can double-click a Script to go directly to the Script Edit window. Scripts can also have keyboard shortcuts added to them to make running them easier when using the keyboard. All form scripts will appear in the new Scripts menu in the menubar at the top of the screen. Selecting a script from the Scripts menu will run the selected script.

Built-in Tap Forms specific objects

A Tap Forms database consists of Forms, Searches, Fields, Pick Lists, Categories, Records and values. A few of these things can be accessed right from within a script using the following built-in objects:

• form
• search
• record

See the Tap Forms JavaScript API to find out what specific functions are available to you.

Snippets

Within the Tap Forms Script Editor, there is a list of Snippets that you can use to help you get access to the records and values that you will need when writing your scripts. For example, to get access to the list of records in a form, use the following line of code:

var records = form.getRecords();

Once you’ve defined the records variable, you can then write code to loop through the array of record objects, picking out values from specific fields in your form. Tap Forms makes this easy by automatically writing code for you when you double-click on a field name and double-click on a Snippet.

For example, here’s a block of code for a form level script which loops through all the records in a form and totals up the revenue from all of the movies in a Movies form:

var records = form.getRecords();
var revenue_total = 0;

for (var index = 0, count = records.length; index < count; index++){
   var theRec = records[index];
   var movie_revenue = theRec.getFieldValue('fld-987c9aac738a4f0fa1d18395902b3fc1');
   if (movie_revenue) {
      revenue_total += movie_revenue;
      console.log('Revenue: ' + movie_revenue);
   }
}

revenue_total;

You may also notice there’s a line of code that says console.log('Revenue: ' + movie_revenue);. That tells Tap Forms to output that line to the console log area on the Script Editor screen. This is very useful for debugging your scripts as Tap Forms doesn’t have a formal JavaScript debugger built-in. You will need to use the console.log() function to aid in debugging.

Fetch Movie Data from Web Service

Here’s an example Field script which fetches movie data when entering a value into a barcode field. You can even use it to scan a barcode using the iOS version. It will automatically fetch the data and fill in the fields for you, including downloading a movie case cover photo.

var movie_title_id = 'fld-987c9aac738a4f0fa1d18395902b3fb1';
var genre_id = 'fld-2a0d16d2aece4562b6f44170cf1736a6';
var case_cover_id = 'fld-e2cf02f376864a7cb9f090e4a597f3e4';
var summary_id = 'fld-28cc8f7f082c43818f1169c96c96e5a9';
var imdb_website_id = 'fld-9bc90613e8db45fea77579f35eb53b9d';
var barcode_field_id = 'fld-7e3ead95de51427fa5a467b2476d58cd';

function fetchProductInfo() {
	var barcode = record.getFieldValue(barcode_field_id);
	var url = 'https://api.upcitemdb.com/prod/trial/lookup?upc=' + barcode;
	var product_info = Utils.getJsonFromUrl(url);
	return product_info;
}

var product = fetchProductInfo();
var code = product['code'];

if (code == 'OK') {
	var items = product['items'];
	var item = items[0];
	var images = item['images'];
	var imageUrl = images[0];
	var offers = item['offers'];
	var offer = offers[0];
	var link = offer['link'];
	record.setFieldValue(imdb_website_id, link);
	record.setFieldValue(movie_title_id, item['title']);
	record.setFieldValue(summary_id, item['description']);

	if (imageUrl != undefined) {
		record.addPhotoFromUrlToField(imageUrl, case_cover_id);
	}
	form.saveAllChanges();
}

* Please note that the field IDs in the above script (e.g. movie_title_id = ‘fld-….’) are unique to the form this script was written for. You would need to use your own field IDs from your own form to make this script work.

And here’s another Field script which returns a simple value by multiplying 2 values together and returning the result:

var amount_id = 'fld.....';
var quantity_id = 'fld....';
var amount = record.getFieldValue(amount_id);
var quantity = record.getFieldValue(quantity_id);
var total = amount * quantity;
'The total is: ' + total;

In the above script, because it returns a Text value, make sure you set the Result Type to Text.

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