mns-core-ui-header

mns-core-ui-header

A NodeJS NPM module that contains the client code for the global header including level 1-3 navigation and enables sharing of common assets in this module between code bases. These code bases are currently:

• FEAR responsive pages
• MCFP non responsive pages
• FESK pages based on mns-fe-starter-kit

This is a temporary step to extract original FEAR header code in to a self contained reusable module. Also to migrate from deprecated fear-core-ui to mns-core-ui. This module also has no dependency on a javascript framework.

UPDATE: The module no longer has dependency on fear-core-ui as a result of https://github.com/DigitalInnovation/mns-core-ui-header/pull/92.

For more info:

• https://confluence.devops.mnscorp.net/display/FF/mns-core-ui-header
• https://github.com/DigitalInnovation/mns-core-ui-header/wiki
• Common header overview

Summary of steps to implement header on your page

Install the module in your application npm install mns-core-ui-header --save

The following steps would usually be performed as part of a build process:

1. copy assets from src/mns-core-ui-header/templates/header/assets to desired location in your application.
2. setup templates (see templates section below)
3. define paths to assets used in styling (see SASS section below)
4. import css bundle @import 'templates/header/bundle';
5. include the javascript bundle:
   • If using es6 import Header from 'mns-core-ui-header/dist/templates/header/bundle';
   • If using es5 define([
'mns-core-ui-header'
], function (Header) {});
6. The header needs to be instantiated:

new Header.Top();

new Header.Navigation();


1. The level2 and level3 markup should be made available server side to the html templates as globalHeader.topNavLevel3 (A subsequent client side call is made in addition to this so that any recent content changes appear in the page navigation)

Templates:

The src folder contains the partials needed for the header and these partials have a .hbs (handlebars) extension for consumption in newer M&S codebases (e.g FESK projects). 

The partials are made available also in the dist folder with a .html extension for consumption in legacy codebases (e.g FEAR) that require templates to have this extension.

It is important to note is that currently the partials only use mustache syntax (i.e the engine used in FEAR) and hence are compatible with handlebars template engines as handlebars is a superset of mustache. Care should be taken if introducing handlebars functionality to the templates whilst they are being consumed by a FEAR page for this reason.


To use templates in your application (FESK)

• the path path/to/node/modules + mns-core-ui-header/src/mns-core-ui-header/templates/header/partials needs to be added to your handlebars partialsDir config property (see docs path)
• assign configuration data to the page handlebars handler.

const headerService = require('mns-fe-unicorn-platform/lib/services/getHeaderContent.js');
import configuration from 'path/to/fesk-configuration';

• assign data to template

res.render('yourPage', {

    header: headerService.getConfig(header.config, configuration)

});

• include the following in your page template {{> templates/header/partials/default/header header }}

Images

• define $mns-core-ui-header-images-dir variable that contains path to where assets have been copied to in above steps
• @import 'mns-core-ui-header/templates/header/sass/module_images';

Fonts

• define $mns-london-font-path variable with path to font asset location e.g mns-core-ui/dist/fonts/mns-london
• define $mns-london-font-name e.g mns-london
• @import 'mns-core-ui/globals/typography/fonts/mns-london/module_mns-london';

Font-icons

• define $mns-core-ui-header-icon-font-family variable e.g mns-icons
• define $mns-core-ui-header-fonts-dir e.g ~mns-core-ui/dist/fonts/
• @import 'mns-core-ui-header/templates/header/sass/module_font-icons';

Configuration



The module exposes a config object:

require('mns-core-ui-header).config



There is core configuration of the header (data) and the associated key (key). This is data that is deemed to not need business control.



* core configuration require('mns-core-ui-header).config.data - contains link data for flags and dropdowns.



A decorators object is also exposed, so this data can be optionally added the full config object. This is data that does/could need business control and could be replaced by an API when thats implemented. Current decorators are:



* labels - labels for dropdown menu items.



For detail on above see /index.js

Events

There are some events that can/should be fired from a client page/application that the header listens to.

1. Update the header mini bag count. event name updateItemCount passing an integer of new page count in variable myBagCount i.e event.myBagCount

Development



The development environment is based on mns-fe-starter-kit and documentation for how that works can be found here


Mocking Routes



Mocked endpoints can be added to your express app by using the ExposeRoutes functionality. Add the following lines to your server.js file. Note that the "ExposeRoutes" line must be added above the current routes that your app defines.

const indexFile = require('../../index');

const ExposeRoutes = indexFile.ExposeRoutes;


server = new ExposeRoutes(server).attachToServer();



You must also make sure that your config file containing the api endpoints is setup with the following:


"loyaltyService": "http://127.0.0.1:3002/loyalty-service/"

"loyaltyServiceStub": "http://127.0.0.1:3002/loyalty-service/"

Testing

To run the UI tests locally:

1. In terminal tab start the webapp npm start
2. In another terminal tab npm run test:ui This will test against localhost
3. Note that UI test spec files must have the the following pattern in order to be picked up ./test/specs/**/*test.spec.js

To run the UI tests in the cloud against a range of browsers and connect to your localhost:

1. In terminal tab start the webapp npm start
2. Add you sauce user credentials to the wdio.sauce.conf.js file, or set them as environment variables SAUCE_USER and SAUCE_KEY
3. In another terminal tab npm run test:ui:sauce
4. You can configure the required browsers in /test/wdio.sauce.conf.js

Visual Tests Admin Panel

1. The visual tests are configured to use the 'Admin Panel' (http://webdrivercss-admin.dev.apps.mnscorp.net/)
2. When the test starts it will first try to pull a baseline matching the id that you supplied
3. When the test ends it will push the results to the admin panel so that you can view the results
4. If this is the first time running the tests you must use the --capture (--c) flag to capture a baseline and push to the Admin panel

To run the Visual tests locally:

1. In terminal tab start the webapp npm start
2. In another terminal type: npm run test:visual -- --id myid (--c if first time)
3. Note that visual test spec files must have the the following pattern in order to be picked up ./test/specs/**/*css.spec.js

To run the Visual tests against sauce labs:

1. In terminal tab start the webapp npm start
2. Add your sauce user credentials to the wdio.css.sauce.conf.js file, or set them as environment variables SAUCE_USER and SAUCE_KEY
3. In another terminal type: npm run test:visual:sauce -- --id myid
4. In another terminal tab npm run test:visual:sauce
5. You can configure the required browsers in /test/wdio.sauce.css.conf.js

To run the Visual tests against another id:

1. In terminal tab start the webapp npm start
2. In another terminal type: npm run test:visual -- -i myid -l anotherid

This will pull the baseline from another id and push the results to your id

Publishing

Shrinkwrap the module

(https://github.com/DigitalInnovation/fesk-documentation/blob/master/how_tos/shrinkwrap_npm_dependencies.md)

Publish the module to NPM

(https://confluence.platform.mnscorp.net/display/FF/publishing+npm+modules)