Overview

Looking for the FRToolBox Function Reference? https://splashdocs.atlassian.net/wiki/spaces/FusionReactor/pages/2202599558

The real power of the Fusion Reactor plugin is that it allows a JavaScript solution running in a web viewer to actively communicate with your database. The possibilities opened by this are limitless, but begin with something as simple as updating FileMaker data based on what the user is doing in a web viewer with interactive content.

To provide two-way communication between your FileMaker database and a JavaScript solution, Fusion Reactor uses AJAX techniques to receive and answer requests. If you've worked with JavaScript and AJAX techniques before, you'll find it very easy to work with Fusion Reactor. If you're more familiar with FileMaker scripting you won't have to get your hands dirty with low-level AJAX development, but may find the asynchronous development model a little different at first.

Fusion Reactor comes with a demo database that includes a wide range of sample solutions, from simple buttons to rich two-dimensional drag-and-drop interfaces. The quickest way to get a ‘feel’ for programming a Fusion Reactor-based solution is to delve into this demo database and see how the different examples are put together.

To understand how the system works, we'll start with a quick look at three different ways of communicating, starting from the lowest level and leading up to the highest. Then we'll work through these techniques in detail in the opposite order, so that you can pick the level at which you need to operate.

Levels of Communication

There are three different levels at which your solution can interact with the Fusion Reactor plugin.

1. Plugin base functions (fiendish)

2. ToolBox callback function (involved)

3. ToolBox high-level functions (easy)

4. ToolBox Object Oriented functions (easiest)

These different levels will suit different developers and different solutions, but all are available simultaneously so you can mix and match, using whichever techniques you find most effective at the time.

At the lowest level, you can talk directly to the plugin using either its two basic ‘callback’ functions: SQL() and Script(), or using the newer XML format requests. https://splashdocs.atlassian.net/wiki/spaces/FusionReactor/pages/2202730599 Doing this will require your JavaScript solution to handle the AJAX communications, which you may want to do if, for example, you are making use of a third-party JavaScript library which includes AJAX handling.

At an intermediate level, you can use the FRTB_FMCallBack() function provided by the Fusion Reactor ToolBox. This function will take care of the AJAX communication handling for you, but will require you to construct and provide complete SQL or XML requests for any interaction with data in your FileMaker tables. This allows you to send and execute more complicated SQL than the easier methods allow.

The Fusion Reactor ToolBox provides a set of “CRUD” (Create, Review, Update, and Delete) functions for working with your FileMaker data. If you don’t speak fluent SQL, and you aren't familiar with JavaScript Object's, this is likely to be the level for you.

Lastly, the Fusion Reactor ToolBox gives you access to an even simpler Object Oriented notation for executing requests on your database. The Object provides useful automated debugging, and automates all aspects of creating and sending multiple requests to FileMaker, allowing you to concentrate on your JavaScript rather than XML, and SQL.

Some Terminology

Before going into more details on the levels of communication, it’s helpful to define a few terms we’ll be using:

SQL (Structured Query Language)

SQL is a widely-used language for communicating with databases. Although it is not a documented feature, FileMaker includes an internal facility for working with data in FileMaker tables using SQL statements. The Fusion Reactor plugin makes use of this feature to help communicate database requests between a JavaScript solution and your FileMaker database. Using SQL, you can frame requests to fetch data from FileMaker tables, update field values, create new records, and delete records.

XML (Extensible Markup Language)

XML (Extensible Markup Language) is a widely-used data format for transmitting and encapsulating data. This format is used in Reactor 3.1 to allow simpler and more accurate parsing of return data for Finds, and also to allow a simple and effective way for users to pass extra parameters and instructions to Reactor in one single request.

Fusion Reactor ToolBox

Included with the Fusion Reactor plugin is a suite of JavaScript functions called the Fusion Reactor Toolbox. These ‘helper’ functions are designed to handle some tasks like AJAX communications handling and SQL query construction, so that you don’t have to take the time to build those into your own JavaScript solution.

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

FRTB Object

FRTB in ToolBox version 2.1 is not compatible with Reactor versions under v3.1. Please make sure you are using FRToolBox 2.1.0 or greater - v2.0.x is significantly different to what is described here.

The FRTB Object is available as soon as you include the FRToolBox file in your JavaScript solution. Something Reactor veterans will note is the new syntax for creating, sending, updating and deleting records. All the old functions are still available and still work just fine - However the new syntax is much simpler and quicker.

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

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:

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.

The FRTB object gives you access to several methods which make it really easy for you to interact with your FileMaker data, and even allow you do do things that weren't previously possible, like evaluating an arbitrary FileMaker Calculation.

Asynchronous Programming Model

The first "A" in AJAX stands for "Asynchronous," and this is one of the more challenging concepts to get to grips with. When your JavaScript solution communicates with FileMaker, it does so by sending off an AJAX-style XML HTTP 'request,' and cannot simply wait for an answer as (for example) a FileMaker script would do. Your solution needs to relinquish control at some point (usually immediately after issuing a request), and when the response to your query arrives it will trigger the execution of another part of your code.

If you're using the Fusion Reactor ToolBox's object oriented functions to talk to FileMaker, the nuts and bolts of the AJAX process, and SQL Request is handled for you and all you need to do is supply a 'success' or 'error' function (see below for further information). After 'sending' a request, the response to your query will then come back from FileMaker and trigger the 'success' or 'error' function, which should contain the appropriate instructions to carry on with the next logical steps.

To see this process in action, take a peek into the sample JavaScript code that underpins the examples in the Fusion Reactor demo database. Here's a fictitious example in the form of the Roster demo:

The key here is the last line of the InitialisePool function: the send() method of the FRTB.find request is called to fetch a list of staff members from a FileMaker table. There are no further commands to be executed after this find command is issued, but the send command includes a reference to an 'onsuccess' function called PopulateStaffPool: this is a separate JavaScript function—defined later in the code—which will receive the list of staff members, and will create the display elements for each one in the staff pool area on screen.