HORNEKS ANS

How to integrate ACF functions into your FileMaker solution

by ·

You have found an ACF function that solves a problem in your application. You have tested it, and it works. How do you make it available inside your own FileMaker solution — and for the people using it?

The approach we use in our customer solutions is straightforward: store the compiled ACF packages in a table, load them when the solution opens, and call their functions from FileMaker calculations. The packages travel with the solution, so users do not need access to the developer’s source files.

What is available after installing the plug-in?

The ACF plug-in provides its built-in functions and a preloaded library called bootstrap. This includes common utilities for selecting files and directories, reading and writing files, checking whether a file exists, and extracting parts of a path.

Additional ACF functions — whether you develop them yourself or obtain their source from the ACF library — must be compiled and loaded before you can call them.

There are three parts to keep in mind:

  • Source: the ACF code, normally saved in a .acf file.
  • Compiled package: the compiled code, represented as Base64 text. The ACFcompiler saves this as a .dsComp file next to your source file.
  • Loaded functions: the functions available to the running plug-in after it installs the package.

Saving a package in your database makes it available for loading. Your initialization script performs that loading step.

Start by developing and testing a package

We provide NEW-ACF-DEVTOOL.fmp12 for developing and testing ACF functions. It contains a table for source code, compiled Base64 text, test parameters, results, and console output.

Its development layout lets you load and recompile source, choose a function to test, and run it with zero to four parameters using the supplied test buttons. This gives you a place to check the function before connecting it to your application’s buttons and scripts.

For a local development setup, you can also compile a source file directly:

ACF_CompileFile ( "/path/to/MyFunctions.acf" )

A successful compilation loads the functions. If you already have a compiled .dsComp file, load it by passing its path:

ACF_InstallFile ( "/path/to/MyFunctions.dsComp" )

Replace these example paths with paths accessible to the computer running the calculation.

Store the package inside your solution

A path on your development computer will not necessarily exist on a customer’s computer. Instead of distributing source files to every user, store the compiled Base64 text in a normal text field in your solution.

For example, you could use a table named ACF_Packages with one record per package and fields for its name, compiled text, and an enabled flag. You can also keep the source and a version field there if useful for maintenance.

To populate CompiledBase64, open the compiled .dsComp file in a plain-text editor, copy its entire contents, and paste them into the text field on the package record. The file already contains Base64 text, so no additional encoding is needed. If you use the developer tool, you can copy the compiled Base64 text from its corresponding field instead.

On the appropriate package record, this calculation loads its functions:

ACF_Install_base64Text ( ACF_Packages::CompiledBase64 )

The table and field names above are examples; use the names in your own solution.

Load enabled packages at startup

In our customer solutions, we bring the developer tool’s table into the target application, together with its development layout, scripts, and required value lists. A menu item restricted to developer accounts opens the layout in a separate window.

The solution’s startup script calls an InitACF script. Its job is to:

  1. Open a utility window on the package layout.
  2. Find the enabled packages.
  3. Loop through those records, evaluating ACF_Install_base64Text for each compiled package.
  4. Register the plug-in’s license.
  5. Close the utility window and continue startup.

If no packages are enabled, skip the loop. If a package fails to load, record the diagnostic information.

This is a script outline, rather than a ready-to-paste FileMaker script. Adapt it to your layout names, access privileges, and startup flow. Loading is usually quick enough to go unnoticed by users.

Call a function from the FileMaker solution

Once a package is loaded, use ACF_run in a FileMaker calculation. For example, if your package defines a function named Greeting that accepts a name:

ACF_run ( "Greeting" ; Contacts::FirstName )

Each argument is passed as a separate parameter. The ACF function’s return statement supplies the result to FileMaker. You can use the calculation in a Set Variable or Set Field script step, for example, and then use that result in the rest of your script.

Use a real function from your package in place of Greeting, with the parameters that function expects.

Clients and server-side scripts

A hosted database can supply the stored package text to its clients, but loading a package in FileMaker Pro does not also load it into FileMaker Server. The plug-in and its packages must be available in the environment that actually executes the ACF call.

For client-side calculations, initialize the packages on the client. For server-side scripts, arrange package loading on the server before calling their functions. Server package autoload is another option in version 1.8.0.10; it is a separate deployment approach from the table-based startup pattern described here.

The install functions also accept an optional isShared parameter. Leaving it out keeps the package in the current database’s namespace. Setting it to true installs it in the shared namespace; it does not distribute packages to other computers. For this introductory pattern, leave it out.

Updating your functions

When you change a function, test and compile the updated source, then replace the stored compiled text for that package. Newly initialized clients will load the updated package.

We also provide a Reload ACF functions menu action so users can load an update without reopening the solution. Updating the stored text alone does not refresh packages already loaded by other clients. Refresh server-side packages separately if the functions run there too.

Start with one package and one call from a script in your own solution. Once that works, the same startup and reload pattern can support the other ACF functions you add.

Use AI to develop functions for your solution

An AI coding assistant such as Codex can help write ACF functions using the structure of your own FileMaker solution. Prepare a workspace containing:

  • Your ACF source files.
  • Your solution’s Save as XML export, split into readable files using DDRparser.
  • The downloaded and unzipped ACF Manual for AI.

Install the ACFcompiler, available from the HORNEKS downloads page, so the assistant can compile the generated source and check for syntax errors. The matching ACFcompiler is also distributed in the plugins DMG or ZIP file (Mac or Windows).

This gives the assistant context about your tables, fields, relationships, and scripts, together with documentation for the ACF functions.

Describe what you want to achieve, and ask the assistant to read the ACF manual and inspect the relevant parts of your solution before writing code. Compile the result, then test it in the developer tool with representative data.

You may also like...