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
andmatch
are ignored.
-
-
userLinks
- links for the user dropdownname
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