Using the Design Synopsis

Using the Design Synopsis Dialog Box

The four tabs of the Design Synopsis dialog box are listed in Table 25.1.

Table 25.1. The Four Tabs of the Design Synopsis Dialog Box

Tab	Contents
Choose Design Elements	A pick list of design objects, such as forms, views, subforms, and mover dialog boxes that enable you to choose specific objects.
Choose DB Info	General, space usage, replication, and access lists (ACL information).
Define Content	A pick list of specific items for each type of design object to be included in the Synopsis.
Format Output	Determines whether the output of Design Synopsis is to a document (the default) or to a database. Also enables choice of separators.

You can choose which design objects to include from the Choose Design Elements tab, and you can pick specific aspects of each type of design object on the Define Content tab. The Choose DB Info tab contains nothing new, but the Format Output tab enables you to define separators for the report and, more important, whether the report goes to the screen or to a database. Creating a database that contains design information can be important for both documentation and research. Because you can append analysis documents to the same database, you can create an archive of design changes. As you will see in the section on Teamstudio Analyzer, the database produced from the Design Synopsis tool isn't nearly as detailed as that produced by Teamstudio Analyzer, but it's a step in the right direction.

The Synopsis dialog box can be launched in two ways. With a database selected or open , you can choose File, Database, Design Synopsis, or you can select Other, Synopsis from the Design list in Domino Designer. The next few sections cover the Design Synopsis dialog box. You will see how each of the tabs contributes to a sophisticated and ultimately more useful design synopsis. See Figure 25.1.

Figure 25.1. The Design Synopsis dialog box in Release 6 has multiple tabs and list boxes. Clicking the Type drop-down produces a list of design elements.

Using the Choose Design Elements Tab

As you can see from Figures 25.1 and 25.2, the Design Elements tab consists of a drop-down list of design elements and a dialog box. When you choose a design element, a list of design objects of that type appears in the window to the left. A selection window appears to the right. The buttons in the middle offer ways to transfer design objects between the windows . You can choose from the following design objects:

• All
• Outlines
• Framesets
• Pages
• Forms
• Views
• Folders
• Navigators
• Agents
• Images
• Subforms
• Shared fields
• Script libraries
• Stored queries
• Other (icons, "About Database" documents, "Using Database" documents, database scripts, shared actions)

In Figure 25.2, two form design objects are chosen . In similar fashion, you can continue on to the next class of design objects and make additional selections. Figure 25.3 illustrates the mix-and-match approach that Lotus has taken to this new implementation of Design Synopsis. This concept extends throughout the remaining tabs.

Figure 25.2. The Design Synopsis dialog box uses "mover" windows to add design elements to the Selected Elements list. Note the drop-down list of available design elements.

Figure 25.3. You can choose any number of design objects of any type and include them in the synopsis. Each type has a different graphic associated with it.

When you complete your selection of design objects, you can move to the next tab.

Using the Choose DB Info Tab

As stated previously, the items on this tab were available in earlier releases. Figure 25.4 shows the Choose DB Info tab. There are only four check boxes:

• General Information
• Space Usage
• Replication
• Access List

Figure 25.4. The Choose DB Info tab adds database-level information to the synopsis.

General Information includes items such as path , filename, creation, and modification dates. Space Usage includes file size , number of documents, and information about the whitespace in the database. Replication is essentially a rehash of the replication settings of the database, and Access List is exactly that ”a text representation of the ACL. All this information is also available from the Database properties dialog box, the Replication Settings dialog box, and the Access Control List. However, here you can produce and store this information as a snapshot of the database at a specific moment in time. Although it might not be quite as useful as a listing of the agents, it is useful as a point of reference.

Using the Define Content Tab

Now this is where the fireworks start. Versions earlier than R5 never provided this level of detail or control over what is stored in the synopsis. For each design-object type, you can select from a list of specific object properties to include in the synopsis. Lotus has exposed all the properties for each of the design objects. All the line items are selected by default; if you want to limit what is produced in the report, you must deselect specific items.

TIP

If you want to see only a very limited amount of information, click the Deselect All button under the Line Items window, and then choose the items you want to see (see Figure 25.5).

Figure 25.5. The Define Content tab shows the drop-down list of design objects. The Line Items list for a page is fairly extensive .

 

Notice the check boxes to the right of Figure 25.5. Now you can get at the LotusScript, HTML, JavaScript, and Java code in design objects. By clicking Include Subcomponents, fields and similar objects appear in the synopsis.

The line items for each design object are the same properties that are available from the Design properties boxes and the IDE. For example, Figure 25.5 shows properties for pages that include Alias, Last Modification, Window Title Formula, and Event Formulas ”all of which are available by opening the Page properties box or opening the page in the IDE. Of course, many more aspects of a page are available than are visible in the figure, and not all the design objects have as many line items. Contrast the extensive list of items available for pages with that available for framesets, shown in Figure 25.6.

Figure 25.6. In contrast to the pages line items list, the options under the framesets design object list are fairly limited.

Although you might think that you'll never find a reason to limit the information on the object properties for each element, sometimes you might simply want a listing of the fields on a given form. To accomplish this, select a form in the Choose Design Elements tab. On the Define Content tab, select Forms in the Line Items list. Click the Deselect All button for the Forms object. Next, uncheck Include LotusScript Code and uncheck Include JavaScript and HTML. If Include Subcomponents isn't checked, check it now. Click the Format Output tab, and specify where you want the output to go (covered in the next section); click OK. You will get a nice output consisting of the name of the form and the fields on the form. If you choose Document as your output, the synopsis appears on a tabbed window in the Domino Designer Work pane. Because fields are considered subcomponents by Design Synopsis, and because no other elements were selected, the output consists of a list of fields contained in the form (see Figure 25.10).

Figure 25.10. A results database can contain Design Synopsis documents from multiple databases.

Using the Format Output Tab

The Format Output tab is pretty straightforward. You can control how each element is separated and where the output goes. There are two choices for separators, as shown in Figure 25.7: Page Break and Blank Line. There are two choices for output, Document and Database. The default choice, Document, sends the report to a nonmodal tabbed window.

Figure 25.7. The Format Output tab has settings for the report separator and output direction.

If you choose to send the output to a database, Domino creates a document based on your choices on the preceding three tabs and stores the results in a database of your choice. Figure 25.8 shows the dialog box that you'll see when you check Write Output to Database and then click OK. As you can see from Figure 25.8, you can pick a server (including local, of course), choose a title, change the result database filename, and elect to append or overwrite the contents of an existing results database.

Figure 25.8. The Results Database dialog box enables you to choose what happens when the synopsis is written to a database.

The results database is based on the template file titled Design Synopsis Template, with a filename of dsgnsyn.ntf. This database consists of a single form and view, both of which are very simple. The form contains fields for the database filename, the server on which it was created, the date of creation, and a field named Body that contains the actual synopsis document itself. The view simply displays the date, server, and database filename.

NOTE

Unfortunately, using the Page Break separator does not produce separate documents in the results database. One lengthy document is produced with page breaks at the end of the report on each element.

The Design Synopsis dialog box is like a wizard dialog box in which you sequentially step through each tab and make selections. When you're satisfied with your selections, click OK, and the report is produced using the current selections. If you need a quick look at a database design object or just want some quick general information about the database, you can select the items to include and direct output to the screen. The settings in the dialog box are not persistent, and the dialog box always opens to the default settings.

Often you need to use the replica ID for a particular database. For example, you might construct a formula using @DbLookup() and want to use the replica ID to specify the lookup database. Design Synopsis is a quick and convenient way of obtaining the ID without looking at the Database properties box and typing that huge hexadecimal string. To get the replica ID, click Replication on the Choose DB Info tab, and click OK (see Figure 25.9). Then you can highlight the replica ID and copy it to the Clipboard. Now you're able to paste it wherever you need it in your application.

Figure 25.9. The replication information captured to the screen enables you to easily copy the replica ID to the Clipboard.

If you want to do a quick search for some specific piece of information, you can direct output to the screen and then use the Find dialog box to locate instances of that information. Perhaps you need to know where @DbLookup() is being used in a given form. Sending the results to the screen and using Find to look for occurrences of DbLookup enables you to locate successive occurrences of the @Function in the form. This is definitely better than laboriously navigating through the field and form-level events of a form in design, especially if the form has a significant number of fields.

You can also use Design Synopsis to create historical documentation of application designs because you can successively append the design synopsis to the same database. To accomplish this, select the same design synopsis database each time you create a synopsis. Each time, a new dated document appears in the database, as shown in Figure 25.10. Extending this technique to other databases, you can build a library of application synopses .

When you have created a persistent record of the design of an application, you can use it as a starting point for technical documentation. It can be as detailed as you need it to be, as you have seen in the preceding sections. You can copy or export the document into another format, such as Lotus WordPro, or even copy it into another Domino database to produce documentation that meets your needs or company standards.

Because the results database is just like any other Domino database, you can full-text index it for more sophisticated searching. This might be useful if you have created a library of application synopses, as described in the section titled "Using the Format Output Tab." For example, you might remember that you used an action button to look up department information in a common lookup database. You can full-text search your application synopsis library for words or phrases that will help you locate the code for the action button. When found, the formula can be copied to the Clipboard and pasted into your new application.

This last scenario illustrates another limitation to the approach that Lotus has taken with the Design Synopsis tool. There is no granularity to the output. Everything is dumped into one gigantic document. Even though you can save it to a database, it is still huge. For a significant database application that can consist of dozens of design objects, this single document is unmanageable. There is no separation of design objects other than the separator that you picked in the Format Output tab. As an alternative, you can use LotusScript to access the design objects and generate a design synopsis that produces a more granular report. Or, you can create a single document for each design object. What the Lotus Design Synopsis tool lacks in granularity can be found in the third-party product covered the next section, "Teamstudio Analyzer."