Building_your_own_BlackBoxes.html
http://wiki.teamdf.com/wiki/pages/S0F9E6s4/Building_your_own_BlackBoxes.html
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.
Typically, you will be creating BlackBox Functions that will implement superb new user interface controls for use in your FileMaker layouts. Sometimes your BlackBox may provide more than one type of control, in which case the BlackBox itself will have multiple functions. The CalPack BlackBox, for example, contains three functions which deliver three different types of calendar controls.
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:
Name — This is the name of the function, as it will appear in FileMaker's external function list (under the Reactor heading)
Function ID — This is a unique numeric ID that identifies each function and differentiates it from all other functions loaded into FileMaker. Whenever you make a new BlackBox function, you'll be asked to supply one of these IDs. Eventually we will set up a registry of function IDs to avoid collisions; in the meantime you should use values between 20,000 and 32,000, and take care not to install BlackBoxes with conflicting IDs.
Function Type — DemoControl is a WebTech Function. It will use web technologies to deliver its stunning result.
Start Page — Every WebTech Function will load up a main 'page' in the web viewer. This page will always be one of your project files.
Below these fields is a portal listing the parameters for the selected function. All FileMaker functions need to have at least one parameter, even if we don't intend to pass them anything useful. Click on the Add Parameter… button to create the DemoControl function's only parameter, and name it YourNameGoesHere. Let's work through the attributes of that parameter:
Parameter Name — This is the 'official' name of the parameter, and it's how you'll refer to it inside your HTML & JavaScript (see later, under "So how did that work?").
Display String — This is the what the parameter will look like when it appears in the function template that you get when you double-click on the function name in FileMaker's function list. We'll take care of the semicolons between parameters, and the curly braces around optional parameters, but you might want to add other characters to the Display String; for example in our own BlackBoxes we put double-quotes at either end to help indicate when we want a parameter that is the actual name of a FileMaker field, rather than a field reference.
Data Type — Defaults to text, which is usually fine, but if you are passing date values in particular you will want to set this appropriately (more information about Parameter Data Types).
Optional — You can mark a parameter as optional, and FileMaker will then not require you to supply a value if you don't want to. In FileMaker's function list, curly braces are shown surrounding optional parameters.
Hidden — If you want to, you can even mark a parameter as hidden. In this case the parameter won't show up at all in FileMaker's function list, but savvy developers can still supply a value if they want (and know!) to.
Note: Optional parameters, and also hidden parameters, can only appear at the end of the parameter list, for obvious positional reasons. You can have more than one of each, and one or more parameters can be both optional and hidden if required, but each type must not be interspersed with their non-optional or non-hidden brothers and sisters. Don't worry: the parameter sorter will wave red flags at you if you get them mixed up, and the build process will stop and yell at you.
Refresh — The Refresh flag indicates that this parameter's value will be included in the URL that will be the result of this function. Generally speaking you will want this option to be checked: without going into the technicalities, a change in the value of this parameter will then cause your Web Viewer to reload. It will also ensure that multiple instances of this BlackBox control used on the same layout will behave as individuals as long as they have different values for these parameters.
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.
To get started, create a directory on your computer, and use the Set Project Directory… button to point it out. Then create a text file inside that directory. Call it whatever you like, but it should end in ".html.rct". Once you've created the file, click the blue-arrowed refresh button and it should appear in the project file list in the BlackBox Builder, as in the screen snap below.
Here's the text for the contents of that file:
<html> <body> <h2>Hi there, <?Reactor $YourNameGoesHere Reactor?>!</h2> </body> </html>
Now that you have your project file, you can nominate it as the Start Page for the DemoControl function. Do that now, on the Functions tab.
Here is a detailed break-down of the components of the Project Files tab:
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 your build didn't work, try reviewing the section above concerning creating a project files directory and the single project file for this BlackBox. In particular, make sure you finish by nominating that project file as the Start Page for the DemoControl function.)
Create an empty FileMaker database, with no fields, and place a Web Viewer on the layout. Tick the boxes as shown, and then for the Web Viewer's address, call your brand-spanking new Reactor BlackBox control and pass it a noble name as a simple text value: DemoControl( "Robert" ). You can just type it in as you see here, or you can click the Specify… button, choose to view External functions, and you should see DemoControl( YourNameGoesHere ) under the Reactor heading.
Switch to browse mode, and see the inspiring results:
 |
Picture 32.png |
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.
When you use a BlackBox Function in a Web Viewer, the Reactor Plugin will begin by loading up the specified Start Page. If that page ends in ".rct" it will parse the page first: in other words it will look inside the page for <?Reactor … Reactor?> tags, treat the text between them as FileMaker calculations, and replace them with the calculation result.
You can put things like Get( CurrentDate ) or Factorial( 7 ) in there, just like a FileMaker calculation, but there is one special feature: any parameters you defined for your BlackBox Function will turn up here as FileMaker variables with the same name. So our YourNameGoesHere parameter can be retrieved using this text:
<?Reactor $YourNameGoesHere Reactor?>
So that if you passed "Dominique" as your parameter value, this whole line:
<h2>Hi there, <?Reactor $YourNameGoesHere Reactor?>!</h2>
… would get magically turned into:
<h2>Hi there, Dominique!</h2>
… 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.
To provide the calculation text for your FileMaker Calculation BlackBox Functions, just type or paste the calculation text into the box in the FileMaker Calculation field of the Functions tab.