Bits and Pieces

Options

Here are two functions I use to pass parameters to scripts: Option() and Get Option():

Handling exceptions

Let’s consider the problem of how to handle exceptions? Assume we have already chosen to go beyond the “method” of simply ignoring them by placing a Set Error Capture[ On ] step at the beginning of a script. Shouldn't we then just write code like this?

Well, I think that though the code above is correct, it still has a problem: it mixes the exception part with the main functionality. It's difficult to follow such a code. Imagine there's three error-checking conditions in a script and you're reading it after a while; you'll have to open three script steps and read their formulas to understand what's going on.

Though you cannot avoid the mix, it worth trying to clearly separate the part that handles exceptions from the rest of your code. After all, exception handling requires very limited functionality: you need to throw an exception, watch for it, and handle it somehow.

I'm going to describe a system I use. The description is fairly long, but actually the system is very simple and takes a couple of fields, a couple of scripts and a handful of very simple custom functions.

Custom functions to simplify reading the current state of modifier keys

The state of modifier keys in FileMaker is represented as a five-bit number taking values from 0 to 31. To read the state of a particular key means to read a particular bit of this number. FileMaker doesn't have native support for binary operations, so developers have to do this on their own. The best way, I think, is to write a few simple custom functions.

The “simplest” (that is without thinking) method would be to go ahead and check the current value of Get( ActiveModifierKeys ) each time you're to read the current state of modifier keys. This approach has several disadvantages. First, one must do it right. Simply checking for

Get( ActiveModifierKeys ) = 4

may or may not give you the state of the Shift key, because at the same moment the user may have the other modifier active. For example, if Caps Lock is active, the result of Get( ActiveModifierKeys ) will be 6; same is for other keys, though they're less likely to be mixed.

Second, it's difficult to check for combinations of keys: the code becomes hardly readable. Time, for example, how long does it take you to answer what exactly is checked by the following code:

Get( ActiveModifierKeys ) = 9

In my applications I use a few custom functions to check the modifier keys' state. For example, I have a function Shift Is Pressed. This function takes no arguments and returns either True or False depending on the current state of the Shift key. It doesn't care whether other modifiers are pressed or not. With such functions the calculations I write look much simpler:

If( Shift Is Pressed, ... If( Option Is Pressed and Shift Is Pressed, ... If( Option Is Pressed and not Control Is Pressed, ...

FileMaker field naming conventions

I have been developing FileMaker applications for quite a long time (about 8 years) and have worked with different field naming conventions. Now I stick to the one I consider the best of all: natural field names.

I used to work, for example, with naming conventions that required me to name fields after their types (global, calculation), certain options (lookup) or roles (key). There were also standardized prefixes, so field names were quite cryptic like OopsThingAMaBobKeyGlob.

I hated this system. It wasn't difficult to understand and thinking up a name for a field was also very simple, because there was very little to think up, but in effect all the names looked same to me. I wasn't able to remember any of them and had to always pick them up from lists, which is a pain for a fast typist like me, especially when the typist is trying to write a complex FileMaker-4-5-6-style calculation.

I used to work with my own system too. I thought it would be fine to leverage the alphabet sorting as the only available field organization tool and designed a system with one-character prefixes to indicate field role. There were prefixes for data fields (d), derivative fields (e), interface-only fields (i), keys (k), script variables (s) and so on. A sample field name would be dName, eSum, iSaveButton, sCounter and so on. The field names were shorter, more readable, and easier to type — I almost never had to pick them from list and even if I had to, I was able to find a field in the list in seconds by typing first few characters of its name.

Unfortunately, the whole approach turned out to be wrong. Yes, automatic sorting is evil. When I sort fields manually, I express certain subtle relations between them: I usually group related fields together, and, for example, tend to put derived fields after source fields, and so on. As I said these relations are subtle, hard to formalize and often vary from table to table and from application to application. If I sort fields automatically, I'll lose all these tiny bits of information that help me to better control the development process.

When I understood this, the rest was straightforward. If I sort fields in what I think is their natural order, I should give them natural names as well. Yes! I should name first name as First Name, sum as Sum, options as Options. The only thing to consider when thinking up a name must be whether it clearly describes the thing and is easy to remember.

What are the advantages?

The more I use the system, the more advantages I see.

• The code becomes far more readable making it easier to communicate with co-developers. A calculation like Subtotal + State Tax + Local Tax + Delivery Fee + Tax on Delivery Fee doesn't require any additional comments, does it?

• Natural names help me to leverage certain FileMaker features with no additional effort. For example, if a field requires a value FileMaker shows a dialog like:

  

  If you use natural names, you may not have to write your own custom message, because the automatic one can already be good enough.

• Finally, sometimes it's good to expose field names to users. (I don't mean unlocking an application to users, though with new security options the idea starts making sense.) In one of projects I develop I had to give users a way to compose text templates with data placeholders and later, when a template is processed, replace these placeholders with actual data. For example, user needed to be able to write something like “this task was completed by <User Name>” and have it changed to “by John Doe” when the task was actually completed.

  Initially I was going to add a table to store possible placeholders and then write a few functions to replace them in a piece of text. I did it actually. The system required two tables with several table occurrences, and a bunch of fields to display the possible choices, and a script to cache values in a global field, and a few custom functions to do the replacement. I think it was good experience, because at the end I realized I don't need all this stuff.

  Most of the placeholders were simply field references and these fields were directly available in the context I needed to calculate them in. Immediately I refactored the whole piece. At the end I had a list of field names, and a very simple selector:

  

  The Event::Created On is what it looks like: a field name. When it is inserted in a field, it gets << and >> at its sides and then a custom function goes through the text and evaluates everything between << and >>.

  The whole module became much simpler, much more manageable and even more flexible and the key part to this were natural field names; I couldn't do this with cryptic geeky ones. By the way, can you guess where the description string below the field name comes from?

  You're correct — this is a comment of the field.

Technorati tags: FileMaker, FileMaker 7, FileMaker 8.

Use modular XSLT to simplify importing XML data into FileMaker

A simple XSLT file encapsulates the target FileMaker grammar into easy-to-use parameterized templates; once written, the file can power any import task with no changes.

To import XML data into FileMaker you have to write:

• Elements of the source grammar;
• Elements of the target grammar, FMPXMLRESULT;
• A list of instructions to transform the former into the latter.

You can put all of this into a single file and it will work; almost all XSLT samples are written this way. But as you face more and more complex import task, you start seeing the drawbacks of this approach:

• You'll have to repeat all the verbose syntax of the target grammar for every XSLT file you write;
• A mix of source and target elements and XSLT instructions can become hardly readable, that is error-prone and difficult to manage.

The universal way to manage complexity is to break something complex into modules that hide all the complexity beneath a simple interface. Let see how it can be done with XSLT.

Assert Equals(): a custom function to test other custom functions

This function is designed to test other custom functions using the extreme programming approach and, most probably, a custom function test unit (if you haven't read the referenced post, you'd better start with it). The function works fairly well both as a specification and as a test engine.

Technorati tags: FileMaker, FileMaker 7, FileMaker 8, custom function, test unit.

“Constant” custom functions to save time and write clearer code

Using some values in FileMaker formulas and scripts isn't very convenient because they are difficult to type or not clearly visible. The samples of these are spaces and tab characters, special symbols like "¶" and an empty value. A possible solution is to use “constant” custom functions instead. Here's a description of four: NULL, TAB, CR and SPACE.

Technorati tags: FileMaker, FileMaker 7, FileMaker 8, custom function.

Develop custom functions more effectively using a simple test unit

An effective approach to writing code is to use automated tests. It's very simple to use the method when developing FileMaker custom functions. All it takes is a little table (you can use the provided sample) and about five minutes to add it to the project you develop.

Technorati tags: FileMaker, FileMaker 7, FileMaker 8, custom function, test unit.