Widgets: Nav Buttons

The <devsite-nav-buttons> custom element allows a group of buttons to reload the current page with a different querystring parameter.

Demo

Java sample code

Usage

To use, create a <devsite-nav-buttons> element with a name attribute and place multiple button elements with different value attributes within it. For each group of buttons, select one as the default by adding a default attribute to the element.

<devsite-nav-buttons name="language">
  <button value="java" default>Java example</button>
  <button value="python">Python example</button>
  <button value="go">Go example</button>
</devsite-nav-buttons>

In a Markdown (.md) file, make sure the custom element is wrapped with a standard HTML element, such as a section, div, or p:

<div>
  <devsite-nav-buttons name="language">
    <button value="java" default>Java example</button>
    <button value="python">Python example</button>
    <button value="go">Go example</button>
  </devsite-nav-buttons>
</div>

You can then use dynamic tags that examine the query string parameters to determine which content to display to the user.

{% dynamic if request.query_string.language == "python" %}
Python sample code
{% dynamic elif request.query_string.language == "go" %}
Go sample code
{% dynamic else %}
Java sample code
{% dynamic endif %}

In-page linking with an ID

As a general rule, it is best to place the <devsite-nav-buttons> element near the top of the page since clicking any of its buttons takes users to a new URL and reloads the page. If you are using the element in the middle of a page and/or want the element's location on the page to be bookmarkable, you should specify a unique id on the element, which will append a named anchor to the URL and make the page scroll to the element's location when the page loads.

<devsite-nav-buttons name="language" id="code-examples">
  <button value="java" default>Java example</button>
  <button value="python">Python example</button>
  <button value="go">Go example</button>
</devsite-nav-buttons>

URL parameter options

By default, after a user clicks one of the buttons, the button's value is saved to localStorage. The selected value is automatically added to the address bar as a URL parameter on other pages with <devsite-nav-buttons> elements that use the same name and value fields.

Remove the URL parameter for the default button

To override the default behavior and remove the URL parameter when the default button is clicked, add param="reset" to the element:

<devsite-nav-buttons name="language" param="reset">
  <button value="java" default>Java example</button>
  <button value="python">Python example</button>
  <button value="go">Go example</button>
</devsite-nav-buttons>

Always display a URL parameter for the default button

When a user visits a page with a <devsite-nav-buttons> element for the first time, the default button is highlighted and there is no change to the address bar until a button is clicked.

To make the address bar update with the URL parameter for the default button, and ensure there is always a URL parameter on pages with a <devsite-nav-buttons> element, add param="always" to the element:

<devsite-nav-buttons name="language" param="always">
  <button value="java" default>Java example</button>
  <button value="python">Python example</button>
  <button value="go">Go example</button>
</devsite-nav-buttons>

Button styling

By default, the buttons within the <devsite-nav-buttons> element have "chip" styling. To increase or decrease the visual impact of the buttons, you can add a type attribute with a value of filled or text, which will style each button element.

Button styling with type="filled" :

<devsite-nav-buttons name="language" type="filled">
  <button value="java" default>Java example</button>
  <button value="python">Python example</button>
  <button value="go">Go example</button>
</devsite-nav-buttons>

Button styling with type="text" :

<devsite-nav-buttons name="language" type="text">
  <button value="java" default>Java example</button>
  <button value="python">Python example</button>
  <button value="go">Go example</button>
</devsite-nav-buttons>