FileMaker Extra: Soliant Development Standards
For this final section of the book, we've
to provide for your consideration the standards our own custom development service firm, Soliant Consulting, uses. We do not want to be guilty of thinking that our coding standards are the only ones available, and if the struggle we had internally to
at a single standard is any indication, we're very cognizant that other approaches are entirely valid and effective. The important point in all of this is to adopt a standard
standard. On the other hand, we felt that a chapter on documentation and standards would be incomplete without presenting at least one concrete set.
Please know these standards are presented largely in their day-to-day undigested form without a great deal of exposition or details on the rationale behind the choices we and our organization made.
If you are interested in learning more about FileMaker standards, or in delving further into an
exploration behind why some of these decisions have been adopted, we strongly recommend you read the document that FileMaker Inc. itself has published on the topic (available free as a PDF download). To get to the FileMaker Development Conventions, go to the following site:
The authors of this book participated in the development of the FDC tech brief and believe that it serves as a comprehensive guide to standards in FileMaker.
Furthermore, in these standards we present the "Anchor Method" of managing the Relationships Graph in FileMaker. Roger Jacques, the initial creator of this approach (and a senior manager at Soliant), published an article, "Managing the FileMaker Pro 7 Relationship Graph," explaining the thinking behind the method in the September 2005 issue of
FileMaker Advisor Magazine
. An electronic version of that article is available, along with archives of all the magazine's articles, as a subscription service on the FileMaker Advisor website:
We recommend that you include a copy of whatever standards you've used with a given solution so that a new developer to the project can review them if you are unavailable for whatever reason.
These conventions are compliant with version 1.0 of the FDC standards published November 1, 2005.
All conventions in this section are required in order for a file or files to
to the Soliant coding and development standards.
Filenames may use only the
AZ, az, 09, and _ (
) and must begin with a letter. Spaces are not allowed, but InterCaps can be used to distinguish words.
Files from one solution need to have a common prefix so that they
together, even if there is only one file. For example:
, and so on
may use only the characters AZ, az, 09, and _ (underscore) and must begin with a letter.
Prefix developer tables with "z_"for example, "z_Globals," "z_Resource," and so on.
Always sort tables by
Tables should always be named for the descriptive entity in question. In other words, for example, use "Invoice" instead of "Table3."
Singular or plural naming convention is optional, but must
consistent throughout the applicationfor example, Employees and Departments, or Employee and Department.
Field names may use only the characters AZ, az, 09, and _ (underscore) and must begin with a letter (with the exception of keys; see the subsection "Key Fields").
Developer fields (except keys): Always prefix with "z_" and only "z_". No other prefixing. Use an optional suffix for more detail if you want (see the "Recommended Conventions" section later in this document). Spaces are not allowed in developer fields, but InterCaps can be used to distinguish words on object names. For example:
z_TempError_gn (note the global denoted in the optional suffix)
Always sort fields by name.
All fields used in relationships must be identified as keys with a "_k*_" prefix. For example:
_kf_contact_n (contact foreign key)
For primary keys we use two underscores to ensure that the field sorts to the top of the list. For example:
__kp_contact_n (contact primary key)
Only keys used in primary data relationships should be
foreign keys. For the rest, use the following:
_ka_SelectedContactName_t (alternate key)
_kc_contactOrg_ct (compound key)
_km_contact_t (multiline key)
_kg_contact_gt (global key)
The prefix "_k*_" means that keys will sort to the top of an alphabetized list of fields.
Only kp and kf are mandatory designations, the rest are optional.
"Temp" Fields Rule
Any field that contains the word "temp" in it makes no assumptions about its contents except within a single script routine (that may also comprise nested scripts). At the end of a script, a temp field can be considered empty or over-writable.
Note that FileMaker 8 introduced script variables. It is often no longer necessary to use temp fields for the purpose of storing
; we have left the rule in the standards for those systems still in place using older versions of FileMaker.
Layout names may use only the characters AZ, az, 09, and _ (underscore) and must begin with a letter.
Layout names need to make use of a prefix to
the "Anchor table occurrence (TO)" to which they are attached. (See the later section "Table Occurrence Naming" to understand what an "Anchor TO" is.) For example:
Layouts from the same Anchor TO should be grouped together in layout order.
Any developer layouts should be prefixed with a
Script names may be divided into functional groups. If so, the standards make no prescription as to what those groups should look like. (Sorting scripts might
, navigation scripts another.)
If functional groups are not used, scripts must be ordered
Version control for client deliverables should be managed via an enclosing folder name, not via changes to the filenames.
No specific folder naming scheme is
. It could be alpha/beta/final, or it could be a simple timestamp.
All compressed archive filenames should be formatted in the timestamp method. Time indication is optional as military time, or AM/PM for morning or afternoon.
Version control applies to archived files, not individual FileMaker files or their
folders. You need to apply the timestamp convention only when you compress/archive the project folder. For example:
script comments, but these are the minimum requirements:
All scripts will include three headers that identify the purpose, dependencies/variables, and edit history of a script. Each developer who edits a script will insert an ID line similar to this:
Purpose: Navigate to Contacts Layout
Dependencies: (examples: layout name for context, script parameters, script variables, or plug-in requirements)
History: scl 2004 jan 01 (helpful to put the day last for quick editing)
End each script with an
script step. This allows the logic of the script to conclude while leaving Script Debugger
. It also serves to explicitly
an end to the routine.
All script parameters should be identified in the script comments as dependencies.
The script parameter
for multiple parameters should remain consistent throughout the application.
Any delimiter other than a hard return can be used.
We have opted to standardize on the "Anchor Method" style for our systems. These are the primary reasons for this:
To help when selecting layout objects from a list dialog of table occurrences
To make the Relationships Graph itself more manageable/comprehensible by other developers
To make a meaningful naming convention possible
In this scheme, those TOs linked together form a Table Occurrence Group (TOG) with one Anchor TO at the leftmost position.
A TOG must be a complete island; there may never be a relationship line between any two TOGs.
All other TOs in the group exist for the purpose of feeding
data to the Anchor TO.
All user layouts should be associated only with an Anchor TO. Developer layouts used in scripts for establishing context, populating sample data, and so on may be based on any TO. Any layout that a
sees must be based on an Anchor TO.
TOGs and TOs are read, and meaningful, from left to right. Even though the FileMaker Relationships Graph is bidirectional, the TOs are arranged hierarchically for clarity. The naming convention mentioned in the text that
creates a similar hierarchical effect in pop-up dialogs.
Some source tables may have multiple TOGs where they serve as an anchor. The decision to create a new TOG is based on functional requirements. Some examples follow:
Data needs to be fed to a set of list/detail screens.
An Anchor table is used in two functionally different ways, and each requires its own TOG.
A UI screen requires a source table; a TOG is based on a developer table.
Figure 27.7 shows a typical TOG.
Figure 27.7. An example of a typical TOG, with the Anchor TO leftmost on the graph.
Figure 27.8 shows the same information that's included in the list of TO names used in a number of dialogs within FileMaker. Note that they order
hierarchically just as they appear on the Relationships Graph.
Figure 27.8. In dialogs that list TO names, this naming convention maps to the same organization that exists on the Relationships Graph.
Table Occurrence Naming
The name of a TO describes the chain of source tables between the anchor and the TO itself, with optional attribute indicators. The attribute indicators can be functional names, names of keys, or any other means of clarifying the purpose of the TO. The ability to read a chain of TOs in both the graph and the various pop-ups and dialogs lends clarity. By reading the name of a single TO, one should be able to grasp where on the Relationships Graph it sits.
These are the rules that
All TOGs start with an anchor. An anchor is named in the following fashion:
The first occurrence of an abbreviation is cappedfor example,
The double underscore makes the anchor sort to the top of all lists.
The corresponding source table name is title casefor example,
attribute indicates that this TO is the anchor for a TOG. You can optionally use
if you'd like.
Subsequent TOs start with the TOG name, but in lowercase:
The leftmost TO name is the anchor; the TO above is part of the
The source table is indicated by the capped abbreviation
. All lowercase TOs are connected, and the single capped TO is the associated source table.
The second element of the name, following two underscores, is the familiar name of the source table entity:
The optional attribute is the functional description:
After an abbreviation for a source table has been established, it must remain consistent throughout the graph.
Some developers use the optional suffix to list the keys used in establishing relationships to table occurrences. The
table occurrence in Figure 27.7 might also be named:
Abbreviations are used to save space: FileMaker Pro on
truncates TO names in several dialogs. Three character abbreviations are typical, but the length of the abbreviation is at the discretion of the developer. The only hard and fast requirement is that names are legible on
The conventions in this section are not mandated, but they provide some standard ways of doing certain things, if you choose to do them.
Calculation Dialog Comments:
Liberally add comments to complex scripts and calculations. Use whitespace for legibility.
function where you would have more than one or two nested functions.
Reuse of Code:
Modular coding of scripts and use of subscripts.
Script parameters for reusable scripts.
In cases in which an array is used in a script parameter, write custom functions for parsing data into and out of the array.
Keep your names as short as reasonably possible. Some dialogs are still width-restricted in FileMaker on Windows.
We use InterCaps for multiple words. Underscores are
to differentiate between elements of a field (or table) name; however, user fields make an exception to that rule, where effort should be made to support ease of reading for end users.
Examples of developer fields that follow these conventions look like this:
z_MainLogo_gr (global container)
z_SortPreference_gt (global text)
z_ColumnSortIcons_grr (global repeating text)
z_recCreateModDisplay_ct (calc text)
Scripts may be subdivided into functional groups and separated by a header. Additionally, insert a single hyphen to appear as a separator. For example:
------------- FILE MANAGEMENT
Relogin for testing
------------- ADMIN ACCOUNT FUNCTIONS
Create New Account
Spaces are acceptable in script names. Keep in mind that on Windows, some dialogs open only to approximately 4050 characters.