FRToolBox Function Reference

Want to know more about the FRToolBox?

The Fusion Reactor Toolbox is just an ordinary file of JavaScript functions, and objects. If you have included the file in the 'libs' folder under your BlackBox project directory, your JavaScript solution can access it at any time with a simple HTML command:

<script type='text/JavaScript' src='./libs/FRToolBox.js'></script>

FRTB Object

Previously to write a find request to FileMaker, you needed to write the following JavaScript:

FRTB_FMFind( 'FM.link', '"Toys"', '"Toys"."Name", "Toys"."Type"', ' "Toys"."Owner"=\'Jane\\\'s\' AND "Toys"."Borrower"=\'Mike\'"', CompletionFunction );

This gets worse when you realize that the native FileMaker way of formatting field names is MyTO::My2ndTo. You can see that escaping the strings also can quickly become a nightmare, because not only are you escaping the string for the JavaScript, you are also escaping the string for the SQL as well. The FRTB object takes care of all that for you, so you only need to escape for the JavaScript.

This is an equivalent find using the new syntax:

FRTB.find( "Toys::Name", "Toys::Type" ).filter("MyTo::Owner=Jane's¶MyTo::Borrower=Mike").send( CompletionFunction );

You don't need to worry about converting native FileMaker fields to another format, and we don't need to worry about escaping any of the values for the SQL either... you don't even need to know what SQL is to understand what's going on here.

FRTB Function Reference

Methods used to create and execute a request on a FileMaker database.

Find Request

FRTB.find( "MyTO::Field One", "MyTO::Field Two" );

This method will return a request object which you can use to add details, debug and send your request. The request would find the FileMaker internal record ID field - Get ( RecordID ) - along with each of the parameters you sent through to the find function... in this case, "Field One" and "Field Two".

Creating a request will not immediately fetch your data from FileMaker - you need to run the .send() method of the returned request object. You can do this in two ways:

// Simply chain the send method to the Request

FRTB.find( "MyTO:Field One", "MyTO::Field Two" ).send();

// Or assign the Request to a variable, then send it.

var MyFind = FRTB.find( "MyTO::Field One", "MyTO::Field Two" );

MyFind.send();

Using the first chaining method allows you to create quick and simple 'throw-away' requests. However, assigning the request to a variable, allows you to add to, or reuse the request further down the track.

You can chain any of the request object methods to the find request. Lets say you only wanted to find the records where the Color field contained the value 'Green'. You could write the request like this:

// Simply chain the send method to the Request

FRTB.find( "MyTO:Field One", "MyTO::Field Two" ).filter( "MyTO::Color=Green" ).send();

The find would then fetch the internal FileMaker record ID, Field One, Field Two and Color. The records returned would only be the records with 'Green' in the color field. You can read more about the .filter() method below.

Create Request

FRTB.create(["MyTO::Field One", "First"], ["MyTO::Field Two", "Second"]);

Like the find request, this method will return a request object, which you can then use to add details, debug and send your request. The request would create a record on the 'MyTO' table, and set 'Field One' to the value 'First' and 'Field Two' to the value 'Second'.

Update Request

FRTB.update(["MyTO::Field One", "First"], ["MyTO::Field One", "First"]);

As with the other request methods, this will return a request object, which you can then use to add details, debug and send your request. The above request - if sent - would set 'Field One' to the value 'First' and 'Field Two' to the value 'Second' for every record in the 'MyTo' table.

// Update records which have 'Pink' in the color field

FRTB.update(["MyTO::Field One", "First"], ["MyTO::Field Two", "Second"]).filter("MyTO::Color=Pink").send()

FRTB.calc( 'Get ( FileName )' );

FRTB.calc( 'Let( $$MyGlobalVariable = "MyValue" ; "" )' ).send();

Request Object Methods.

FRTB.find('MyTO::MyField').filter('MyTo::MyColor=Reactor Blue').send()

• = ( field equals constant )
• > ( field is greater than constant )
• < ( field is less than constant )
• >= ( field is greater than or equal to constant )
• <= ( field is less than or equal to constant )
• <> ( field is not equal to constant )
• ~ ( field is LIKE constant - wild card ( * ) capability )

FRTB.find('MyTO::MyField').filter('MyTo::MyColor=Reactor Blue\nMyTo::MyStatus<>Deleted').send()

FRTB.find('MyTO::MyField').filter('MyTo::MyColor=Reactor Blue\\n').send()

FRTB.find('MyTO::MyField').filter('MyTo::MyColor=Reactor Blue||White||Black').send()

FRTB.find('MyTO::MyField').filter('MyTo::MyStatus<>Deleted&&On Hold').send()

FRTB.find('MyTO::MyField').filter('MyTo::MyColor=Reactor Blue||White||Black\nMyTo::MyStatus<>Deleted&&On Hold').send()

Send Method

FRTB.find('MyTO::MyField').send()

Debug Method

FRTB.find('MyTO::MyField').debug()

FRTB.find('MyTO::MyField').send({'onError':function(error){ error.request.debug() }});

Poll Method

You can implement a poller by chaining this method to your find request.

FRTB.find('MyTO::MyField').poll( myCallback ).send()

myCallback handles the actual updates deletes and grabbing the new records... the poller will pass it a list of rowid's that need updating, removing or retrieving in the form of an object looking like this:

{

	create : ArrayOfRowIDs

	update : ArrayOfRowIDs

	remove : ArrayOfRowIDs

}

If your original request looks like this

FRTB.find( FieldOne, FieldTwo ).send( completionFunction );

It will end up looking something like this:

FRTB.find( FieldOne, FieldTwo ).poll( myCallback ).send( completionFunction );

You are able to put the .poll() wherever you like, and it will still work - even after the send. You could even start the poll inside the completion function.

FRTB Utility Methods

The FRTB object also provides you access to certain ancillary functions which may become useful in some circumstances.

FRTB Actions

An 'Action' is a standardized way of giving users the ability to supply their own method of responding to a particular interaction, or event. For example, in the Day Calendar, we give the FileMaker developer the ability to 'do something' when the end-user clicks on one of the appointments. To the FileMaker developer, we call this 'ActionOnApptSelect', and they can specify if they want that action to set a field, or run a script, and they can also specify the value they wan't to populate the field with, or pass to the script.

FRTB.getAction( 'Script=MyScript', 'myAction' );

The above action, when performed would run the script 'MyScript' while passing no default parameter.

FRTB.getAction( 'SetField=MyTO::MyField', 'myAction' );

The above action, when performed, would set the field 'MyField' on the table occurrence 'MyTO' (as we haven't specified a value, however, it would empty the field.

Action Syntax

Action Type	Description
Script	Run a FileMaker script using the 'GetField' or 'Parameter' option as the parameter.
SetField	Set a FileMaker field using the 'GetField' or 'Parameter' option as the value to set. Using a SetField, we automatically get the current value of that field when the Action is initialized, for the JavaScript to use.
SetGlobal	Set a FileMaker global variable using the 'GetField' or 'Parameter' option as the value to set. Using a SetGlobal, we automatically get the current value of that field when the Action is initialized, for the JavaScript to use.
Function	Runs a JavaScript function using the 'GetField' or 'Parameter' option as the functions parameter.

Lets say we wanted to set the global variable '$$MyGlobal' to the value 'ActionPerformed' whenever our action was performed...

FRTB.getAction( 'SetGlobal=$$MyGlobal|Parameter=ActionPerformed', 'myAction' )

Notice how we separated the global variable name with the |Parameter=. The same is true when using a GetField:

FRTB.getAction( 'SetGlobal=$$MyGlobal|GetField=MyTO::MyField', 'myAction' )

How does the get field know which record to use when performing the action? You need to tell it. When you do your find for record data, you can add the result of a FRTB.getAction call into a FRTB.find request. The find request will automatically find any fields that the action needs, and include those values in the resulting data. For example:

var MyAction = FRTB.getAction( 'SetField=MyLayoutTO::CurrentRecord|GetField=MyDataTO::MyID', 'myAction' );

FRTB.find(

'MyDataTO::FieldOne',

'MyDataTO::FieldTwo',

// Include any action fields...

MyAction

).send(getData);

function getData( response ){

FRTB.performAction( 'myAction', response.data[0] )

}

Now, lets go through that line by line. First, we set up the action. We want the action to set the field 'CurrentRecord' on 'MyLayoutTO' to whatever the value of 'MyID' on 'MyDataTO' is for the passed record - we name that action myAction, and store the action in the 'MyAction' variable.

Next, we perform the find. We know we want to find FieldOne and FieldTwo for each record, and we know we want to find whatever 'GetField' is in 'MyAction' - currently this is, 'MyID', but this could be changed by a FileMaker Developer, or end user if we give them some way to do that. We send the response, using the 'getData' function as our completion function for the find.

In the 'getData' function, we perform 'myAction', and we pass the first records data as the second parameter.

The performAction script will automatically extract the 'MyID' field from the passed data object, and will use that as the value to set the 'CurrentRecord' field.

Request Configuration

If you need to specify advanced configuration options for your request, you can do this by passing an object to the .send() method when sending your request to FileMaker.

FRTB.find('MyTO::MyField').send({

})

The possible configuration options are listed in the table below.

Debugging

The Fusion Reactor ToolBox contains a useful debugging console with advanced features to assist with your development. The FRTB object uses the debugger to provide developers with feedback on many of its functions. Find out more about JavaScript Debugging with Reactor.