03. Using BlackBoxes in your own solutions
- KKozue
03. Using BlackBoxes in your own solutions
After looking at our demo BlackBoxes, you’re sure to want to take one of them, and use it in your own solution. Reactor BlackBoxes are very portable, so this is a cinch!
Before starting this article, it’s recommended you go through the Reactor tutorial. It’s a very painless process, and it’s all available within the Reactor application itself. It’ll launch the first time you open it, but you can always relaunch it from the Support screen.
For our purposes, we’ll be using one of the plethora of demo BlackBoxes: xGanttChart. Before you launch into this - full disclosure. We didn’t code this from scratch - in fact, we didn’t code any of our BlackBoxes from scratch - with all the fantastic JavaScript libraries out there there’s no need to! This BlackBox uses the dhtmlxGantt library:
https://dhtmlx.com/docs/products/dhtmlxGantt/
Our BlackBox takes a set of records (items, tasks, schedules, etc) and displays them in a visual Gantt Chart. Not sure what a Gantt chart is? In its simplest form it shows a project schedule, it’s essentially a horizontal bar chart, used to coordinate and track items. Our Gantt chart can even represent dependencies between these items, and provide you the ability to group smaller items within a larger item.
As you can see, the horizontal axis represents time, and the vertical axis represents different schedules. Arrows that connect from one item to another indicate dependencies. For example, in the above screenshot, the session with a shrink cannot happen until the full medical has taken place. You can even colour the items according to some sort of categorisation (priority, resource, etc).
So to start with, lets see what parameters this BlackBox uses, click over to the Functions, and take a look at the definition preview:
And take a look at the parameters we provide in the preview:
As you can see, the parameters fall into three categories:
Date Range (
ChartStartDate,ChartEndDate)Schedules (
id_field,description_field, barcolour_field,startts_field,endts_field,order_field,progress_field,parentid_field)Links (
id,id_source,id_target,type)
So now what we need to do, is pop the BlackBox into a new solution that contains this sort of data. So create a new solution with two tables; Schedule and Links - with the following fields:
And now create a new layout with a single object on it. A WebViewer. The contents of the web-viewer should be the xGantt function, with your new fields plugged into it:
You can also copy the web-viewer calculation from our preview by clicking this little guy:
However, after pasting into your own solution, you will need to change the parameters to point to your own field names and table occurrences. Unless you happen to name them exactly the same as our demo.
You may wish to wrap the field references in GetFieldName(). Why? To future-proof things. You could just enter the Description field as "Schedule::Description" but if one day you decide to rename that field, it would break the Gantt Chart, you’d have to update the parameter with the new name. By wrapping GetFieldName around the field reference, it keeps things dynamic. So if the field name changes, it will change in the web-viewer as well.
The first two parameters set the date range of the chart.
There’s also a field you’ll need to add to each table: zModID. This is a Timestamp field with an auto-enter set: modification timestamp.
This field is used for any BlackBoxes that utilise polling, such as this one. This ensures that any data that is edited, created or deleted (outside of the web-viewer) is reflected in the web-viewer. Basically, it makes your data live. That is, any changes are updated more-or-less instantly, we’re not giving it sentience. You don’t enter this field as a parameter, Reactor automatically detects it, and uses it to manage polling.
Let’s add a Schedule record to get things started.
And click back to our web-viewer:
And there it is!
So go ahead and start adding more schedules, and even linking them up.
Not a fan of the blue? go into the data and change the colour of the schedules :
Any data you change will be reflected on the Gantt chart!
So there you go, you have incorporated a Gantt chart into your own solution. The next step is to ensure the BlackBox is installed before it even attempts to draw the chart.
For instance, if you distribute your new solution to someone who has never opened the Reactor application, FileMaker Pro won’t know what you’re on about. It will think you’re speaking gibberish.
So you’ll need to provide the means to install two things:
The Reactor plugin
The xGanttChart blackbox
So create two container fields to store these. The best way to do this is to create a table with a single record - there’s a chance you have one of these already, it’s usually used to store general preferences.
Now we just need to swing by the Reactor application to grab these files.
First off, the Reactor plugin can be sourced from the Plugins screen:
And grab the Reactor plugin(s) that suits the system(s) you’re looking to deploy your solution onto. You can either just click into the container field and copy the contents to the clipboard, or click the download button to save to a location on your computer.
Then head back to your own solution, and paste/insert the file into your new container field for the Reactor Plugin (ensuring you’ve created a single record first):
Now swing back around to the Reactor application, head to the xGanttChart BlackBox, and cast your eyes to the right side of the screen.
This is the BlackBox file. Click it, and save it to a location on your computer (ensure you give it an extension of .rbb).
Then head back again to your own solution, and insert the file in your other container field:
So there you go. Now you need to make sure they’re installed. We suggest writing a script that is run whenever your solution is opened:
If you are deploying onto a multiple-OS scenario, grab all three versions of the Reactor plugin, and write a version of this script-block to install the appropriate version:
No need to do this with the BlackBox file, they’re already cross-platform compatible.
So there you go! You’ve incorporated a demo BlackBox into your own solution, and provided a mechanism to ensure the Reactor plugin and BlackBox are ready to go.