How to write your first module

A short overview of how to write a function in Python, install it, and call it from FileMaker.

If you haven't yet installed the plug-in, proceed to the Getting started section.

Let's see what it takes to write Python code for FileMaker:

  • Write the first version of the code.

  • Somehow get it into FileMaker so we can call it.

  • Actually call it.

  • Debug the code and repeat until it's ready.

How to write the code#Back to top

Use any suitable text editor of your choice and save the file on your disk. Later you'll see how to add a reference to the file to PyFM Tools and use it to load the code, so you'll be able to make changes and reload them into FileMaker with only one press of a button.

Technically you can type code right in FileMaker, but this is going to be fairly inconvenient, I'm afraid; only for short snippets, perhaps.

What to write#Back to top

Everyone will travel a different path here, so I'll just point to useful resources.

Of course, you're supposed to know Python well enough to write the function you want. If you don't know Python, start with Python tutorial.

Python code for FileMaker is pretty much similar to any other Python code, but there are a few important peculiarities explainded in Writing Python code for FileMaker. Also, you will often need to closely interact with FileMaker, i.e. not only receive the parameters and return the result, but also use evaluate() to query additional information. It really helps to understand both Python and FileMaker; at least have a reference of FileMaker functions nearby.

Here are function references for v11 and v12.

For a hands-on introduction check Samples and for everything else check List of modules (especially the filemaker module), and List of services.

How to put your code into FileMaker#Back to top

The fastest way would be to use the PyFM Tools file. Open the file and go to files:

The Files table comes with example code and these samples are stored as literal text, but you can also store binary files, or references to files, which is especially useful during development. Add a new file, select ‘Binary’, and select your file. Make sure to store only a reference:

Files stored as a reference have a shortcut icon, so you can tell them from embedded ones.

Now press the ‘Install’ button to have it installed. The file status should change to ‘Installed’:

You're ready to call it.

How to call your code#Back to top

You'll normally call your code with the PyRun service:

PyRun( "mymodule"; "myfunc"; ... )

Here mymodule is the name of your file, myfunc is the name of the function you're calling, and the rest can be parameters as required by the function.

Another way to call your code during development is to use the Python console in PyFM Tools. Console is a great way to test small bits of code and to quickly run your module. With console this will be like that:

>>> import mymodule
>>> mymodule.myfunc(...)

Console may be especially useful during debugging, because if Python raises an exception, the console will print a full stack trace. With PyRun() you'll only get the exception alone.

If your code uses evaluate() or execute_sql(), you may not be able to fully test your module from the console because the environment of your file and environment of the cosole are going to be different. Still, you might be able to inspect the state of the global variables, call helper functions, and so on.

When you install a new version of your module, the plug-in removes the old version from sys.modules, so the next time you call it with PyRun() it will automatically load a new version. But if you use the console, you'll have to manually reload your module:

>>> reload(mymodule)

How to debug your code when writing#Back to top

First, use the Python console. If you're not sure how something works, fire up the console and try it. It really helps. If your module can be called from a console, do it; if it cannot, still load it there so you can inspect its contents (e.g. print out a global variable).

Second, use logging. For now use the standard Python logging module. (PyFM has its own logging module, but I haven't yet documented it.)

For now there's no debugger and pdb won't work with PyFM console. I plan to add a debugger later, but it's rather far in the list of todos.

Repeat writing, loading, and running and sooner or later your module will be ready. By that time you'll probably be interested in further steps:

  • Handling errors.

  • Distributing your modules with your FileMaker application (not yet written).

  • Installing your modules on FileMaker Server (not yet written either).