Section 4: The Protected Template Catalog

The "Protected" catalog is where the templates that are distributed with the Database Designer are kept. The templates in the catalog are split into a number of collections, which serve as an organization mechanism for templates, similar to the way folders (directories) are used to organize files in a computer's filesystem. Every collection in the catalog contains zero or more additional collections, to further refine the organization of the catalog, and zero or more templates that can be added to the design in the workspace. For example, the picture below shows how the Designer's various branch templates, which have been built for use in databases for storing data on the forest canopy, are kept in a collection named Branches that is itself kept in a collection called Canopy Studies Templates.

Section 5: Manipulating the Custom Catalog

The custom catalog is where user-created entity and observation templates are stored. Just like the protected catalog, the custom catalog is composed of one or more collections, each of which can contain a combination of nested collections and templates. In contrast to the protected catalog, however, the structure and content of the custom catalog are freely modifiable. The following subsections introduce the various program features that support manipulation of the custom catalog, and describe how to use them.

Adding a New Collection to the Catalog

The Database Designer is distributed with an empty custom catalog:

Before you can begin creating your own templates, you must create at least one collection within the custom catalog. To do this, right click on the words Custom Templates displayed at the top of the catalog panel when the Custom tab is active, and choose the Add New Collection option from the popup menu that appears. Doing so will cause a dialog box to appear asking you to specify the name you'd like to give to your new collection. Once you click the OK button, your collection will be created and added to the custom catalog.

Placing a Collection within an Existing Collection

A collection can be created within an existing collection in the custom catalog. To create such a collection, right click on the name of the collection into which the new collection should be placed , and choose the Add New Subcollection option from the popup menu that appears. From there the process of adding a collection proceeds as described in the previous section.

Adding a New Template to a Collection

A new template can be created using the template editor, and stored in a collection within the cutom catalog. To invoke the template editor and begin constructing a new template, right click on the name of the collection in the custom catalog in which you'd like the new template to be kept, and choose the Add New Template option from the popup menu that appears. For help with using the template editor, see section 7

Recall there are two kinds of templates within the Database Designer: ENTITY templates and OBSERVATION templates. How do you tell the program which type of template you'd like to create? The rule is simple:

• Any template created within a collection or a sub-collection within a collection named OBSERVATIONS is an OBSERVATION template;
• Any template created anywhere else is an ENTITY template.

Copying Templates between Collections

A copy can be made of a template in either the custom or the protected catalog and placed (pasted) into a collection inside of the custom catalog. To copy a template, right click on its name within the catalog panel and choose the Copy option from the popup menu that appears. To put a copy of the template into a collection of the custom catalog, right click on the target collection's name, and choose the Paste option from the popup menu that appears. Note that an observation template can be pasted only into a collection named Observations and an entity template can be pasted only into a collection named something other than Observations.

Editing an Existing Template

Most attributes of a template in the custom catalog can be modified by reinvoking the template editor after the initial editing session has been completed. To load an existing template into the template editor, right click on the template's name in the catalog panel and choose the Edit option from the popup menu that appears.

Deleting a Template or Collection

Templates and collections can be deleted from the custom catalog. To delete a template or a collection, right click on its name in the catalog panel and choose, as appropriate, either the Delete or the Delete Collection option from the popup menu that appears.

Section 6: The Database Design Workspace

The workspace is where a database design is laid out. Templates are selected from the template catalogs, and instances of those templates are placed into the workspace. It is here also that relationships between entities and observations and among entities themselves are made clear to the application. The Data Design tab contains the workspace pane, which provides a view into the workspace that is currently being worked in. This section of the guide describes the various ways in which one can interact with the workspace through the Database Designer application.

Adding Entity Templates to the Workspace

To add an instance of a particular entity template to the workspace, double click on the name of that template where it appears on the catalog panel. After you do so, the Template Preview pane will be activated, and you'll have the opportunity to review the various attributes of the selected template. To complete the addition of an instance of the template to the workspace, click on the Add Template to Design button. If, on the other hand, you decide you do not wish to place an instance of the template after all, simply click on the Data Design tab to reactivate the workspace pane without adding the template.

The following subsections provide an overview of some of the issues you might encounter when adding an instance of an entity template to the workspace.

Entity Already in Workspace Error

At most one instance of a template with any given entity name can be present in the workspace at once. If you attempt to add to the workspace an instance of an entity template that has entity name N and an instance of some entity template of entity name N is already present in the workspace, an error dialog will be displayed, letting you know that what you have attempted to do is not allowed.

The meaning of "entity name" will now be given. Recall that in the section on relationships between entities it was stated that an entity template can have a dependency on another entity template. An entity template's entity name plays an important role in determining whether or not the template can satisfy any given general dependency possessed by another entity template. The group of templates that are capable of satisfying a particular general dependency is characterized by two pieces of information: the template collection in which the satisfying template must reside (the template may also reside in a subcollection of the collection specified), and the entity name that all candidate templates have in common. Each of the Branch templates in the protected catalog, for example, has a general dependency on something of entity name "Stem" that lives in the collection "Canopy Studies Templates/Stems". There are nine entity templates that meet these two criteria, and therefore there are nine templates that can be used to satisfy a Branch's dependency on a Stem.

An entity template's entity name also appears in the generated database as a table name, when a table is created for an instance of that template.

Auto-resolved Dependencies

In some cases, after you have told the program to add an instance of a particular entity template to the workspace, you'll notice that, in fact, more than just one entity was added. This happens when the template you choose to instantiate has a specific dependency on an entity template not already instantiated in the workspace. For example, the protected template Place, located in the General Research Templates collection, has a specific dependency on the Place_type template within the same collection. If you choose to add an instance of Place to your workspace and an instance of Place_type is not already present there, an instance of each will be added. If, on the other hand, an instance of the latter template is already there, that instance will be used to resolve the specific dependency of the newly-added Place template. A (resolved) dependency between two entity template instances in the workspace is indicated by a line drawn between their representations on the workspace pane.

Unresolved Dependencies

It is always possible for the application to automatically resolve a specific dependency by, if needed, inserting an instance of the depended-on template into the workspace. It is not always possible, however, for it to resolve an occurrence of the other type of dependency, the general dependency, when one is possessed by an entity in the workspace. This is because there usually exists more than one template that can be used to resolve a particular general dependency, and the choice of which one of those to use must be made by the user. As a result, one of two things will happen when you add an instance of an entity template with a general dependency to the workspace:

1. A template already in the workspace will be used to resolve the newly-added template's general dependency. This occurs if one of the templates in the workspace satisfies the appropriate criteria (i.e., it has the proper entity name and is contained within the proper template collection, as described above).
2. An indicator of an unresolved dependency will appear on the workspace pane. This occurs when no template instance in the workspace meets the criteria it must in order to satisfy the newly-added entity's general dependency. The indicator appears as a red rectangle, as in the picture below. Right clicking on the rectangle causes a menu to appear from which you can choose the entity template that will be used to resolve the dependency.

Built-in Observations

Some entity templates in the protected catalog come with built-in observations — observations that are automatically placed on every instance of that template in a workspace. These observations may be hidden by default (see this section for information on hiding and unhiding observations). It is not currently possible to give custom templates built-in observations by using the template editor.

Adding Observation Templates to the Workspace

Recall that an instance of an observation template in the workspace is always related to a particular entity template instance. As a result of this, you must let the program know, for each observation that you add to the workspace, which entity that observation is to be added to. You can approach this from either of two directions:

1. To add an observation to a chosen entity, right click on that entity's representation on the workspace pane and select the observation you wish to add from the Show Template... submenu available on the popup menu that appears.
2. To add an observation selected from the catalog to the workspace, double click its name where it appears on the catalog pane, then click the Add Template to Design button on the Template Preview panel. You will then be asked to select the entity on which you would like the observation to be added.

Relationship Quantifiers

Regardless of which method you use to do it, every time you add an observation to the workspace, you will be prompted to specify a relationship quantifier that further clarifies the nature of the relationship between entity and observation. The desired relationship quantifier(RQ) is selected from two options, labelled "once" and "more than once", that are presented to you on a dialog box when you move to instantitate the observation. "Once", corresponding to the word "one-to-one" in database terminology, and "more than once", which corresponds to "one-to-many", answer the question, posed by the dialog just mentioned, "How often do you plan to record this observation?". If you need space in the generated database to record the data collected for just one measurement of the attributes comprised by the DataBank observation in question, select the "once" option; selecting this option results in the simplest database. If, however, you intend to take a given observation more than once — perhaps you will record it once a day, or separately for different sections of the object under study — choose the "more than once" option, and you will have all the space you need.

Other Workspace Manipulations

There are a number of other actions that you can perform on your workspace. The following subsections describe these actions and how to perform them.

Saving and Restoring a Workspace

You can save the current workspace to disk, or restore a previously-saved workspace into the Designer by selecting either Save Workspace or Open Workspace, as appropriate, from the File menu.

Removing an Instance of a Template from the Workspace

A specific instance of an entity or observation template can be removed from the workspace by clicking on the template's representation on the workspace pane, and pressing the delete key. The same effect is had by right clicking on the template's representation and choosing the Delete option from the popup menu that appears.

Showing and Hiding an Entity's Observations

It is possible to "hide" an instance of an observation template, so that a representation of it does not appear on the workspace pane. This should be done simply to reduce visual clutter on the screen; it has no effect on the database that is generated from the workspace. To hide a specific observation instance, right click on its representation, and choose the Hide this Observation option from the popup menu that appears. To hide all of an entity's observations at once, right click on the entity's representation, and select Hide All Observations on Entity. Hidden observations can be unhidden by right clicking on their entity's representation, and choosing the Show All Observations on Entity option, or choosing from the Show Specific Observation on Entity... submenu.

Note that some built-in observations may be hidden by default.

Grouping Entities

Another way to reduce clutter on the workspace pane is to place two or more entities into a group. As with observation hiding, grouping of entities has no effect on the generated database. To create an entity group, select the representations of the entities you want to make part of the group, then press the G key, or right click on one of the entity representations and select the Group Selected Entities option from the popup menu that appears. After doing so, the green rectangles representing the grouped entities, and any blue rectangles on the workspace pane representing observations on those entities, will be gone, and in their place will be an orange rectangle representing the group. By default, this rectangle is labelled Group, but the label can be altered by double clicking on the group rectangle and editing the text in the text-entry field that appears.

To undo the grouping, select the representation of the group on the workspace pane and press the G key. Another way is to right click on the representation and select the Ungroup option from the popup menu that appears. Note that any observations on the grouped entities will remain hidden after ungrouping and must be unhidden via a separate action.

Other Manipulations

By right clicking anywhere within the empty space on the workspace pane (i.e., in space not occupied by a representation of a template, unresolved dependency, group, or connecting edge), you can access the options to erase everything from the current workspace (Clear Workspace) and to ask the program to try to find a better layout for the things on the workspace pane (Arrange Templates).

Information on the details of a specific entity template instance's template can be viewed on the Template Preview pane by right clicking on that instance's representation on the workspace pane and choosing the Show Template... option from the popup menu that appears.

Section 7: Using the Template Editor to Create and Modify Templates

• With the template editor you can create a new template or edit an existing template.
• When you click on an item on the left panel, the appropriate information-entry panel will be displayed on the right.
• Templates can be saved and placed into the custom catalog by pressing the Save button.

The Information Panel

This is the basic input form for a template.

1. Template Name, required
2. Entity Name, required, used for the table name
3. Display Name, required; must be unique, used in catalog display
4. Description, required
5. Image (Large), optional, image for template detail display
6. Image (Small), optional, image for the icon

The Attributes Panel

This is the attribute information entry form. Use it to add, edit, or delete an attribute (follow the instructions at the top of the panel). You can change the order of the attributes with the Move up and Move down buttons.

1. Name, required
2. Data Type, required; select from list
3. Unit, optional
4. Description, optional

The References Panel

This is the reference information entry form. This is where a dependency of one entity template on another is declared. Use this panel to add, edit, or delete a reference (follow the instructions at the top of the panel). You can change the order of the references with the Move up and Move down buttons.

1. Name, required
2. Catalog Type, required; select from list
3. Dependency Type, required; select from list
4. Entity Name, required; select from list
5. Path, filled in automatically, based upon value specified for Entity Name

If you have questions or comments about using the DataBank Generator please contact us. E-mail us at scidb@evergreen.edu. Also see the DataBank website at canopy.evergreen.edu/databank/ for updates to the generator and the manual.