API Navigation Items

A navigation item can include content from an app by using an app API as the item content. For example, you could automatically include store category links in your navigation sidebar by setting the Item Type field to "API" when adding a new navigation item. You could then enter the store category filter API tag in the API call field.

The API tag would be just like the API tag that you would use to show categories on a page. The difference between using an app API tag on a page and using it as a navigation item is how the API template is set up.

API Template

The goal of the API template is to return data in a format that could be used to build navigation items. The navigation system needs the data returned back in a specific format. Below is a very simple example of displaying store categories.

{% for category in categories %}
    {% set item = {
        url: category.url,
        linkText: category.categoryName
    } %}
    
    {% if category.subCategories %}
        {% set item.subs = [] %}
        {% for sub in category.subCategories %}
            {% set subItem = {
                url: sub.url,
                linkText: sub.categoryName
            } %}
            {% set item.subs = item.subs|merge([subItem]) %}
        {% endfor %}
    {% endif %}
    
    {% do set_api_navigation_item(item) %}
{% endfor %}

Essentially what is going on above is that we're building an object to hold the navigation item data.

In this example, we're also setting up some sub navigation by storing sub categories as an array in {{ item.subs }}.

Once all of the values have been set for an item in the {{ item }} variable (you could actually use any variable name that you want), the {{ item }} object gets added to the navigation item data through this line of code:

{% do set_api_navigation_item(item) %}

Navigation item values

Below is a full list of the values that can be set for each navigation item. The "Key" is the object key name. For example, to set the value for the URL you would do:

{% set item.url = category.url }}

At a minimum you need to set the following values:

  • url
  • linkText
Key Description
activeImage

Only applies if an image is being used to display the navigation item instead of plain text.

The image path to use if the navigation item is the current navigation item.
anchor

The value to use if the link is an anchor link.
appData

An array of miscellaneous information that can be passed to the navigation template for an individual navigation item.
cssClass

The "class" attribute value for the link tag.
cssId

The "id" attribute value for the link tag.
defaultImage

Only applies if an image is being used to display the navigation item instead of plain text.

The image path to use if the navigation item is not the current navigation item or a current parent navigation item.
email

The email address to use if the link is an email link.
emailBody

The email body if the link is an email link.
emailSubject

The email subject if the link is an email link.
hoverImage

Only applies if an image is being used to display the navigation item instead of plain text.

The image path to use when hovering the navigation item.
imageAlt

Only applies if an image is being used to display the navigation item instead of plain text.

The value for the "alt" attribute on the image tag.
imageBorder

Only applies if an image is being used to display the navigation item instead of plain text.

The value for the "border" attribute on the image tag.
imageClass

Only applies if an image is being used to display the navigation item instead of plain text.

The value for the "class" attribute on the image tag.
imageId

Only applies if an image is being used to display the navigation item instead of plain text.

The value for the "id" attribute on the image tag.
imageName

Only applies if an image is being used to display the navigation item instead of plain text.

The value for the "name" attribute on the image tag.
imageTitle

Only applies if an image is being used to display the navigation item instead of plain text.

The value for the "title" attribute on the image tag.
imageUsemap

Only applies if an image is being used to display the navigation item instead of plain text.

The value for the "usemap" attribute on the image tag.
linkAccessKey

The "accesskey" attribute value for the link tag.
linkRel

The "rel" attribute value for the link.
linkText

The text for the link.
linkTextIsHtml

Whether or not the link text is HTML.
Accepted values are "true" and "false".
linkTabIndex

The "tabindex" attribute value for the link.
linkTarget

The "target" attribute value for the link tag.
onClick

The "onclick" attribute value for the link tag.
onDblClick

The "ondblclick" attribute value for the link tag.
onKeyDown

The "onkeydown" attribute value for the link tag.
onKeyPress

The "onkeypress" attribute value for the link tag.
onKeyUp

The "onkeyup" attribute value for the link tag.
onMouseDown

The "onmousedown" attribute value for the link tag.
onMouseMove

The "onmousemove" attribute value for the link tag.
onMouseOut

The "onmouseout" attribute value for the link tag.
onMouseOver

The "onmouseover" attribute value for the link tag.
onMouseUp

The "onmouseup" attribute value for the link tag.
parentImage

Only applies if an image is being used to display the navigation item instead of plain text.

The image path to use if the navigation item is the current navigation item.
passwordProtectedDisplay

Whether or not the navigation item should be shown if an account holder is logged in. It could also be hidden if an account holder is logged in. 

Accepted values are: always, loggedIn and loggedOut.

Defaults to always.
url

The URL for the link.