We’re thrilled to announce the official, “integration-ready” version of LOgiCATOR. LOgiCATOR is a modular search interface for FileMaker that can be easily integrated into new or existing solutions. It’s designed to help users locate data with logical precision, via a powerful yet intuitive interface for searching across FileMaker tables. This article includes a download link for the module and demo file, describes what’s changed since the preview version (a lot), and explains how to integrate LOgiCATOR into your FileMaker solutions.
Visit the LOgiCATOR page at Beezwax.
Re-Introduction to LOgiCATOR
In many cases, an external file reference and two scripts in the calling file are all that is needed: LOgiCATOR “just works.” Even customization, when needed, has been designed to be straightforward. Before we get to implementation details, let’s recap things.
Part 1 of this series introduced LOgiCATOR and described its genesis and features. Part 2 looked in-depth at some of LOgiCATOR’s enabling technologies, like JSON and the new card-style windows introduced with FileMaker 16. I had previously said that Part 3 would delve into how we leveraged JSON to build LOgiCATOR, but I’m too eager to get this into your hands to wait for Part 4, so our article on JSON will have to wait instead (but not too long). Read on to learn how to integrate LOgiCATOR into your FileMaker solutions today.
Before we get started, download the integration-ready version of LOgiCATOR here.
A Brief LOgiCATOR Recap
Once you’ve added a file reference to your calling file, copied the scripts over, and added a Find button to your layout(s), LOgiCATOR is ready to do its magic. When you click Find, LOgiCATOR scrapes the layout for searchable fields, including those on hidden panels or popovers or sitting beyond the explicit right layout border. It uses algorithms to derive user-friendly display names (e.g., “Street Address”) from the underlying field names (e.g., “streetAddress”) for displaying in LOgiCATOR’s fields popup menu, and to determine each field’s rule type, which drives the options available for searching on that field (more later). When customization is needed, for example, to modify the automatic display names or rule types, the script parameter for the “Open LOgiCATOR” script is your “one-stop shop,” as we’ll soon explore.
LOgiCATOR is a separate .fmp12 file that opens in a card window, where the user can set up one or more search rules:
The search rules are passed back to the calling file, where the actual find is then executed. Searches can also be saved and run again in the future. A FileMaker application can be paired with its own dedicated LOgiCATOR instance, or one LOgiCATOR file can be shared by multiple calling files.
It’s Time To Start The Integration
This article explains how to integrate LOgiCATOR into your FileMaker applications, and contains important tips for integration and customization, aimed at helping you get the most out of LOgiCATOR while making integration simple. The ReadMe file accompanying the download, and available as a script in the module, contains more details about integrating LOgiCATOR; it’s highly recommended that you read it before adding LOgiCATOR to your applications.
Exploring the Demo File
To see LOgiCATOR in action, and to get a feel for the difference between an “it just works” integration (no customizations) and a customized one, open the “LOgiCATOR Demo.fmp12” file you just downloaded and compare the search experience in the tabs “Albums (default LOgiCATOR)” and “Albums (customized LOgiCATOR).” Click the Find button on each to open the LOgiCATOR window. Can you spot the differences?
First thing to note is that the default implementation did pretty well in deriving field display names (e.g., “Is a Compilation”) from actual field names (e.g., “isACompilation”) for the fields popup menu, and determining correct rule type (e.g., when searching on “Artist,” LOgiCATOR lets you enter a string, whereas “Rating” gives you an iTunes-like star widget). The customized implementation overrides a few of the automatic display names, excludes one field completely, and adds unit labels (e.g., “tracks” or “USD”) to a few of the rules: spit and polish.
The “Tracks” tab doesn’t yet have a Find button. Let’s see what we can do about that. In layout mode, go back to the layout displayed in the first tab, “Albums | default LOgiCATOR.” Recall that that’s the one with no customizations. Copy the Find button. Now head over to the “Tracks” layout and paste that button into the upper left corner. Back in browse mode, try it out. How did it do at scraping a different layout and context for the correct fields, and determining display names and rule types? And how much work (customization) did that take on your part?
What’s Changed Since the Preview
LOgiCATOR has undergone a lot of engineering work since we introduced the “preview” version in Part 1. There we had suggested that you refrain from integrating it into your applications until a more integration-ready version was available. Your patience has paid off, as much of that work was aimed at making it easier to integrate and easier to update going forward. A complete list of changes accompanies the download in a Release Notes file, but a couple are worth elaborating on here, and one deserves its own future blog post.
As previously described, LOgiCATOR is a module that sits in its own file; the calling file only needs a couple scripts and an external file reference. It follows that updates should be as simple as just swapping an updated LOgiCATOR.fmp12 file into the folder in place of the existing module. But there are those two scripts in the calling file: you may want to modify those. For example, you may want to handle the “no records found” case is a manner that’s specific to your application. If we modify those scripts in an update, then we wipe out the your modifications when you update your application to a newer LOgiCATOR version.
In order to reduce the odds that an update will need to touch those scripts, much of the logic that was previously written into those scripts has been moved into the LOgiCATOR module itself. That way, we can continue to develop that logic without requiring an update to touch those scripts (although that may sometimes be necessary). The code that got moved includes the logic for parsing the current layout’s fields to determine their rule types (a “currency” search vs. a generic “number” search, for example), as well as the logic for constructing the final search values (e.g., =="logi"*) that will be popped into Find mode back in the calling file.
There is an even more profound change to be noted in the calling-file scripts, and it involves the way the calling file and the LOgiCATOR module communicate with each other. We’re now using John Renfrew’s Function-Separation model to facilitate interaction between the files, rather than the mutual file references of the preview release. It’s a significant improvement to LOgiCATOR that merits a future blog post of its own; look for that article to follow this one.
Automatic Display Names
As mentioned above, LOgiCATOR can automatically parse user-facing display names out of your underlying field-naming convention. These are then displayed in the fields popup menu in the LOgiCATOR interface and provide a welcome alternative to confronting your users with field names like “totalAnnualBudget” or “SUB_COMPONENT_NUMBER.”
One new feature since the preview release that is sure to be helpful to a lot of developers is support for parsing camelCase field names. The preview version introduced support for snake_case (also called underscore) and SCREAMING_SNAKE_CASE — yes, that’s a thing — field names, such that if you have fields named “first_name” and “LAST_NAME,” we can derive the user-facing display names “First Name” and “Last Name” for displaying in the fields popup menu. With added support for camelCase, we can now parse “streetAddress,” as well, in order to derive “Street Address.” It even handles acronyms: “machineIPAddress” correctly yields “Machine IP Address.”
Some developers use FileMaker’s field comment to store display names. Is that you? Not to worry, we’ve got you covered, too!
The ReadMe file explains how to tell LOgiCATOR which of the supported systems you use. Note that if your convention calls for field names like “z_gbl_t_fk_nameL_sum,” we won’t be able to pull display names out automatically, so you’ll have to use the customization option (below) for those. (There are some miracles that LOgiCATOR can’t perform.)
LOgiCATOR’s Rule Types
Rule type determines the operators and other options that are available for searching a particular field. For example, for a “string” rule type, the comparison operators are “starts with,” “contains,” “is,” “has a value,” “has no value,” and “contains duplicates.” In contrast, a “number” rule type presents the user with the operators “is equal to,” “is less than,” “is less than or equal to,” “is greater than,” “is greater than or equal to,” “is between,” “has a value,” and “has no value.”
Supported rule types are “string,” “longText,” “valueList,” “number,” “currency,” “rating,” “boolean,” and “date” (see table). LOgiCATOR contains algorithms to automatically determine rule type. Like automatic display names, the automatic rule types can be overridden on a per-field basis by customizing the “Open LOgiCATOR” script parameter (see below).
Summary, container, and unstored calc fields, as well as any fields with global storage, are excluded from the search. Other fields appearing on a layout can be excluded by customizing the “Open LOgiCATOR” script parameter (see below). Lastly, searching of time (either time of day or interval time) and timestamp fields is not currently supported.
How to Integrate LOgiCATOR
Who remembers Jeff Goldblum’s iMac commercial (“there is no step three”)? We’ve got a step three, but in many cases, you’ll be finished after that.
- Add an External Data Source named “LOgiCATOR” to your calling file(s) that points to the LOgiCATOR module. For example in the demo, the LOgiCATOR module is in a nested folder named “LOgiCATOR Module” within the same folder as the demo file, so the file path is “file:LOgiCATOR Module/LOgiCATOR”. This can also be a remote path.
- Copy the script folder “LOgiCATOR Scripts,” containing the scripts “Open LOgiCATOR” and “on timer | LOgiCATOR | Perform Find,” as well as the “LOgiCATOR README” script, from the LOgiCATOR Demo file into your calling file(s).
- Decide how you want users to invoke the LOgiCATOR search module, e.g., buttons, custom menus, keyboard shortcuts, etc. and configure those to call the script “Open LOgiCATOR.” The script parameter is optional — in many cases, LOgiCATOR “just works” — but in some cases you’ll want to include it to customize the search options (see below).
Optional steps, depending on whether customization is desired:
- Modify system-wide defaults as needed (see below).
- Customize LOgiCATOR as desired (see below).
Customizing LOgiCATOR
While LOgiCATOR handles most formatting decisions automatically, you may occasionally desire to override some of those decisions or further customize the user experience. Some of the properties that can be customized include overriding automatic display names and/or rule types, overriding the system-default currency symbol, and displaying an optional unit label (e.g., “mg,” “parsecs,” or “USD”) after the input field for number and currency rule types, to indicate units in which the user should enter their search value. You can also exclude a field altogether from being searched.
The ReadMe file explains how to modify the “Open LOgiCATOR” script parameter to customize these properties, and also how to modify several system-wide defaults. Here is an example of a rule that shows several customizations, including an overridden display name and a display label (“USD”):
Interface
Objects on each of the five user-facing layouts in LOgiCATOR have been formatted with named custom styles. To skin the interface to match your application’s styling, duplicate and rename the “LOgiCATOR_Default” theme and modify the custom styles as desired.
Security
Please refer to the ReadMe file for information about the module’s default accounts and privilege sets, and suggestions regarding security.
Have Fun
We truly hope that LOgiCATOR makes it easy for you to provide a powerful yet intuitive search experience for your users. We can’t wait to see how LOgiCATOR gets used in the wild. As always, we’d love to hear from you: kudos, complaints, suggestions, questions, philosophical musings on modular design…
License
Copyright © 2017, Mark Scott | Beezwax Datatools Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The “About LOgiCATOR” window and layout, unmodified or minimally modified only to re-style buttons, including original credits and this unmodified copyright notice and license, shall be included in all copies or substantial portions of the Software, and shall be accessible to end users from the main LOgiCATOR search-entry view via a menu command labeled “About LOgiCATOR” and/or a button on the layout labeled “About.”
THE SOFTWARE IS PROVIDED “AS IS,” WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The LOgiCATOR name, “Locate data with logical precision!” tag line, and reading-magnifier logo are trademarks of Beezwax Datatools, Inc.
Beezwax is available on a consulting basis to help integrate LOgiCATOR into your FileMaker application. Find us at www.beezwax.net.
Credits
Created by Mark Scott at Beezwax.
Thanks to the following who contributed and inspired:
Vincenzo Menanno, Beezwax’s director of FileMaker Development, for prodding me to abstract a mostly hard-coded search interface I had previously developed, for suggesting we gather as much information as possible from the user’s current layout, for insisting that it have a cool name, and, most importantly, for providing me the space to work on this; Julian Nadel, Beezwax president and founder, for supporting the effort (“Onward!”); Jay Gonzales at Beezwax, for ever-helpful guidance; Michael Cinkosky, Principal, Third Street Software, for long-ago but not forgotten discussions about what makes a great search interface; fellow bee, Lon Cook, for pointing out that keeping LOgiCATOR as a separate file would make integration much easier; John Renfrew of att.it{ude} for proposing the use of an on-timer trigger to eliminate the need for a file reference within LOgiCATOR (the “Function-Separation” model); and to all the beez for the daily inspiration to do excellent work.
3 thoughts on “LOgiCATOR Part 3: Ready, Set, Integrate…Into Your FileMaker Apps”