FileMaker Pro Advanced gives us developers to create our custom function, our own calculation that returns a result. These are FileMaker Custom Functions. Using custom functions is a boss-level technique, and we all now get to use them and share them. With great power comes great thinking: you as a developer get to decide when/how to use them. But first, let’s take a look at how to work with custom functions.
FileMaker custom functions
Custom functions are lines of code that we write that returns a simple or complex result. They are found in the “File / Manage Custom Functions” menu.
Custom Functions have a few characteristics to them:
- They require a name.
- They can accept parameters, but don’t have to.
- Some sort of calculation is required.
- They are file specific
- At this time, the custom function dialog is not type-ahead enabled, as is a regular calc dialog.
- They can return one result or a recursive result.
Let’s look at each of these.
Require a name
Once a name is given, the custom function is available in both the functions list (under custom functions) or as part of the typeahead. Some folks clearly identify a custom function in its name with some prefix. I tend to use “_” at the beginning: “_CF_BeginningOfWeek”, (a function that returns the date of the first day of a week) but the structure can be anything, even containing spaces between words.
Parameters are bits of information we pass into the custom function and is used in the calculation. These parameters are in the ( ) that appears after the name.. For example in the “_CF_BeginningOfWeek ( anyDate)” custom function, I am passing in a date. I’ve named it “anyDate” but that’s what it could be. I could work with any of these:
_CF_BeginningOfWeek ( Get ( CurrentDate ) )
_CF_BeginningOfWeek ( Date ( 3 ; 19 ;2018 ) )
_CF_BeginningOfWeek ( “5/8/2018” )
What’s in the parentheses gets passed into the custom function and is used throughout. For example, in this custom function, Date ( 3; 19; 2018) is passed into the calculation, and this value is assigned to the variable “anyDate”, the one I put in the CF set up.
Let ([ _dow = DayOfWeek ( anyDate ); //anyDate = 3/19/2018 _first = _dow - (_dow - 1); _end = "" ]; GetAsDate (_date - _first) )
A CF can contain any number of parameters, including zero. Many folks create custom functions that turn the numerical returned value from a FileMaker function into something readable. The FileMaker function Get ( Device ) returns 1 if the user is on the mac. Would you remember 1 being the Mac (especially is your device of choice is a machine with the Windows OS)?
So folks will take this function into a custom function and call the custom function instead.
One other note about parameters, you can use any number of parameters, and each one must contain something passed to it. Look at this custom function called _IsOverlap. Its purpose is to determine if two date ranges overlap.
As I built this for a project, I realized that sometimes there is no end date for one of the ranges. I still need this to work, so I have to pass something into the custom function for the end dates. So inside the custom function, I’m checking to see if the EndDate parameters are empty. If so, I put a placeholder date in there.
The whole point of a custom function is to do some calculation, so do something in this section. You can use any combination of existing FileMaker custom functions, from-scratch calculations or even other custom functions (provided those exist already).
The calculation can be simple or complex. It all depends on your needs, as we’ll discuss in a bit.
Custom functions are file specific. Each file has zero custom functions at first creation. But it is a simple matter of copying a set of custom functions from one to another file. Simply select the ones to copy in Manage Custom Functions in File A and paste them in the same dialog in File B.
The custom function calculation dialog does not have the type-ahead feature we’ve not gotten used to in other areas. Some folks complain. I don’t. I deal with it and move on. You can select FileMaker functions from the dialog, but it is simpler to type them out.
And finally, custom functions can be used to be recursive, to call itself until a condition is met, and then return the result. We will address these in a later post.
Well-used custom functions
FileMaker custom functions have their uses, and you can make the decision for yourselves. Here are a few good thoughts on it by others. Beyond that, it’s a simple decision to make when considering a CF based on these ideas.
One calc used many times
There is a calculation that does exist in FileMaker that will need to be used throughout the whole custom app. If many places in your app require the date of the first day of any week, then that seems a likely candidate for a CF. This has an added benefit that if the calculation needs to be changed for some reason, (returning the Sunday date instead of Monday date), there’s one place to update all the results. That’s useful.
You want a result that makes sense to humans: _CF_GetDevice() will return “Mac” instead of 1. Making it readable means you don’t have to even think. Here’s another example of a set of custom functions using the Get(Device) FileMaker function
Each of these returns 1 or 0, true or false for a given device.
These can be used in a series of logic script steps. For example:
One more thing
In the history of the custom functions, many people have discussed the pros and cons about them. Some of those cons have gone away now that we all have access to the feature, but it is worth noting there still are a few. We’ll look at those in a later post.
Resources for Custom Functions:
There are tons of FileMaker custom functions out there for different purposes. Developers come up with CF’s that fit a specific need and then make it available. Here are just a few resources.
FileMaker Custom functions are a part of the full toolbox we all now have at our fingertips. Knowing how they work and when/why you would use them is important. Explore them and see how they fit into your development work.
Also published on Medium.