@volvo-cars/site-nav-embed NPM

@volvo-cars/site-nav-embed

A component to let you consume the Site Navigation Service. Optimized and tested with Next.js but should work with any Server Side Rendered React application.

Install

npm install @volvo-cars/site-nav-embed
# or
yarn add @volvo-cars/site-nav-embed

Usage

Configuration

If you want to avoid having to pass the baseUrl in runtime, you can set the environment variable SITE_NAV_URL to https://www.volvocars.com/ui/site-navigation.

Edge Side Includes

The simplest way to integrate is by rendering the component with the siteSlug property.

import { SiteNavigationEmbed } from '@volvo-cars/site-nav-embed';
import MainContent from './MainContent';

const MyApp = () => {
  return (
    <>
      <SiteNavigationEmbed
        baseUrl="https://www.volvocars.com/ui/site-navigation"
        siteSlug="us"
      />
      <MainContent />
    </>
  );
};

When building your application with NODE_ENV=production, this will output

<esi:include
  src="https://www.volvocars.com/ui/site-navigation/us/v2.html"
  onerror="continue"
></esi:include>

This assumes your application is served by a CDN with Edge Side Includes enabled (e.g. Akamai on volvocars.com), and will not work in development.

It's important that the React component stays mounted and is not unmounted and then remounted again. For Single Page React apps, make sure it's located outside of any routing logic.

Next.js With ESI

For a Next.js application that fetches the Site Navigation in development but uses ESI in production, you need a pages/_document.js file that looks something like this:

:warning: Passing content related props like siteSlug, variant... directly to SiteNavigationEmbed component when not using esi tags will not work as expected. Those props should be first passed to getSiteNavigationPropsForRequest and the returned props should be passed to SiteNavigationEmbed

import React from 'react';
import {
  getSiteNavigationPropsForRequest,
  SiteNavigationEmbed,
} from '@volvo-cars/site-nav-embed/dist';
import Document, { Head, Html, Main, NextScript } from 'next/document';

class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const { query, req } = ctx;
    const siteSlug = query.siteSlug;
    const siteNavProps = await getSiteNavigationPropsForRequest(
      siteSlug,
      req,
      'experimental-lazy'
    );
    const initialProps = await Document.getInitialProps(ctx);
    return {
      ...initialProps,
      siteNavProps,
    };
  }

  render() {
    const { siteNavProps } = this.props;
    return (
      <Html>
        <Head />
        <body>
          <SiteNavigationEmbed {...siteNavProps} />
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

For more detailed examples with different Next.js data fetching strategies, see the Next.js example app.

We also set css variables if needed:

The height is exposed as the CSS variable --sitenav-topbar-height:

.MySubNav {
  position: fixed;
  top: var(--sitenav-topbar-height);
}
.SiteNav-Topbar-hidden .MySubNav {
  top: 0;
}

Some CSS classes are added to the <body> element of your page when the Site Navigation changes state:

SiteNav-Topbar-hidden - added when the Topbar has been fully hidden because the user scrolled
SiteNav-SideNav-open - added when the Side Navigation (Hamburger menu) is open
SiteNav-CarsMenu-open - added when the Desktop Cars Menu is open

Topbar and Local Sub Navigations

If your page includes a sub navigation or action bar at the top of the page, the main navigation topbar should not be fixed to the top of the page when scrolling, to avoid obscuring a large part of the content. Your sub navigation should use position: sticky, and the behaviour of the main navigation should be toggled by setting the CSS custom propertiy --hideonscroll.

.LocalSubMenu {
  position: sticky;
}
#site-navigation {
  --hideonscroll: var(--ON);
}

This can be done either in an external CSS file, or if you want to keep it local to your component by rendering

<style>
#site-navigation {
  --hideonscroll: var(--ON);
}
</style>

Variants

Return a specific variant of the Site Navigation.

nocars. Renders a a static topbar with deferred loading and rendering with no Cars Menu.
experimental-lazy. Renders a static topbar with deferred loading and rendering of Cars Menu and Side Navigation.

SiteNavigationEmbed Props

Property	Type	Required?	Description
esi	boolean	false	Explicitly enable or disable Edge Side Includes (`<esi:include>`)Enabled by default when `NODE_ENV === 'production'` server side
baseUrl	string	false	Base URL to Site Navigation serviceDefault to `process.env.SITE_NAV_URL`
siteSlug	string	false*	Market site slug to fetch navigation for.Required if no `html` prop is given.
html	string	false	Custom HTML to render. Overrides `esi` prop.
variant	`nocars \\| experimental-lazy`	false	Returns a specific variant of the Site Navigation.- `nocars`. Renders DotCom navigation with no Cars Menu.

Volvo Cars Chat

When the navigation service is embedded on a page, it exposes a window.VolvoCarsChat object that provides information about the chat as well as events and a trigger to open the chat box.

API

window.VolvoCarsChat.availability

Returns: 'disabled' | 'pending' | 'online' | 'offline'

disabled: Chat is not configured for the market or URL/Chat initialization failed. pending: Initial availability until chat is loaded/failed to load. online: An agent is online and ready to recieve messages. offline: No agents are online.

window.VolvoCarsChat.state

Returns: 'opening' | 'open' | 'closed'

opening: A request to open the chat box was sent. open: Chat box is open. closed: Chat box is closed.

window.VolvoCarsChat.open()

Returns: void

Opens Chat box

window.VolvoCarsChat.addEventListener(EventType, Listener)

Returns: void

Adds an event listener for events that are triggered for different availablity and state changes.

EventType: 'online' | 'offline' | 'open' | 'close' | 'opening'

Listener: function(event){}

window.VolvoCarsChat.removeEventListener(EventType, Listener)

Returns: void

Unsubscribes from an eventListener added by addEventListener. Works similar to DOMs EventTarget, the same Listener reference has to be provided to clean up correctly.