CodeCharge StudioThe directory form is specifically intended for displaying hierarchical content. The content that is displayed in a directory form is stored by top level items which have subsequent sub categories. The directory form implements a drill down of information starting from parent categories and proceeding to successive subcategories. A good way to conceptualize the directory form would be to think of the yahoo site directory or the directory of most search engines.
The Directory Builder is the fastest and easiest way to create directory forms. Before you begin you must have a database connection in your project which contains a table configured according to the specifications in the above section. To begin creating the form, click the Directory Builder option under the Builders tab of the Toolbox.
A directory form is composed of two main components that operate synchronously to provide ease of navigation. The first component is a Path which displays the sequences of categories that are currently being displayed by the second component, the Directory.
The directory form imposes certain requirements on the design of the database table that will contain information to be displayed in the form. While the table can contain as many fields as the user requires, there are three specific fields that must be present:
| Parameter | Description |
|---|---|
| Category ID | Each item displayed in the directory form must have a category ID field that uniquely identifies the category. In other words, the category ID field must be the primary key field for the table. |
| Category Name | Along with having a category ID field for identification, each category must also have a name field that contains descriptive text for the category. |
| Parent Category | Since the directory form displays hierarchical content, the table must have a field that indicates the parent category to which each category belongs. In this parent category field top level categories are marked using a special value such as zero. For all other categories that belong to a higher category, the parent category field is populated with the category ID field of the parent category. Each category that is not a top level category must have a value in its parent category field pointing to the category to which it belongs. |
You don't have to use any particular name for any of the above fields but they must exist in the table since you will be required to identify them during the process of building the directory form.
The Path consists of links which the user can click on to navigate to specific points in the hierarchy of categories. The value of the Path changes according to the links that the user clicks in the directory form. As the user navigates deeper into a hierarchy, the Path adds links to all the categories leading up to the present category.
The properties for a Path can be exposed in the Properties window by clicking on the name of the Path in the Project Explorer window.
| Property | Description |
|---|---|
| Name | A unique name for the Path component. |
| Connection | Database connection used by the component. |
| Source Type | Type of database resource that provides the data for the Path. |
| Data Source | Table, SQL query or stored procedure that provides the data for the Path. |
| ID Field | Database field which contains the ID of the categories displayed in the Path. |
| Parent Field | Database field which contains the Parent ID of the categories displayed in the Path. |
The Path component is composed of two Link fields and one Label field.
The properties of the directory form can be exposed in the Properties window by clicking on the name of the form in the Project Explorer.
| Property | Description |
|---|---|
| Name | A unique name for the directory form. |
| Connection | Database connection used by the form. |
| Source Type | Type of database resource that provides the data for the form. |
| Data Source | Table, SQL query or stored procedure that provides the data for the form. |
| Category ID Field | Database field which contains the ID of the categories displayed in the Path. |
| Subcategory ID Field | Database field which contains the ID of the subcategories. This is essentially the same as the Category ID field but the field comes from an alias table. |
| No. of Columns | Directory form displays categories in columns. Use this property to set the number of columns to be used. |
| No. of Subcategories | Each category in the directory form can have a number of subcategories. This property limits the number of subcategories that could be displayed. A link is provided to access extra columns if they are more than the limit. |
| Restricted | Specifies whether a user has to be authenticated in order to view the form. |
The Data Source for the directory form is based on a join query that matches the category ID field against the Parent Category ID field of the same table. As you can seen in the Visual Query Builder screenshot below, the same table (yp_categories) is used, albeit with two different aliases (cat and sub). The relationship between the table aliases is formed by the category_id field in the first table and the category_id_parent field in the second table.
The main components of the directory form are three Link controls.
