SeedCodeHierarchy

Multiple Hierarchies

How can I use a second (different) hierarchy somewhere else in my solution?

You can use what we call "multiple hierarchies" to this. Multiple hierarchies let you show records from one set of tables in one case, and from another set of tables at other times.

Demo

Your can also check out "SeedCodeHierarchyMultiples.fp7" which you can find inside the Extras folder you downloaded with SeedCode Hierarchy. Example Four in this file demonstrates multiple hierarchies. If you've purchased SeedCode Hierarchy, you can open up the relationship graph in this file to see how a graph set up for multiple hierarchies looks.

Overview

Remember, the hierarchy is looking at a section of your relationship graph to draw the hierarchy. And in that section of the graph (that Table Occurrence Group, or TOG), there is a single table defined as the top level table (level 1). In our sample date this table contains company records.

But what if you have another occasion where you want to show the hierarchy-- perhaps another layout-- but in this other situation, you want the hierarchy to show a completely unrelated set of data: you don't want companies at the top level, but something else. That is what multiple hierarchies are for: they let you look at a second (or third, or fourth, etc.) section of your relationship graph (a second TOG) to draw a different hierarchy.

When using multiple hierarchies, all hierarchies use the same portal and all the same code and scripts. You just tell the scripts which hierarchy you'd like to use via the use the "Use Hierarchy ( Number )" script in SeedCode Hierarchy.

Note that these multiple hierarchies won't let you see two different hierarchies at the same time, ether beside each other on the same layout, or in different windows that are open at the same time. That is one of the limitations of SeedCode Hierarchy: you can only view one hierarchy at a time.

Integrating Multiple Hierarchies

1. Backup your files. Make sure you have a basic integration working for a single hierarchy, then backup your work before continuing. You'll be editing some new areas of the hierarchy-- areas you didn't have to work on when getting your first hierarchy up and running. This is kind of a peek under the hood, but once you get a second hierarchy working, you'll be able to add a third or fourth much more quickly.

2. Creating new "data" table occurrences.

You'll essentially be duplicating all of the "...Data..." and "...Portal..." table occurrences you created when first integrating the hierarchy. And you'll be connecting these to HierarchyPortal the same way. But you'll point them at different data tables in your file and you'll be naming them a bit differently. You can get an idea of where we're heading by taking a look at this example: the table occurrences in brown are the ones you'll be adding to enable multiple hierarchies. We only show 3 levels here, but your second hierarchy can have up to five levels, just as your first one can.

Begin in the "data" section by creating representation of your data on the graph. Create new table occurrences on your relationship graph to represent the data you'd like to see in the top level of your new hierarchy. In our example second hierarchy we have Brands, Makes, and Models of cars, and each of these is related to each other as you'd expect: Brands and Makes by BrandID, etc. You may already have a section of your relationship graph which depicts this "natural" relationship between your tables, but you'll need a separate one for the hierarchy.

So make a simple Table Occurrence Group (TOG) for use in the 2nd hierarchy and relate your version of Brands, Makes, and Models to each other as naturally as possible, even if you're using self-joins or join tables. Then, rename the table occurrences so that the top-level TO (Companies in our example) is named "Hierarchy2DataLevel1" (without the quotes), the next one down is "Hierarchy2DataLevel2", etc. Note that these names are the same as the names in your first hierarchy, except that we are placing a 2 in between "Hierarchy" and "Data".

SeedCode Hierarchy supports any number of hierarchies, so if you're making your 9th, use a 9 between "Hierarchy" and "Data" instead of a 2.

4. Create a Second Version of this TOG: the "portal" table occurrences.

Now create a second version of this TOG in your graph. The table occurrences in this second group don't need to be related to each other but I usually begin by drag-copying the first group, renaming the TOs, and then deleting the relationships between them. The names of the TOs in this group will be similar to those in the first group, but instead of the word "Data", they'll use the word "Portal" so that the Brand TO (in our example) would be named "Hierarchy2PortalLevel1" (without the quotes), Makes would be "Hierarchy2PortalLevel2", etc.

Keep checking in here to make sure you're naming these TOs exactly the same way we are. If that image is too hard to read, check out the relationship graph in our example file "SeedCodeHierarchyMultiples.fp7" in the Extras folder of SeedCode Hierarchy.

5. Create new layouts.

As you did in the first hierarchy, create one blank layout for each of your new hierarchy's data levels. These will be named "Hierarchy2Level1", "Hierarchy2Level2",etc. and will be based on the "data" table occurrences you created in step 3 above. So the layout "Hierarchy2Level1" will show records from "Hierarchy2DataLevel1".

If you want to be able to create new items in your data tables from this second hierarchy, you'll need to edit these layouts just a bit: on each layout, place all the key fields for that table. So in our sample data you'll see that for the layout Hierarchy2Level2 we have two fields there, the primary key for the table ("MakeID_kprime") and the foreign key we link to Brands ("MakeBrandID_kf"). Add each table's key fields to each of the "HierarchyLevel.." layouts and make sure the fields are enterable in browse mode.

6. Scripts.

You'll have to edit a few scripts to get the second hierarchy working with the same features as the first one. Most of these edits involve scripts you don't have to edit when you just integrate one hierarchy, but these scripts now require additional Go To Related Record statements since we have a second set of table occurrences to deal with. Don't worry: this list isn't as bad as it seems. And remember that you can check with the example file "SeedCodeHierarchyMultiples.fp7" that came in the Extras folder with your purchase; use this file as a reference if you're not sure what to do in the notes that follow.

If you intend to filter the second hierarchy, edit the script "Build Found Set for Top Level { Show }" and find the comment "Filter by different fields if necessary." A bit below that you'll see a comment beginning "Specify the field you'd like to search in a second hierarchy...". Change the following SetField step to search whichever top-level field in your second hierarchy you'd like to use as your filter. In our example this is "Hierarchy2DataLevel1::BrandName".

Edit the sort scripts. Each of the scripts like "Sort Level 1 Records" has a section for sorting a second hierarchy: add your own Sort Record script step in that section and sort by a field in the appropriate level. For example, in the "Sort Level 1 Records" script, you'd sort by something in "Hierarchy2DataLevel1" like "Hierarchy2DataLevel1::BrandName".

Edit the script "Go to Item". You'll see that this script has a comment beginning "You're using hierarchy number 2." Each of the levels there has a comment describing the kind of Go To Related Record script step you need to add. You can copy the ones from the first hierarchy section above to get started, but read these comments carefully and add the Go To Related Record script step that each describes.

Edit the script "Open Close ( Level )" and look again for the comment "You're using hierarchy number 2." As in the script above, you'll see a single comment following that describing the Go To Related Record script step you need to add. You'll need to add one of these Go To Related Record script steps for each level: you can see where level 2 is, for example, because it is after "Else If [$Hy_Level = 2].

Edit the script "Build Hierarchy Level 1". Look for the comment "You're using hierarchy number 2." As in the script above, you'll see a single comment following that describing the Go To Related Record script step you need to add. That is the only change you need to make to this script. But you will need to make a similar change to each of the "Build.." scripts for which you have a level in your second hierarchy. So do the same to "Build Hierarchy Level 2 { Open All }", "Build Hierarchy Level 3 { Open All }", etc.

Finally, edit the script "Reveal Item in Hierarchy ( ID ) { Use Hierrachy }" and look for the comment "You're using hierarchy number 2." As before you'll see a single comment following that describing the Go To Related Record script step you need to add. And, as with the script "Open Close ( Level )" above, you'll have to do this once for each level in the script: look for lines like "$$Hy_SelectedItemLevel = 3" set off by white space to indicate where each level starts.

7. Expanding Field Definitions to Display Information from your Second Hierarchy.

You'll have to edit the "DisplayContentsLevel__Calc" fields in the Hierarchy table when you employ more than one hierarchy. Fortunately these fields are already prepped for additional hierarchies. You'll need to edit each each of the 5 calc fields, but begin by taking a look at "DisplayContentsLevel1Calc". You'll see a line there which looks like this:

; // ####### Hierarchy number 2. Use fields from Hierarchy2PortalLevel1...

Immediately after that, add a new line that contains the formatted fields you'd like to show from the first level of hierarchy 2. In our example file, where we're showing Brands as the first level, we use this...

TextStyleAdd ( Hierarchy2PortalLevel1::BrandName ; Bold )

...but you can show any field(s) from Hierarchy2PortalLevel1 (or from any TO attached to Hierarchy2PortalLevel1 for that matter). Continue working through "DisplayContentsLevel2Calc", "DisplayContentsLevel3Calc", etc. for each level for which you have a record in the 2nd hierarchy.

8. Tabs on Example Three.

If you're letting users create and delete records from the hierarchy as we demonstrate in example three, then you'll want to edit the tabs in the right half of the Example Three layout so that some of these tabs apply to your second level hierarchy.

Now it could very well be that you won't have hierarchies 1 and 2 using the same layout as we do in our example file, but even if you have a separate tab controller for your second hierarchy, you'll still need to edit the tab names and place fields from your 2nd hierarchy table occurrences on the tab control.

Step no. 3 here shows how to get at the tab control on Example Three. Once you can edit the tabs you'll want to create new tabs for each level in your hierarchy. So, if you have 3 levels in hierarchy 2 you'll create three new tabs. The tab's name isn't important, but the object name of each tab is very important. The first tab of hierachy two-- the top level tab-- should be named "2.1" without the quotes. The second level tab would be 2.2, etc. Check the tab control in our example file "SeedCodeHierarchyMultiples.fp7" for reference.

Once these tabs are created, add fields from your 2nd hierarchy tables to them. Use fields from "Hierarchy2PortalSelectedItemLevel___" in all of these new tabs.

Going further, we also use object names to indicate which of these fields your cursor should land on when creating a new item. So, enter layout mode and select the field you'd like users to be placed in when the create a top-level record in your 2nd hierarchy (this should be on the tab with an object name of 2.1). Assign this field and object name of "Level2.1FirstField" without the quotes. Do the same with the main fields on each of the 2nd hierarchy's tabs here: the 2nd level's main field would be named "Level2.2FirstField" without the quotes.

(To edit an object's name, select the object in layout mode than select "Object Info" from FileMaker's "View" menu. You'll then see a small floating pallet where you can edit the object name. For tabs, remember you're naming the individual tab, not the group of tab objects.)

Switching Hierarchies

You can easily switch hierarchies by calling the script "Use Hierarchy ( Number )" and sending the number of the hierarchy you're interested in as the script parameter. This can be called from any layout (that is, you don't have to have a hierarchy visible to do this). You'll see an example of this script in action on the Example Four section of our example file "SeedCodeHierarchyMultiples.fp7".