Custom Navigation

Custom NavigationProblem

  1. Teachers want to upload documents for themselves, but Options > Add is not available.
  2. Teachers want to see Student Journal entries across all students…but there’s no screen for this.
  3. Specialists would like a convenient way to see all 504 plans for a school, or across the district.

These are just three examples of what Aspen’s Custom Navigation feature can do to eliminate what previously was either impossible or less than ideal.

In this post, you’ll learn how to import solutions to these problems, and begin to get familiar with this incredibly powerful feature.

What is Custom Navigation?

We’re all familiar with the ways we can customize Aspen to match our district’s unique needs:

  • User-defined fields
  • Templates and Field sets
  • Custom reports, procedures, imports, and exports
  • Extended data dictionaries
  • Workflows and forms
  • Calculated fields, validation rules, etc., etc

With Custom Navigation, though, Aspen has opened the door to making your own:

  • Top tabs
  • Side-tabs
  • Side-tab groups

This is really huge!

At Boston Public Schools, after introducing a few custom side-tabs, we’re getting great suggestions from users for other places to put information so that it is more logically organized and intuitive from their perspective.

So I’m sold already…how do I do it?

Creating a new top tab or side-tab from scratch is fairly technical, but fortunately we can import one just as easily as a report, procedure, import, etc.

Let’s go through the basics of importing a custom navigation file, and then we’ll dig into a few of the details. I’ve provided a ready-to-import custom navigation definition that you can download in Step 2 of these instructions.

Importing a Custom Navigation file to create a “My Files” side-tab for Staff that allows them to upload their OWN documents.

1. First, navigate to District view > Admin tab > Custom Navigation to see where you’ll manage these.
Custom Navigation
2. Next, import the user-defined navigation file to create a new “My Files” side-tab in the Staff view.

Click Options > Import and select the file.

Import Custom Navigation File

Select Analyze on the top-right of the screen, and if all is well, you can select Import at the bottom left.

3. You should now see a record in your list, and when you select it, you should have the following in the Details screen:

Custom Navigation - My Files details

4. The last thing to do is Reload Navigation, which is akin to reloading the Data Dictionary. Doing this loads the navigation definition as well as any resource keys / values.

Reload Navigation

5. Now, when you switch to the Staff view, you should see your new side-tab AND anyone with the Staff role should be able to see it as well as Add and Delete records!

My Files screenshot from Staff view

NOTE: When you make changes to a Custom Navigation definition and then select Reload Navigation, you may need to change your views (or log-off and back on again) to see those changes. It depends on the kind of a change you’re making whether you can just refresh your screen, or if you need to exit and then re-enter the view.


Two Gotchas

When you get to your new side-tab, you’ll notice two things:

  1. There is no Field Set!
  2. There is no Template for the detail page!

These are easily put in place, thankfully.

For the field set, create a new one called Default Fields, making sure to set the owner type to District.

For the template, make a copy of your existing template for Staff Documents from the District or School view (context = staff.staff.list.doc.detail). On the copy, change the context to be your new side-tab, which has a navkey of mystuff.myrecord.staff.file. Finally, add “.detail” on the end to complete the entire context for the template:


Pretty cool, right?

Sure, but you promised 3 of these. I’ve only seen 1 link so far!

Yes, of course. Here are the other two:

For both of these, you’ll need to handle the 2 Gotchas above, creating a field set and copying a template. You’ll also need to add a “Student Name” field to the top of the template, since in the regular templates, the student is selected above, which isn’t the case in these new side-tabs.


Wonderful, but I don’t like to use things I don’t understand

I totally agree! Let’s try and break these down a bit.

There are six parts to a custom navigation entry:

  1. Position
  2. Parent navigation ID
  3. Definition
  5. Resources
  6. Security — read this one if you don’t read any other
Position This is where the tab or side-tab will show up relative to other tabs.

  • To put a custom tab before all others, use position 0.
  • If you enter 99, you can ensure your custom tab will be at the end (or bottom).
  • If you want your tab in between two existing tabs, you’ll need to login with a System Administrator user and count ALL the possible tabs (including opening up grouped tabs).
  • If you want your tab to be in between the 3rd and 4th tabs, make it position 3.
    1. In the event that two tabs have the same position, built-in tabs seem to be rendered above custom ones.
    2. In the event that two custom navigation tabs have the same position, the most recently created (or imported) one seems to be rendered above the older one.
Parent navigation ID This one is a bit tricky, as it varies a bit.

  • For adding a top-tab, this is root
  • For adding a side-tab, there are two answers:
    1. For top tabs like Student, Staff, My Info, Gradebook, etc.
      • You always select a record first, and then all the side-tabs are related to that initially selected record
      • A custom side-tab under one of these top tabs, the parent navigation ID is the full navkey (aka context) of the top tab:
    2. For tabs like District, School, Attendance, Conduct, etc.
      • Side-tabs under these are independent of one another. In other words, selecting a record in one list doesn’t filter what you see in a different list.
      • For a custom side-tab under one of these top tabs, the parent navigation ID is just the first part of the navkey:
Definition This is where it gets quite technical.

The definition is an XML description of:

  • Records (table) to display
  • Options menu items
  • Filters to make available to users
  • Sort order, and
  • Detail page settings

The degree of difficult of these makes creating one from scratch pretty challenging (at least for me), but as more and more of us are familiar with them, we should be able to share them around and people can start making their own by comparing and customizing examples.

Views Ah…an easy one! Just check the boxes where you want your custom navigation to display.
Resources These seem hard at first, but the great thing is that if you are missing something, Aspen will tell you exactly what is missing.

You can see in our example that we have entries for:

  • node.mystuff.myrecord.staff.file.description
  • node.mystuff.myrecord.staff.file.detail.description

The ones that end in “name” are what shows up in the navigation, and the ones that end in “description” are the hover text when you position your mouse over the tab.

But, if you’re confused by this, here’s what happens when you create a new side tab and forget to make your resources:

Resources missing

This tells me I need entries for the following:


I’ll also need one of each of those that ends with “description” instead of “name” for the hover text.

After entering these (with en_US as the locale) and then Reloading Navigation, my screen looks like this:

Resources added

Security  This is not directly on the Custom Navigation, but rather in the place you’d really want it to be…under Security Roles!

When you create a new top tab or side-tab, it will show up in the Navigation sub-tab for all your security roles.

It will be there by default for any security role with read permissions to the base table.

For the example of 504 Plans, it will show up by default for any role with read permissions to the Student Ed. Plan table.

Custom Navigation Security

If you don’t want a particular user role to see this new tab, just remove it for them.

And lastly, if you have tons of security roles and want a quick way to see which ones will get this new tab by default, create and save the following direct SQL query on your Roles side-tab:

 AND SUP_PRIVILEGE_ID = '{prompt:supPrivName}'

When you run the query, use in the prompt.
> “sep” is the prefix from the Data Dictionary for the Student Ed Plan table. You can use this with any table just by substituting that table’s prefix.

Unfortunately, this post turned out to be even longer than my first one. I’ll endeavor to create a short one at some point.

Happy Customizing!!

Leave a Reply