We've had our Navigation APIs for a while and this morning we just added some more functionality, so I figured it's a good time to give an overview of what our Navigation APIs are and how you can use them.
The Navigation Menu API lets you do the following things.
- Use the same navigation menu in different areas of your website but display it differently each time.
- Pull just sub-navigation items into a different part of the site and optionally display it using a different navigation template.
The Navigation Item API lets you do the following.
- Get the information about a single navigation menu to do things like loading content into an iframe.
Navigation Menu API
They way that you use the Navigation Menu API is to customize the Navigation Menu API Tag that is used to show the navigation menu.
A basic Navigation Menu API Tag looks like this: {ap_navigation:left} .
It's important to note that you don't need to customize the Navigation API Tag if you only want to show the default navigation menu information
Below are the different parameters for the Navigation Menu API Tag
templateId
The numeric ID of the Navigation Template to use.
Example: templateId="3"
parentId
Show only the sub-navigation items for the item with the specified ID.
Example: parentId="4"
getParentItem
Whether or not to include the parent navigation item when getting sub-navigation items.
Example: getParentItem="true"
Example Tag
{ap_navigation:left templateId="5" parentId="3"}
The above tag will only show the sub-navigation items for the navigation menu with an ID of 3 using the Navigation Template with an ID of 5.
Navigation Item API
With the Navigation Item API you can retrieve just a single Navigation Item.
A use case scenario might be if you wanted to load external links in a navigation menu in an iframe. You could change the link URL to go to a specific page that has the iframe on it. The URL would contain a query parameter like that passes through the navigation item id. You could use this API to retrieve the navigation item details and build the iframe code.
Basic Tag {ap_api:site:navigation:getMenuItem itemId="1" templateId="1"}
Required API tag parameter
itemId
The numeric ID of the Navigation Item to work with.
Example: itemId="3"
Optional API Tag Parameters
templateId
The numeric ID of the Navigation Template to use.
Example: templateId="3"
This is needed unless the responseFormat parameter is data
responseFormat
The format to return the API call.
Example: responseFormat="data"
Values: "data" or "template"
data: Will return the Navigation Item as an array. Example: {#nav|setApi call="site.navigation.getMenuItem" itemId="1" templateId="12" responseFormat="data"}
template: This the default value and shouldn't need to be set. This tells the system to use the specified Navigation Template to build the response.
Summary
When we're building sites we'll try to keep the number of Navigation Menus to a minimum. Usually any sub-navigation that shows in the primary navigation menu will also show in the secondary navigation. In those cases it's easier to just use the Navigation Menu API to pull in the sub-navigation that's necessary and use a different navigation template to display them.