How Does the Hierarchy Determine Which Top-Level Records to Show?
The script "Build Found Set for Top Level { Show }" controls which top level records show up in the hierarchy. This script basically performs a "Find" in your Level 1 table and uses the found set of records as the top level. The script determines which records to show based on a script parameter called "Show". Sometimes you'll probably want to find All your top level records which is the default and you can just leave "Show" blank and call the script "Build Found Set for Top Level { Show }" without doing anything else.
However, if you have a lot of records in your top level, you may want to restrict these so you're not looking at a hierarchy that is thousands of rows long. (The hierarchy supports displaying up to 5,000 rows, but your users probably don't want to scroll through that many.)
For example, if your top level represents Companies, you may only wish to see your companies with active projects. Or, if your top level represents Products, you may only wish to see products that are in kits. In both cases you'll "filter" the hierarchy to show just the top level contents you want. (Example Two of SeedCode Hierarchy illustrates this kind of filtering, using the company name as an example.)
You'll use the "show" attribute of the "Build Found Set for Top Level { Show }" script to restrict the top-level records to just the ones you're interested in. The parameter "show" can be sent to the script as a script parameter, but you'll most often "send it" by setting a global variable called "$$Hy_Show" (without the quotes) to the same value as you'd send the script parameter. The easiest way to do this is in the "Filter Hierarchy" script itseld, and you can see how we do that within the script.
While you can expand upon this, the following are the currently accepted values for "Show":
All -- Shows all top level records and this is the default if $$Hy_Show is empty and no script parameter is sent.
Any Number -- Send any number to show just that number of top level records. This is really only useful when demoing and testing the hierarchy so you can play with both large and small hierarchies. This is how we show 15 or 300 records for example.
Filter -- If you send "Filter" (without the quotes) in the script parameter or in $$Hy_Show then the hierarchy will search your top level records for the contents of the field FilterGlob in the hierarchy table. You'll modify the script "Build Found Set for Top Level { Show }" so that is searches the correct field in your table (our
integration notes discuss this in step 10). The script "Filter Hierarchy" we use in Example Two current sets the global variable $$Hy_FilterBy to "Name". You can branch the script "Build Found Set for Top Level { Show }" to accept other values instead of "Name" and you'll see an example already there where $$Hy_FilterBy = "Something Else."
Note that the "Set Default Contents" script of SeedCode Hierarchy sets value of $$Hy_Show to "15". You'll want to change or remove this if you import our "Upon Opening" script into your file.
Now, if you use the filtering option, you'll be able to restrict which top level records show up, however, in the following levels you'll see ALL the related records for each top level record. So if you filter to only show companies with active jobs, you'll see ALL jobs for each company shown unless you go further and restrict the 2nd level records as well. Instructions for doing so follow.
How can I restrict which 2nd and 3rd level record show up? What if I only want to see *active* jobs for my companies, when companies are the top level?
You have two options for filtering records other that the top level records.
In Relationships.
You can edit the Hierarchy Data relationships (the ones between HierarchyDataLevel1 and HierarchyDataLevel2, etc.) so that instead of showing all related records they only show some related records. For example, if level 1 were Companies and level 2 were Jobs, you could edit the relationship between HierarchyDataLevel1 and HierarchyDataLevel2 so that the relationship were only true for a company's *active* jobs, something like this:
CompanyID_kprime = JobsCompanyID_kf
CommonOne = JobActive
(where CommonOne is a calc equal to 1 and JobActive is a number field containing a 1 when the job is active.) The only disadvantage to this method is that you'll always see just the active jobs, since the relationship can't be changed on the fly. (Unless you use a relationship whose contents can be changed on the fly.)
In Scripts.
Though somewhat more complicated, you may find more flexibility doing this in scripts. You can edit each of the scripts that build the hierarchy so that they only see the related records you wish them to. You have to address this in two places: first, where we determine if there are related records, and then when we write them to the hierarchy.
Begin by editing the script "Build Hierarchy Level 1". You'll see a comment which begins "Is there a child of this Record?..." You'll need to change the following SetVariable line so that it only returns a 1 if there are related records you wish to see (as opposed to any related records, which is how it works now.) Following our example of "active" jobs, you might change the SetVariable calculation to this...
Not isEmpty ( List ( HierarchyDataLevel2::JobActive ) )
...which would return a 1 if there are any active jobs for that company. You'll need to change this for each of the levels you wish to restrict on this way. And note that you can branch this calculation to look at a global field or global variable for instructions. For example, you may have a global variable that says "all" or "active", meaning which kinds of jobs to show. In that case your calc would look like this:
Case (
$$ShowJobs = "all" ;
Not IsEmpty ( Evaluate ( "HierarchyDataLevel2::" & $$Hy_IDFieldNameLevel2 ) ) ;
$$ShowJobs = "active" ;
Not isEmpty ( List ( HierarchyDataLevel2::JobActive ) )
)
Next, edit the build script for the level you're restricting. In our example this is level two (where projects live), so we'd edit the script "Build Hierarchy Level 2 { Open All }". You'll see a loop within this script. Right inside the loop add an If() statement that only executes the contents of the loop if the record should be shown: in our example this would be if the job is active. So our loop would now look like this:
Loop
If ( JobActive = 1 ) <-- This is a new line.
#Record the ID of the Level 2 Record
< script continues >
End If
#
End If <-- This is a new line.
Go to Record/Request/Page [Next; Exit after last]
End Loop
Note that we put the new End If before the Go to Record Request step. That's it.
