Using the Database Design Report

Beyond documenting your solution within its structure and code, FileMaker Pro 8 Advanced includes a Database Design Report (DDR) feature that is quite useful and may very well stand as the centerpiece for your system documentation. The report includes an overview of the system, along with detailed information about your database schema, including tables, fields, relationships, layouts, value lists, scripts, accounts, privilege sets, extended privileges, and custom functions. The report can be created as an integrated set of linked HTML documents or as a set of XML files.

Tip

Using XSLT, you can transform the XML output of the DDR into a Microsoft Word document that your constituents may find easier to digest and more commonly associated with what they think of as documentation.

Creating a DDR

Creating a Database Design Report is a simple task. But first, you must have FileMaker Pro 8 Advanced and you must open all the files that you want to include in the report. The files must be opened with an account that has full access privileges. After the files have been opened, choose Tools, Database Design Report to display the dialog box shown in Figure 27.4.

By default, all tables in all available files are included in the report. You can uncheck files or tables you do not want to include. You can also specify the types of information to include for each file. Choose either HTML or XML for the report format. Finally, click the Create button and specify the location to which to save the report files.

If you e not sure whether the HTML or XML version of the DDR is more useful to you, think of it this way: The HTML version produces a set of linked web pages that you can open and navigate immediately in a browser. The XML output is more appropriate if you need the data in a raw form and plan to manipulate it in some way before viewing or presenting it. One type of manipulation might consist of writing one or more XSLT stylesheets to transform the DDR XML data into a form suitable for importing into a FileMaker database.

Working with the DDR in HTML

The HTML version of the DDR includes a Summary.html document along with three additional HTML documents (_ReportFrame.html, _TOCFrame.html, and .html) for each of the FileMaker files in your solution. These three files all work together to create a frame-based view of database information for each database file. A Styles.css file is also created. This file includes formatting information used by all the HTML documents. To view the report, open the Summary.html file in any frames-capable web browser. See Figure 27.5 for an example of the Report Overview. Each of the solutions files is listed, along with counts of elements within those files. Click on a filename or any of the element counts to view details. All the details for a particular file are included on one (possibly lengthy) page. Use the navigation frame at the left side of the window to quickly move to the section you are interested in. You might also use your browsers Find feature to locate a particular element within the report.

Tip

If you want to distribute the HTML-based DDR, one way is, of course, to host the files on a web server and distribute the URL (making sure that you give it only to people who should be allowed to see the internals of your database!). If you feel that hosting the files on the Web is insecure, or web hosting is impractical for other reasons, you can distribute the HTML files as a group. If you do this, be sure to keep all the files together, in the same relative positions and with the same filenames they had when they were first generated.

The DDR includes many hyperlinks that make it easy to navigate the report. For instance, the Fields section lists every layout, relationship, script, and value list that uses each field. Each of the listed items is a link that displays the element.

Using the XML Version

When you choose to generate the DDR as XML, youll get a file called Summary.xml, and an additional file called .xml for each database file you choose to analyze. The XML version of the DDR includes all the information in the HTML version, as well as many more details. (In particular, you get a great deal more information about the position and styling of layout objects.) Although the XML DDR can be viewed in any text editor, you will likely prefer to use a program that understands XML (for example, an XML-aware web browser such as Internet Explorer or Mozilla, or an XML editor such as Oxygen or XMLSpy). You may also want to use an XSL style sheet to format or transform the raw XML. Figure 27.6 shows an overview of an XML DDR viewed with most of the entities collapsed. The XML DDR contains an extensive amount of data broken down into 10 sections: BaseTableCatalog, RelationshipGraph, LayoutCatalog, ValueListCatalog, ScriptCatalog, AccountCatalog, PrivilegesCatalog, ExtendedPrivilegeCatalog, CustomFunctionCatalog, and Options. Each of these sections contains information about one area of the database. The XML element names in each section are relatively self-explanatory.