FileMaker Pro 9 Advanced ® Development Guide
© 2007 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. All other trademarks are the property of their respective owners. FileMaker documentation is copyrighted. You are not authorized to make additional copies or distribute this documentation without written permission from FileMaker.
Contents Chapter 1 Introducing FileMaker Pro Advanced About this guide Using the FileMaker Pro Advanced documentation Where to find PDF documentation Abiding by the license agreement for runtime solutions Your responsibilities as a developer 5 5 5 6 6 7 Chapter 2 Creating database solutions Using the Developer Utilities About creating runtime solutions Converting and upgrading previous solutions Binding the solution Starting runtime database solutions Distributing runtime solutions Organizing solution com
FileMaker Pro Advanced Development Guide 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 39 39 40 40 40 41 41 41 41 Appendix A Feature comparison of the runtime application with FileMaker Pro Application and document preferences Toolbar comparison Menu command comparison Ignored script steps Stored registry s
Chapter 1 Introducing FileMaker Pro Advanced Welcome to FileMaker® Pro Advanced. This product includes advanced development and customization tools designed especially for database developers. You can use either FileMaker Pro or FileMaker Pro Advanced to create and test your database solutions.
FileMaker Pro Advanced Development Guide The following manuals are included: 1 FileMaker Pro Advanced Development Guide (this manual): describes how to use the features available in FileMaker Pro Advanced 1 Installation and New Features Guide for FileMaker Pro and FileMaker Pro Advanced: contains installation instructions and a list of the new features in the current version 1 FileMaker Pro User’s Guide: contains key concepts and basic procedures 1 FileMaker Pro Tutorial: contains step-by-step les
Chapter 1 Your responsibilities as a developer | Introducing FileMaker Pro Advanced 7 If you distribute database files with passwords or you have removed full access privileges and do not want FileMaker to repair a file for a customer who requests this service, you must: The accounts and privileges protection in a FileMaker file should not be viewed as an absolute barrier that will prevent a customer from accessing files.
FileMaker Pro Advanced Development Guide
Chapter 2 Creating database solutions FileMaker Pro Advanced provides Developer Utilities that let you: 1 rename a set of database files and automatically update the internal links to related files and scripts 1 bind your database files into a stand-alone runtime database solution that does not require FileMaker Pro or FileMaker Pro Advanced in order to be used on a computer 1 remove administrative access from all accounts and prevent users from modifying most design or structural elements of your dat
FileMaker Pro Advanced Development Guide 9. If you do not want the new files to overwrite earlier versions, clear Overwrite matching files within the Project Folder. 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. 11.
Chapter 2 About creating runtime solutions Use the Developer Utilities to produce a stand-alone runtime database solution that users can access without running FileMaker Pro or FileMaker Pro Advanced. The Developer Utilities create a copy of your files, and bind the database file or files to a runtime application with a name that you specify. Runtime applications do not have all the functionality and features of FileMaker Pro.
FileMaker Pro Advanced Development Guide Binding the solution To bind database files into a runtime database solution: 1. Follow the procedures in “Using the Developer Utilities” on page 9. 2. In the Specify Solution Options dialog box, select Create Runtime solution application(s). 3. To name your runtime application: 1 For Runtime Name, type a name. The name is used for the runtime application filename and for the name of the folder that contains the runtime database solution files.
Chapter 2 Distributing runtime 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.
FileMaker Pro Advanced Development Guide Choosing a distribution method After you have organized the files that comprise your solution, you need to decide how your users will install them. You can distribute your bundled solution on a CD-ROM, over a network, or via the internet. In order to run your runtime database solution, your users will need the same minimum equipment and software required by the FileMaker Pro Advanced application.
Chapter 2 Creating a custom Help layout The FileMaker Pro Advanced Help system is not available in runtime applications. Create a Help layout that provides instructions for how to use your custom solution and add data to it. Then create a script in the primary file of your solution to display the Help system. Use the custom menus feature to make the script available as a command in the Help menu. To create a web page to document your solution, put a web viewer in your Help layout that opens the web page.
FileMaker Pro Advanced Development Guide To distribute an updated primary file: 1. Open the original primary file from your copy of the runtime solution in FileMaker Pro Advanced. 2. Make the changes to the primary file. 3. If necessary, create an Import script so users can import their existing data into the new primary file. Creating Kiosk solutions Kiosk mode is a way of displaying your database solution or your runtime database solution on a full screen, without any toolbars or menus.
Chapter 2 To create a Kiosk account: 1. Ensure you have a limited access account. | Creating database solutions 17 To change the default option of logging into the file with the Admin account: 2. With the database solution open, choose File menu > Manage > Accounts & Privileges. 1. With the database solution open, choose File menu > File Options. 3. In the Manage Accounts & Privileges dialog box, click New. 3. Click OK. 4.
FileMaker Pro Advanced Development Guide
Chapter 3 Customizing database solutions You can use FileMaker Pro Advanced to customize your solutions beyond what is possible with FileMaker Pro. You can: Copying or importing field and table schemas 1 1 1 1 1 1 You can copy or import field and table schemas within a file or to other database files.
FileMaker Pro Advanced Development Guide Creating custom functions Use the Custom Functions feature to create custom functions that can be reused anywhere in the database file in which they are created. Once formulas are written for the function, they don’t have to be rewritten to be applied to other fields or used in other scripts. You can maintain and edit custom functions and the formulas they contain in one central location.
Chapter 3 | Customizing database solutions 21 About custom menus You can customize menus by: With FileMaker Pro Advanced, you can create custom menus, menu items, and menu sets for your database solutions. You can: editing a copy of a standard FileMaker menu. Use this method to make minor changes to existing menus, for example, to modify the properties of a few menu items. 1 1 1 1 create a menu or edit an existing menu 1 starting with an empty menu.
FileMaker Pro Advanced Development Guide Creating custom menus The Edit Custom Menu dialog box appears. To create a custom menu: 1. Choose File menu > Manage > Custom Menus > Custom Menus tab. Menus in brackets are not customizable; they are locked 2. Click Create. 3. In the Create Custom Menu dialog box, do one of the following, then click OK: 1 1 Click Start with an empty menu. Click Start with a standard FileMaker menu, then select a menu from the list. 4.
Chapter 3 To create or edit a custom menu item: 1. Choose File menu > Manage > Custom Menus > Custom Menus tab. 2. In the Manage Custom Menus dialog box, select the menu from the list, then click Edit. 3. In the Edit Custom Menu dialog box, specify which menu items are included in the menu: To Do this Add a command Click Command. Customizing database solutions 4. Select each menu item from the Menu Items list and specify its properties. To Do this Change a command for Click Specify.
FileMaker Pro Advanced Development Guide Creating custom menu sets You can create custom menu sets to include the menus you require. To create or edit menu sets: 1. Choose File menu > Manage > Custom Menus > Menu Sets tab. Menus appear in the menu bar in the order shown in this list. Drag an arrow up or down to change the order. 2. Create a menu set, or edit or duplicate an existing menu set. You can also delete menu sets that your users will not need.
Chapter 3 Creating custom layout themes FileMaker Pro and FileMaker Pro Advanced 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 XMLSpy or XMetaL).
FileMaker Pro Advanced Development Guide 2. Rename the copy and include the .fth extension with the new filename. 6. Remove any elements that you don’t want to specify. Keep the new file in the Themes folder. In order for the New Layout/ Report assistant to display a theme option, the theme file must reside in the Themes folder and it must have the .fth filename extension. Be sure to remove the entire single-line or multi-line element including its start and end tags. 3.
Chapter 4 Debugging, analyzing, and optimizing files The FileMaker Pro Advanced features explained in this chapter are: 1 the Script Debugger for systematic testing and debugging of FileMaker scripts 1 1 the Disable script step feature for testing portions of a script the Database Design Report feature for publishing comprehensive documentation on database schema and options 1 1 the Data Viewer for monitoring fields, variables, and calculations the File Maintenance features for compacting the size o
FileMaker Pro Advanced Development Guide Disabling script steps You can disable and enable script steps to test portions of a script. When you run a script, disabled script steps are skipped. Click to view restricted access expressions To disable script steps: Click a column heading to sort 1. Choose Scripts menu > ScriptMaker™. Or, choose File menu > Manage > Scripts. 2. In the Manage Scripts dialog box, double-click the script name. Or, click the Edit button in the Script Debugger dialog box.
Chapter 4 6. Click the Watch tab. | Debugging, analyzing, and optimizing files 29 8. In the Edit Expression dialog box, select the database file containing the expression, then build or edit the expression you want to monitor. Select mathematical and text operators Drag an arrow up or down to change the order Select comparison and logical operators Choose the way functions are listed in the dialog box Select functions Filename Choose field references 7.
FileMaker Pro Advanced Development Guide Using the Database Design Report Use the Database Design Report (DDR) feature to document the schema of your database and publish it to an HTML or XML file. You can choose which elements and database tables in the database you want to report. The HTML version of the report is hyperlinked and you can view or print it in a Javascript-enabled web browser.
Chapter 4 Compressing and optimizing files 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.
FileMaker Pro Advanced Development Guide
Chapter 5 Developing third-party FileMaker plug-ins If you are a C or C++ programmer and familiar with calculations in FileMaker Pro and FileMaker Pro Advanced, 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 Pro Advanced Development Guide Contents of the FMExample folder File/Folder Description Folder Description FMPluginFunctions.cpp Contains code for implementation of external functions in FMExample. Example folder Contains all of the files that are part of the FMExample. FMPluginFunctions.h Contains definitions for external functions, including function IDs. Contains function definition files for the FileMaker API.
Chapter 5 | Developing third-party FileMaker plug-ins To install a plug-in, drag the plug-in file into the Extensions folder inside the FileMaker Pro Advanced folder. In Windows, the plug-in extension must be .fmx. In Mac OS X, the plug-in extension must be .fmplugin. 2. Click Configure. To enable a plug-in: 1. Open the Preferences dialog box. 3. Follow instructions in the configuration dialog box to configure the plug-in. Windows: Choose Edit menu > Preferences. 4. Click OK.
FileMaker Pro Advanced Development Guide Function’s name and parameter XMpl_StartScript (filename; scriptname) XMpl_Version 4. Select FMExample. Description of external function Runs the script specified by the scriptname parameter on the file specified by the filename parameter. Returns the version of the plug-in. It has no parameters. Note A version function similar to the one provided in the example plug-in is required for every FileMaker Pro plug-in.
Chapter 5 | Developing third-party FileMaker plug-ins 37 14. Click OK to close the Manage Database dialog box. Customizing the example resources Mac OS Plug-ins created for PowerPCs need to be re-compiled as universal binaries in order to run natively when FileMaker Pro is run on Intel-based Mac computers. Universal binaries allow applications to run natively on both PowerPC and Intel-based Macintoshes.
FileMaker Pro Advanced Development Guide Requirements for writing external function 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. FileMaker plug-ins are most useful when they contain a single function or a set of functions with similar features.
Chapter 5 | Developing third-party FileMaker plug-ins 39 FileMaker messages sent to the plug-in Characters in the option string Description of characters 1-4 Characters 1-4 are the plug-in ID. Register the ID as a Creator code on the Apple Developer Support website at www.apple.com. 5 Character 5 is always “1.” 6 Set the sixth character of the option string to “Y” if you want to enable the Configure button for plug-ins in the Preferences dialog box.
FileMaker Pro Advanced Development Guide For the FMPluginExample plug-in, the Do_PluginInit function is called when the Initialization message is received. The Do_PluginInit function first checks the version of the API that the plug-in was compiled with to verify that it’s compatible with the version of FileMaker Pro, FileMaker Pro Advanced, or FileMaker Server that has loaded it. Then the function checks for preferences and sets them if they exist.
Chapter 5 | Developing third-party FileMaker plug-ins 41 Avoiding potential Mac OS X resource conflicts The plug-in should display a dialog box that will allow the user to set any specific configuration data required by the plug-in. If the plug-in requires user-definable preferences, you should implement your user interface here. The Configure button will only be enabled if the sixth character of the option string is set to “Y.” For more information, see “Option string syntax” on page 38.
FileMaker Pro Advanced Development 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 Pro Advanced Development Guide Application and document preferences In the runtime application, some options are not available on the General tab of the Preferences dialog box. The File Options dialog box in the runtime application displays only the Spelling tab. File Options dialog box in FileMaker Pro General preferences in a runtime application (Mac OS X) The Layout tab is changed to the Color tab in the Preferences dialog box for the runtime application.
Appendix A | Feature comparison of the runtime application with FileMaker Pro Toolbar comparison Windows File Menu command 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. File Options The Help tool on the standard toolbar in the runtime application is dimmed unless a custom Help script has been specified.
FileMaker Pro Advanced Development Guide Windows Windows Edit Menu command Undo/Can’t Undo Redo/Can’t Redo Cut Copy Paste Paste Special Clear Duplicate Select All Find/Replace Spelling Object Export Field Contents Preferences Mac OS X View Menu command 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 1 1 1 1 1 1 1 1 1 1 1 View as List View as Table Toolbars Status Bar Status Area Text Ruler Zoom In Zoom Out 1 Picture Sound File Object Windows View M
Appendix A Windows Format Menu command Font Size Style Align Text Line Spacing Text Color Text | Feature comparison of the runtime application with FileMaker Pro 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 Records Menu command Replace Field Contents Relookup Field Contents Revert Record Requests Menu command (Find mode) Add New Request Duplicate Request Windows Records Menu command New Record Duplicate Record Delete Record Delete All Records Go to R
FileMaker Pro Advanced Development Guide Windows Scripts Menu command ScriptMaker Save Script Save All Scripts Revert Script
