Integration
Overview: Adding the Hierarchy to Your File
SeedCode Hierarchy is made to be used with your own files: you can teach the hierarchy about your own tiered structures and see your records within the hierarchy. You'll actually add the hierarchy code to your file so that SeedCode Hierrachy.fp7 doesn't have to be part of your solution and can be something you use just for reference: the whole hierarchy will be in your file. The following instructions will walk you through this step-by-step.
Using FileMaker Advanced?
Moving SeedCode Hierarchy into your file is much easier if you have FileMaker Advanced, since it allows you to copy and paste field definitions between files. You can integrate the hierarchy without Advanced, it is just a bit more work. So if you don't have FileMaker Advanced, consider getting a copy: you'll appreciate it. Otherwise, feel free to contact SeedCode, we can get you a fixed price to do this integration for you.
Getting Started: The Relationship Graph in Your File
1. Backup your files.
Really. ;-)
2. Create a New Table.
Create a new table in your file called "Hierarchy"; this doesn't need to have any fields associated with it yet, so just make the table and nothing else. A Table Occurrence (TO) for this will be added to your relationship graph (File / Manage / Database... and the click on "Relationships"). Create a second TO based on Hierarchy and name it "HierarchyPortal". You don't need to relate these two to anything, just leave them alone on your relationship graph.
Now create a table called "HierarchyInterface" and leave it alone on your graph as well; we'll add fields to it later.
3. Create a 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 hierarchy. (Don't worry about having multiple hierarchies at this point, you can come back to that later.) In our example we have Companies, Projects, and Tasks, and each of these is related to each other as you'd expect: Companies and Projects by CompanyID, then Projects and Tasks by Project ID. 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 hierarchy and relate your version of Companies, Projects, and Tasks 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 "HierarchyDataLevel1" (without the quotes), the next one down is "HierarchyDataLevel2", etc. You'll find a TOG like this in the relationship graph of SeedCodeHierarchy.fp7 and make sure you match the TO names used there exactly.
4. Create a Second Version of this TOG.
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 Companies TO (in our example) would be named "HierarchyPortalLevel1" (without the quotes), Projects would be "HierarchyPortalLevel2", etc. When you're done, this section of your relationship graph should look like this:
5. Pasting in Field Definitions.
If you're using FileMaker Advanced, copy all the fields from the Hierarchy table in SeedCode Hierarchy and paste them into the Hierarchy table in your file. (If you're not using Advanced you'll need to recreate the fields one at a time. If you're doing this one at a time, start with the regular fields first and then move to the calculation fields. Note that fields DisplayContentsLevel1Calc, ...Level2Calc, etc. can't be entered by hand yet: we'll tackle those in the next two steps.)
Note that the fields DisplayContentsLevel1Calc, ...Level2Calc, etc. paste over commented out (that is, they are surrounded with /* .... */). We'll fix those in the next two steps.
If you see more errors than these (i.e. more fields commented out) you may have slightly different names for your "Hierarchy" and "HierarchyPortalLevel1" etc. table occurrences. If that's the case, delete the newly pasted fields, correct the names of your TOs and try again.
Note. You'll want to double check that all the calculation fields you've pasted are defined from the correct context. (The context of a calc is shown in the "Evaluate this calculation from the context of.." menu at the very top of the calculation entry screen.) The following calcs should be defined from the context of "HierarchyPortal", the remainder from the context of "Hierarchy":
Add the fields from HierarchyInterface the same way. These are simple container globals and there are no special options to worry about with them.
6. Linking Table Occurrences: "Hierarchy Portal" to "HierarchyPortalLevel1", "...Level2", etc.
Move to the relationship graph in your file and connect the TO "Hierarchy Portal" to "HierarchyPortalLevel1" by linking "Level1KeyCalc" in "Hierarchy Portal" to the primary key field in "HierarchyPortalLevel1": in our example that would be the CompanyID field.
Continue, linking "Hierarchy Portal" to "HierarchyPortalLevel2" using "Level2KeyCalc" in "Hierarchy Portal" to the primary key field in "HierarchyPortalLevel2": in our example that would be the ProjectID field. Continue in this way until you've linked each of the "HierarchyPortalLevel..." TOs to "HierarchyPortal".
7. Linking Hierarchy to Hierarchy Portal.
Now connect Hierarchy to Hierarchy Portal, using PortalKeyGlob on the Hierarchy side, and RecordNumber on the HierarchyPortal side. Use the ">" operator so that PortalKeyGlob "is greater than" RecordNumber.
That's it. Those are all the changes you need to make to your relationship graph in order to get the hierarchy to display.
If you want to show the details of selected items as we do in Example Three, you'll go a little further. See Using Example Three for more information. (You'll want to complete steps 1 and 2 of those instructions before continuing.)
8. Editing the "DisplayContents..." Fields.
In step 5 we left a few fields that were commented out and we'll now return to fix those. Open the field definition for the field "DisplayContentsLevel1Calc" in your file and remove the leading and trailing comments (remove the /* at the beginning of the calc and the */ at the end of the calc). Now edit the field definition itself, adding the fields you'd like to see depict your level 1 record: in our example this would be "HierarchyPortalLevel1::CompanyName" (without the quotes). Note that the fields from your top level table should come from "HierarchyPortalLevel1" and that the calculation should be defined from the perspective of "HierarchyPortal".
Continue in this manner with each of the "DisplayContentsLevel..." calcs, choosing which content to display for each level. Note that you have a lot of control over the text formatting of the hierarchy, so be creative.
Layouts Part 1
9. Creating Layouts in Your File.
First, create a new layout in your file called "Hierarchy" and base it on the Hierarchy table occurrence. (This layout may have been created for you in step 1 above: if so, just delete all the fields from it so you have an empty layout and move on.) You may not end up using this down the road as you can include the hierarchy on any layout in your file, but the layout name is used in our scripts and you'll likely want to keep this layout around as a test layout for making sure the hierarchy works and making changes to it.
Next, create one blank layout for each of your data levels. These will be named "HierarchyLevel1", "HierarchyLevel2",etc. and will be based on the "data" table occurrences you created in step 3 above. So the layout "HierarchyLevel1" will show records from "HierarchyDataLevel1", etc.:
If you want to be able to create new items in your data tables from the hierarchy, you'll need to edit these layouts just a bit: on each layout, place all the key fields for that layout's table. So in our sample data you'll see that for Level2 we have two fields there, the primary key for the table ("ProjectID_kprime") and the foreign key we link to Companies ("ProjectCompanyID_kf"). Add each table's key fields to each of the "Level.." layouts and make sure the fields are enterable in browse mode.
Scripts
10. Importing Scripts.
Open ScriptMaker in your file and import all of the scripts from SeedCodeHierarchy.fp7 into your file. You'll see a couple sections of scripts within the "Hierarchy" section and you'll only need to edit the script that are in the "Data Scripts" section-- and you'll find that these edits are very simple.
Lastly, if your file doesn't have a script that runs on file open (Fie / File Options), you can use the "Upon Opening" script you imported from the Hierarchy. If you already have one, add a Perform Script line to your opening script to call ours at some point. You may want to delete these last two PerformScript() lines from our "Upon Opening" script if you're not showing the hierarchy right away.
Layouts Part 2
11. Pasting in the Hierarchy Layout.
Now that you've got all the necessary scripts in place, you're ready to add the contents of the Hierarchy layout (from Example One, Two, or Three). Select all of the layout elements from the Hierarchy layout in SeedCodeHierarchy.fp7 and then move to the Hierarchy layout in your file, removing the Header and Footer parts, if any. Then paste the layout elements into your layout. Don't worry if it doesn't look quite right or work yet: it won't until we import the interface records in the next step.
If you want to filter the hierarchy as we do in Example Two, you can copy the whole "begins with..." blue pill from our Example Two layout and paste that on to your layout as well. If you're interested in using example three you can move on to that and copy it's layout elements after you complete the next step below.
Almost Done: Importing Records
12. Import the Hierarchy's Interface Records.
The hierarchy uses 5,001 place holder records to depict the records in your tables. These record's aren't data per se, and they don't take up much room. You'll need to import these records into your file in order to get the hierarchy working, and to bring the hierarchy's interface to life.
From the Hierarchy layout in your file, select "Import Records... / File" from FileMaker's File menu and select SeedCodeHierarchy.fp7 as the file to import from. Make sure the table on the left side of the import (the SeedCode Hierarchy side) is set to use the Hierarchy table, and that the import order is set to use "matching names". Then import the 5000 records, marking the "perform auto enter..." checkbox as yes.
When you created your HierarchyInterface table, FileMaker added a layout for this to your file. Navigate to that layout and select "Import Records... / File" from FileMaker's File menu and select SeedCodeHierarchy.fp7 as the file to import from. Make sure the table on the left side of the import (the SeedCode Hierarchy side) is set to use the HierarchyInterface table, and that the import order is set to use "matching names". Then import the 1 interface record.
That's it! Your hierarchy is all set to go. Click the "show hierarchy" button to load your records and then have fun! If you want to take advantage of the features in Example Three, you need to add a couple more things to your file and can continue your integration here: using example three.
