FileMaker Pro 10 Advanced ® Development Guide
© 2007-2009 FileMaker, Inc. All rights reserved. FileMaker, Inc. 5201 Patrick Henry Drive Santa Clara, California 95054 FileMaker, the file folder logo, Bento and the Bento logo are either trademarks or registered trademarks of FileMaker, Inc. in the U.S. and other countries. Mac and the Mac logo are the property of Apple Inc. registered in the US and other countries. All other trademarks are the property of their respective owners. FileMaker documentation is copyrighted.
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 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 compo
FileMaker Pro Advanced Development Guide Chapter 5 Developing third-party FileMaker plug-ins About external functions About the example plug-in Contents of the FMExample folder Contents of the Example folder Contents of the Support folder Installing, enabling, and configuring the example plug-in Description of the FMExample plug-in’s external functions Using the example plug-in Customizing the plug-in example Customizing the example resources Customizing FMPluginExample.cpp Customizing FMPluginPrefs.
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 1 FileMaker Pro Tutorial: contains step-by-step lessons that teach you how to create and use FileMaker Pro databases 1 FileMaker Pro Advanced Database Design Report XML Output Grammar manual: describes the FileMaker Pro Advanced Database Design Report (DDR) XML output grammar for users who want to create tools that analyze or process the structure of databases 1 FileMaker Instant Web Publishing Guide: describes how to make FileMaker Pro and FileMaker Pro Advanc
Chapter 1 | Introducing FileMaker Pro Advanced 7 Your responsibilities as a developer FileMaker has established procedures for repairing files. If a customer complies with these procedures, then FileMaker may supply a repaired file to the customer. 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: 1.
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 databas
FileMaker Pro Advanced Development Guide 10. Do one of the following: 1 If you want to create a copy of your database files with new names, click Create. Note FileMaker Pro Advanced automatically updates internal links to related files and scripts. 1 If you want to further customize your database files or bind the files, under Solution Options, click Specify. 11.
Chapter 2 | Creating database solutions 11 You may need to bind your database files several times before you prepare them for delivery to your users. When you have completed development and the final version is bound and ready to distribute, you should thoroughly test your runtime solution to ensure that it behaves as expected. Note FileMaker Pro and FileMaker Pro Advanced allow you to include as many database tables as you need in a database file.
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 | Creating database solutions 13 Starting runtime database solutions Double-click to start Runtime application icon Solution file icon Important Your users should start your solution by double-clicking the runtime application icon, not the solution file icon. Double-clicking the icons for the solution or auxiliary files might result in errors, depending on whether there are other copies of the runtime application on their hard disk.
FileMaker Pro Advanced Development Guide Windows solution folder Runtime application Bound primary and auxiliary solution files DLLs generated during binding Extensions Mac OS X solution folder Runtime application package Bound primary and auxiliary solution files Extensions Dictionaries Dictionaries language resource folders Example of Windows and Mac OS X solution contents for distribution Important These files and folders must not be renamed.
Chapter 2 | Creating database solutions 15 Using a compression utility program If your runtime database solution is not complex and you have confidence in the technical experience of your end users, you might consider a compression utility program rather than a custom installation program. Sharing solutions over a network Users cannot share your runtime database solution over a network unless they access the files using FileMaker Pro or FileMaker Pro Advanced installed on their machines.
FileMaker Pro Advanced Development Guide 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 appendix A, “Feature comparison of the runtime application with FileMaker Pro.” 1 Verify that all scripts and buttons work as expected. This is especially important if you’re displaying your solution in Kiosk mode. See “Creating Kiosk solutions” on page 17.
Chapter 2 | Creating database solutions 17 To distribute a new or updated auxiliary file: 1. In FileMaker Pro Advanced, create the new auxiliary file or open the original auxiliary file (before it was bound) and make changes as required. 2. If necessary, create an Import script so users can import their existing data into the new file. For more information about importing data into upgraded runtime solutions, see Help. 3.
FileMaker Pro Advanced Development Guide To enable Kiosk mode: 1. Follow the procedures in “Using the Developer Utilities” on page 9. 2. In the Specify Solution Options dialog box, select Enable Kiosk mode for non-admin accounts. 3. Select other options as required click OK. 4. To be able to quickly repeat the process, click Save Settings, and choose a folder and location for your settings file. For information on saving solution settings, see Help. 5. Click Create.
Chapter 3 Customizing database solutions You can use FileMaker Pro Advanced to customize your solutions beyond what is possible with FileMaker Pro. You can: 1 1 1 1 1 copy and paste fields for use within the same file or other database files copy or import existing tables into your database file create custom functions for use anywhere within a file create custom menus create custom layout themes Important You must have full access privileges to customize database solutions.
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 Menu display title 21 Menu bar Menu set (for this file window) Submenu Menu Separator Menu item Custom menu terminology You can customize menus by: 1 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 starting with an empty menu. Use this method to make significant changes to menus, for example, to add menus and change menu item properties.
FileMaker Pro Advanced Development Guide Creating custom menus To create a custom menu: 1. Choose File menu > Manage > Custom Menus > Custom Menus tab. Menus in brackets are locked and not customizable 2. Click Create. 3. In the Create Custom Menu dialog box, do one of the following, then click OK: 1 Click Start with an empty menu. 1 Click Start with a standard FileMaker menu, then select a menu from the list. The Edit Custom Menu dialog box appears. 4.
Chapter 3 | Customizing database solutions 23 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. In the Specify FileMaker Command dialog box, do one of the following, then click OK. 1 Click No command assigned. FileMaker Pro Advanced adds an Untitled menu item to the Menu Item list. You must specify properties for this command (see Stepstep 4). 1 Click Use a FileMaker command, then select a command from the list.
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. 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. 3. Specify which menus to include in the menu set, and click OK.
Chapter 3 | Customizing database solutions Fill color and pattern for header part 25 Text in header part Fill color and pattern for body part Field label Field text Field fill, border and shadow effect Text in footer part Fill color and pattern for footer part Create themes to automatically apply different styles to text and background fills in layout parts, fields, and field labels Note A FileMaker theme is not a stylesheet and does not contain positioning information for objects on a layout.
FileMaker Pro Advanced Development Guide 3. Open the theme file in a text editor. Single-line element Multi-line element Attributes 4. Change the name of a theme by replacing the value of the THEMENAME element with a new name. Important 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. 5.
Chapter 3 | Customizing database solutions 27 Requirements for theme files 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. This FMTHEMES root element can contain one or more FMTHEME elements.
FileMaker Pro Advanced Development Guide
Chapter 4 Debugging and analyzing files The FileMaker Pro Advanced features explained in this chapter are: 1 the Script Debugger for systematic testing and debugging of FileMaker scripts 1 the Disable script step feature for testing portions of a script 1 the Database Design Report feature for publishing comprehensive documentation on database schema and options 1 the Data Viewer for monitoring fields, variables, and calculations Note See Help for detailed, comprehensive information and step-by-step proce
FileMaker Pro Advanced Development Guide You can view sub-scripts when you step through scripts in the Script Debugger. For example, if Script A calls Script B, which then calls Script C, you can view the steps in all three scripts. The Script Debugger recognizes the privileges attached to each script. A script will only appear in the Script Debugger if you have editing privileges for the script and the access privileges for the script are set to to log in and edit script steps in restrictedModifiable.
Chapter 4 | Debugging and analyzing files 31 Using the Data Viewer You can use the Data Viewer to monitor expressions like field values, local and global variables, and calculations. You can monitor these expressions while running scripts or while testing them in the Script Debugger. You can also monitor field values and variables in the database file.
FileMaker Pro Advanced Development Guide 6. Click the Watch tab. Drag an arrow up or down to change the order 7. Choose one of the following: To Do this Add an expression Click Edit an expression Select an expression, then click Duplicate an expression Select one or more expressions, then click . Delete an expression Select one or more expressions, then click . . or double-click the expression. 8.
Chapter 4 | Debugging and analyzing files 33 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.
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 plugins can take advantage of recursion and looping or hook into other programming interfaces.
FileMaker Pro Advanced Development Guide The plug-in example files include all the source code required to compile the plug-in for the Windows and Mac OS X platforms. In addition to the plug-in source code, FileMaker Pro Advanced includes project files for Microsoft Visual Studio 2005 and Apple Xcode 3.0. The example plug-in files are located in the English Extras\Examples\FMExample folder on the FileMaker Pro Advanced CD or electronic download.
Chapter 5 | Developing third-party FileMaker plug-ins File/Folder Description MacExample.plc Contains bundle definition for Mac platform. Resource.h Contains definitions for resource file. 37 Installing, enabling, and configuring the example plug-in External function plug-in files must be installed in the appropriate folder and enabled in FileMaker Pro, FileMaker Pro Advanced, or FileMaker Server before they can be used. Some plug-ins must also be configured by the user.
FileMaker Pro Advanced Development Guide Plug-in description text is defined in a resource string Select a plug-in to enable it To configure a plug-in: 1. Select the plug-in in the Preferences dialog box. 2. Click Configure. The Configure button is only available when the sixth character in the option string of the selected plugin is “Y.” See “Option string syntax” on page 42. 3. Follow instructions in the configuration dialog box to configure the plug-in. 4. Click OK.
Chapter 5 | Developing third-party FileMaker plug-ins 39 Function’s name and parameter Description of external function XMpl_UserFormatNumber (textOrNumber) Returns the parameter as a text string formatted as specified in the configuration dialog box. Use this function to format text or numbers such as telephone numbers, postal codes, and so on. Formatting proceeds from right to left. Each # symbol in the format string is replaced by the next character in the parameter string.
FileMaker Pro Advanced Development Guide 11. 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. 12. Replace the parameter placeholder with the required parameter or parameters for the function. 13. Continue to build the formula then and click OK when you’re done. 14. Click OK to close the Manage Database dialog box.
Chapter 5 | Developing third-party FileMaker plug-ins 41 Customizing FMPluginPrefs.cpp This file contains the Do_PluginPrefs function for the implementation of the configuration dialog box. Revise or remove this code as needed. Customizing FMPluginFunctions.cpp Revise or remove the functions provided in the FMPluginFunctions.cpp file and define your own. Do_PluginInit refers to these functions when evaluating external functions in calculations.
FileMaker Pro Advanced Development Guide Option string syntax The option string must be 11 characters long for plug-ins. The first four characters of the option string are the ID of the plug-in. The ID must be unique for each plugin and must not begin with “F,” “FM,” or “Web.” For the Mac OS X, it is recommended that you set the creator type of the plug-in to this same value. The ID can only contain low-ASCII alphanumeric characters (such as 0-9, A-Z, and a-z).
Chapter 5 1 1 1 1 | Developing third-party FileMaker plug-ins 43 kFMXT_Shutdown — the Shutdown message kFMXT_Idle — the Idle message kFMXT_DoAppPreferences — the Preferences message kFMXT_External — the External Function message received by legacy plug-ins that set character 7 in the options string to “Y” and that register their functions the old external way 1 kFMXT_GetString — the GetString message received by plug-ins that use the new style of registration when the plug-ins provide the option strin
FileMaker Pro Advanced Development Guide Idle message The Idle message, kFMXT_Idle, is only sent to the plug-in during idle time if the idle feature flag was set to “Y” in the option string and the plug-in is currently enabled. There are five times when this message is called by the FileMaker application. If the idleLevel parameter is not zero, then the routine has been called while the application is running a script or is being controlled by the user.
Chapter 5 | Developing third-party FileMaker plug-ins 45 GetString message The GetString message, kFMXT_GetString, is sent to the plug-in when FileMaker Pro, FileMaker Pro Advanced, 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.
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. 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. General preferences in a runtime application (Windows) The File Options dialog box in the runtime application displays only the Spelling tab.
Appendix A | Feature comparison of the runtime application with FileMaker Pro 49 Menu command comparison The following tables show the menu commands that are available in FileMaker Pro (Pro) and in the runtime application (RT).
FileMaker Pro Advanced Development Guide Windows Edit Menu command Mac OS X Pro RT Pro RT Undo/Can’t Undo 1 1 1 1 Redo/Can’t Redo 1 1 1 1 Cut 1 1 1 1 Copy 1 1 1 1 Paste 1 1 1 1 Paste Special 1 1 Clear 1 1 1 1 Duplicate 1 Select All 1 1 1 1 Find/Replace 1 1 1 1 Spelling 1 1 1 1 Object 1 1 Export Field Contents 1 1 1 1 Preferences 1 1 1 Windows View Menu command Mac OS X Pro RT Pro RT Browse Mode 1 1 1 1 Find Mode 1 1 1 1
Appendix A | Feature comparison of the runtime application with FileMaker Pro Windows Insert Menu command Mac OS X Pro RT Pro RT Picture 1 1 1 1 QuickTime 1 1 1 1 Sound 1 1 1 1 File 1 1 1 1 Object 1 1 Current Date 1 1 1 1 Current Time 1 1 1 1 Current User Name 1 1 1 1 From Index 1 1 1 1 From Last Visited Record 1 1 1 1 Windows Format Menu command Mac OS X Pro RT Pro RT Font 1 1 1 1 Size 1 1 1 1 Style 1 1 1 1 Align Text 1 1 1 1
FileMaker Pro Advanced Development Guide Windows Records Menu command Mac OS X Pro RT Pro RT Modify Last Find 1 1 1 1 Saved Finds 1 1 1 1 Sort Records 1 1 1 1 Unsort 1 1 1 1 Replace Field Contents 1 1 1 1 Relookup Field Contents 1 1 1 1 Revert Record 1 1 1 1 Requests Menu command (Find mode) Windows Mac OS X Pro RT Pro RT Add New Request 1 1 1 1 Duplicate Request 1 1 1 1 Delete Request 1 1 1 1 Go to Request 1 1 1 1 Show All Records 1
Appendix A | Feature comparison of the runtime application with FileMaker Pro Windows Window Menu command Mac OS X Pro RT Pro RT New Window 1 1 1 1 Show Window 1 1 1 1 Hide Window 1 1 1 1 Minimize Window 1 1 1 1 Tile Horizontally 1 1 1 1 Tile Vertically 1 1 1 1 Cascade Windows 1 1 1 1 Arrange Icons 1 1 1 1 1 1 Bring All To Front 1 1 Windows Help Menu command Pro Mac OS X RT Pro FileMaker Pro Help 1 1 Keyboard Shortcuts 1 1
FileMaker Pro Advanced Development Guide Application Menu command (Mac OS X only) About FileMaker Pro Pro RT 1 About FileMaker Pro Runtime (Displays if no custom About script is specified) 1 About (Displays if custom About script is specified) 1 Preferences 1 1 Services 1 1 Hide FileMaker Pro 1 1 Hide Hide Others 1 1 Show All 1 1 Quit FileMaker Pro 1 Quit 1 Ignored script steps Because some features have been removed fro
Appendix A | Feature comparison of the runtime application with FileMaker Pro 55 Stored registry settings or preferences Windows registry settings FileMaker Pro stores its registry settings at HKEY_CURRENT_USER\Software\FileMaker\FileMaker Pro\.0 FileMaker Pro Advanced stores its registry settings at HKEY_CURRENT_USER\Software\FileMaker\FileMaker Pro\.0A The runtime application stores its registry settings at HKEY_CURRENT_USER\Software\FileMaker\\.
FileMaker Pro Advanced Development Guide
Index A About layout 6 required contents of 7 access keys, custom menus 23 access privileges 7, 19 accounts and privileges 7, 19 for Kiosk mode 17 removing Admin access 10 Admin access removing from files 10 removing from Kiosk solutions 18 Apple events in runtime applications 47 Apple Xcode 36 ASCII characters in plug-in IDs 42 attributes in layout themes 24 authenticating scripts 30 auxiliary files problems with double-clicking icons 13 updating 17 B backups 16 binding key about 12 updating runtime datab
FileMaker Pro Advanced Development Guide extensions, filename.
| Index M P Mac OS X resource conflicts 45 runtime application package 14 stored preferences 55 MacInstallerBuilder 14 Manage Scripts 30 Manage submenu unavailable in runtime applications 47 menu commands available in runtime applications 49 menu separators 23 menu sets, creating 24 messages error log 10 sent to external function plug-ins 42 Microsoft Visual Studio 36 Microsoft Windows stored registry settings 55 MindVision Installer VISE 14 multiple tables per database file 11 passwords, required warn
FileMaker Pro Advanced Development Guide recovering damaged files 15 starting 13 updating 16 upgrading 11 runtime database solutions, documenting 14 S Save Records as PDF script step 54 schemas, database copying or importing 19 documenting 33 Script Debugger 29 with script triggers 30 script triggers, debugging 30 scripts authenticating 30 debugging 29 disabling script steps 30 steps ignored by runtime applications 54 unlocking 30 Scripts menu commands available in runtime applications 52 separators,
