LOgiCATOR Read Me

INTRODUCTION

LOgiCATOR is a search module that can be easily integrated into new or existing FileMaker applications. The calling file only needs two scripts and a file reference (external data source). LOgiCATOR has been designed to be easy to integrate. In many cases, simply adding the external file reference, copying the scripts over, and adding a “Find” button to your layout(s) is all that is needed; LOgiCATOR “just works.” When customization is needed, the script parameter for the “Open LOgiCATOR” script is your “one-stop shop.” 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.

This document 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. Please read the LICENSE and CREDITS, below, before doing so.

Download latest LOgiCATOR release and documentation at www.beezwax.net. Beezwax is available on a consulting basis to help integrate LOgiCATOR into your FileMaker application.

HOW IT WORKS

A script in the calling file (“Open LOgiCATOR”) scrapes the current layout and compiles a list of searchable fields, which is passed into LOgiCATOR. LOgiCATOR then parses that list to generate end user-friendly display names (e.g., “First Name,” where the underlying field name is “firstName”) and rule types, then opens a card window which presents the user with the search interface.

LOgiCATOR is able to automatically parse user-friendly display names out of field names that use either a “camelCase” naming convention (e.g., “firstName,” “MachineIPAddress,” etc.) or an “underscore”/“snake_case” naming convention (e.g., “first_name,” “STREET_ADDRESS,” etc.). For example, if you use a camelCase convention, then LOgiCATOR will correctly parse the display name “Machine IP Address” out of the field name “MachineIPAddress”; acronyms are properly handled for camelCase, although not for underscore-style field naming. These display names are then shown in LOgiCATOR’s fields popup menu, from which users select the field(s) they wish to search. If your convention calls for using the field comment to store user-facing display names, that is also supported in LOgiCATOR. The automatic display names can be overridden on a per-field basis by customizing the “Open LOgiCATOR” script parameter (see below).

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.” Like automatic display names, rule types can be overridden on a per-field basis by customizing the “Open LOgiCATOR” script parameter (see below).

Supported rule types are:

  • "string" - for short, text values, such as last name or company
  • "longText" - for longer text fields, such as memo, comment, or description fields
  • "valueList" - for fields whose values are chosen by value list (e.g., drop-downs, popup menus, radio buttons, etc.); LOgiCATOR displays the same value list, in a popup menu, to ease search value selection
  • "number" - for most numeric fields, except those that are better handled by one of the more specific rule types below; can be configured to display an optional unit label (e.g., “acres” or “mg”) after the input field, to indicate units in which the user should enter their search value
  • "currency" - for monetary values; displays a currency symbol (e.g., “$” or “€”) and can be configured to display an optional unit label (e.g., “USD“), as well
  • "rating" - for a ”star“ rating field as used in iTunes and the app store; displays in LOgiCATOR as a star widget allowing selection of 0-5 stars
  • "boolean" - for yes/no or true/false fields (a number field limited to 0 or 1) "date" for date fields

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 fields (either time of day or interval time) and timestamp fields is not currently supported.

HOW TO INTEGRATE LOgiCATOR

  • 1. 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.
  • 2. Copy the script folder ”LOgiCATOR Scripts,“ containing the scripts ”Open LOgiCATOR“ and ”on timer | LOgiCATOR | Perform Find,“ as well as this ”LOgiCATOR README“ script, from the LOgiCATOR Demo file into your calling file(s).
  • 3. Decide how you want users to invoke the LOgiCATOR search module, e.g., buttons, a 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).
  • 4. Modify system-wide defaults as needed (see below).
  • 5. Optionally customize LOgiCATOR as desired (see below).

SYSTEM-WIDE DEFAULTS

If needed, modify these defaults at the top of the ”Open LOgiCATOR“ script:

  • $_namingStyle - tells LOgiCATOR how to parse user-facing display names out of your field names; supported options are "camelCase" (e.g., ”firstName“ or ”FirstName“), "underscore" (e.g., ”first_name“ or ”FIRST_NAME“), "field comment" (if display name stored in field comment), or "as is" (to use the actual field name as the display name)
  • $_fiscalYearStart - a number representing the first month of the fiscal year in effect for your application; e.g., the US fiscal year starts in October so this variable is set to 10
  • $_defaultCurrencySymbol - e.g., ”£“

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.

Automatic field display names and rule types can be overridden, or a field excluded from being searched altogether, on a per-field basis. Also, an optional unit label (for ”number“ and ”currency“ rule types) can be displayed and the default currency symbol (for ”currency“ rule type) can be overridden on a per-field basis; the default fiscal-year start (see above) can be overridden on a per-layout basis.

All customization is accomplished by modifying the ”Open LOgiCATOR“ script’s JSON- encoded parameter. In its simplest form, the parameter is just:

   JSONSetElement ( ”{}“;
[
”modifyLast“;
If ( Get ( ActiveModifierKeys ) = 4 /*Ctrl*/  
or Get ( ActiveModifierKeys ) = 6 /*plus Caps Lock*/; True; False ); JSONBoolean
] )

...where the expression in the fourth line can be modified according to how (if at all) you want your users to modify the last-entered search. By default, LOgiCATOR opens the last- entered search when the user Control-clicks the ”Find“ button. The parameter can be omitted altogether if you don’t wish to allow a "modify last" functionality and don’t need to customize any field options (below).

In order to customize the search experience, a second top-level object, "customizations", is added to the parameter, which contains up to three discretionary items, "namingStyle", "fiscalYearStart", and "fields", which are explained below. A typical parameter might thus look like this:

    
JSONSetElement ( "{}";
[
"modifyLast";
If ( Get ( ActiveModifierKeys ) = 4 /*Ctrl*/  
or Get ( ActiveModifierKeys ) = 6 /*plus Caps Lock*/; True; False ); JSONBoolean
]; [
]; [
         "fiscalYearStart"; 10; JSONNumber
      ];
      [
         "fields"; JSONSetElement ( "{}";
         [
            GetFieldName ( Department::budgetAnnual ); JSONSetElement ( "{}";
              [ "displayName"; "Total Budget"; JSONString ];
              [ "ruleType"; "currency"; JSONString ];
              [ "displayUnit"; "CAD"; JSONString ];
"customizations"; JSONSetElement ( "{}";
[
   "namingStyle"; "camelCase"; JSONString
     [ "currencySymbol"; "$"; JSONString ]
); JSONObject
]; [
            ); JSONObject
         ]
         ); JSONObject
      ]
      ); JSONObject
   ]
)

The "namingStyle" item allows you to override the naming convention specified in system- wide defaults on a per-layout basis; see System-Wide Defaults, above, for the supported options. This item can be omitted if the naming style specified in system-wide defaults is in effect for the current layout.

The "fiscalYearStart" item allows you to override the value set in system-wide defaults on a per-layout basis; see System-Wide Defaults, above, for further explanation. This item can be omitted if the fiscal-year start specified in system-wide defaults is in effect for the current layout.

The "fields" item allows you to override various field-level options, as well as display an optional unit label or exclude the field from being searched. Only include the fields to be customized, and for each of those, only include the options being customized. If no field-level customizations are needed, the "fields" item can be omitted altogether. Be sure to protect the field names by wrapping them in GetFieldName ( ), as shown above.

Supported customization options under "fields" include:

  • "displayName" - use this option to override the display name produced by the automatic algorithm, or if your field-naming convention is not supported by LOgiCATOR. These display names are then shown in LOgiCATOR’s fields popup menu, from which users select the field(s) they wish to search.
  • "ruleType" - use this option if the automatic algorithm does not yield the correct rule type. See ”How It Works,“ above, for the supported rule types.
  • "displayUnit" - for ”currency“ and ”number“ rule types, use this to display a unit label (e.g., ”AUD“, ”mg“, or ”parsecs“) after the input field, to indicate units in which the user should enter their search value
  • "currencySymbol" - use this to override the symbol specified in the System-Wide Defaults (see above).
  • "excludeFromSearch" - set this to True to exclude a field shown on the layout from being searchable in LOgiCATOR.

LOgiCATOR only includes fields displayed with a standard control type (e.g., edit box, popup menu, etc.) on the layout in the calling file (unless excluded as noted above). To include a field that is not displayed on the layout, or is displayed only as a merge field, add an instance of the field displayed with a standard control type in the area to the right of the explicit right layout border.

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

The downloaded version of LOgiCATOR includes two accounts, “Admin” and “Module,” tied to “[Full Access]” and “Module” privilege sets, respectively. Neither account is currently password-protected. The LOgiCATOR file is set to automatically login to the Admin account, making it easy for you to modify the module as needed. (You’ll have to switch to the standard FileMaker menu set (Tools > Custom Menus > [Standard FileMaker Menus]) in order to gain access to the areas you wish to modify.)

For deployment, we suggest that you modify the file settings (File > File Options...) to log in using the “Module” account. No password should be set on this account, lest the end user get challenged for the account’s password every time they perform a search. The corresponding “Module” privilege set is configured with standard “Data Entry” settings, which are sufficient to support the module’s end-user functionality. You should also either add a password to the Admin account or replace that account with a password-protected “[Full Access]” account of your choosing.

Of course, if your security needs dictate additional or alternative measures, those will supersede the advice offered here.

LICENSE

Copyright © 2017, Mark Scott at Beezwax

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.

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 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, Beezwax Technical Project Manager, 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 beez for the daily inspiration to do excellent work.