PyFM is a FileMaker plug-in for versions 7 to 16. A few things set it apart from other plug-ins: rich functions with named parameters, use of variables to return results, and extensibility.
FileMaker plug-ins are code libraries that enhance FileMaker with new functions and, starting with v16, with new script steps. Plug-ins can be directly used by FileMaker desktop clients, server, and web publishing engine. The mobile FileMaker Go cannot use plug-ins autonomously, but can cooperate with the server to get their results.
Some of these functions return the result that you can directly use, e.g. compose a vCard from a contact record. Such functions are similar to native FileMaker functions. Other functions perform some action, e.g. receive email, and their result only reports if the function succeeded or not. These functions are used almost exclusively in scripts.
If a function cannot perform whatever it must do, it reports an error. There are two ways to do this. Some plug-ins return a value that is very unlikely to be a valid result: the value may start with an unusual combination of symbols, the word “ERROR,” or something like that. Other plug-ins report the error as prescribed by FileMaker plug-in API (when this happens, FileMaker shows the function result as a question mark), and provide a separate function that returns the description of the error occurred in the last call. PyFM uses the second approach; the error function is PyLastError.
The PyFM plug-in has some enhancements that are uncommon among other plug-ins: it uses rich functions with rich parameters, may return results in variables, and is easy to extend.
PyFM provides functions that perform different actions depending on passed
parameters. For example, to work with CardDAV you need to find CardDAV address
books using the base URL, get contents of an address book and the initial sync
token, get changes since the last sync, add a new card, and so on. In PyFM all
this functionality will be combined in a single function: PyCardDAV
.
For this to work rich functions take named parameters. Some functions may accept lots of parameters, but usually most of them are optional. Named parameters can be passed in any order and result in readable and self-documented code.
Not all PyFM functions follow this pattern; some take the usual positional parameters, for example, PyRun.
PyFM functions may return results in FileMaker variables. This is convenient
if the result has multiple pieces of data. For example, when the PyCardDAV
function retrieves a list of changes since the last sync, it reports the
following:
$vcardCount
: number of changed vCards.
$vcardData
, $vcardUri
, and $vcardEtag
: data, URIs, and ETags for each of these vCards. These variables are repeating and contain data for all
the changes.
$newSyncToken
: the sync token for the next sync.
By default functions return result to local script variables, but if necessary, you can override variable names.
If PyFM does not provide a function you need, you can extend it yourself. PyFM has an embedded interpreter for Python, which is a high-level language that emphasizes code readability, has a vast number of third-party libraries under permissive licenses, and is one of most popular programming languages in the world, usually number 4 or 5 in the TIOBE Index.
The built-in Python wraps FileMaker plug-in API into the filemaker
module
so you can use it in convenient Python style. The plug-in also contains a Zip
archive with Python modules, so once you write your extension, you can add it
to this Zip archive and it will become a part of the plug-in.
Although technically the archive is a valid Zip archive that conforms to the specification, many Zip tools can only read it, but not modify (and some cannot even read). The recommended way to extend the plug-ins is to use the included “PyFM.fmp12” file.