FileMaker Developer 7 Developer’s Guide TM
© 1996-2004, FileMaker, Inc. All Rights Reserved. FileMaker, Inc. 5201 Patrick Henry Drive Santa Clara, California 95054 FileMaker is a trademark of FileMaker, Inc., registered in the U.S. and other countries, and ScriptMaker and the file folder logo are trademarks of FileMaker, Inc. FileMaker documentation is copyrighted. You are not authorized to make additional copies or distribute this documentation without written permission from FileMaker.
Contents Chapter 1 Getting started About FileMaker Developer Using the FileMaker Developer documentation Where to find PDF documentation Registration and customer support About the license key Abiding by the license agreement About the TechInfo database 7 7 8 8 9 9 9 Chapter 2 Using FileMaker Developer features Creating Database Design Reports Using the Script Debugger Using the File Maintenance feature Using custom functions Creating custom functions Editing custom functions Deleting custom functions Dup
FileMaker Developer’s Guide What your users need Documenting the installation procedures Starting runtime database solutions Recovering damaged files Providing user documentation Creating an About layout Creating a custom Help layout Including printed documentation Your responsibilities as a developer Testing before and after creating your solution Distributing updates to runtime database solutions 31 32 32 32 33 33 34 35 35 36 37 Chapter 5 Customizing database solutions About Kiosk mode Navigating in
Contents 5 Requirements for writing external function plug-ins API code files Option string syntax Table of option string characters FileMaker messages sent to the plug-in Initialization message Shutdown message Idle message Preferences message External Function message GetString message Avoiding potential Mac OS X resource conflicts Providing documentation for your plug-in Registering your plug-in Revising a registered plug-in 64 64 65 65 66 66 66 67 67 67 68 68 68 68 69 Appendix A Feature comparison of
FileMaker Developer’s Guide
Chapter 1 Getting started Welcome to FileMaker® Developer. FileMaker Developer is the Developer edition of FileMaker Pro. It includes advanced features for developers. You can use either FileMaker Pro or FileMaker Developer to create and test your database solutions. You use FileMaker Developer to transform your database solution into a runtime or kiosk-mode application that you can distribute to your users.
FileMaker Developer’s Guide 1 FileMaker Pro User’s Guide: contains key concepts and basic procedures 1 FileMaker Pro Tutorial: contains lessons that teach you how to use the major features of FileMaker Pro 1 FileMaker Instant Web Publishing Guide: describes how to make FileMaker Pro and FileMaker Developer databases accessible to web browser users over an intranet or the Internet 1 Converting FileMaker Databases from Previous Versions: contains information about converting databases from previous vers
Getting started 9 About the license key Abiding by the license agreement FileMaker software comes with a unique, 35-character-string license key. Do not lose this license key; it cannot be replaced. We recommend that you keep the license key in a safe place in case the software ever needs to be reinstalled. The FileMaker Developer license agreement allows you royalty-free distribution of an unlimited number of FileMaker Pro runtime database solutions.
FileMaker Developer’s Guide
Chapter 2 Using FileMaker Developer features In addition to all of the features that are available with FileMaker Pro, FileMaker Developer contains a number of advanced development and deployment features to speed up and enhance the development process.
FileMaker Developer’s Guide Using the Script Debugger Use the Script Debugger to troubleshoot scripts in FileMaker databases. The Script Debugger enables you to execute your scripts step-by-step to view issues that may arise as the script is performed. You control how the Script Debugger steps through the script either by using the buttons in the Script Debugger window or the commands in the Debug menu.
Using FileMaker Developer features If a script with access privileges set to Modifiable performs a script with Executable Only access, the Executable Only script will perform in its entirety without showing its steps in the Script Debugger. If an Executable Only script performs a script with privileges set to Modifiable, only the steps in the Modifiable script will appear in the Script Debugger. For more information about script privileges and running scripts with full access, see Help.
FileMaker Developer’s Guide Using the File Maintenance feature Use the File Maintenance feature to improve the performance of your database files. The Compact File option removes free disk space from a file, reducing the file size and streamlining data access. The Optimize File option improves file access speed by moving logically related data closer together. Both features reduce disk-head movement.
Using FileMaker Developer features 1 If you do not have full access privileges and attempt to edit a scripting or field calculation that uses a custom function that is restricted to full access accounts, you will see the string instead of the custom function. You cannot change the calculation when appears in the formula. 15 1 Names cannot contain spaces; be sure to replace spaces with underscores or running the parts of the name together. 4. Build a formula.
FileMaker Developer’s Guide To add a Do this Constant value Type the value. Function In the functions list, double-click a function. In the formula box, replace the example parameter with a value or expression. You can also type parameter names, operators, and functions in the Edit Custom Functions dialog box instead of using the lists or keypad. 8. All accounts is the default option for Availability and allows all 3.
Chapter 3 Using the Developer Utilities FileMaker Developer provides Developer Utilities that let you: 1 bind your database files into a stand-alone runtime database solution that does not require FileMaker Pro or FileMaker Developer in order to be used on a computer 1 rename all of your database files and automatically update the internal links to related files and scripts 1 1 1 add a custom script to an About menu command so you can display a special layout screen about your solution change the name
FileMaker Developer’s Guide Here are some general considerations for preparing solution files: 1 If desired, create a custom theme for all the layouts in your database solution. See “Creating custom layout themes” on page 47 for information. 1 If you’re creating a solution that will have versions for Windows and Mac OS X, test the different versions of the solution on their respective platforms. For more information, see Help.
Using the Developer Utilities 19 8. If you do not want the new files to overwrite earlier versions of 10.In the Specify Solution Options dialog box, select one or more them, clear the Overwrite matching files within the Project Folder checkbox. options. Important If Overwrite matching files within the Project Folder is selected, the Developer Utilities will overwrite files with the same names as those in the list of files. 9.
FileMaker Developer’s Guide To Do this Add the FileMaker extension to the filenames of database files Choose Databases must have a FileMaker file extension Note This option is not available if you select Create Runtime solution application(s). You can use this feature to add extensions to files that do not have extensions. Create a log file to Choose Create Error log for any processing errors record any errors See “Creating an error log” in the next section. encountered during processing 11.
Using the Developer Utilities 1 Will your users be printing reports or other information from your runtime database solution? It’s a good idea to set document margins if your runtime database solution will be printed from a variety of printers. For more information, see Help. 1 Do you want users to be able to perform spell checking on records? You can change the main spelling dictionary language for your database solution by choosing one from the dictionaries supplied with FileMaker Developer.
FileMaker Developer’s Guide Binding files for both platforms If your solution will be used in Windows, bind it using the Developer Utilities for Windows. If your solution will be used on Mac OS X, bind it using the Developer Utilities for Mac OS X.
Using the Developer Utilities The runtime name is used for the runtime application filename and for the name of the folder that contains the runtime database solution files. See “Choosing filenames for runtime database solutions” in the next section. 4. For Extension, type a three-character filename extension. The extension is used to associate the solution files with the runtime applications. See “Assigning three-character filename extensions” on page 23. 5.
FileMaker Developer’s Guide The Developer Utilities automatically update all files to use the three-character extension that you specify and append the extension to the filenames. Internal file references used in relationships, scripts, and external value lists are updated to interact with the new filenames. Note No matter what the filename extensions are, runtime database files can still be opened in FileMaker Pro and FileMaker Developer.
Using the Developer Utilities 25 Setting the binding key Modifying bound runtime files The runtime name that you specify in the Developer Utilities is used for the name of the runtime application and can also be used for the name of the new solution folder that contains the bound runtime database solution files. You can open a bound runtime file in FileMaker Pro and FileMaker Developer to make modifications to it.
FileMaker Developer’s Guide Modifying a set of solution settings To modify a settings file: 1. Open the Developer Utilities. 2. Click Load Settings. 3. Locate and select the settings file that you want to modify. 4. Click Load. 5. Specify options. 6. Click Save Settings, then click Save. 7. Click Yes to replace the file. Your alterations are saved and may be reused again.
Using the Developer Utilities 4. Add a button to activate the script. 5. Repeat steps 3 and 4 for each upgraded file. 6. Use the Developer Utilities to bind your upgraded solution files into the new runtime database solution. 27 Note All database files must have at least one active account or they can’t be opened. You can’t use the Remove admin access from files permanently option if the accounts with Full Access privilege sets are the only active accounts in the file.
FileMaker Developer’s Guide
Chapter 4 Distributing runtime database solutions The final steps in developing your runtime database solution are to bundle all of the necessary files together, choose how you will distribute your solution—for example, on a CD-ROM or over a network—and provide your users with documentation for installing your solution. In addition, your documentation should include instructions for starting the runtime application and what to do if a file is damaged. Important These files and folders must not be renamed.
FileMaker Developer’s Guide DLL files for Windows runtime solutions Extensions folder for Windows solutions The Developer Utilities generate a set of Dynamic Link Libraries (DLLs) during the binding process. These are in the solution folder along with the runtime application and bound database files. They must be delivered as part of the runtime solution. If any of these files are missing or become damaged, they must be replaced.
Distributing runtime database solutions 3. Open the Dictionaries folder. 4. Delete dictionaries for languages not supported by your solution. Mac OS X 1. Open the Extensions folder that is copied to the runtime solution folder. 2. Open the Dictionaries folder. 3. Delete dictionaries for languages not supported by your solution. 4.
FileMaker Developer’s Guide Documenting the installation procedures You’ll need to provide instructions to your users on how to install your runtime database solution. Here’s a list of things you should document: 1 Provide written instructions for copying or installing your solution to your users’ hard disks. 1 Include software and instructions specifying how your users can decompress your solution files. 1 Include information about the minimum equipment and software requirements.
Distributing runtime database solutions During the recovery process, the runtime application: 1 1 creates a new file 33 information. Then use the Developer Utilities to attach scripts to menu commands that open the About and Help layouts. renames any damaged file by adding Old to the end of the filenames (for example, Contact Manager is renamed to Contact Manager Old) Note The FileMaker Pro and FileMaker Developer Help system is not available in runtime applications.
FileMaker Developer’s Guide 3. Type About in the Layout Name box. Note For runtime database solutions, you must include the word “About” in the layout name. You must also include certain specific information in the layout. See “Your responsibilities as a developer” on page 35. file of your solution to display the Help system. Use the Developer Utilities to make the script available as a command in the Help menu. See “Adding custom scripts to the Help menu command” on page 45. 4.
Distributing runtime database solutions 35 Including printed documentation Your responsibilities as a developer In addition to an online Help system, you should include printed documentation that explains how to install your database solution and briefly how to use it in case users are not able to open your solution files. FileMaker has established procedures for repairing files. If a customer complies with these procedures, then FileMaker may supply a repaired file to the customer.
FileMaker Developer’s Guide 6. If full access privileges have been permanently removed from your database solution by selecting the Remove admin access from files permanently option in the Developer Utilities, then the About layout must contain this exact warning: 1 Make sure your runtime database solution does not use a standard FileMaker Pro feature that is hidden or disabled in the runtime application. See “Feature comparison of the runtime application with FileMaker Pro” on page 71.
Distributing runtime database solutions Distributing updates to runtime database solutions If you make feature enhancements or modifications to the primary bound file of your runtime database solution, you can distribute the updated file to your users without rebinding it. If you change the filename of the primary file, however, you’ll need to rebind the file and distribute a new version of the runtime application along with the updated file. 37 To distribute a new or updated auxiliary file: 1.
FileMaker Developer’s Guide
Chapter 5 Customizing database solutions You can use FileMaker Developer to further customize your solutions: 1 Use the Developer Utilities to create a solution that displays your database in Kiosk mode. When users without administrative accounts open a Kiosk solution, it displays on a full screen and without toolbars, menus, or other window controls. 1 Use ScriptMaker to create scripts that can then be attached to buttons.
FileMaker Developer’s Guide To ensure that users can access the primary file and quit the application cleanly: 1 In each auxiliary file, provide a startup script that opens the primary file. 1 5. For Layouts, Value Lists, and Scripts, select either All view only or All no access. 6. Clear the Manage extended privileges checkbox. 7. Select other options as required. In each auxiliary file, place a “Main Menu” button that runs the startup script to open the primary file. 8. Click OK.
Customizing database solutions controls, navigate, and much more. For more information about creating scripts to automate tasks, see Help. Note Use the Debug Scripts option on the Scripts menu to test scripts. See “Using the Script Debugger” on page 12. Creating startup scripts Startup scripts are useful for controlling what appears when users open a file in your solution. You can control which layout is displayed and the size, position, and magnification of the window.
FileMaker Developer’s Guide To emulate these interface elements Create buttons with these script steps attached Vertical scroll bar Scroll Window (if the layout is longer than one screen) Horizontal scroll bar Scroll Window (if the layout objects are wider than one screen) Window size and location Move/Resize Window Global repeating field Repetition number Creating dynamic buttons By using scripts and calculations to evaluate the state of button fields, you can make dynamic buttons that chang
Customizing database solutions 43 When the Developer Utilities process your database files, they create a menu command named “About ” and place it in the Help menu (Windows) or Application menu (Mac OS X). For more information, see “Creating an About layout” on page 33. Case function for dynamic buttons 8. Click OK. Custom About command in a runtime application (Windows) To connect the field and the script: 1. Choose View menu > Layout Mode. 2.
FileMaker Developer’s Guide The About layout in this runtime solution example includes a button to return to the main screen To add a custom script to an About menu command in your solution: This dialog box appears in the runtime application if you don’t specify a custom script for the About command Note In runtime database solutions, you are required to include an About layout that provides information about your company and where users can go for technical support.
Customizing database solutions If you did not bind the files to a runtime application, the Developer Utilities copy the selected database files to the Project Folder. If you did bind the files to a runtime application, the Developer Utilities copy all of the runtime files to a new folder, created inside the Project Folder and named after the runtime solution. To add a custom Help script command to the Help menu in your solution: For more information, see “Creating an About layout” on page 33.
FileMaker Developer’s Guide Renaming the Scripts menu Use the Developer Utilities to rename the Scripts menu for your database solution. The setting is stored in the primary file of your solution and the new menu name appears in the menu bar in FileMaker Developer and in a runtime application. Windows To specify a keyboard accelerator, type an ampersand (&) before the character you want to use as the accelerator key.
Chapter 6 Creating custom layout themes FileMaker Pro and FileMaker Developer use a variety of layout themes to describe the colors, patterns, fonts, and borders of text, fields, and parts in a new layout. A theme is an Extensible Markup Language (XML) document that can be read and edited in a text editor (such as Notepad for Windows or BBEdit for Mac OS X) or XML editor (such as XML SPY or XMetaL).
FileMaker Developer’s Guide Important The XML for a layout theme must be well-formed and comply with the required syntax. See “Requirements for theme files” on page 49 and “Checking theme files for errors” on page 56. 4. Change the name of a theme by replacing the value of the To modify a theme: Note If your THEMENAME value contains any upper-ASCII characters, use the HINT attribute to ensure that the theme name will appear on both the Windows and Mac OS X platforms.
Creating custom layout themes Follow the instruction in the New Layout/Report assistant. The third panel presents you with a list of themes to select from. 49 Minimum XML elements for themes Every theme file must begin with an XML-document processing instruction that declares it as an XML document using the XML 1.0 specification. In addition, an XML document for a layout theme must contain the and start and end tags for the file.
FileMaker Developer’s Guide XML editors expect these characters to be coded as character entities: A single-line element, such as the PEN element, begins with on a single line: Character Coded as ampersand (&) & less than (<) < greater than (>) > apostrophe (‘) ' quote (“) " Using the character instead of the character entity results in an error from the XML editor.
Creating custom layout themes This multi-lined element is used To describe this layout part Leading grand summary — appears at the beginning of a report and displays a summary field for all the records in a found set.
FileMaker Developer’s Guide These multi-line elements May contain these elements TITLEHEADERPART FILL HEADERPART FIELD LEADGRANDSUMPART TEXT BODYPART TEXTLABEL TRAILGRANDSUMPART FOOTERPART TITLEFOOTPART LEADSUBSUMPART FILL TRAILSUBSUMPART FIELD PARTNUMBER TEXT TEXTLABEL BORDER and EFFECT elements share the same pen size. When used together, the pen size value that you set for BORDER will also apply to the EFFECT width.
Creating custom layout themes These single-line elements Must contain these attributes SIDES THEMENAME HINT (optional) VALUE Syntax examples: THEMEDEFAULT VALUE Valid values for theme attributes The following table describes the attribute values supported by FileMaker Developer in a layout theme. Values must be enclosed within quotation marks (“ ”).
FileMaker Developer’s Guide This attribute Is used to describe these characteristics And may contain these values This attribute Is used to describe these characteristics And may contain these values FONT The name of the font. More than one font name can be specified, separated by commas. The first font available on a user’s computer will be used in the layout. FONT = “Times New Roman” PATTERN One of 64 valid patterns from the fill pattern palette in FileMaker Developer.
Creating custom layout themes This attribute Is used to describe these characteristics STYLE Character styles for text in fields, text blocks, and field labels. More than one style can be specified, separated by commas or spaces. And may contain these values STYLE = “PLAIN” STYLE = “BOLD” STYLE = “ITALIC” STYLE = No error checking is done for “STRIKEOUT” contradicting styles, such as STYLE = UPPERCASE and LOWERCASE. “STRIKETHRU” The PLAIN style value overrides all STYLE = other style values.
FileMaker Developer’s Guide 1 2 3 4 5 6 7 8 Adding comments to theme files You can add additional information to your XML theme files by enclosing the information in comment tags: FileMaker Pro and FileMaker Developer will ignore any unknown (but syntactically correct) XML elements you may choose to include. This allows your theme files to be backward and forward compatible with other versions of FileMaker Pro and FileMaker Developer.
Creating custom layout themes 1 All elements are complete. There are no missing attributes, values, quotation marks, start tags, or end tags. 1 All values are enclosed in quotation marks (“value”). There are no missing opening or closing quotation marks, and there are no missing values (no blank quotation marks “ ”). 1 All elements and attributes are spelled correctly. 1 All attribute values are spelled correctly and are valid. 1 Every single-line element ends with />.
FileMaker Developer’s Guide
Chapter 7 Developing third-party FileMaker plug-ins If you are a C or C++ programmer and familiar with advanced calculations in FileMaker Pro and FileMaker Developer, you can create external function plug-ins that extend the feature set of the applications. The plug-ins can take advantage of recursion and looping or hook into other programming interfaces.
FileMaker Developer’s Guide Contents of the FMExample folder File/Folder Description Folder Description FMPluginFunctions.cpp Example folder Contains all of the files that are part of the FMExample. Contains code for implementation of external functions in FMExample. FMPluginFunctions.h Contains definitions for external functions, including function IDs. Headers folder Libraries folder Contains function definition files for the FileMaker API.
Developing third-party FileMaker plug-ins Description of the FMExample plug-in’s external functions 2. Click the Plug-Ins tab. 3. Select the plug-in in the list. A plug-in will appear in the list if it’s installed in the correct folder inside the FileMaker Developer application folder. The FMExample plug-in provided in the Microsoft Visual C++ and CodeWarrior example projects adds the following external functions to FileMaker Pro, FileMaker Developer, and FileMaker Server.
FileMaker Developer’s Guide Function’s name and parameter Description of external function XMpl_UserFormatNumb Returns the parameter as a text string formatted as er (textOrNumber) specified in the configuration dialog box. Use this function to format text or numbers such as telephone numbers, postal codes, and so on. XMpl_FormatNumber (formatString; textOrNumber) Formatting proceeds from right to left. Each # symbol in the format string is replaced by the next character in the parameter string.
Developing third-party FileMaker plug-ins 63 12. Continue to build the formula then and click OK when you’re done. 13. Click OK to close the Define Database dialog box. Customizing the plug-in example 10. Double-click an external function to add it to the formula box. All external function calls require the name of the external function to call and the function’s parameter value, even if the value is null.
FileMaker Developer’s Guide Customizing FMPluginExample.cpp Make your modifications to the FMPluginExample.cpp in the functions listed in the following table. Function name Customization Do_PluginInit Provide your own unique plugin ID for “pluginID.” Register each function, providing its name, description, and function to be used. Call fmx::ExprEnv::RegisterExternalFunction to register your functions. Do_PluginIdle Add any idle processing your plug-in needs.
Developing third-party FileMaker plug-ins FMExternCallStruct defines the structure of the parameter block. FMExternCallPtr is a pointer to that structure and gFMExternCallPtr is a global variable that should be defined in your code. The FMXCalcEngine.h file contains the register and unregister functions. It will be used in most plug-ins, as the plug-ins will likely need to register functions.
FileMaker Developer’s Guide your plug-in. FileMaker has reserved certain naming conventions for external functions. For more information, see “Registering your plug-in” on page 68. FileMaker messages sent to the plug-in There are six possible calls that FileMaker Pro, FileMaker Developer, or FileMaker Server can request of your plug-in. Messages sent to your plug-in are supplied in the whichCall field of the parameter block, FMExternCallStruct, defined in the FMXExtern.h file.
Developing third-party FileMaker plug-ins 67 The FMPluginExample plug-in does not allocate any persistent memory on the heap, and therefore does not do anything when it receives the Shutdown message. You should implement a clean-up function in your plug-in, however, to deallocate anything you have on the heap and exit from any operating system services you may be using.
FileMaker Developer’s Guide GetString message The GetString message, kFMXT_GetString, is sent to the plug-in when FileMaker Pro, FileMaker Developer, or FileMaker Server want to retrieve one of the following strings from the plug-in. The plug-in developer can decide where to store the strings.
Developing third-party FileMaker plug-ins Revising a registered plug-in If you need to revise information about a plug-in that is already registered to you, you must send an email message to FileMaker at plugins@filemaker.com.
FileMaker Developer’s Guide
Appendix A Feature comparison of the runtime application with FileMaker Pro When you double-click the FileMaker Pro application icon to start the application, the New Database dialog box opens and you can choose a database file. When you start a FileMaker Pro runtime application, the primary bound database file opens automatically.
FileMaker Developer’s Guide The Layout tab is changed to the Color tab in the Preferences dialog box for the runtime application. General preferences in a runtime application (Mac OS X) General preferences in a runtime application (Windows) The File Options dialog box does not have the Open/Close and Text tabs in the runtime application, only the Spelling tab—as shown below.
Feature comparison of the runtime application with FileMaker Pro Toolbar comparison Windows The New Database and Open tools in the standard toolbar (in Browse mode, Find mode, and Preview mode) are not available in the runtime application. The Help tool on the standard toolbar in the runtime application is dimmed unless a custom Help script has been specified.
FileMaker Developer’s Guide Windows View Menu command Browse Mode Find Mode Layout Mode Preview Mode View as Form View as List View as Table Toolbars Status Bar Status Area Text Ruler Zoom In Zoom Out Mac OS X Windows Pro RT Pro RT 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 Format Menu command Font Size Style 1 1 1 1 1 Align Text Line Spacing Text Color Text Insert Menu command Picture QuickTime Sound File Object Current Date Current Time Current User Name From
Feature comparison of the runtime application with FileMaker Pro Requests Menu command (Find mode) Add New Request Duplicate Request Delete Request Show All Records Perform Find Constrain Found Set Extend Found Set Revert Request Windows Mac OS X Pro RT Pro RT 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 Windows Scripts Menu command ScriptMaker
