6. FRToolBox関数のリファレンス

Want to know more about the FRToolBox? 5. FRToolBoxの概要

Get the latest version of FRToolBox (see comments at the top of the file for changes):

FRToolBox.js.rct

Open

(Version 2.7.2 uploaded 16 July 2015)

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 under 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.3 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::MyField. 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.

FRTB Function Reference

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

Find Request

This method will create a find request which will retrieve data from the FileMaker database. You may use as many parameters to this method as you need. Each parameter should be a fully qualified field name.

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:

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:

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

This method will create a new record request, which will add a record to the FileMaker database. You may use as many parameters to this method as you need. Each parameter should be an array - the first element contains the fully qualified field name, and the second should contain the value you want to set into that field.

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

Again, you can chain any of the request object methods to the create request - although .filter(), .poll(), and .where() would each have no effect on the create request.

Update Request

This method will create a new update request, which can be used to modify any set of records in your FileMaker database. You may use as many parameters to this method as you need. Like the create request, each parameter should be an array - the first element contains the fully qualified field name, and the second should contain the value you want to set into that field.

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.

To specify a set of records or a specific record to update, you need to add either a .filter() or .where() (or both).

All of the request object methods are available for use with the update request.

Calculation Request

This method allows you to perform a FileMaker calculation and return the result to your completion function. This can be used to set global variables, or get the results of FileMaker or Custom Functions etc. Anything that can be done in a FileMaker calculation engine, can be done with this method.

This method will return a request object, which you can use to add further details, debug and send the request. The above request - if sent - would evaluate 'Get ( FileName )' in the current layout context, and return the result to your completion function, in the 'result' property of the response object.

This request would evaluate the let statement, and would set the Global variable in your database.

Request Object Methods.

Filter Method

You can implement a simple filter by chaining this method to your find, update, or delete request.

In the above example, 'Reactor Blue' is a text constant. This will match all MyColor fields in the table which have the value 'Reactor Blue'.

The filter can be either a single, or multi line key. Each predicate must contain a fully qualified field name (on the left side), and a text/number/date constant (on the right side). You may use any of the following operators to compare the fields contents with the data:

• = ( 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 )

An example of a multi predicate filter:

This filter would match each record where the 'MyColor' field equaled 'Reactor Blue', and where the 'MyStatus' field was NOT equal to 'Deleted'.

\n signifies a new line character.. if you want to search for 'Reactor Blue\n' explicitly, you need to escape the string to look like this:

Filters may also be used to specify advanced and/or clauses. Lets say you wanted to get all records where 'MyTo::MyColor' is 'Reactor Blue', 'Black' or 'White', you could specify a request like this:

Conversely, if you wanted to find all records where the MyStatus field is not 'Deleted' or 'On Hold', you would need to use the 'and' join like this:

You can also join these requests together to create even more advanced finds.

This filter would match each record where the 'MyColor' field equaled 'Reactor Blue', 'White' or 'Black', AND where the 'MyStatus' field was NOT equal to 'Deleted' or 'On Hold'.

The filter can be used anywhere in the request chain and can (but is not required to) be used in conjunction with a traditional 'where' clause. The filter is essentially a simpler (but in some ways, not as powerful) method of creating or adding to a where clause.

Send Method

The send method allows you to fire off a request that you have previously constructed. This is usually the last method that you would add to a request chain.

The send method accepts a single parameter which can be either a completion function, or an object with request configuration details.

Debug Method

The debug method can be used by chaining this method to any request created using the FRTB object.

This will send a request to the filemaker database, and print more detailed information about any errors to the log. As the name suggests, it is often only useful in development or testing of a project, but can be used to provide feedback to users about which fields are missing or misnamed.

This is often very useful to use in the 'onError' completion function:

You can optionally supply a callback function to the debug request, which receives an array of the fields or errors that occurred during debugging. You can then iterate over this array to give your users useful feedback on what is going wrong.

The default implementation (without supplying a callback) will show a popup dialogue message with a list of fields that may have caused errors in the find.

Poll Method

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

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:

If your original request looks like this

It will end up looking something like this:

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.

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

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

There are a few different options can be supplied for an action.

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

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

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:

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.

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. 7. JavaScriptのデバッグ

FRToolBox.js.rct.2.5.5.zip

Open