@appdirect/universal-header

Universal Header

Appdirect header that can be added in our sub apps.

Getting started

1. Install the package

npm install universal-header

2. Include the dependency and launch the tag manager

import UniversalHeader from 'universal-header';

var universalHeader =  new UniversalHeader(); 
universalHeader.configure({
	locale: 'en-US', // default to 'en-US',

  	widgets: ['Header'], // widgets loaded, currently the only available is header
  	sub: 'appwise' // appwise, apphelp, appinsights, defaults to: appdirect
 	marketUrl: 'http://marketplace.appdirect.com' // link to the targetted marketplace, defaults to: http://marketplace.appdirect.com
});
universalHeader.configure({renderTo:'#universalHeader'}, 'header');
universalHeader.init();
	

Alternate loading via window.

You can alternatively load the componenet via the window object if your app have no access to npm packages. Once the file is loaded in the page, you can retreive the tag manager.

var universalHeader =  new window.Ad_tag_m();

universalHeader.configure({
  	widgets: ['Header'], // widgets loaded, currently the only available is header
  	sub: 'appwise' // appwise, apphelp, appinsights, defaults to: appdirect
 	marketUrl: 'http://marketplace.appdirect.com' // link to the targetted marketplace, defaults to: http://marketplace.appdirect.com
});
universalHeader.configure({renderTo:'#universalHeader'}, 'header');
universalHeader.init();
	

Caching

Enabling caching helps reduce the header loading latency, specifically it will take a localstorage verison of your header without calling any header.

Enabling Caching:

import UniversalHeader from 'universal-header';

var universalHeader =  new UniversalHeader(); 
universalHeader.configure({
	cache: true,
	userId: 123123123, // must be the logged userid or null (not undefined)
	channel: 'APPDIRECT' // default to: APPDIRECT
  	widgets: ['Header'],
  	sub: 'appwise'
 	marketUrl: 'http://marketplace.appdirect.com'
});
universalHeader.configure({renderTo:'#universalHeader'}, 'header');
universalHeader.init();
	

Why is the userId and channel is required?

The userId config is required so we do not call the bootstrap-context api. When not provided it will still load the cached header after doing this api call if available.

The channel is required to retreive the theme customizer channel templates in case they are not currently saved. When not set it will call the bootstrap-context api and continue will the cached version if available.

Clear Cache

You can clear the cache of the header widget with a custom event exposed on the document.

  document.dispatchEvent(new CustomEvent("universalnav:call", { detail: {'widget': 'Header', method: 'clearStorage' }}));

ReRender a widget

You can dispatch an event to re-render a widget, when doing so, no cache is used, meaning all ajax calls will be reloaded.

document.dispatchEvent(new CustomEvent("universalnav:render", { detail: {'widget': 'Header', options: {template: 'headerOut'}}}));

Set an icon active

Possible values: wise-link, home-link, wise-link, insight-link, marketplace-link

document.dispatchEvent(new CustomEvent("universalnav:icon:active", { detail: {'icon': 'wise-link'}}));

### Listen to header rendered event

You can know when the header has finished loading by using this dom event.

```javascript
	document.addEventListener('universalnav:header:loaded', () => {  });

Token and refresh token

The AppWise search widget embedded in the universal header requires a token to function correctly. You can simply pass a token when configuring the universal header.

import UniversalHeader from 'universal-header';

var universalHeader =  new UniversalHeader(); 
universalHeader.configure({
	token: 'asdasdsd',
	userId: 123123123, // must be the logged userid or null (not undefined)
	channel: 'APPDIRECT' // default to: APPDIRECT
  	widgets: ['Header'],
  	sub: 'appwise'
 	marketUrl: 'http://marketplace.appdirect.com'
});
universalHeader.configure({renderTo:'#universalHeader'}, 'header');
universalHeader.init();

It is possible that at some point in your application life cycle you may want to refresh the token and UI associated with it. Using the universalnav:refresh:token, it will refresh the token internally and then refresh the search widget.

document.dispatchEvent(new CustomEvent("universalnav:refresh:token", { detail: {'token': 'asdasd' }}));

Changing the logo

As a 3rd party you may want to use your logo instead of the appdirect logo.

import UniversalHeader from 'universal-header';
var universalHeader =  new UniversalHeader(); 

universalHeader.configure({
  widgets: ['Header'],
  logoUrl: 'https://s3-us-west-2.amazonaws.com/apphelp-assets/AppHelp_Logo_RGB_161114_230448.png',
  logoWidth: '105px', // not required but fix fouc
});
universalHeader.configure({renderTo:'#universalHeader'}, 'header');

universalHeader.init();

Overloading the icons and other links click event

You can change the function that is called when clicking the icons. This feature was required by AppWise as they want to use their own router for some of the links.

Example:

import UniversalHeader from 'universal-header';
var universalHeader =  new UniversalHeader(); 

universalHeader.configure({
	widgets: ['Header'],
});
universalHeader.configure({renderTo:'#universalHeader'}, 'header');

universalHeader.configure({links: {
	'home-link': function(){ alert('home'); },
  'logout-link': function(logoutMarketplaceLink, element){ alert('logout'); },
  'login-link': function(logoutMarketplaceLink, element){ alert('login'); },
	'teams-link': function(){ alert('wise'); }
}}, 'header');

universalHeader.init();

Get default templates

When in the theme customizer, you have a insert default templates button to reset templates, you can retreive de default templates, by creating a new instance and using the getDefaultTemplates method.

var templates = AdUniversalHeader.getDefaultTemplates();

Overriding search bar search execution for each filter

  tagManager.configure({
    widgets: ['Header'],
    sub: 'appdirect',
    marketUrl: 'https://marketplace.appdirect.com',
  	onSearchQuery: function(content) {console.log(content); },
  	onSearchApps: function(content) {console.log(content); },
  	onSearchMarketplace: function(content) {console.log(content); },
  	onSearchPeople: function(content) {console.log(content); },
  	customSearchQuery: function() {return 'my search query';},
  });

Static Mode

When integrating the Universal Header you might want to start without actually doing calls to 3rd party server but with a static version. This allow you to have the default appdirect universal header UI

When Logged out you only need to pass the static option.

Logged out:

universalHeader.configure({
    widgets: ['Header'],
    static: true,
    marketUrl: 'http://marketplace.appdirect.com'
});

When Logged in you must also pass the userUUID and some information normally contained in the bootstrap data. Passing back in static data the CurrentUser, UserInfo and CHANNEL_SETTINGS content. The minimum information required is demonstrated below.

Logged in:

universalHeader.configure({
    widgets: ['Header'],
    userUUID: '123123',
    static: true,
    staticData: {
    	CurrentUser: {
    		uuid: "213123123",
    	},
    	UserInfo: {
    		given_name: "Cedric"
    	},
    	CHANNEL_SETTINGS: {}
    },
    marketUrl: 'http://marketplace.appdirect.com'
});

NPM Commands

npm run lint Run the linter npm run build Build the project npm run test Run the test suite npm run test:watch npm run watch:sass

npm run start Starts the webpack server, starts the js and sass watchers

Working with React components

universal-header templates support a special kind of tag that is interpolated at runtime. The tag will insert a DOM element that will act as the mounting point for a React component.

{{NICE-COMPONENT}}

Results in:

<div class="my-react-component"></div>

In order to have a functioning React component:

1. Identify the template file where you want to place the tag.
2. Name your component using the convention {{*-COMPONENT}} eg. {{NICE-COMPONENT}}
3. Register your component in the template.utils.js > tagsToReactMountEl the key is the name, and the value is the DOM element.
4. Make sure the tag matches the key. (Try using simple names for tag names, all uppercase)
5. Render your component in the component-helper.js file

Troubleshooting

If the template doesn't refresh with your new tag, try flushing the localStorage.