How To Download & Install A FileMaker Pro Custom Function

One of the core productivity aspects of FileMaker Pro is custom functions.

This post is for:

• FileMaker: Absolute beginners.
• Covering: Downloading, installing & using custom functions
• Resources: Brian Dunning, FM Custom Functions
• FM Version: FM Pro Advanced

We’ve talked about certain aspects of FileMaker development previously, using one of two approaches:

1. Things to do from day one
2. Things to explore and do later

Custom functions are a day one thing. But, sensibly you should just try to use them in their simplest form from day one, for creating shorthand calculations (as in the above screencast), and similar, this way you will become accustomed to the method of how they work before trying to write your first “Large Hadron Collider” function

Custom functions can be as simple or complex as you like, they make you significantly more productive and organised. In this article we’ll be looking at how to acquire a custom function (via free downloads) and how to install and begin using it.

Getting Your Head Around Custom Functions

So, what are custom functions?

Well, put simply, they are calculations that can be reused.

But what does that mean exactly?

It means that a custom function is a calculation that you create yourself, saved to a predefined place in your FileMaker Database Application, that you employ whenever you need to perform the calculation that you have saved in the custom function.

Manage all custom functions from the Manage menu

Where do I save them?

You create and save custom functions in the File » Manage » Custom Functions menu location, as shown here.

How does a custom function work?

It works in the exact same manner that any other calculation in FileMaker works. The only difference is that a custom function uses your calculation formula, hence ‘custom’.
(n.b. There is some functionality can only be achieved by using custom functions, such as recursion, but for now we will ignore that.)

Why are they called ‘functions’?

Functions are a common term in software, almost all programming languages have functions, sometimes a language has classes, which are essentially functions, for ease of understanding. Functions contain calculations. Functions are a calculation group consisting of one, or more, sub-calculations. Functions end with a result. That result is either shown to the user, or it is used for another calculation, rather like chaining functions together.

Anything that has a function is referring to a location where some work is performed in order to pass the result of that work to the next process.

Imagine it’s like pass-the-parcel – when the music stops, the person holding the parcel gets to open it to see what’s inside. In this analogy, the music is the chain of functions (one or more), when there is no more music (no more calculations to perform) the user (the parcel holder) sees what’s inside the parcel (see’s the result of all the calculations).

Acquiring Your First Custom Function

By far the easiest way to get started with custom functions is to download them. You can use either of the sites noted at the top of this article, both have excellent resources and the custom functions that you see on those sites can be downloaded and used free.

Word of Caution: Please, please, please always test any custom function that you download and install. DO NOT PRESUME THAT THEY ARE 100% TESTED – do your own tests.

For our example we will use Brian Dunning’s site. We are going to choose a simple custom function, you can choose any custom function from the site that you like.

If you would like somewhere to store your custom functions, here is a free solution download
for housing your custom functions.

On Brian Dunning’s site I chose: DaysDifference( Date1 ; Date2 ) custom function. This is a very easy to understand custom function which simply calculates the number of days between two dates.

A nice easy function to calculate the number of days between two dates

Click the image to enlarge it. Very handily the site shows you what the parameters for the function are, which we’ll go into in minute, and also shows you the expected inputs and outputs for/from using the function.

About parameters: The easiest way to understand what parameters are and what they do is to watch this quick screencast. The parameters are where the information needed for the calculations is stored, and is the vehicle for passing that information into the custom function so that the work can be performed. It’s how the function gets its data from you.

Here is the code:

//Custom Function Name/Params:
DaysDifference( Date1 ; Date2 )
 
//Calculation:
GetAsNumber ( Date2 ) - GetAsNumber ( Date1 )

The Process Of Installing the Custom Function

• Tip: If the function name and parameters have not been provided in the main code window, simply copy it from the title at the top and paste it into the window, as shown below in Fig.1
• Select all of the code and copy it from the main window, including what you have just pasted yourself.
• Go to FileMaker custom functions menu in your FileMaker solution
• Click “New” from the bottom menu, as shown Fig.2 and Fig.3
• Paste the clipboard contents into the main window, as shown below Fig.4
• Cut the function name from the main window you just pasted, and paste it into the Function Name field, as shown Fig.5
• One at a time, cut and paste the parameters from the main window into the parameters field, pressing “+” or Enter after each one, as shown in Fig.6
• Finally, if there is not a lot of documentation given with the custom function then write some notes in the main window so that you will know what the custom function is for, and what the syntax is, as shown in Fig.9, Placing your comments within a comment block, like so: /* notes here */
• After you click OK, your custom function will be registered in the manage custom functions dialogue window (Fig.7). Your custom function will also now be available for use in the calculation dialogue box for any field in your database (Fig.8)
• You can now start to test your custom function before using it in a production database.

Fig. 1

Fig. 2

Fig. 3

Fig. 4

Fig. 5

Fig. 6

Fig. 7

Fig. 8

This Is What You Should End Up With

Fig.9 Custom Function fully entered, but not yet tested

When you have finished entering all of the information into your custom function you should be left with something that resembles this image. I can’t stress the importance of documenting the custom function.

If you write one of your own or download one, it makes no difference, always document and document thoroughly.

Now You Are Ready To Test Your Custom Function

Clearly, this example custom function is a very simple one. Therefore the testing will be minimal, in a more complex custom function the testing can get quite involved, not to mention difficult to debug. In the future I will go into more detail about complex custom functions.

So, you can now pull up the dataviewer, or use three test fields in a test database to check the custom function, Date1, Date2, DaysDiff (using your custom function as the calculation).

I’m going to use the dataviewer here, which also means that I need to specify that the free text I’m going to enter is a date, as the dataviewer would have no clue that my text is a date otherwise, if you use date fields in your test database you don’t need to use the GetAsDate() function like I am here.

Fig.10 Test the custom function before you use it in a live database.

Insert the function into the calculation dialogue box, enter the required parameters, and click “Evaluate Now” (as in the image Fig.10)

As you can see, the result is correct, therefore for this simple custom function we can assume that it is working correctly.

Always check different connotations of data, for instance, make sure that by reversing the dates, by making Date1 the greater date, that the function still works. I’m not going to do that here – but you should if you are following this tutorial.

I’ll be doing a series of these custom function implementation articles. The first few, like this one, will be aimed at the absolute beginner. Gradually we will be working up through more and more complex custom functions, learning how to take them apart so that we can understand how they work, learn how to debug them during testing, and finally, extend and combine them.

As you get more skilled with custom functions you will often find yourself tweaking a readily available custom function to suit your needs, we will cover all of that in future articles.

If you followed this tutorial, let me know how you got on with your custom function implementation. Did it work as expected? Did you do something really daring and try to write your own custom function?

Let me know in the comments.

About the Author: Darren Lunn is on a mission to help new FileMaker Pro developers to become competent FileMaker Pro Developers. You can connect with Darren on Twitter

Related posts:

1. Introduction to FileMaker Pro Custom Functions
2. Keep Your FileMaker Pro Custom Functions Organised
3. FileMaker Pro – Getting Started, Fresh After the Install

Tagged as: Basic Techniques, Custom Functions, Database Development, FileMaker Development, Productivity