For Windows and Mac FileMaker Developer 6 ® Developer’s Guide © 1998, 2000-2002 FileMaker, Inc. All Rights Reserved. FileMaker, Inc. 5201 Patrick Henry Drive Santa Clara, California 95054 www.filemaker.com FileMaker documentation is copyrighted. You are not authorized to make additional copies or distribute this documentation without written permission from FileMaker. You may use this documentation solely with a valid licensed copy of FileMaker software. FileMaker is a trademark of FileMaker, Inc.
THIS PAGE INTENTIONALLY LEFT BLANK
Contents Chapter 1 Welcome to FileMaker Developer About the Developer edition of FileMaker Pro About this guide Registration and customer support About the installation code Hardware and software requirements Networking requirements Web publishing requirements Requirements for advanced features (Windows) Requirements for advanced features (Mac OS) Features not supported In Mac OS X Opening files from previous versions Updating your User Dictionary Read Me file Electronic documentation Abiding by the license
iv Developer’s Guide Protecting your database solution files Providing user documentation Creating an About layout Creating a custom Help layout or file Providing What’s This? Help (Windows) Including printed documentation Design tips for cross-platform solutions Creating a consistent appearance Simulating outline and shadow text styles Using common character sets Designing text layouts for cross-platform solutions Using a common color palette Using graphics in cross-platform solutions Using QuickTime mov
Contents Chapter 7 Distributing FileMaker Pro runtime database solutions Organizing your runtime database solution components Generated DLL files for Windows runtime database solutions System files for Windows solutions Solution Extras files for Mac OS solutions FileMaker Extensions files for Mac OS solutions Choosing the distribution method Requirements for distributing on floppy disks Using a custom installation program Using a compression utility program What your users need Sharing your solution over a
vi Developer’s Guide Using the CDML Tool and templates Using the Templates tab Using the Tags tab Customizing a format file template Categories of CDML tags Using an intratag parameter About the CDML Reference database Creating error messages Using an encoding parameter with a CDML replacement tag Planning your web site Looking at the three CDML examples Employee Database example Guest Book example Shopping Cart example 9-5 9-6 9-6 9-6 9-8 9-9 9-9 9-11 9-12 9-12 9-13 9-14 9-14 9-15 Chapter 10 Using File
Contents Example 1: Looking at the FileMaker Pro Explorer application 11-8 Setup requirements 11-9 Install the example and the FileMaker JDBC Driver 11-9 Open and share your databases via the Web 11-9 Run the FileMaker Pro Explorer application 11-9 View the source code of the example 11-10 Example 2: Creating the JBuilder Inventory application 11-11 Install the example and FileMaker JDBC Driver 11-11 Set up JBuilder to use the FileMaker JDBC Driver 11-11 Open and share the Inventory.
viii Developer’s Guide Appendix B Valid names used in CGI requests for FileMaker Pro XML data Generating a –find, –findall, or –findany request Examples of –find, –findall, and –findany requests Generating a –view request Examples of –view requests Generating a –new request Examples of –new requests Generating an –edit request Examples of –edit requests Generating a –delete request Examples of –delete requests Generating a –dbnames request Examples of –dbnames requests Generating a –layoutnames request Ex
Chapter 1 Welcome to FileMaker Developer Welcome to FileMaker® Developer 6. FileMaker Developer 6 consists of the Developer edition of FileMaker Pro, and the FileMaker Developer Tool application. You use FileMaker Pro to create and test your database solutions. You use FileMaker Developer Tool to transform your database solution into a runtime or kiosk-mode application that you can distribute to your users. Thoughout this Guide, references to FileMaker Pro include the Developer edition of FileMaker Pro.
1-2 Developer’s Guide Or choose Help menu > FileMaker on the Web. At the web site, you will find the FileMaker Service Directory, which details the service options available to North American customers, as well as links to FileMaker international sites, answers to frequently asked questions, and access to the TechInfo knowledgebase used by Technical Support. If you do not have access to the Web, please refer to the FileMaker Service Directory included in the software box.
Welcome to FileMaker Developer Some FileMaker Pro features are unique to or work differently on certain operating systems. This manual and online Help use the label “Mac OS 9.x or earlier” to indicate when a described feature is specific to Mac OS 8.6 through 9.2.2. However, keep in mind that Mac OS 8.6 is the earliest Mac OS version that FileMaker Pro supports.
1-4 Developer’s Guide FileMaker Pro advanced feature URL support and the Speak script step Software requirement In Mac OS 9.x or earlier, the Internet control panel and the Speech Manager extension are usually available as part of a normal system software installation. Make sure they’re turned on in the Extensions Manager control panel.
Welcome to FileMaker Developer 1-5 • If you add or remove the .FP5 filename extension as part of the Updating your User Dictionary conversion process, you must re-specify file locations for related or external files when the database is first opened. If you added words to a User Dictionary in a previous version of FileMaker Pro, you may want to use it with FileMaker Pro 6. For more information about converting a User Dictionary, see FileMaker Pro Help after you have installed FileMaker Developer 6.
1-6 Developer’s Guide Abiding by the license agreement The FileMaker Developer license agreement allows you royalty-free distribution of an unlimited number of FileMaker Pro runtime database solutions. However, there are several terms and conditions in the license agreement you must abide by, including the following: • You must provide all of the end-user technical support. • You must provide an “About” layout that includes your name, address, and the telephone number for your technical support.
Chapter 2 Installing FileMaker Developer in Windows Before you begin the installation process, exit other open programs and save your work. For late-breaking information about FileMaker Developer, browse the contents of the CD and view the Read Me file or visit www.filemaker.com. • During installation, you can choose whether to install all program features (Complete), or to install only selected portions of the program (Custom).
2-2 Developer’s Guide 3. In the command window, type E:\Files\setup.exe /v“/Lr C:\FMP6InstallLog.txt” 4. Follow the on-screen instructions. The FMP6InstallLog.txt file will be located on the C drive of your hard disk. You can view it with Notepad, Wordpad, or a word processing program. Note If your CD or DVD drive is not located at drive E, then substitute the correct letter for your drive. Where files are stored on your hard disk The FileMaker Developer InstallShield Wizard appears. 3.
Installing FileMaker Developer in Windows Adjusting network software Depending on the networking protocol you’re using, you may have to modify settings on the host and/or guest computers. Changing the network protocol During installation, you select a network protocol (or none) for FileMaker Pro. You must choose a network protocol if you want to share FileMaker Pro databases over a network, either as a guest or as a host.
2-4 Developer’s Guide • Windows XP: the Network Connections control panel • Windows 2000 Professional: the Network and Dial-up Connections control panel 2. Right-click on the network connection you are using. 3. Select Properties from the menu. 4. Select the IPX/SPX protocol from the list and click Properties. For more information on managing memory, see the documentation that came with your computer. To change the cache size that FileMaker Pro uses: 1.
Chapter 3 Installing FileMaker Developer in the Mac OS Before you begin the installation process, quit other open programs and save your work. For late-breaking information about FileMaker Developer, browse the contents of the CD and view the Read Me file or visit www.filemaker.com. Installation notes Before you install FileMaker Developer, review the following notes: • The FileMaker Developer CD contains two installer programs, one for Mac OS 9.x or earlier, and one for Mac OS X.
3-2 Developer’s Guide Choose Easy Install or Custom Install A final dialog box tells you the installation on your hard disk was successful. 9. Click Quit to leave the Installer. Installing ODBC drivers in Mac OS X Displays where FileMaker Developer will be installed In Mac OS X, you must manually install the ODBC drivers after the FileMaker Developer installation is complete. 1. Navigate to the folder Applications\FileMaker Developer 6\FileMaker ODBC Drivers. 4.
Installing FileMaker Developer in the Mac OS • Template and tutorial files: If a non-administrator user needs to access these files, perform a Custom Install and install these files into the user’s Applications folder. • Web Security folder and Web folder: Set file permissions so that all valid users have Read & Write access to the Web Security databases and Read only access to the Web folder. For more information on setting file permissions, see the Mac OS X topic “Setting Access Priviledges.
3-4 Developer’s Guide To change the amount of memory FileMaker Pro uses: 1. If FileMaker Pro is open, quit the application by choosing File menu > Quit. 2. In the Finder software, open the FileMaker Developer 6 folder. Select the FileMaker Developer application icon by clicking it once. Note If you click the application icon twice, you will start the Developer edition of FileMaker Pro. If that happens, choose File menu > Quit and try again. 3. Choose File menu > Get Info > Memory. 3.
Installing FileMaker Developer in the Mac OS Enabling the FileMaker Pro Web Companion (Mac OS X) Note For instructions on enabling the FileMaker Pro Web 3-5 The first time you enable the Web Companion, FileMaker Pro displays the following dialog, which requests permission to make a one-time change to your computer’s setting to facilitate web publishing on a port number below 1024. Companion in Mac OS 9.x or earlier, see chapter 14 of the FileMaker Pro User’s Guide.
3-6 Developer’s Guide 5. Do one of the following three options: 8. Click OK again to close the Application Preferences dialog. To To use a port number other than 80, open the Application Preferences dialog again (choose the FileMaker Developer application menu > Preferences > Application), click the Plug-Ins tab, select the Web Companion plug-in, and click Configure.
Installing FileMaker Developer in the Mac OS 3-7 Accessing databases that are published to the Web When you publish a database to the Web, your users access that database by entering the host machine’s URL in their web browser. If the FileMaker Pro Web Companion is configured to use port number 80, the default port, the URL your users will enter will look like this: http://12.34.56.78/ The number “12.34.56.78” is an example; in its place, your users would enter the actual URL of your host machine. 5.
THIS PAGE INTENTIONALLY LEFT BLANK
Chapter 4 Creating a database solution You use FileMaker Pro to design and build your database solution, and FileMaker Developer Tool to bind the Kiosk-mode or customized stand-alone runtime application. Note The Developer edition of FileMaker Pro includes Database Design Report and Debug Script menu commands to assist you in designing your database solution.
4-2 Developer’s Guide Overview of preparing your solution files As you design, build, and test your database solution, keep in mind how your users will interact with it. This includes navigational scripts and buttons, effective use of layouts and themes, and Help for the user. 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 chapter 5, “Creating custom layout themes” for information.). 2.
Creating a database solution The \Developer Extras\FileMaker, Inc\Examples\Creating Dynamic Buttons\ folder on the FileMaker Developer CD contains information about buttons you can use to make opening and closing files easier for users. See “Creating dynamic buttons” on page 4-6 for information. • Will the runtime application operate in Kiosk mode? If your runtime database solution will display in Kiosk mode, the entire interface must be accessible via buttons on the layouts.
4-4 Developer’s Guide Navigating in Kiosk mode The primary file is the main database that users see first in your Kiosk solution. Because Kiosk mode does not contain any menus or window controls, the primary file must contain buttons that users can click to navigate through the solution, close the files, and to quit FileMaker Pro or the runtime application. To decide how users will navigate your Kiosk database solution, start by planning your navigation design on paper.
Creating a database solution 4-5 To create a startup script: 1. In FileMaker Pro, open the file that will contain the script, such as the primary file. 2. Choose Scripts menu > ScriptMaker and create a script to perform the desired actions. 3. Choose Edit menu > Preferences > Document.. Mac OS X: choose FileMaker Developer application menu > Preferences > Document. The Kiosk Solution Example contains buttons for navigating between screens, adding and deleting records, and quitting the database 4.
4-6 Developer’s Guide Centering a database window in the Kiosk screen To center your databases in the middle of a Kiosk screen, create a startup script that uses the Toggle Window and Set Zoom Level script steps. When a file is opened in Kiosk mode, two things will happen: • The database window snaps to fit layout objects at the right and bottom edges of the layout. • If the window is smaller than the available screen area, it is centered in the middle of the screen.
Creating a database solution Protecting your database solution files If passwords have not been defined, your solution files can be opened in FileMaker Pro, and users can access and modify scripts, field and relationship definitions, access privileges, and layouts. You may want to set a master password that gives you access to the entire file and another password that gives users limited access.
4-8 Developer’s Guide Providing user documentation There are several ways that you can provide documentation for your database solution, including printed manuals, an online Help system, and an About layout screen that is available from any layout in the solution. Create custom About and Help screens that document what your database solution is, how to use it, and where users can go for more information. Then use the Developer Tool to attach scripts to menu commands that open the About and Help screens.
Creating a database solution 4-9 2. Include your logo, any other graphics, and your company information. 2. Select Switch to layout, and choose the About layout from the popup menu. 3. Notify users if the solution files are protected with passwords or if database design access has been removed. Creating a custom Help layout or file primary file. (To create the button, use the button tool or a button image with a script attached to it.
4-10 Developer’s Guide 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. See the paragraph below,“Including printed documentation,”and “Documenting the installation procedures” on page 7-5, for information.
Creating a database solution • How to use your Help system • How to use What’s This? Help (Windows) • How to start the database solution (see “Starting your runtime database solution” on page 7-5) • What to do in case of a damaged file (see “Recovering damaged files” on page 7-6) • How to reach you for technical support 4-11 Creating a consistent appearance To ensure a consistent look for files across platforms, try to use the same font technology, for example TrueType.
4-12 Developer’s Guide To simulate a shadow effect for text: Mac OS-only characters: 1. Add text to your layout. • ≠ (not equal) • ≥ (greater than or equal to) • ≤ (less than or equal to) • √ (square root/check mark) 2. Set its text color to a shade of gray. (Choose Format menu > Text Color and choose gray from the color palette.) 3. Duplicate the text object. (Select the text object and choose Edit menu > Duplicate.) 4. Set the text color of the duplicate to black. 5.
Creating a database solution If you put a left-aligned label over a column of right-aligned numbers, for example, the report might look fine on your computer. But font substitution could cause field labels to shift when the file is opened on another computer. If a wider font is substituted on the second computer, your column heading will shift to the right. If a more narrow font is used, the text will display too far to the left.
4-14 Developer’s Guide 5. Select Make playable on non Apple computers. The first time you play a movie from another platform, FileMaker Pro prompts you for the location of the movie. Keep the files in a common folder and avoid choosing the wrong file—this could lead to unexpected results. Showing the status bar in Windows FileMaker Pro for Windows includes an option to show the status bar, which allows users to specify whether status bar information at the bottom of a window is visible or not.
Creating a database solution Creating platform-specific scripts Although most ScriptMaker steps work on both platforms, some script steps rely upon platform-specific features. The following steps are platform-specific: Windows-only script steps • DDE Execute • Send Message • Insert Object • Update Link Mac OS-only script steps • Send Apple Event • Perform AppleScript • Speak The Windows Print Setup script step is translated to the Mac OS Page Setup script step, and vice versa.
4-16 Developer’s Guide The password protection in a FileMaker file should not be viewed as an absolute barrier that will prevent a customer from accessing files. FileMaker, Inc. cannot guarantee that a customer will not be able to identify or bypass the password without any assistance from FileMaker, Inc. Therefore, FileMaker Inc. recommends that you take appropriate steps to protect your consulting and development efforts without relying solely upon the password.
Creating a database solution 4-17 In general, to upgrade your solution, you need to do the following: To prepare your upgraded solution for importing data: 1. Open the original solution database files in the current version of FileMaker Pro. 1. Open the original solution database files in the current version of FileMaker Pro. The original solution files will be renamed “ Old” and the converted files will keep the original name.
4-18 Developer’s Guide When users execute the Import script, the runtime application finds the original solution file, converts it, then imports the records into the new solution file. During the script, the runtime application temporarily converts a copy of the old file to the FileMaker Pro runtime version, and deletes it when the original file is closed. Your users should delete the original solution files after making a backup copy of the new solution files.
Chapter 5 Creating custom layout themes FileMaker Pro uses a variety of layout themes to describe the colors, patterns, fonts, and borders of text, fields, and parts in a new layout. A FileMaker Pro theme is defined in an Extensible Markup Language (XML) document that can be read and edited in text editors (such as Wordpad for Windows or BBEdit for Mac OS) or XML editors (such as XML SPY or XML Pad).
5-2 Developer’s Guide 2. Rename the copy and include the .fth extension with the new filename. Keep the new file in the Themes folder. See the table in “Valid values for theme attributes” on page 5-7 and “Finding values for patterns and colors” on page 5-9 for guidelines. In order for the New Layout/Report assistant in FileMaker Pro to display a theme option, the theme file must reside in the Themes folder and it must have the .fth filename extension. 6.
Creating custom layout themes Basic requirements for a theme file FileMaker Pro layout themes are described in an XML document saved in text file format. Each text file must have the .fth filename extension and reside in the Themes folder inside the FileMaker Developer application folder so FileMaker Pro can display the themes in the New Layout/Report assistant. XML resembles HTML in many ways—however, unlike HTML the XML for layout themes must be well-formed and comply with the required syntax.
5-4 Developer’s Guide Removing elements from a theme file The FileMaker Pro layout theme files contain multi-line elements for fields, field labels, text, and every part in a layout. Each of these elements contains other multi-line elements and single-line elements. You can remove any of these elements, but you must remove the entire element—that is, everything inside the element’s start and end tags and the start and end tags as well.
Creating custom layout themes This multi-lined element is used To describe this layout part Trailing grand summary — appears at the end of a report and displays a summary field for all the records in a found set. (A layout can have only one trailing grand summary part.) Footer — appears at the bottom of every screen or page (except the first one if there’s a title footer).
5-6 Developer’s Guide These multi-line elements May contain these elements FIELD BASELINE (text/data in a field) BORDER CHARSTYLE EFFECT FILL Table of single-line elements The following table describes the correct syntax for all single-line elements and their attributes. Examples of attribute values are indicated in boldface. For a list of the possible values you can use for these attributes, see the next section, “Valid values for theme attributes.
Creating custom layout themes These single-line elements Must contain these attributes THEMENAME HINT (optional) VALUE Syntax examples:
5-8 Developer’s Guide This attribute FONT Is used to describe these characteristics And may contain these values 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.
Creating custom layout themes This attribute SIZE (for the PEN element) Is used to describe these characteristics And may contain these values Thickness in pixels for the outline of text blocks, field labels, and field borders. SIZE = “0” SIZE = “-1” SIZE = “1” through The value for NONE is “0” SIZE = “8” and the value for HAIRLINE SIZE = “12” is “-1.
5-10 Developer’s Guide 1 2 3 4 5 6 7 8 Select a color Then choose Other Color 2. Select the HTML Picker icon on the left side of the dialog box and read the hex value for the selected color in the HTML box on the right side.
Creating custom layout themes Checking your theme document for errors FileMaker Pro cannot parse an XML theme document that is not well-formed, and it does not validate the XML in your documents. If one required item is missing or wrong, FileMaker Pro will ignore the entire document. Here is a list of things to check for if your new layout themes don’t appear in the New Layout/Report assistant as expected: • The theme filename has the .fth extension. • The theme file is in text format.
THIS PAGE INTENTIONALLY LEFT BLANK
Chapter 6 Using the FileMaker Developer Tool FileMaker Developer provides a utility application called the FileMaker Developer Tool that lets you: • bind your database files into a stand-alone runtime database solution that does not require FileMaker Pro in order to be used on a computer • rename all of your database files and automatically update the internal links to related files and scripts These example solutions are on the FileMaker Developer CD in the \Developer Extras\FileMaker, Inc\Examples fold
6-2 Developer’s Guide To use the FileMaker Developer Tool: 1. Close all of your database files that you are going to customize. 2. If necessary, install the FileMaker Developer Tool. (See chapter 2, “Installing FileMaker Developer in Windows,” or chapter 3, “Installing FileMaker Developer in the Mac OS.”) 3. Double-click the Tool application. file icon to start the FileMaker Developer What you select determines which screen the Developer Tool displays next.
Using the FileMaker Developer Tool Select this option To create a copy of your database files and do this Add or remove FileMaker Pro extension Add or remove the .fp5 filename extension to associate files with the FileMaker Pro application. The .fp5 extension is useful for database solutions that will be used on Windows machines, and is not necessary for solutions that will only be used on Mac OS machines. 6-3 Note You do not have to type in a filename extension. However, if you want the .
6-4 Developer’s Guide The primary file stores the custom settings and is the database that users should open first. If you’re binding your files into a runtime database solution, the runtime application will open the primary file first. Use this file for navigation buttons or scripts to other auxiliary files, an About layout, a custom Help layout or file, and to quit the application. 11. If desired, select Use custom About script, and choose the script name from the pop-up menu.
Using the FileMaker Developer Tool 6-5 Select Filename Extension screen on Windows machines 21. On the Specify Location for Solution Folder screen, click Browse (Windows) or Select (Mac OS) to specify the location for the runtime database solution. The name of the new solution folder is determined by either the name of the primary file or the name of the runtime solution. 22. Select the location and click OK (Windows) or click Choose (Mac OS). 23. Click Finish.
6-6 Developer’s Guide If an error occurs during the binding, a message displays and the error is logged in the Error Log.txt file: Folder Platform FileMaker Developer 6\Developer Tool Windows FileMaker Developer 6\FileMaker Developer Tool Mac OS FileMaker Developer 6\FileMaker Developer Tool Mac OS X Note Windows 2000 and Windows NT users with limited access privileges may not be able to write to the error log file in the Developer Tool folder.
Using the FileMaker Developer Tool 4. Specify the database files that you want to bind, rename them if desired, and click Next to go to the next screen in the runtime binding process. 5. Select a primary file. All of the settings for binding are stored in the primary file. The primary file opens automatically when a user double-clicks the runtime application. 6. Select Use custom About script and choose the script’s name from the pop-up menu.
6-8 Developer’s Guide Assigning a three-character filename extension The three-character filename extension associates all of the solution files with the FileMaker Pro runtime application. If a user has more than one runtime database solution on a machine, the filename extension together with the binding key will ensure that the correct runtime application is started when a solution file is double-clicked.
Using the FileMaker Developer Tool Note No matter what the filename extensions are, runtime database files can still be opened in the FileMaker Pro application. To prevent users from modifying your runtime database solutions, create passwords for specific access privileges or select the Permanently prevent modification of database structure option in the Developer Tool before you bind the files into a runtime database solution.
6-10 Developer’s Guide 5. Specify the database files that you want to customize, rename them if desired, and click Next. 6. Select a primary file, select other options as desired, and click Next to go through the rest of the screens depending on what other options you selected. 7. Specify the location for the solution files, rename the folder if desired, and click Finish. The Developer Tool creates a duplicate copy of the database files with a new Kiosk-mode interface and places them in a new folder.
Using the FileMaker Developer Tool Removing design access to your databases Use the FileMaker Developer Tool to prevent users from altering the design and structure of your database files and from changing any passwords or groups that you’ve set up.
6-12 Developer’s Guide Custom About command in a runtime application (Windows) Custom About command in FileMaker Pro (Windows) Custom About command in FileMaker Pro (Mac OS) Custom About command in a runtime application (Mac OS) In runtime applications, the custom About menu command replaces the About FileMaker Pro menu command.
Using the FileMaker Developer Tool 6-13 Custom Help command in a runtime application (Windows) Custom Help command in FileMaker Pro (Windows) The About layout in the 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: 1. Close all of your database files that you are going to change. 2. Start the FileMaker Developer Tool application and click Next.
6-14 Developer’s Guide Renaming the Scripts menu Use the Developer Tool 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 Pro and in a runtime application. Database solution with Scripts menu Adding the FileMaker Pro extension to database filenames Use the FileMaker Developer Tool to quickly add the FileMaker Pro filename extension to your database files.
Using the FileMaker Developer Tool Note Windows 2000 and Windows NT users with limited access privileges may not be able to write to the Solution Options file in the Developer Tool folder. Log in with administrator privileges or install the FileMaker Developer Tool to a location outside of the Program Files folder. 6-15 To modify the text file for auto-customizing: 1. Open the Solution Options file in a text editor.
THIS PAGE INTENTIONALLY LEFT BLANK
Chapter 7 Distributing FileMaker Pro runtime database solutions The final steps in developing your FileMaker Pro 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 disc, over a network, or on floppy disks—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.
7-2 Developer’s Guide Generated DLL files for Windows runtime database solutions The following table describes the Dynamic Link Libraries (DLLs) that are provided for your runtime database solutions running on Windows machines. These files are generated by the Developer Tool during the binding process and must reside in the root level of the solution folder along with the runtime application and bound database files. Required DLL files Description Fmeng10.
Distributing FileMaker Pro runtime database solutions System folder and files Description Excel.imp Used to import Excel files XML.imp Used to import XML files Claddon.clr Spelling dictionary that contains computer terminology Ukenglsh.mpr Primary British English dictionary of over 100,000 words that the runtime application uses to check the spelling Usenglsh.mpr User.upr Tip You can add other folders and files to the Solution Extras\Extensions folder and they will be copied to the appropriat
7-4 Developer’s Guide FileMaker Extensions folder and files Description Ukenglsh.mpr Primary British English dictionary of over 100,000 words that the runtime application uses to check the spelling User.upr Spelling dictionary that stores your customized list of spelling exceptions and additions to the User dictionary Usenglsh.
Distributing FileMaker Pro runtime database solutions Sharing your solution over a network Because the runtime application does not support FileMaker Pro file sharing (peer-to-peer or client/server networking), users cannot share your runtime database solution over a network unless they access the files using the FileMaker Pro application on their machines. For optimal performance, they can host the solution files using FileMaker Server.
7-6 Developer’s Guide Recovering damaged files During the recovery process, the FileMaker Pro runtime application: Power failures, hardware problems, or other factors can damage a FileMaker Pro file. If your database solution becomes damaged, your users need to recover the damaged file. When the runtime application discovers a damaged file, a dialog box appears, telling the user to contact the developer.
Distributing FileMaker Pro runtime database solutions If you forget the original binding key for your runtime database solution and want to update or add a file, you’ll need to rebind all of the database files with a new binding key and redistribute the entire solution. To distribute an updated primary file: 1. Open the original primary file (before it was bound) in FileMaker Pro. 2. Make the changes to the primary file.
THIS PAGE INTENTIONALLY LEFT BLANK
Chapter 8 Publishing your database on the Web The FileMaker Pro Web Companion plug-in makes it possible for you to publish your database on the Internet or an intranet in several different ways, giving you more choices and control over the design and functionality of your web pages.
8-2 Developer’s Guide For a list of JDBC resources, see the product support pages on the FileMaker, Inc. web site at www.filemaker.com. As a shortcut, in FileMaker Pro, choose Help menu > FileMaker on the Web. Custom web publishing with CDML The FileMaker Pro Web Companion lets you publish your database with custom web pages using a proprietary markup language called CDML. Included with FileMaker Pro are all the tools, templates, and examples you need to create your own custom web pages using CDML.
Publishing your database on the Web There are two folders that can be used to store files to be served to the Web; the Web folder, and the cdml_format_files folder, both located at the root level of the FileMaker Pro folder. Your custom web pages, CDML format files, and XSLT style sheets can be stored in the Web folder in order for the Web Companion to serve them on the Web.
8-4 Developer’s Guide 2. In the Web Companion Configuration dialog box, choose an HTML file from the Home Page list so the Web Companion will automatically display it when web users enter the IP address. The [Built-in] option displays the “FileMaker Pro Instant Web Publishing” home page by default. All other HTML files that are located in the root level of the Web folder appear in this list. See “Creating a custom home page” on page 8-5 for more information. 3.
Publishing your database on the Web 8-5 Sharing the database via the Web Each database that you’re publishing on the Web must be open and shared via the Web Companion. To share a database on the Web: 1. In FileMaker Pro, choose File menu > Open and open the database. 2. Choose File menu > Sharing. 3. Select the Web Companion checkbox. For Instant Web Publishing, choose a web style and layouts for each view (instant web page) 5. Click Done to close the Web Companion View Setup dialog box. 6.
8-6 Developer’s Guide If you’re hosting multiple sites each with its own home page, you can have each home page named “default.htm” or “index.htm” inside each site folder within the Web folder, and the Web Companion will display them when web users enter the name of the site folder after the IP address. http://17.17.17.17/guest_book If you want, create a link to the IP address of the site folder— otherwise, let users know so they can type it in their web browsers.
Publishing your database on the Web About the FileMaker WebPortal object With the Web Companion in FileMaker Pro, you can access the elements of the Instant Web Publishing home page (such as database names or the URL to access a Form View of a database) as separate JavaScript objects and extract data from them to build your own custom home page.
8-8 Developer’s Guide First, you create a startup script to hide the Instant Web Publishing interface. Then you create buttons in the layouts to navigate the web site and perform database functions. To bypass the Instant Web Publishing home page, you use a custom home page that contains a redirect statement for opening the database layout in a particular instant web page.
Publishing your database on the Web Note For information about FileMaker CGI requests made in custom web publishing, see “Generating FileMaker Pro CGI requests using CDML” on page 9-3 and “Generating FileMaker Pro CGI requests for an XML document” on page 10-8. FileMaker script step CGI request Open URL [] Set window location Use this with a text field to the specified URL or calculation field with a text result to construct target URLs.
8-10 Developer’s Guide FileMaker script step CGI request Description FileMaker script step CGI request Description Go to Record/Request/Page Go to last record [Last] Also supported in a multistep button. Exit Record Submit form Go to Record/Request/Page Go to previous [Previous] record Also supported in a multistep button. This submits -edit record, -new record, and -find requests. Go to Record/Request/Page Go to next record [Next] Also supported in a multistep button.
Publishing your database on the Web Support for scripts with multiple script steps The Web Companion supports 1 to 3 script steps in a script button used for Instant Web Publishing. (Any steps after 3 valid script steps are ignored.) The script must include a change of mode, layout, or current record. The script may also include the submission of a form containing either a -find request or an edited record.
8-12 Developer’s Guide You only need the Toggle Status Area [Hide] script step in your startup script to hide the Instant Web Publishing interface.
Publishing your database on the Web Note In the Internet Explorer 4.5 for Mac OS browser window, you must allocate at least 6 MB of memory to the web browser in order to display the database layout. Here’s another example of a redirect statement that displays the database layout in the browser window.
8-14 Developer’s Guide Monitoring your site The FileMaker Pro Web Companion generates three types of log files that you can use for gathering information about web users who visit your site: • access.log • error.log • info.log For information on enabling log files, see “Setting Web Companion configuration options” on page 8-3. When you enable the Access Log File option in the Web Companion Configuration dialog box, the Web Companion generates an access.
Publishing your database on the Web 8-15 Using the info.log file The info.log file, stored in the root level of the folder for the database, contains entries generated by the [FMP-Log] CDML replacement tag. Whenever web users access FileMaker Pro from your custom CDML web page, information you’ve included within a [FMP-Log] tag is recorded by the Web Companion in the info.log file. For information about the CDML replacement tags, see chapter 9, “Custom web publishing using CDML.” 6.
8-16 Developer’s Guide 9. Click Done to close the Define Fields dialog box. Exporting data to a static HTML page External function’s name and parameter Web-Version, 0 Returns the version of FileMaker Pro Web Companion that loads when you open FileMaker Pro To quickly display the existing data in your FileMaker Pro database on the Web, you can export it into an HTML table and publish your database as a static web page.
Publishing your database on the Web 3. In the Specify Field Order for Export dialog box, indicate how you want FileMaker Pro to export the data by selecting fields in the left box and moving them to the Field Order box on the right — in the order that you want them to appear. 8-17 7. Select Format output using current layout if you want to use number, date, and time field formatting as specified for the included fields on the current layout (for example, to export a number as $3.70 instead of as 3.7).
8-18 Developer’s Guide To set up your computer to act as a single-machine network, enable and activate TCP/IP networking. On Windows machines, this is usually already set up for you (if you can connect to the Internet, then TCP/IP networking is active). On Mac OS machines, one way to set up TCP/IP networking is to create a new TCP/IP control panel configuration that connects via Ethernet to any IP address manually.
Publishing your database on the Web Opening and closing databases using CDML To open or close databases remotely using a –dbopen request or –dbclose request (CDML variable tags), you must also specify a –format parameter. If desired, use the [FMP-CurrentError] and [FMP-CurrentDatabase] tags in the format file to display the results of the request (the “current database” was successfully opened or the “current database” could not be opened because of “error #”).
THIS PAGE INTENTIONALLY LEFT BLANK
Chapter 9 Custom web publishing using CDML The FileMaker Pro Web Companion supports CDML, a proprietary markup language that enables your HTML pages to interact with a FileMaker Pro database. The FileMaker Developer CD includes: • the CDML Tool database and template files to help you insert the CDML tags into your HTML pages (These HTML pages that contain CDML tags are referred to as format files.
9-2 Developer’s Guide General steps for custom web publishing using CDML In general, to publish your FileMaker Pro databases on the Web you must have a TCP/IP connection to an intranet or Internet Service Provider, the Web Companion must be enabled, and your databases must be open and shared via the Web Companion. (For more information, see chapter 8, “Publishing your database on the Web.”) 1. Design your web site and how web users will interact with your database.
Custom web publishing using CDML 9-3 < INPUT TYPE=“hidden” NAME=“-error” VALUE=“Filename.htm”> Note Format files that contain the “FMPro FMRES” form action are instant web pages generated by the Web Companion Instant Web Publishing feature. (See chapter 14, “Publishing databases on the Web,” in the FileMaker Pro User’s Guide for information about Instant Web Publishing or see FileMaker Pro Help.
9-4 Developer’s Guide Or, web users might click on a submit button in an HTML form containing the FMPro form action and the following hidden INPUT elements:
Custom web publishing using CDML
9-6 Developer’s Guide Using the Templates tab 3. Choose a parameter or value list option, if applicable, and click the 1. With the Templates tab selected, choose a format file from the check box on the left to select your choice. When a value list option is selected, the parameter appears in the CDML Syntax box. Format File (Action) pop-up menu for the type of action that you want users to perform on your database.
Custom web publishing using CDML 9-7 Choose this template So web users can do this with your database 2. Use the CDML Tool to add any CDML tags for the fields and other types of data you’re requesting from the database. Edit.htm Make changes to one record See “Categories of CDML tags” next. Edit_reply.htm Receive feedback after editing a record 3. Add text, images and links as desired. New.htm Add a record 4. Name and save the file in your web site. New_reply.
9-8 Developer’s Guide Categories of CDML tags There are three types of FileMaker CDML tags: • Action tags — these tags are used to make a specific request to the Use tags in this category For this type of interaction with FileMaker Pro Fields (Add) Static Display static field name and value list information from the database in HTML form elements (text field, text area, check box, radio button, repeating fields, scrolling list).
Custom web publishing using CDML [FMP-Cookie: {intratag}] Use tags in this category For this type of interaction with FileMaker Pro Replacement Display specific data from the database in one of 44 types of replacement tags on the web page. For example, display the web user’s IP address in the [FMP-ClientIP] replacement tag.
9-10 Developer’s Guide 4. Click the home button to return to the FileMaker Pro CDML Reference screen. From the home screen, you can open the CDML Tool by clicking the tool button. 5. Click the Custom Web Publishing tab to view general information about custom web publishing using CDML. Click to view a topic 2. On the CDML Tag Index tab, click a button to see a list of tags grouped by one of these categories: All tags, Action tags, Variable tags, Replacement tags, or HTML Input Types (form elements).
Custom web publishing using CDML 9-11 • Include a specific error page with a filename that the Web Companion recognizes when it’s located in a folder named “Error” inside the Web folder. The –error tag in a FileMaker Pro CGI request overrides both the built-in error pages and the pages within the Error folder. For any error page not included in the Error folder, the Web Companion generates a built-in error page instead. The Web Companion recognizes these error pages in the Error folder: NoResults.
9-12 Developer’s Guide For examples of error pages, see the gb_error.htm file in the Guest Book example, the errors.htm file in the Employee Database example, and the reqfielderror.htm file in the Shopping Cart example. (See “Looking at the three CDML examples” on page 9-13 for more information.) This encoding parameter Display Developer Extras\FileMaker, Inc\External FileMaker APIs\CDML\CDML Examples Using an encoding parameter with a CDML replacement tag You can use a special encoding parameter with
Custom web publishing using CDML 9-13 Three examples are included with FileMaker Developer to give you ideas on how to organize a site. You can also use them as templates and modify them for your own sites. Looking at the three CDML examples The FileMaker Developer CD includes three CDML examples that demonstrate ways to publish your databases on the Web using CDML. These examples are located in the CDML folder: Developer Extras\FileMaker, Inc\External FileMaker APIs\CDML\CDML Examples To examine the thr
9-14 Developer’s Guide Employee Database example And the CDML replacement tags appear statically on the page. The Employee Database example is designed to demonstrate the most widely used CDML tags. It shows how to • search for records in the database • select sorting options • browse the database • preselect how many records to view at a time • add a record to the database The second example link contains a FileMaker Pro CGI command for a CDML -view request.
Custom web publishing using CDML 9-15 Arrow icons on the New Record page indicate three fields that are required fields in the database. If any of these fields is left blank when the information is submitted to the database, then the error message page (gb_err.htm) is displayed. The error page is specified on the New Record page in a hidden INPUT element.
9-16 Developer’s Guide The site keeps track of each web user by passing CDML tokens from one web page to the next. Some of the CDML format files use the [FMP-Include] replacement tag to reference text files and include their content on the web pages. In addition, the site uses scripting for easy navigation, which is described in the nav.js JavaScript library. The default.htm page in the Shopping Cart Example folder Items that are placed in the Shopping Cart are added to the OrderedItems.fp5 database.
Chapter 10 Using FileMaker Pro XML to deliver your data on the Web Using the Web Companion, FileMaker Pro can deliver data from your database to the Web in Extensible Markup Language (XML) format. In the same way that HTML has become the standard display language for communication on the World Wide Web, XML promises to become the standard language for structured data interchange.
10-2 Developer’s Guide General process for custom web publishing using XML Here’s a simple overview of the process for publishing your FileMaker Pro database on the Internet or an intranet using XML: 1. You send a FileMaker Pro CGI request (such as to find records in the database) to the Web Companion through an HTML form, an HREF link, or a script on your web page. The request can also be made by typing the URL in the web browser.
Using FileMaker Pro XML to deliver your data on the Web Use one of these grammars in your document or web page to display and work with FileMaker data in XML format. Note XML data generated by the Web Companion is encoded using UTF-8 format (Unicode Transformation Format 8). For information, see “About UTF-8 encoded data” on page 10-8. About XML namespaces To avoid name collisions, unique XML namespaces help distinguish XML tags by the application they were designed for.
10-4 Developer’s Guide The following is an example of a Microsoft XML DSO applet tag that you might use in your web page to query FileMaker Pro for XML data using the FMPDSORESULT grammar—where the “url” parameter can be any valid FileMaker Pro CGI request containing a –format parameter equal to “–dso_xml” or “–dso_xml_dtd.” (See “Generating FileMaker Pro CGI requests for an XML document” on page 10-8 for a list of valid FileMaker CGI requests.
Using FileMaker Pro XML to deliver your data on the Web 10-5 Note If the –lay parameter is not specified in the FileMaker Pro CGI request, the LAYOUT element is empty and data for every field in the database is returned. (See “Generating FileMaker Pro CGI requests for an XML document” on page 10-8 for information.) For a list of valid FileMaker CGI requests, see “Generating FileMaker Pro CGI requests for an XML document” on page 10-8.
10-6 Developer’s Guide The METADATA element of the FMPXMLRESULT grammar contains one or more FIELD elements, each containing information for one of the fields/columns of the result set—including the name of the field as defined in the database, the field type, the Yes or No allowance for empty fields (EMPTYOK attribute) and the maximum number of repeating values (MAXREPEAT attribute). Valid values for field types are TEXT, NUMBER, DATE, TIME, and CONTAINER.
Using FileMaker Pro XML to deliver your data on the Web
Marketing The order of the COL elements corresponds with the order of the FIELD elements in the METADATA element—for example, where the “First Name”, “Last Name”, and then “Department” elements are listed in the METADATA, “Joe”, “Smith”, and then “Engineering” are listed in the same order in the RESULTSET ROW.
10-8 Developer’s Guide About UTF-8 encoded data All XML data generated by the Web Companion is encoded in UTF-8 (Unicode Transformation 8 Bit) format. This format compresses data from the standard Unicode format of 16 bits to 8 bits for ASCII characters. XML parsers are required to support Unicode and UTF-8 encoding.
Using FileMaker Pro XML to deliver your data on the Web Use this request name To generate this request –scriptnames Retrieve names of all available scripts for a specified open, web-shared database –dbopen –dbclose To go with these requests –stylehref (stylesheet HREF) Optional for all requests Open a database that’s in the Web folder with Remote Administration enabled –password Optional for –dbopen requests. Specifies the database’s password.
10-10 Developer’s Guide The following is an example of an –edit request for editing records in a portal, where “Address::” is the name of the relationship, “City.1” is the first row in the portal, and “City.2” is the second row in the portal: FMPro?–db=employees.fp5&–lay=LayoutOne&recid=11& FirstName=Sam&LastName=Smith&Address::City.1=Seattle &Address::City.2=New York&–format= –fmp_xml&–edit The –styletype parameter is used for setting the value of the type attribute (type=text/css or type=text/xsl).
Using FileMaker Pro XML to deliver your data on the Web 10-11
10-12 Developer’s Guide These three examples were designed to be viewed in the Internet Explorer 5.0 for Windows web browser. For information on new browsers that can be used to view the examples, double-click FileMaker on Web (included on the FileMaker Developer CD) to go to the FileMaker Product support pages in your browser. To view the examples: 1. Place a copy of the Simple Examples folder and its files in the Web folder inside the FileMaker Developer application folder on your hard disk.
Using FileMaker Pro XML to deliver your data on the Web 10-13 This example demonstrates the use of a CSS document with an XML document. The following CGI command was used to generate the FMPDSORESULT grammar for the People.fp5 database and to apply the People_form.css stylesheet to the generated XML data: fmpro?–db=people.fp5&–lay=xml form&–format=dso_xml& –styletype=text/css&–stylehref=people_form.
10-14 Developer’s Guide ERRORCODE, DATABASE, LAYOUT, Picture { visibility: hidden; } /* * Since it is not possible to add additional text to the output * of the XML document via CSS, we must rely on the XML document to * provide the labels when displaying the field data. In this case, * the labels are from global fields defined in the database.
Using FileMaker Pro XML to deliver your data on the Web XSL lets you display images in container fields, format the data, and add field labels and a logo to the XML document The three global fields for field labels in the People.fp5 database are not necessary when you’re using an XSL document. You can use XSLT to add labels after the XML document has been generated by FileMaker Pro. Note You can also include scripting (such as JavaScript) in your XSL document.
10-16 Developer’s Guide JavaScript scripting language example Using HTML and a scripting language with your XML document can allow your web users to interact with the database after it has been downloaded. For example, a simple onClick scripting event handler can allow web users to click a button and see different records in the database. This example demonstrates the use of the JavaScript scripting language with an XML document to publish the People.fp5 database on a web page.
Using FileMaker Pro XML to deliver your data on the Web function nextRecord( ) { if (foundSet.nextRecord( )) populateFields( ); 10-17 This example was designed to be viewed in the Internet Explorer 5.0 for Windows web browser. For information on new browsers that can be used to view the example, in FileMaker Pro, choose Help menu > FileMaker on the Web to go to the FileMaker Product support pages in your browser. } function previousRecord( ) { if (foundSet.
10-18 Developer’s Guide To view the XML Inventory example: 1. If necessary, copy the Inventory example files from the FileMaker Developer CD onto your hard disk. Developer Extras\FileMaker, Inc>External FileMaker APIs\XML\Inventory Example 2. Place a copy of the Inventory Example folder and its files in the Web folder inside the FileMaker Developer application folder on your hard disk. Web \ Inventory Example Note For security, when actually publishing a database on the Web, you should not keep the data
Using FileMaker Pro XML to deliver your data on the Web It is possible to have both the Detail View and Add Record windows open at the same time. The Detail View and Add Record windows will automatically close when a visitor clicks the Back or Forward button in the browser. 10-19 A detail view of an empty record opens in a separate window with a blinking insertion point in the Item field.
10-20 Developer’s Guide The found set of records is displayed in the List View window 12. In List View, click Show All to display all the records in the database, including any records you added. If you want, you can examine the XML Inventory example’s JavaScript library as you view the source for the example pages. FMP.js text file containing the JavaScript library for this example 2.
Using FileMaker Pro XML to deliver your data on the Web The scripts and functions are well commented in the source and in the FMP.js library, providing information about each step. It’s useful to arrange the windows so you can switch between the example pages in the browser, the source, and the script library. Tip Use code snippets from the FMP.js JavaScript library for scripting your own web sites.
THIS PAGE INTENTIONALLY LEFT BLANK
Using JDBC to deliver your data 11-1 Chapter 11 Using JDBC to deliver your data If you’re a Java programmer, you can use the FileMaker JDBC Driver with any Rapid Application Development (RAD) tool to visually create your FileMaker Pro database-aware Java application or applet. The FileMaker JDBC Driver lets you directly access FileMaker Pro data using a RAD tool as you’re building your code.
11-2 Developer’s Guide Using the FileMaker JDBC Driver You can use the FileMaker JDBC Driver with any Java compiler or RAD tool to connect with your database while you build the code for your Java application or applet. After the Java application or applet has been created, the FileMaker JDBC Driver must be present with the files or included within the code in order for the application or applet to communicate with the database.
Using JDBC to deliver your data 11-3 while (resultSet.next()) System.out.println(resultSet.getString("last name") + ", " + resultSet.getString("first name")); jdbc:fmpro:http://1.184.21.234:80 The Web Server Connector allows you to encrypt and decrypt your data via HTTPS. } catch(ClassNotFoundException classNotFoundException) jdbc:fmpro:https://www.filemaker.com:80 { System.out.
11-4 Developer’s Guide Property Description SQL statement Definition escape A string containing the characters to be escaped in table name, field name, and layout name SQL identifiers. The driver will escape all identifiers returned via any method in the DatabaseMetaData class. This will allow RAD tools that don't support spaces and periods in SQL identifiers to work with any FileMaker Pro database. The driver will automatically escape all identifiers for you.
Using JDBC to deliver your data recordid=4 11-5 { // register the FMPJDBC driver To add a specific repeating field or field in a portal, add a period and the number zero (0) to the end of the field name and enclose the field name in double quotation marks. For example, to add the City field to a portal in the Address relationship: INSERT INTO “Employees.fp5” LAYOUT “Data Entry” (“Last Name”, “Address::City.
11-6 Developer’s Guide } Using the ModID pseudo column catch(ClassNotFoundException classNotFoundException) Each record in a FileMaker Pro database has a corresponding modification ID (ModID) number that increases incrementally every time the record is modified. To detect modification collisions, the FileMaker JDBC Driver provides a ModID pseudo column that can be used in the WHERE clause of an UPDATE statement in conjunction with the RecordID.
Using JDBC to deliver your data SQL statement examples The following are some examples of SQL statements, some of which use RecordID and ModID pseudo columns, and DbOpen and DbClose pseudo procedures: 11-7 FileMaker data type mapping to JDBC SQL and Java data types SELECT recordid, modid, "last name", "first name", department FROM "Employees.
11-8 Developer’s Guide About the FileMaker JDBC Driver interfaces and extensions The FileMaker JDBC Driver implements all of the following JDBC interfaces: • CallableStatement • Connection • DatabaseMetaData • Driver • PreparedStatement • ResultSet • ResultSetMetaData • Statement The API documentation for these standard interfaces and the FileMaker extensions is included in HTML format on the FileMaker Developer CD: Developer Extras>FileMaker, Inc>External FileMaker APIs>FileMaker JDBC Driver>JDBC Docum
Using JDBC to deliver your data 11-9 Setup requirements Run the FileMaker Pro Explorer application Included with the example is the swingall.jar file, on the FileMaker Developer CD. The FileMaker Pro Explorer application is located in the FileMaker Explorer folder: Developer Extras>FileMaker, Inc>External FileMaker APIs>FileMaker JDBC Driver>JDBC Examples>FileMaker Explorer Developer Extras\FileMaker, Inc\External FileMaker APIs\FileMaker JDBC Driver \Examples\FileMaker Explorer\FileMakerExplorer.
11-10 Developer’s Guide See “Using a JDBC URL to connect to your database” on page 11-2 for information. The columns correspond to the fields available for the selected layout. 3. Select Inventory.fp5 (or other database name) on the left side of the window to see information about it on the right side. 4. Expand the Inventory.fp5 node (folder) to expose the Layouts and Scripts nodes. 9. Select the Scripts node to display the names of scripts for the Inventory.
Using JDBC to deliver your data 11-11 Developer Extras\FileMaker, Inc\External FileMaker APIs\ FileMaker JDBC Driver\Fmpjdbc12.jar The JBuilder 3.0 Professional example folder contains the database file used in this example and all of the completed files generated by the JBuilder wizard for the application. Set up JBuilder to use the FileMaker JDBC Driver 1. In a text editor (such as Notepad), open the Jbuilder.ini file from the bin folder inside the JBuilder 3.0 Professional application folder.
11-12 Developer’s Guide 3. In the dialog box, specify the name and location for the project file Create the data module (JBuilder Inventory). 1. In JBuilder, choose File menu > New. 4. Choose Project menu > Properties. 2. In the New dialog box, select the Data Module icon and click OK. 3. In the New Data Module dialog box, make sure that inventory is in the Package text box and that the checkbox for Invoke Data Modeler is selected. 4. Click OK to open the Data Modeler. 5.
Using JDBC to deliver your data 11-13 JBuilder connects to FileMaker Pro. 7. In the Data Modeler, click the + symbol to expand Tables. 8. Click the + symbol to expand the Inventory$2efp5 table (now encoded with the period escaped). 9. Click the + symbol to expand Columns. 2. In the Driver text box, type com.fmi.jdbc.JdbcDriver. 3. In the URL text box, type jdbc:fmpro:http://localhost/ properties?escape=.%20.
11-14 Developer’s Guide 2. Click the Java Client Layout tab. Because JBuilder requires a unique row identifier for updating and deleting rows, it automatically adds the RecordID pseudo column to the list of output columns, which you probably don’t want displayed in your application. 3. Deselect the Layout check mark for the RecordID identifier. 4. Choose File menu > Generate. The field attributes used for the example from the Inventory.
Using JDBC to deliver your data 11-15 Field type Field name Field attribute Set up Visual Cafe to use the FileMaker JDBC Driver Date Date Purchased User defined entry field 1. Start Visual Cafe 4.0 Expert Edition for Windows. Container Picture Graphic import 2.
11-16 Developer’s Guide 3. In the DataBound Project Wizard, select Application for the project type and click Next. 11. In the DataBound Project Wizard, select inventory_db in the list of database tables and views, and click Next. 4. Select Define another data source and click Next. 12. Click Clear to move all the used columns to the Available Columns list. 5. In the DataBound Project Wizard, click New. 6. In the Insert Datasource dialog box, click Add Driver. 7.
Using JDBC to deliver your data Field type Field name Text Location Field attribute Value List/Location List (Pop-up menu) Fred’s Office Dirk’s Office Pedro’s Office Anne’s Office Julie’s Office Ruth’s Office Joanna’s Office Business Center The field attributes used for the example from the inventory_db database are described in the following table: Field type Field name Field attribute Text Item User defined entry field Text Category Value List/Category List (Pop-up menu) Office Furniture Com
THIS PAGE INTENTIONALLY LEFT BLANK
Chapter 12 Understanding external function plug-ins If you are a C or C++ programmer and familiar with advanced calculations in FileMaker Pro, you can create external function plugins that extend the feature set of FileMaker Pro—including calculation formulas that take advantage of recursion and looping, or that hook into other programming interfaces. Users can enable your plug-ins in FileMaker Pro and use your external functions in their calculation fields and scripts.
12-2 Developer’s Guide The example plug-in files in Windows are located in the Developer Extras\FileMaker, Inc\External FileMaker APIs\External Function Plug-in\(Output)\x86 folder on the FileMaker Developer CD. The plug-in example source code files are located in subfolders in the FMExample plug-in folder. The following tables describe some of the files.
Understanding external function plug-ins File/Folder Description FMMain.c• Contains source code for plug-in entry point functions. FMFunct.h Contains definitions for external functions. FMFunct.c Contains source code for external functions. Installing, enabling, and configuring the example plug-in Plug-in description text is defined in a resource string. See “Required resource files” on page 12-7.
12-4 Developer’s Guide Description of the FMExample plug-in’s external functions The FMExample plug-in provided ins the Microsoft Visual C++ and Code Warrior Pro example projects adds the following external functions to FileMaker Pro. Function’s name and parameter Xpl-Version, “ ” Function’s name and parameter Description of external function Xpl-NumWords, This function returns a number in bank check format. For example 44.
Understanding external function plug-ins 12-5 Dialog box that appears when you configure the example plug-in 4. Click OK to use the default format, or type a new format. The “#” symbols are replaced by numbers. All other text in the format string is retained as is. 10. Double-click an external function in the list that begins with the 5. Click Done to close the Application Preferences dialog box.
12-6 Developer’s Guide 13. Click Done to close the Define Fields dialog box. //String Table• Edit the String Table strings as appropriate, including the plug-in name, the Feature String,and the list of function names in the plug-in. See “Required resource files” on page 12-7, and “Feature string syntax” on page 12-8, Customizing the plug-in example The plug-in example in FileMaker Developer is designed to be easily modified so you can add your own custom functions.
Understanding external function plug-ins 12-7 Requirements for writing an external function plug-in typedef enum { kFMXT_Init, kFMXT_Idle, kFMXT_Internal1, kFMXT_External, kFMXT_Shutdown, kFMXT_DoAppPreferences, kFMXT_Internal2 } FMExternCallSwitch; FileMaker Pro plug-ins are most useful when they contain a single function or a set of functions with similar features.
12-8 Developer’s Guide • The second string (ID 129)is the descriptive text displayed in the Application Preferences dialog box when the plug-in is selected. • The third string (ID 130) must be empty. • The fourth string (ID 131), referred to as the feature string, contains the plug-in’s unique ID and feature flags.
Understanding external function plug-ins The fifth character of the feature string is always “1,” the eighth is always “Y,” and the tenth is always “n.” Other values for these flags are reserved for FileMaker, Inc. use only. Here’s a description of each character in the feature string: Characters in the feature string Description of characters 9• Set the ninth character of the feature string to “Y” if the kFMXT_Idle message is required.
12-10 Developer’s Guide Main entry point for Windows environments External function naming conventions The Windows platform plug-in exists as a 32-bit DLL with one exported, named entry point. The filename extension for the DLL must be “.FMX” and the name of the entry point must be “FMExternCallProc.” The function name prefix for all of the plug-in’s external functions must be a unique value containing 4 or 5 characters and must not begin with the characters “FM” or “Web.
Understanding external function plug-ins The Initialization message The Initialization message, kFMXT_Init, is sent to the plug-in whenever it is enabled in FileMaker Pro. This may or may not correspond with the startup of the FileMaker Pro application, depending on whether the plug-in is enabled in the Application Preferences dialog box.
12-12 Developer’s Guide There are two times when this message is called by the FileMaker Pro application: • If the unsafeCalls parameter is non-zero, then the routine has been Depending on the value of the param2 variable, the FMExample plug-in (FMFunct.
Understanding external function plug-ins Debugging your plug-in Your plug-in code could include a preprocessor instruction to cause your plug-in to behave differently during the debugging process. For example, the FMExample plug-in will behave in the following ways when the DEBUG_VERSION flag is set to “1”: • The DebugPlugin routine will be substituted for the PluginVersion function.
12-14 Developer’s Guide 2. Click the Registering a Plug-in link to display the online registration form. 3. Enter information about you, your company, and others who can be contacted about your plug-in. 4. Enter the required information about your plug-in. The following table describes some of the required fields: Plug-in Name • Your plug-in’s name as it will appear in the FileMaker Pro Application Preferences dialog box.
Appendix A Feature comparison of the runtime application and FileMaker Pro When you double-click the FileMaker Developer application icon to start the application, the New Database dialog box opens automatically, from which you can open a database file. When you start a FileMaker Pro runtime application, the primary bound database file opens automatically.
A-2 Developer’s Guide Color application preferences in the runtime application General preferences in the runtime application (Windows) The Document Preferences dialog box does not have the General tab in the runtime application, only the Spelling tab. Spelling document preferences in the runtime application General preferences in the runtime application (Mac OS X) The Layout tab is changed to the Color tab in the Application Preferences dialog box for the runtime application.
Feature comparison of the runtime application and FileMaker Pro Toolbar comparison 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 Menu command Define Value Lists Define Relationships The Help tool on the standard toolbar in the runtime application is dimmed unless a custom Help script has been specified.
A-4 Developer’s Guide Edit Menu command Clear Select All Find /Replace Spelling Object Preferences 1 See Windows Mac OS 9 Mac OS X Pro RT Pro • • • • • • • • • • • • Pro RT • • • • • • • • • • • • RT • • • • Insert Menu command Object Picture QuickTime Sound • • 1 1 Current Date Current Time Application Menu table Current User Name 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
Feature comparison of the runtime application and FileMaker Pro Records Menu command Duplicate Record Delete Record Delete All Records Modify Last Find Show All Records Show Omitted Omit Record Omit Multiple Sort Replace Contents Relookup Contents Revert Record Windows Mac OS 9 Mac OS X Pro RT Pro • • • • • • • • • • • • • • • • • • • • • • • • Pro RT • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • RT • • • • • • • • • • • • Requests Menu command Windows Mac OS 9 Mac
A-6 Developer’s Guide Window Menu command Tile Horizontally Tile Vertically Cascade Arrange Icons Window s Mac OS 9 Mac OS X Pro RT Pro RT Pro • • • • 1 • • • • • Minimize Window Bring all to front Help Menu command FileMaker Pro Help Contents and Index What’s This? FileMaker on the Web Send Feedback to FileMaker Register Now About FileMaker Pro • • • • • • • Mac OS X (Mac OS 9 only) Pro RT Pro RT Pro Pro About (Displays if custom About script is specified) Pro R
Feature comparison of the runtime application and FileMaker Pro A-7 Appplication Menu command Window s Mac OS 9 Mac OS X Stored registry settings (Mac OS X only) Pro RT Pro RT Pro On Windows machines, FileMaker Pro stores its registry settings at Hide Others Show All Quit FileMaker Pro Quit • • • RT • • The runtime application stores its registry settings at hkey_current_user\software\FileMaker\\6 • Ignored script steps Because some features have been remo
THIS PAGE INTENTIONALLY LEFT BLANK
Appendix B Valid names used in CGI requests for FileMaker Pro XML data This appendix describes the valid names of requests and their parameters you can use in a CGI (Common Gateway Interface) command when requesting FileMaker Pro data in XML format. Included are HREF link and HTML form examples of each request. For scripting examples of each request, see the JavaScript library, FMP.js, in the XML Examples folder.
B-2 Developer’s Guide To find any record using a hypertext link: Find a random record for today’s daily quote To find some records using a form action: Generating a –new request
B-4 Developer’s Guide Examples of –dbnames requests PAGE 183
Valid names used in CGI requests for FileMaker Pro XML data B-5 Generating a –dbopen request Generating a –dbclose request Name/Value Type: Open Database Request Name/Value Type: Close Database Request What it does: Opens a specified database that’s located in the Web folder with Remote Administration enabled in the Web Companion (web users must enter “Admin” as the user name) What it does: Closes an open database that’s located in the Web folder with Remote Administration enabled in the Web Companio
B-6 Developer’s Guide Examples of -dup requests To duplicate the specified record using a link: Specifying parameters for the request Duplicate record with ID 14 The following are the parameters for requesting FileMaker Pro data in XML format. Some parameters are required to be present in the CGI command along with certain requests; others are optional.
Valid names used in CGI requests for FileMaker Pro XML data –format (Format) B-7 Required with: –edit and –delete requests Name/Value Type: Parameter What it does: Specifies the XML grammar used for returning the results of a request. Value is: –dso_xml, –dso_xml_dtd, –fmp_xml, or –fmp_xml_dtd. Optional with: –find requests Example: FMPro?–db=employees.
B-8 Developer’s Guide Example: FMPro?–db=employees.fp5&–format= –fmp_xml& Example: FMPro?–db=employees.fp5&–format= –fmp_xml& Last+Name=Smith&Birthdate=2/5/1972&–lop=and&–find –op=eq&FirstName=Sam&–find –op (Comparison operator) –max (Maximum records) Name/Value Type: Parameter Name/Value Type: Parameter What it does: Specifies the comparison operator to apply to the field name/value pair that follows it in a –find request.
Valid names used in CGI requests for FileMaker Pro XML data –sortfield (Sort field) –script (Script) Name/Value Type: Parameter Name/Value Type: Parameter What it does: Specifies the field that will be used for sorting. The –sortfield parameter can been used multiple times to perform multiple field sorts. The position in which –sortfield appears in the CGI command will determine the sort order of the fields.
B-10 Developer’s Guide –styletype (Style type) –password (Database password) Name/Value Type: Parameter Name/Value Type: Parameter What it does: Tells the FileMaker Pro Web Companion to generate an XML-stylesheet processing instruction within the grammar— setting the value of the type attribute (type=text/css or type=text/ xsl)—so you can use cascading style sheets (CSS) or Extensible Stylesheet Language (XSL) documents with your XML document.
Appendix C FileMaker Pro values for error codes The FileMaker Pro Web Companion generates an error code for databases published in XML, JDBC, or CDML format every time data is requested. The following table describes the value of each error code, which is based on the type of query to the database. Use these values to do error handling on your web pages.
C-2 Developer’s Guide Error code value Description Error code value Description 405 Number of records specified exceeds number of records that can be omitted 601 Combined header and footer exceed one page 602 Body doesn't fit on a page for current column setup 406 Replace/Reserialize criteria is invalid 603 Print connection lost 407 One or both match fields are missing (invalid relationship) 700 File is of the wrong file type for import 408 Specified field has inappropriate data type for
FileMaker Pro values for error codes C-3 Error code value Description Error code value Description 720 Error in parsing the XML document (after XSL transformation) 903 Command cannot be used in a shared file 904 721 Error when exporting--intended format does not support repeating fields Command can only be used in a file hosted under FileMaker Server 905 800 Unable to create file on disk No active field selected--command can only be used if there is an active field 801 Unable to create temp
THIS PAGE INTENTIONALLY LEFT BLANK
Index Numerics 3-character filename extensions for runtime databases (Mac OS) 6-8 for runtime databases (Windows) 6-8 registered by the runtime application 7-5 A About layout adding a custom script 6-2, 6-4, 6-11 creating 4-8 displaying 4-9 example 4-8 password warning 4-15 prevented modification warning 4-15 requirements 4-8 using 4-8 About FileMaker Pro Runtime, default menu command 6-12 Access Log File option 8-4, 8-14 access privileges settings for Kiosk mode 4-7 Access Privileges comma
I-2 Developer’s Guide CGM graphic import filter 7-2 character entities, XML 5-3 character escaping 11-4 characters, platform-specific 4-12 Claddon.clr spelling dictionary 7-3 COLOR attribute 5-7 color palette FileMaker Pro 5-10 for cross-platform databases 4-13 color values for layout themes 5-10 com.fmi.jdbc.
Index Do_Init function 12-11 Document Object Model (DOM) Microsoft 10-3 W3C 10-16, 10-17 Document Preferences in runtime applications A-2 document type definitions (DTDs) 10-2, 10-3, 10-5 documenting custom databases 4-8, 4-10 external function plug-ins 12-13 runtime databases 7-5, 7-6 double colons in portal fields in CGI requests 9-4, 10-9 in XML documents 10-4 driver properties, for FileMaker JDBC URL 11-3 DRW graphic import filter 7-2 –dso_xml format parameter 10-3 Dynamic Link Libraries (DLLs) 7-1, 7-
I-4 Developer’s Guide hardware and software requirements 1-2 installation code 1-2 installing (Mac OS) 3-1 installing (Windows) 2-1 license agreement 1-6 registering 1-1 FileMaker Developer Tool automating the process 6-15 described 6-1 generated DLLs (Windows) 7-2 generated runtime files 7-1 options, described 6-2 saving option settings 6-14 specifying files 6-3 using 6-2 FileMaker JDBC Driver data type mapping 11-7 described 11-1 driver class and main entry point 11-2 escaping lower ASCII characters 11-
Index H I Handles 12-12 header layout parts 5-4 Help Balloon Help (Mac OS) 4-8 button on toolbar in runtime applications A-3 custom layout 4-8, 4-9 custom menu command 6-2, 6-13, A-1 documentation for custom databases 4-8, 4-10 examples of custom layouts 4-9 FileMaker Pro Help Status Bar Help (Windows) 4-8 What’s This? Help (Windows) 4-10 Help layout adding a custom script 6-2, 6-13 hexadecimal (hex) values for layout themes 5-10 HINT attribute 5-2, 5-8 home button in browser 8-13 home pages built-in 8-5
I-6 Developer’s Guide layout parts, XML elements for 5-4 layout themes attribute values 5-7 attributes for single-line elements 5-6 basic requirements 5-3 checking for errors 5-11 color values 5-10 comment tags 5-10 creating 5-1 default values 5-9 elements for layout parts 5-4 elements for layout text 5-5 modifying 5-1 multi-line elements 5-4, 5-5 pattern values 5-9 single-line elements 5-4, 5-5 -layoutnames requests B-4 layouts About layout 4-8, 6-12 cross-platform 4-11 Help layout 4-9 leading grand summ
Index ONOFF attribute 5-8 onscreen Help.
I-8 Developer’s Guide R Rapid Application Development (RAD) tools 8-1, 11-1, 11-2 Raw encoding parameter 9-12 -recid request parameter B-7 RecordId pseudo column 11-4 recovering damaged runtime files 7-6 registering FileMaker Developer 2-2 FileMaker JDBC Driver 11-2 FileMaker Pro external function plug-ins 12-1, 12-13 plug-in ID 12-8 registry conflicts with filename extensions 6-8 settings stored for runtime applications A-6 Relational Example 4-1 Remote Administration option 8-4 Remote Data Access Compan
Index searching databases on the Web 8-1, 9-14 TechInfo database 1-6 security 8-3, 8-4 SELECT SQL statements 11-4, 11-6 Set Multi-User script step A-6 Set Zoom Level script step 4-6 setting document margins for printing 4-3 setting up single-machine networks 8-18 shadow and outline text styles 4-11 sharing databases via the Web Companion 8-5 runtime files over a network 7-5 Shopping Cart CDML example 9-13, 9-15 Shutdown message 12-11 SIDES attribute 5-8 SimpleText 11-10 single-line elements for layout them
I-10 Developer’s Guide URLs (Uniform Resource Locators) accessing Java resources 11-2 FileMaker JDBC URL 11-2 for FileMaker Pro CGI requests 10-2 using to access databases 8-1 Usenglsh.mpr spelling dictionary 7-3, 7-4 user driver property 11-4 User.upr spelling dictionary 7-3, 7-4 UTF-8 (Unicode Transformation 8 Bit) format 10-8 V values for error codes C-1 VBScript 10-3 -view requests B-2 Visual Cafe 4.
