...
The BlackBox Builder is a special database that you can use to build your own BlackBoxes. You can then use these BlackBoxes as building blocks in your own FileMaker solutions, or you can even make them available to other FileMaker developers.
Anatomy of a BlackBox
BlackBox Functions
The BlackBox that you create will contain one or more BlackBox Functions, and once your BlackBox is installed, those functions will appear in FileMaker's own function list, grouped together under the "Reactor" heading in the External functions section. It's a little bit like creating custom functions within FileMaker, but a lot more powerful.
...
BlackBox functions come in two flavors: WebTech Functions are the superstars, delivering sophisticated controls using a range of web technologies like HTML, CSS, and JavaScript. You can also create FileMaker Calculation functions, which allow you to perform straightforward FileMaker calculations — these are very similar to FileMaker's own custom functions, but have the advantage that they get parcelled up and carried around effortlessly inside your BlackBox. Sometimes the functions inside your BlackBox may even call each other as part of a team endeavor to deliver your finished control.
Project Files
The other important component that will be involved in creating your BlackBox is a set of Project Files. These are HTML, CSS, and JavaScript files, image files, etc., all of which pull together to build up the control delivered by your WebTech Function(s).
Project files live on your hard disk drive while you are developing your BlackBox. They work very much like similar files would work to create a web-based application, but when you build your BlackBox they will get bundled up inside, ready to deliver their promise later inside a Web Viewer on your FileMaker layouts.
Creating a BlackBox
Getting Started
The BlackBox Builder is a FileMaker database that will help you organise and build your BlackBoxes. We'll build a simple BlackBox called DemoBB as an example here. If you get confused, or something goes wrong, just take a fresh copy of the BlackBox Builder and start again.
DemoBB is a very simple BlackBox that does absolutely nothing useful. It delivers a simple BlackBox control that you can place on a FileMaker layout purely to demonstrate some features of BlackBox creation. To create a new BlackBox, click the Create/Import… button on the Main Screen, enter the name of your new BlackBox in the dialog, and click the Create button.
...
The Main Screen
Below is a snapshot of the BlackBox Builder main screen, showing DemoBB. On the left hand side is a list of all your BlackBoxes, and buttons for creating, importing and deleting them. Clicking on a BlackBox's name selects it and displays its details in the main panel. Let's take a tour of this panel, starting at the top:
BlackBox Name — Every good BlackBox has one. This will be used as the filename for the finished portable BlackBox file. Alongside it is a field for the version number, so you can distinguish between new or legacy versions.
Description — Write up an overview of what the plugin does. Particularly useful if you plan to share the BlackBox, this is also useful to remind yourself what your plans for the plugin are.
The Help Page field can contain a URL to a page that describes how to use the BlackBox. This URL can be accessed by the BlackBoxHelp("DemoBB") function built into Reactor, and is a good way to provide detailed instructions on its use to a wider audience.
On the right, the Compiled BlackBox container will hold the BlackBox once it has been built. You can click the 'Load' or 'Remove' buttons to place or delete the BlackBox file in the correct location on your machine so that it will be available in the External functions section (building a BlackBox will automatically load it).
The Build Count field will automatically increment every time you build a BlackBox – likewise, the Modified and Created fields will help you keep track of changes to your BlackBox. You can add your name to the Author field, too, so others can tell who created this awesome piece of coding wizardry.
...
The Functions Tab
This tab displays details of the functions that this BlackBox will provide. On the left is a list of functions which can be clicked to be selected, along with Create and Delete buttons. Click the Create… button, and enter 20001 as the Function ID to create a new function for the DemoBB BlackBox. Let's name it DemoControl. At the top of this panel are the following fields:
...
The order of the parameters can be set by clicking the Sort Order… button, which displays the function and its parameters as they would appear in the calculation screen. Just drag the parameters around to change their order. (How does that sorter work? It's a Reactor BlackBox Control, of course!).
The Project Files tab
Every WebTech function requires at least one project file, and even our trivial DemoBB is no exception. While you're developing your BlackBox, project files reside on your own computer, and you edit them there during the development process. When you build the BlackBox, copies of these files are packaged up along with other information to form a single distributable BlackBox file.
...
Project Directory — this is the directory on your own computer which contains your project files. You will edit those files while you're developing your solution, and each time you build your BlackBox, fresh copies of those files will be gathered up and packed away inside the BlackBox.
Project File(s) — this is the BlackBox Builder's internal list of files in your Project Directory. You can resynchronise the list any time you want (e.g. if you add or delete project files to or from the directory), but it's not generally necessary: the list will be resynchronised each time it is built.
Building a BlackBox
In the bottom-right corner is a Build BlackBox… button. Each time you hit this button, the BlackBox Builder will gather up all the information you have entered about your BlackBox (function names, parameters, etc.), scoop up current copies of all the project files, and package them all up into a single compiled BlackBox file. It will then save this file into your own FileMaker Extensions directory, and even load it into FileMaker so that you can start testing it straight away. Typically you'll have a test database open off to one side that uses the BlackBox control you're working on, and after hitting the build button you can swap straight to that and start testing it (although, naturally, your code will work perfectly the first time!)
Going back to the Details tab, you will see a file in the Compiled BlackBox container which can be used in your solution's deployment. If you are Deploying Reactor with a Database, for example, you can deploy the BlackBox automatically by creating a new record in your Reactor Resources table and dragging the BlackBox into the new record's container.
Using DemoControl
If all has gone well, by now you will have built and installed the all-singing all-dancing DemoBB BlackBox without errors. Let's see how it works.
...
If you're feeling truly adventurous, you could create a People table with a Name field, and specify that field as the parameter instead of literal quoted text:
...
So how did that work?
The key things we haven't talked about are how the parameter values get through to the web page, and what those funny little <?Reactor … Reactor?> tags are for.
...
… before being loaded into the Web Viewer. Nifty, huh?
Other Notes
FileMaker Calculations
As well as the mighty WebTech Functions, you can create BlackBox Functions that simply perform FileMaker calculations without using any web technologies at all. These are very similar to FileMaker's own custom functions, but they offer the advantage that they can be packaged up in the portable BlackBox file. Typically they will be useful utility functions that exist to be called, perhaps multiple times, by WebTech Functions in the same BlackBox.
...