Register custom functions with MBS Plugin

[MonkeybreadSoftware]

With MBS FileMaker Plugin 15.3 we allow you to dynamically register custom function via plugin functions. Yes, make your own functions on the fly and use them in all your database files. Instead of defining custom functions in FileMaker directly and then copying & pasting them to other files, you can store them in records and register them at startup.

Each function gets the following:

• ID

  It needs an unique ID which is what FileMaker internally uses to find the function. Please use an ID >= 3 and assign them yourself to the functions.

• Name

  An unique name, which doesn't match a FileMaker function or an existing custom function. Just like names in FileMaker, you may only use a subset of characters, e.g. no brackets.

• Prototype

  The function needs to have a prototype for display in the function list.

  The prototype gives our parameters a name for the variables.

• Expression

  You pass the calculation to evaluate. This is a FileMaker calculation just like in a custom function in FileMaker. You can use the names defined for variables in the prototype.

  Independent of parameter names, you can always use Plugin.CustomFunctionParameterCount to query the number of parameters and then query the value with Plugin.CustomFunctionParameter function. This allows your function to take a variable number of parameters.

  Since parameters are stored per thread, you may prefer to read any variable parameter values into local variables before doing any recursion.

• Min/MaxParameter

  You can define a minimum and a maximum number of parameters. Both are optional and default to 0 for minimum and no limit (-1) for maximum parameters.

• Flags

  For MBS Plugin 15.4 we add optional flags. Default is 0 here for compatibility with older versions. You can pass 1 to enable the use of JavaScript here. Later we added 2 for using JavaScript with WebKit instead of Duktape. 

  Then we added the flag 4 which allows to remember values from one call to the next. Great for using multiple calls within a script and have one custom function take data, parse it and remember it, so other custom functions can read this data.

Once registered somewhere, you can use the functions everywhere in all calculations.

Examples

Let's show you an example:

MBS("Plugin.RegisterFunction";

    123; // ID to use

    "Concat"

    "Concat(Value1; Value2)";

    "Value1 & Value2";

    2; // min and max parameters

    2)

This registers the Concat() function, which returns two values concatenated. We can do the same with JavaScript:

MBS("Plugin.RegisterFunction"; 7; "ConcatJS"; 
    "ConcatJS(Value1; Value2)"; 
    "function ConcatJS(a, b) {

        return String(a) + String(b);

    }"; 2; 2; 1)

This uses DukTape engine to run the JavaScript. It converts the values a and b to String if needed and then appends one to the other.

Now for JavaScript we can use a per thread engine, so we can use globalThis in JavaScript and store values:

MBS( "Plugin.RegisterFunction"; 11; 
    "TestCounterWK()"; 
    "function TestCounterWK() {

        globalThis.counter = (globalThis.counter || 0) + 1;

        return globalThis.counter;

    }"; 0; 0; 2 + 4)

If you run this custom function, it counts upwards.

Summary

• Store functions in records in a database. No need to copy & paste to other files!
• Register at startup of solution.
• Use in all files
• Define with FileMaker expression or JavaScript code
• Variable number of parameters
• Recursion possible

For the upcoming MBS FileMaker Plugin 15.4 version we add the possibility to use JavaScript in the function definition. Please try.