ArcNav UI Component

Usage

The component can be added to a page either as a standalone self-rendering bundle or a UMD-based React component library.

Standalone

Include the following on the page's HTML:

<link rel="stylesheet" href="https://nav-prod.home.static.arcpublishing.com/css/arcnav.css">
<script src="https://nav-prod.home.static.arcpublishing.com/js/arcnav-standalone.js" async></script>

The component will be rendered out to the element with ID of navbar. JSON Configuration can be passed via a <script> tag:

<script id="navbar" type="application/json">
  {
    "appname": "example app",
    "homeLink": {
      href: "/"
    },
    "links": [
      {
        "name": "Page 1",
        "href": "/page1",
        "text": {
          "en": "Page 1",
          "es": "Página 1",
          "de": "Seite 1",
          "fr": "Page 1"
        }
      },
      {
        "name": "Page 2",
        "href": "/page2",
        "text": {
          "en": "Page 2",
          "es": "Página 2",
          "de": "Seite 2",
          "fr": "Page 2"
        }
      },
      {
        "name": "Page 3",
        "text": {
          "en": "Page 3",
          "es": "Página 3",
          "de": "Seite 3",
          "fr": "Page 3"
        },
        "sub": [
          {
            "name": "SubPage 1",
            "href": "/page3/sub1#frag1",
            "text": {
              "en": "Sub Page 1",
              "es": "Subpágina 1",
              "de": "Unterseite 1",
              "fr": "Sous Page 1"
          }, {
            "name": "SubPage 2",
            "href": "/page3/sub1#frag2",
            "text": {
              "en": "Sub Page 2",
              "es": "Subpágina 2",
              "de": "Unterseite 2",
              "fr": "Sous Page 2"
          }
        ]
      }
    ],
    "userLinks": [
      {"name": "Option 1", "href": "/option1"},
      {"name": "Option 2", "href": "/option2"}
    ]
  }
</script>

React Component (UMD Module)

Include the following on the page's HTML:

<link rel="stylesheet" href="https://nav-prod.home.static.arcpublishing.com/css/arcnav.css">
<script src="https://nav-prod.home.static.arcpublishing.com/js/arcnav.umd.js"></script>

The component library will be exported as an ArcNav global.

<ArcNav
    appname='Example App'
    homeLink={href : '/'}
    links={[
      {
        "name": "Page 1",
        "href": "/page1",
        "text": {
          "en": "Page 1",
          "es": "Página 1",
          "de": "Seite 1",
          "fr": "Page 1"
        }
      },
      {
        "name": "Page 2",
        "href": "/page2",
        "text": {
          "en": "Page 2",
          "es": "Página 2",
          "de": "Seite 2",
          "fr": "Page 2"
        }
      },
      {
        name: 'Super Items',
        sub: [
          {
            "name": "SubPage 1",
            "href": "/page3/sub1#frag1",
            "text": {
              "en": "Sub Page 1",
              "es": "Subpágina 1",
              "de": "Unterseite 1",
              "fr": "Sous Page 1"
            }
          },
          {
            "name": "SubPage 2",
            "href": "/page3/sub1#frag2",
            "text": {
              "en": "Sub Page 2",
              "es": "Subpágina 2",
              "de": "Unterseite 2",
              "fr": "Sous Page 2"
            }
          }
        ]
      }
    ]}
    userLinks={[{name: 'User Settings', href: '#/settings'}]} />

Configuration

The following fields are support for configuring the component:

• appname - application display name (required)
• homeLink – URL for the "home" view for the app
  • href - URL to use with the link
  • usePushState - If set to true, uses HTML5 pushState to update page url (default: false)
• permissionKey - Path to your apps permission object EG: Ellipsis.global Do not use if no permissions are nessecary
• links - array of navigation links in top navbar (default: [])
  • name - display text of the nav item (required)
  • href - URL to use with the link
  • usePushState - If set to true, uses HTML5 pushState to update page url (default: false)
  • target – target attribute for the resulting anchor tag (default: '_self')
  • permission - Array of permission keys. If not included, same as everyone EG: ["ADM", "ED"]
  • text - Object containing the translations for the visible text (See Supporting i18n below)
  • match - matching criteria for highlighting item (Basic path-to-regexp options are supported)
    • path - pattern for matching the path
    • hash - pattern for matching the URL fragment
    • sensitive - (default: false)
    • strict - (default: false)
    • end - matched (default: false)
  • sub - array of 2nd level navigation links. If specified, href and match are ignored.
• userLinks - links for the user dropdown
  • name
  • href
  • usePushState
  • target
  • permission
  • text
• hideEnv - whether to hide the environment label (default: false)
• version - product version number to display

Supporting i18n

If your application requires different text for a language, than you need to supply the translations to the navbar. Currently the navbar uses the language set in the browser. In the future; when Arc has a global settings, the navbar will also check for that field.

The navbar looks for the "text" property on the link. The text property is an object with the keys being the iso language codes. If you have a generic translation for a language that use the short code. EG: en, es, de. If you want to have alternative translations for a specific country than use the long code. EG en-ca.

The navbar first checks for the long code, than the short code, and than defaults to english. If no code is found, it defaults to the name property.

{
  "name": "color",
  "href": "/color",
  "text": {
    "en": "color",
    "en-ca": "colour",
    "en-uk": "colour",
    "de": "farbe"
  }
}

So with the above, if the user has their browser set to en-ca, they will get "colour". If their browser is set to french, it will defailt to "en" since there is no "fr" in the object.

Now if you do not want to provide all the translations in the JSON, some teams just use their i18n layer in their application and alter the "name" property to have the correct translation.

If you want to test Arc Nav i18n support without altering your browser langauge, you can set your local storage key to override the browser default. This setting will NOT work in production. The value will be read from global settings when it is implemented globally.

// Update the item 'arc.lang' with your code
localStorage.setItem('arc.lang', 'es')

// do not forget to remove it when done testing
localStorage.removeItem('arc.lang')

Adding Permissions to certain links

In the user's permissions for your application it is going to look like the following

"permissions" : {
  "yourApplication" : {
    "global" : ["AD", "BC", "DE", "FG"]
  }
}

So you need to set up the key to the permission for your application so the NAVBAR knows what app to look up.

{
  "appname": "example app",
  "permissionKey": "yourApplication",
  "links": []
}

With this propery set, you can now add a permission list to each link. If the link does not have the permission property, it is the same thing as saying everyone can see it. So let us add a permission that only people with the permissions "AD" or "XY" can see it. You can add this to main link, sub links, and user links.

{
  "name": "color",
  "href": "/color",
  "text": {
    "en": "color",
    "en-ca": "colour",
    "en-uk": "colour",
    "de": "farbe"
  },
  "permission": ["AD", "XY"]
}

Development

Requirements

• Docker
• A localhost.arcpublishing.com host entry that points to 127.0.0.1

Commands

Serve the assets on a dummy page for development:

make build up

Access the application at http://localhost.arcpublishing.com. Login with user admin and no password. Click the Arc Nav Test application in the tiles.

Package the assets under dist/ for deployment:

npm run build

Run linting and tests:

make test

TODO

• [ ] HTML5 History API (pushState()) support