INTRODUCTION

The Fusion Reactor plugin allows you to add rich interfaces to your FileMaker Pro database.

Using the power of web technologies (HTML, JavaScript, etc.) inside a web viewer, you can place anything on your FileMaker layouts from a simple element such as a slider control through to a full sophisticated drag-and-drop interface to your data.

The Fusion Reactor plugin comes with some powerful pre-built interface controls ('Black-box Controls") that can be dropped in to your FileMaker solution with no coding required. These controls are designed to be integrated into your solution with a minimum of fuss, using just one function call and a few simple settings.

If you want to go beyond that starting point and develop your own interface tools, this User Guide and the examples included with the plugin will help you get to grips with using the Fusion Reactor plugin in a JavaScript development environment. (For the rest of this manual, we’ll use the term ‘JavaScript solution’ as shorthand for whatever interactive content you may have inside your web viewer.)

How it Works

To carry out its job, Fusion Reactor behaves much like a mini-web server, 'listening' for contact from a FileMaker web viewer.

The Fusion Reactor plugin works for you in two main ways:

1. It 'serves' information to a FileMaker web viewer from within the database itself, avoiding the need to store HTML, JavaScript, images etc. in separate disk files or on remote servers.
2. It allows the interactive content of a web viewer to talk back to FileMaker, so that FileMaker can 'react' to what is going on. Most importantly, Fusion Reactor ensures that what goes on inside a web viewer can feed back into your database.

DOCUMENTATION

This User Guide provides the detailed information you will need if you are developing sophisticated solutions from scratch using JavaScript and HTML.

If you're looking to get started with the powerful Black-box features, you won't need this much detail: the best way to learn is to dive straight into the demo database and see how they are used in the examples.

SYSTEM REQUIREMENTS

Fusion Reactor requires FileMaker Pro 8.5 or later, including FileMaker Pro 10.

The Macintosh version requires OS X 10.4 or later.

The Windows version requires Windows XP, XP Pro, or Vista, with Internet Explorer 6 or above.

INSTALLATION

When you first open the Fusion Reactor demo database, it will offer to install the plugin for you.

To update to a newer version, download a fresh copy of the demo database and launch it; it will offer to install the new version of the plugin.

If you prefer to install the plugin manually, the Installation Options button will take you to a screen where you can save the plugin to your hard drive. You can then transfer the plugin to the appropriate folder for your computer (consult your FileMaker Pro documentation for further details).

COMPONENTS

The downloaded zip file contains a FileMaker Pro demonstration database. The plugin itself is stored in the database, and will prompt you for an automatic installation when first opened. Manual installation options are also provided.

The demo database also contains a trial license agreement, and this User Guide.

TRIAL MODE

In trial mode, the Fusion Reactor plugin is limited to 30 minutes of usage per session. To continue using the plugin, simply restart FileMaker, or purchase a license key at http://fusionplugins.com

CONTACT US

If you have further suggestions or comments pertaining to Fusion Reactor, feel free to contact us. We are dedicated to enhancing our products constantly, and your feedback and ideas are appreciated.

In order to communicate with you most efficiently, we provide technical support via e-mail or fax. We will do our best to respond to your requests in a timely manner.

The latest developments and tips can be found on our home page.

Contact details:

E-Mail: reactor@fusionplugins.com

Web: http://fusionplugins.com

GETTING STARTED

Registering your Fusion Reactor

Fusion Reactor is ready to go in 30-minute trial mode as soon as you launch FileMaker Pro with the plugin installed. For a finished solution, however, you will want to lift the control rods and take it out of trial mode with the RegisterReactor() function. (NB the legacy StartReactor() function is no longer required, but continues to work and will register the plugin if given the same parameters.)

RegisterReactor() is best called in a startup script. You should supply two parameters to the function: the company name that you used when registering the plugin, and the license key that you received, e.g.:

Please note that both the company name and the license key must match exactly.

(NB In Reactor v2 you no longer need to keep track of the result of this function call.)

Remember to tell your database to execute your startup script when the database is opened: choose File Options... from the File menu, and look under the Open/Close tab for the Perform script: setting.

Checking your Fusion Reactor’s Version

You can determine version and licensing information for the currently-installed Fusion Reactor plugin with this external function:

The single parameter can be used to specify the format in which the version number will be returned:

• 0 or blank ( "" )

• "VID"

• "License"

Example

Create a calculation field called “Version Number”. It should have a text result and be unstored. The calculation should be:

You can then display this field on your FileMaker Pro layout in order to show which version of the Fusion Reactor plugin is installed.

SERVING CONTENT

Overview

Using the Fusion Reactor plugin, you can serve any kind of data straight from your database, ready to be collected and viewed in a web viewer layout element.

FileMaker's web viewer layout element displays information in any format that would be viewable in a web browser (e.g. HTML pages, JPEG images, etc.). When you add a web viewer to a FileMaker layout you specify a web address (i.e. a URL) which tells it where to find the information that it should display. Typically this URL will specify a file stored on either a local disk or a remote web server.

Using the Fusion Reactor plugin, you can instead specify a special URL that will actually refer to the plugin itself, and the plugin will serve up the content you ask for without the need for external files or remote servers. This is all accomplished with a single FileMaker external function call that loads data into the Fusion Reactor, and returns a URL to be used as a web viewer’s Web Address value.

Loading Content

In order to serve an HTML page, JPEG image, JavaScript solution, or other web content from the Fusion Reactor plugin, you first load that content into the plugin’s memory using the FeedReactor() function:

FeedReactor( Name, Content )

This function achieves two important things:

1. It loads content into the Fusion Reactor plugin so that it can be served.
2. It returns the URL which can be used to retrieve that content.

The Content parameter specifies the content that you are loading. This will normally be a FileMaker field reference: typical examples would be a page of HTML text sourced from a text field, or a JPEG image sourced from a container field.

The Name parameter is a name that distinguishes this item of content from other items that may be loaded into the Fusion Reactor. The plugin will use this name to build up the complete URL which will uniquely identify this item. You can then use that URL to load the content item into a web viewer.

The content item will be remembered and served by the Fusion Reactor plugin until it is overwritten with a fresh copy, or until FileMaker quits, so you can access it over and over again.

If you call this function again with the same Name parameter, it will overwrite the existing element and begin serving the new Content.

Examples

This function call will load an HTML page ready for serving under the name “MyPage.html”. The HTML text is sourced from a field called “MyPage” in a FileMaker table called “MyContentTable”.

Here we are loading and serving a JPEG-format photograph from a container field. Note that the Name parameter is formed by incorporating a unique value from the FileMaker record. Because the name will therefore be different each time, this will load and serve a new and separate JPEG image for each record that we view, as opposed to overwriting the same image each time. This important technique allows us to keep multiple content elements loaded simultaneously in the Fusion Reactor plugin, e.g. in order to display a portal containing photos from a range of records.

In the demo database included with the Fusion Reactor plugin, all the examples are served out of FileMaker fields. Sometimes more than one served element is involved, e.g. the Roster example includes the JavaScript solution that provides the rostering functionality, but also each staff member photograph is a separate served element drawn from container fields, and even the small image for the delete buttons is served from a global container field.

Retrieving Content

When you call the FeedReactor() function as described above, it will return a URL that uniquely identifies the content you just loaded.

If you then use that URL as the web address of a web viewer element in a FileMaker layout, FileMaker will know to ask the Fusion Reactor plugin for that content.

The URLs from the examples above would look something like this:

• http://127.0.0.1:54265/MyPage.html
• http://127.0.0.1:35674/Convict_176-671.jpg

127.0.0.1 is a special IP address that means ‘this computer’, and 54265 (in the first example) is the port number on which Fusion Reactor is currently listening (the port number will change each time you run FileMaker).

Putting It All Together

There are a number of different ways in which you can arrange for content to be loaded and later retrieved. For example, you might use a FileMaker script step to call the FeedReactor() function, and store the resulting URL in a global variable:

After executing this script step (perhaps in a startup script), you can simply use the global variable $$MyPageURL as the web address for a web viewer.

A more direct method is to write your web viewer’s web address as a FileMaker calculation that calls FeedReactor() to load the content and provide the URL all in one go:

When the web viewer needs to know its URL, it will execute this calculation. As a result, the page will be loaded into the Fusion Reactor plugin at that point, and the FeedReactor() function call will return a URL like the one above, which the web viewer will then use to fetch its content for display.

Important Note regarding Safari 3 Beta on Mac OS X: At the time of release, there is a significant incompatibility between FileMaker Pro and Apple’s beta release of Safari 3 (specifically, its WebKit underpinnings). In particular, making use of a FileMaker field reference in a Web Address calculation will crash FileMaker, regardless of whether Fusion Reactor is installed (full radiation containment is nonetheless guaranteed). For this reason you should not use the above method if you have the Safari 3 beta release installed. FileMaker’s advice to avoid this problem is to uninstall the beta release of Safari 3.

INTERACTING WITH THE DATABASE

Overview

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
2. ToolBox callback function
3. ToolBox high-level functions

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 its two basic ‘callback’ functions: SQL() and Script(). 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 requests for any interaction with data in your FileMaker tables. If you’re familiar with using SQL to interact with databases, you might prefer to work mostly at this level.

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

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

• Fusion Reactor ToolBox

SQL in the ToolBox functions

If you are familiar with SQL, you may wish to build and submit complete SQL commands to the FRTB_FMCallBack() function. However the four higher-level ‘CRUD’ functions will help you prepare and send database requests without having to be familiar with SQL syntax. These four functions require only ‘snippets’ of simple SQL which, for common simple operations, will use the same sort of terminology that you’ll already be familiar with from JavaScript and even FileMaker’s own scripting language.

For example, this FRTB_FMFind() function call

is equivalent to this FRTB_FMCallBack() function call

FileMaker’s internal SQL support is not publicly documented, but is very similar to the documented SQL support in FileMaker Server, which you can read about in the document fm7_odbc_jdbc_developer.pdf, available from FileMaker’s website.

Some important points:

• When using a FileMaker table or field name that includes spaces or other special characters, you need to surround the name with double-quotes in order to avoid ambiguity. For example:

• When referring to a literal value in SQL, it must be surrounded by single quotes (NOT double-quotes). Because your SQL request or SQL snippet will itself often be a text string surrounded by single quotes, you will generally need to ‘escape’ the inner quotes with backslashes to avoid confusion, just as you would if you were assigning the same value to a JavaScript variable:

• FileMaker’s SQL implementation uses an uncommon symbol for the ‘not equals’ operator: where JavaScript uses != and FileMaker uses ≠ , the appropriate symbol in SQL is two angle-brackets: <>

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 high-level CRUD functions to talk to FileMaker, the nuts and bolts of the AJAX process is handled for you and all you need to do is supply a 'completion function' (see below for further information). After issuing a request, your JavaScript solution should relinquish control by executing no further instructions. The response to your query will then come back from FileMaker and trigger the completion function, which contains 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 an example from the Roster demo:

function InitialisePool() {

// Create a 'pool' container where staff member objects will be displayed,

// ready for dragging onto the roster.

// Then send off a request to fetch a list of staff members from the FileMaker database

// and use it to populate the pool.

CreateBlockContainer(

PoolContainerName,

PoolX, PoolY, PoolWidth, PoolHeight,

1, PoolSlotsHigh,

SlotWidth, SlotHeight,

PoolBlockColour, PoolBorderWidth, PoolBorderColour );

// Allow the pool to scroll if there are more staff members

// than can be displayed within its boundaries.

document.getElementById( PoolContainerName ).style.overflow = 'auto';

FRTB_DebugMessage( 'About to request a list of pool staff from FileMaker' );

FRTB_FMFind( FMLink, RosterStaffTableName, '"Name", "Photograph Link"', '', PopulateStaffPool );

}

The key here is the last line of the function: the Fusion Reactor ToolBox's FRTB_FMFind() function 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 find command includes a reference to a completion function called PopulateStaffPool: this is a separate JavaScript function—defined later in the code—which will receive the list of staff members, and create an object for each one in the staff pool area on screen.

Level 3 Communications: ToolBox CRUD Functions

The Fusion Reactor ToolBox provides a set of four high-level functions for performing basic Create, Retrieve, Update and Delete operations. By using these functions when they suit your needs, you can keep your JavaScript solution clean and readable by eliminating the need to manually construct SQL queries and perform explicit AJAX communication handling.

Each function takes a range of parameters, but two common ones are worth discussing first:

• FMTarget

• CompletionFunction

• Status Code

• Response Text

Retrieving data from FileMaker tables: FRTB_FMFind()

The FRTB_FMFind() function lets you look up data in FileMaker tables, and bring the resulting data through into your JavaScript solution.

• FMTarget

• TableNames

• FindExpression

• MatchCondition

• CompletionFunction

A typical call to FRTB_FMFind() will specify a single FileMaker table name, and one or more fields to be retrieved. If you don't want data from every record in the FileMaker table, you will also want to specify a MatchCondition to help narrow down the results.

There is a limited range of information that you can retrieve using SQL that is not drawn from FileMaker tables. For example the SQL request “SELECT 6 * 9” will return “54”, while “SELECT CURRENT_DATE” will return today’s date. For this reason, an empty string (“”) can be supplied for the TableNames parameter in these cases.

More usefully, it is possible to retrieve information from multiple tables in a single operation. For example:

This call is retrieving client and invoice information by performing an SQL ‘join’, which is similar to a FileMaker Relationship. The MatchCondition links client and invoice records based on a client ID, and the information returned is the client name (from the “Clients” table) and the invoice total (from the “Invoices” table) for each invoice for an amount greater than 1000. Note that you do not need to have a FileMaker relationship pre-defined in your database for this join to work.

You may also want to retrieve information from just one table, but include criteria from another table as part of your MatchCondition. For example, to find clients who have received large invoices:

Here we have only asked for client names. We have used a join to help us refer to the invoices table so that we can narrow down the results, even though we are not actually fetching any data from the invoices table.

It is also possible to use FRTB_FMFind() to count the number of records in a table, optionally with a match condition. To do this, use the special SQL function COUNT(*) in your find expression. For example, to count the number of overdue invoices:

The response text for this example will be an integer value indicating the number of matching records, and will be zero if no records match.

Updating data in FileMaker tables: FRTB_FMUpdate()

FRTB_FMUpdate( FMTarget, TableNames, UpdateExpression, MatchCondition, CompletionFunction, DatabaseName )

This function will allow you to update information in FileMaker records.

When the user interacts with a JavaScript solution in a web viewer, you may want to update your FileMaker database to reflect the actions a user has taken. This function will allow you to talk to your FileMaker database to send it updated data to be stored in existing FileMaker records.

• FMTarget

• TableNames

• UpdateExpression

• MatchCondition

• CompletionFunction

• DatabaseName

A typical call to FRTB_FMUpdate() will specify a single FileMaker table name, one or more fields to be updated (with values), and a simple match condition. Often that match condition will use a unique key field and value to select a single record from the FileMaker table to be updated.

When no match condition is given in a standard SQL update operation, ALL records in the specified table are updated. A programming error could very easily result in an empty match condition where it wasn't intended, leading to a potentially catastrophic loss of data when all records are updated with a single value. For this reason, FRTB_FMUpdate() will not carry out an update unless a non-empty match condition is supplied. (If you were very confident that you wanted to update every record in your table, you could supply a match condition like “1 = 1”: as this is always true, it will always match every record in your table.)

Let’s look at an example:

FRTB_FMUpdate( FMTarget, 'Data', 'SliderValue = ‘ + CurrentSliderSetting + ', 'RecordIDField = 12' )

In this example, FRTB_FMUpdate() is being called as the user operates a slider control. The MatchCondition parameter 'RecordIDField = 12' tells FileMaker to only update the specified record in the FileMaker table named ‘Data’ (as specified in the TableNames parameter).

The UpdateExpression in this example is being constructed by concatenating the text “SliderValue = “ and a JavaScript variable which defines the setting. If the variable contained the value 7, the UpdateExpression would therefore be ‘SliderValue = 7’, indicating that the new value for the SliderValue field in this record should be 7.

Important note about record locking

In FileMaker, you can be prevented from updating a field if another user is working in the same record, or you are working in the same record in another window. This is because the record is 'locked' until the changes are committed.

When Fusion Reactor goes to update a FileMaker record, it can also be prevented from doing so if you have made uncommitted changes to FileMaker fields or other controls in the current window. e.g. if you type some text into an ordinary FileMaker field and then immediately use a Reactor-based control which wants to update that record, it will be blocked from doing making that update (the record will be 'locked' as though another user was editing it, or it was being edited in a separate window).

To deal with this issue, the FRTB_FMUpdate() command will try to commit the current record before performing the update. To make this attempt, it will need a little extra help from your solution, as detailed below. These extra steps are optional but highly recommended: if you don't take them, all record lock situations will result in an alert like this:

However with the commit attempt working correctly, you should not have record lock problems when the current record has uncommitted changes, and for 'genuine' record lock situations (other users/other windows), FRTB_FMUpdate() will display the above dialog minus the 'Possible cause' note. (This is—intentionally—very similar to what FileMaker does itself with other user/other window record locks.)

To enable the commit attempt, you need to add a very simple FileMaker script to your database, and supply the name of the database as a final parameter to the FRTB_FMUpdate() function.

The FileMaker script, which you can copy from the demo database, consists of just a single 'Commit Record' step:

The DatabaseName parameter must also be supplied so that FRTB_FMUpdate() knows where to find this script. In order to 'pad out' the parameter list so that you can supply the DatabaseName parameter in the final position, you will need to supply a value for the CompletionFunction parameter: this can safely be a blank value ( '' ) if you don't want to use a completion function of your own. Note that if you do provide a completion function, it will be executed after the record-lock checking has been done. As usual, your completion function will receive the ReponseText and Status values that resulted from the attempt to update the FileMaker record.

Creating new FileMaker records: FRTB_FMCreate()

FRTB_FMCreate( FMTarget, TableName, FieldList, ValueList, CompletionFunction )

This function will allow you to create new records in FileMaker tables.

• FMTarget

• TableName

• FieldList

• ValueList

• CompletionFunction

You should be aware of some significant differences between the way FileMaker creates records from its normal user interface (or a FileMaker script), and how they are created by this function using FileMaker’s hidden SQL features:

Firstly, it is necessary to specify at least one field and a corresponding value to be initialised.

Secondly, no auto-enter operations take place. Apart from the initialisations specified with the FieldList and ValueList parameters, the new record created will be completely empty. Any auto-enter settings specified in FileMaker’s normal interface will be ignored.

FRTB_FMCreate( FMTarget, ‘Data’, ‘SliderValue’, ‘0’ )

In this example, a new record is being created in the FileMaker table named “Data”. When the record is created, the field named “SliderValue” will be set to the value zero. Any other fields in the record will be left empty.

Deleting FileMaker records: FRTB_FMDelete()

FRTB_FMDelete( FMTarget, TableName, MatchCondition, CompletionFunction )

This function will allow you to delete existing records from FileMaker tables.

• FMTarget

• TableName

• MatchCondition

• CompletionFunction

No set of CRUD operations is complete without a delete operation, but this function should be used with extreme caution. As for the FRTB_FMUpdate() function, the underlying SQL request that performs record deletions is capable of deleting ALL records in a FileMaker table if no match condition is supplied. For this reason a non-empty MatchCondition parameter is mandatory in this function.

FRTB_FMDelete( FMTarget, ‘Pages’, ‘Status = \’Marked for deletion\’’ )

In this example, we are deleting records from a FileMaker table named “Pages”. The MatchCondition specifies that the only records that will be deleted are those where the field named “Status” has the value “Marked for deletion”.

Executing FileMaker scripts: FRTB_FMScript()

FRTB_FMScript( FMTarget, DatabaseName, ScriptName, ScriptParameterValue )

This function will allow you to trigger the execution of FileMaker scripts.

• FMTarget

• DatabaseName

• ScriptName

• ScriptParameterValue

• CompletionFunction

You can use FRTB_FMScript() to trigger the execution of any FileMaker script, including a script in another open database file.

If you pass information to the Filemaker script using the optional ScriptParameterValue parameter, the FileMaker script can retrieve that value using FileMaker’s built-in Get( ScriptParameter ) function.

It's important to note that if you supply a completion function, this will be executed immediately after the script has been triggered: unlike the CRUD functions above, it does not wait until the operation (the FileMaker script in this case) is complete.

If your JavaScript solution needs to take some further action on completion of a triggered FileMaker script, it is probably best to have the FileMaker script trigger a reload of the web viewer as its final act. Your JavaScript solution should be coded with this in mind: it may simply refresh itself to reflect the new state resulting from the FileMaker script having been executed, or alternately the FileMaker script may set some sort of flag field or variable, which is then interrogated by the JavaScript solution.

Level 2 Communications: ToolBox CallBack Function

Using the high-level CRUD functions detailed in the previous section helps to keep your JavaScript code more readable, eliminating the need for constructing SQL queries to perform the required database interactions.

Sometimes, however, you may need to send a request that isn’t easily handled by these functions. For example you may want to use SQL’s ORDER BY or GROUP BY clauses to sort or group the results of a find operation. Or you may simply prefer working in native SQL.

Direct callback to Filemaker: FRTB_FMCallBack()

FRTB_FMCallBack( FMTarget, Request, CompletionFunction )

This function will allow you to pass an SQL() or Script() request directly back to the Fusion Reactor plugin.

• FMTarget

• Request

• CompletionFunction

The request parameter in this function is a text string which will be passed directly to the Fusion Reactor plugin. In the current version, it can be either an SQL request or a Script execution request, as detailed below.

NOTE: The SQL() and Script() function names are case-sensitive.

• SQL(...)

• Script(...)

• DatabaseName

• ScriptParameter

NOTE: Take care not to use spaces inside the Script() function unless they are intended (e.g. you wish to execute a script whose name starts with a space). Database names and script names that contain commas are not supported, and will prevent the function from succeeding.

Examples:

FRTB_FMCallBack( FMTarget, ‘SQL(SELECT “Client Name”, “Invoice Number”, “Invoice Total” FROM “Invoices” ORDER BY “Invoice Total” DESC)’ )

Here we are using a complete SQL statement to retrieve a list of invoices, sorted from highest to lowest value.

FRTB_FMCallBack( FMTarget, ‘Script(MyDatabase,Go To Next Record)’ )

This example uses the Fusion Reactor plugin to ask FileMaker to execute a script called “Go To Next Record”: this might be happening because the user has pressed a ‘next record’ button inside a JavaScript solution. Note that there are no spaces inside the parentheses or around the comma here: see the note above.

FRTB_FMCallBack( FMTarget, 'Script(MyDatabase,Display Warning,You shouldn\'t have pressed that!)' )

Here a text value (a warning message) is passed to a FileMaker script so that it can be displayed, for example by using FileMaker’s Show Custom Dialog script step.

Level 1 Communications: Basic Plugin Functions

At the lowest level, your JavaScript solution can talk directly to the plugin.

To communicate this way you will need to first be familiar with AJAX programming in JavaScript. Using an XML HTTP request object, you can send a Fusion Reactor callback function directly to the plugin.

Example

In the following JavaScript code extract, xhr is an XML HTTP request object ready for use, and FMTarget is your link back to FileMaker (see above for details). Request is a JavaScript variable containing the text of a callback function: either “SQL(...)” or “Script(...)” (see the previous section for information on how to compose the text of these functions).

xhr.open("POST", FMTarget, true );

xhr.setRequestHeader( "Content-Type", "application/x-www-form-urlencoded" );

xhr.onreadystatechange = function() {

/* readyState change handling code goes here */

}

xhr.send( Request );

Remember that your readyState change function will be called multiple times as the state changes from 1 to 4.

Special note about status codes and response text values at this level

SQL operations sometimes have no logical values to return, e.g. a find (SELECT) operation which finds no records has an empty result.

Testing has shown that both Mac OS (WebKit) and Windows (Internet Explorer) are prone to problems when returning empty response text values for AJAX operations, so the Fusion Reactor plugin will return a special status code of 210 in these cases, and a response text of ‘204 No data’. Your solution should check for a status code of 210 and treat it the same as a status code of 200, with no response text.

Note that the Fusion Reactor ToolBox functions (level 3 and level 2) will intercept status code 210 for you, and will pass a status code of 200 and an empty response text value to your completion function.

Debugging output

The Fusion Reactor ToolBox contains a debugging output feature to assist you with your development. You can add a special debugging output area to the code that runs in your web viewer, and use the FRTB_DebugMessage() function to add a line of debugging output into that area.

Start by adding an element into your HTML code with the ID "DebugHolder":

<div id="DebugHolder"></div>

If you want debugging output to be active, set the FRTB_Debugging global to true early in your JavaScript:

FRTB_Debugging = true;

(You can then use this global to control other aspects of your debugging process, e.g. the Roster example in the demo database uses it to decide whether to create a smaller roster area, in order to leave room on screen for debugging output.)

Next, set up the DebugHolder element by calling:

FRTB_InitialiseDebugging()

This will populate your DebugHolder element with the following default HTML code, sourced from a global which you can override in order to format it differently to suit your needs:

FRTB_DebugOutputElementCode =

'<p>Debugging (latest lines at top)<\/p>\n' +

'<textarea cols="60" rows="30" id="DebugBox"></textarea>\n';

All that remains is to sprinkle your JavaScript code liberally with calls to FRTB_DebugMessage() in order to give you a readout of the progress of your scripts, e.g.:

FRTB_DebugMessage( 'I\'m at floor number ' + String( FloorNum ) + ', and no problems so far!' );