Blackboard Navigation Item Reference

Navigation Items are used by Blackboard to create all the menu links and entries in caret lists. You can also use them in Building Blocks.

All the navigation items in the system, for both core Bb functionality and for Building Blocks, are stored in the NAVIGATION_ITEM table. It's worth having a look in the database if you're interested in using this functionality.

Configuring Simple Navigation Items in your bb-manifest file

To create a navigation item handle you need to ensure you set a handle attribute on your application links in bb-manifest.xml. In the example below, the link handle is set to helloworld.

<application handle="myapp" type="course" name="plugin.tool.title">
    <description>plugin.tool.description</description>
    <links>
        <link>
            <type value="course_tool" />
            <name value="plugin.link.helloworld.name" />
            <url value="HelloWorld.action" />
            <handle value="helloworld" />
            <description value="plugin.link.helloworld.description" />
        </link>
    </links>
</application>

The full Navigation Item reference for this Application Link, would be: myu-myapp-nav-helloworld

This is made up of the following parts vendor id-application handle-nav-link handle

Referencing them in your JSP pages

Once you have the full Navigation Item reference, you can use it in your JSP page as follows.

<bbNG:learningSystemPage ctxId="ctx" navItem="myu-myapp-nav-helloworld">
</bbNG:learningSystemPage>

when you do this, you no longer need to specify the page title, or navigation bar in the bbNG page tags. The information will be automatically picked up from your bb-manifest.xml file.

Sub-navigation and Caret Lists

If you need more complex navigation in your Building Block, you can specify multiple links which then refer to each other.

In the following example, there is a parent navigation item and two children. The navhandle attribute of the parent is set to "", and the children refer to the parent.

<application handle="mySystemToolApp" type="system" name="My System Tool Application">
    <description lang="en_US">My System Tool Application</description>
    <links>
        <link>
            <type value="system_tool"/>
            <handle value="landing"/>
            <navhandle value="" />
            <name value="Main Navigation Item"/>
            ...
        </link>
        <link>
            <type value="nav_handle_param"/>
            <handle value="configure"/>
            <navhandle value="myu-mySystemToolApp-nav-landing" />
            <name value="Sub Navigation Item"/>
            ...
        </link>
        <link>
            <type value="nav_handle_param"/>
            <handle value="doSomethingElse"/>
            <navhandle value="myu-mySystemToolApp-nav-landing" />
            <name value="Sub Navigation Item Two"/>
            ...
        </link>
    </links>
</application>

When you use this in a bbNG page tag, the breadcrumbs will be populated for you automatically.

You can also create a Blackboard caretList page with the following JSP

<bbNG:genericPage ctxId="ctx" navItem="myu-mySystemToolApp-nav-landing">

    <bbUI:caretList 
        navItem="myu-mySystemToolApp-nav-landing" 
        sortItems="true" 
        numberOfColumns="2"/>

</bbNG:genericPage>

Inserting your links into Blackboard's navigation

You can use these same concepts to insert your Building Block's links into Blackboard's pre-defined navigation. You simply need to know the Navigation Item reference of the Blackboard Navigation element.

As an example, if we wanted to insert a link into the Users and Groups menu in the course control panel, we could use the following link in bb-manifest

<link>
    <type value="nav_handle_param" />
    <subgroup value="users_group" />
    <handle value="myToolHandle" />
    <navhandle value="course_top" />
    <name value="My Course Tool" />
    <url value="MyTool.action?course_id=@X@course.pk_string@X@" />
    <description value="A Description for my tool" />
</link>

You can investigate Blackboard's navigation items by poking around in the Blackboard database, especially the NAVIGATION_ITEM table.