Navigation Drawer Specification

ig-nav-drawer Navigation drawer component is a container element for side navigation providing quick access between views, suitable for deep navigation apps, or such with top-level views. It is hidden until invoked by the user.

Objectives

It is providing API for the most common use cases when it comes to perform side navigation, access to views and app navigation.

<igx-nav-drawer id="test"
    (opened)="logEvent($event)"
    (closed)="logEvent($event)"
    (opening)="logEvent($event)"
    (closing)="logEvent($event)"
    [position]="position"
    pinThreshold=""
    [pin]="pin"
    [enableGestures]='gestures'
    [isOpen]="open"
    [width]="drawerWidth"
    [miniWidth]="drawerMiniWidth"
    [disableAnimation]="false">
        <div class="ig-drawer-content">
            <h3>Drawer Title</h3>
            <div *ngFor="let navItem of navItems"><img src="http://www.infragistics.com/assets/images/favicon.ico" width='16' /> <a routerLink="{{navItem.link}}"> {{navItem.text}} </a></div>
        </div>
        <div *ngIf="miniTemplate" class="ig-drawer-mini-content">
            <span class="hamburger" igxNavToggle="test" > &#9776; </span>
            <div *ngFor="let navItem of navItems"><img src="http://www.infragistics.com/assets/images/favicon.ico" width='16' /></div>
        </div>
</igx-nav-drawer>

User Stories

Developer

As developer I want to have an option for a temporary navigation drawer that can toggle open or close. Tap outside the drawer closes it.
As a developer I want to enable swipe gesture to open/close the navigational drawer.
As developer I want to have option for a left or right temporary navigation.
As developer I want to be able to choose the width of the side menu drawer. The drawer always spans full height.
As developer I want to have option for an open and closed persistent navigation drawer. The drawer sits on the same surface elevation as the content. It is closed by default and opens by selecting the menu icon, and stays open until closed by the user. The state of the drawer is remembered from action to action and session to session.
As developer I want to have option for a persistent navigation drawer on screen depending on a customizable screen threshold set in px.
As developer I want to have option for a using a mini-drawer. It’s resting state is as a mini drawer, showing icons at the same elevation as the content clipped by the app bar. When expanded appears as a standard persistent navigation drawer.
As a developer I want to have a property which controls the animation of the transition of the tabs' contents.

End user

As an end-user I want to have option for a hidden by default navigation drawer that provides quick access to different parts of the app.
As an end-user I want to toggle open or close the temporary navigation drawer:
Upon tap(click) on an icon.
Upon swipe gesture.
As an end-user I want to have a navigation drawer that gets fixed and is always visible on the screen when I am using devices with bigger display.
As an end user I want to have option for a using a persistent drawer. It is closed by default and opens by selecting the menu icon, and stays open until closed. The state of the drawer is remembered from action to action and session to session.
As an end user I want to have option for a using a mini-drawer. It’s resting state is as a mini drawer, showing icons at the same elevation as the content clipped by the app bar. When expanded appears as a standard persistent navigation drawer.

Acceptance criteria

Have container element, representing different view states.
Have buttons to manipulate navigation drawer visibility.
Handle events to handle and track user interactions.
Handle drawer position and swipe direction.

API

Properties

Name	Type	Description
`ID`	string	ID of the component.
`position`	string	Position of the Navigation Drawer. Can be "left"(default) or "right". Only has effect when not pinned.
`enableGestures`	boolean	Enables the use of touch gestures to manipulate the drawer - such as swipe/pan from edge to open, swipe toggle and pan drag.
`isOpen`	boolean	State of the drawer.
`pin`	boolean	Pinned state of the drawer. Currently only support.
`pinThreshold`	number	Minimum device width required for automatic pin to be toggled. Deafult is 1024, can be set to falsy value to ignore.
`width`	string	Width of the drawer in its open state. Defaults to 300px based on the `.ig-nav-drawer` style. Can be used to override or dynamically modify the width.
`miniWidth`	string	Width of the drawer in its mini state. Defaults to 60px based on the `.ig-nav-drawer.mini` style. Can be used to override or dynamically modify the width.
`disableAnimation`	boolean	Enables/disables the animation for the opening and the closing of the drawer. Set to `false` by default.

Internal properties

Name	Type	Description
`hasAnimateWidth`	boolean	Property to decide whether to change width or translate the drawer from pan gesture.
`maxEdgeZone`	string	Used for touch gestures (swipe and pan). Defaults to 50 (in px) and is extended to at least 110% of the mini template width if available.
`state`	string	Exposes optional navigation service

Methods

Name	Description
`open`	Open the Navigation Drawer. Has no effect if already opened. @param fireEvents Optional flag determining whether events should be fired or not. @return Promise that is resolved once the operation completes.
`close`	Close the Navigation Drawer. Has no effect if already closed. @param fireEvents Optional flag determining whether events should be fired or not. @return Promise that is resolved once the operation completes.
`expectedWidth()`	Get the Drawer width for specific state. Will attempt to evaluate requested state and cache.
`expectedMiniWidth()`	Get the Drawer mini width for specific state. Will attempt to evaluate requested state and cache.
`toggle`	Toggle the open state of the Navigation Drawer.@param fireEvents Optional flag determining whether events should be fired or not. @return Promise that is resolved once the operation completes.

Internal Methods

Name	Description
`getWindowWidth`	Get window width
`setDrawerWidth`	Sets the drawer width. @param width Width to set, must be valid CSS size string.
`ensureDrawerHeight`
`getExpectedWidth`	Get the Drawer width for specific state. Will attempt to evaluate requested state and cache. @param mini Request mini width instead.
`getDrawerWidth`	Get current Drawer width.
`setXSize`	Sets the absolute position or width in case the drawer doesn't change position.@param x the number pixels to translate on the X axis or the width to set. 0 width will clear the style instead.@param opacity optional value to apply to the overlay

Events

Name	Description
`opening`	Event fired as the Navigation Drawer is about to open.
`opened`	Event fired when the Navigation Drawer has opened.
`closing`	Event fired as the Navigation Drawer is about to close.
`closed`	Event fired when the Navigation Drawer has closed.

Functionality initial notes

Component API

Because of the component architecture there are limitations to the API that a component can expose publically – specifically there’s no way to randomly query the DOM for the element and access the component API from that. There’s also no default handling for rich declarative API (think … type of structure) as those are essentially supposed to be a new component.

Touch Events

Angular2 has a provider + typings using Hammer.js but does not include it as a dependency.
There is HammerGesturesPluginCommon event detector built in, so such events are supported out of the box, there are no typings for the event parameter though. Also be aware that for now there’s a check + error in case the Hammer script is not loaded on the page for such handlers. They do have a small test sample with the script embedded (custom build with some fixes) https://github.com/angular/angular/tree/master/modules/playground/src/gestures

The angular way to assign event handler is to use the DomRenderer(can be injected) listen method. There’s a global listen that is currently not implemented on the Hammer plugin, however the target passed to the single element method can be ‘document’.

CSS Animation (TS)

Currently marked as in development in the docs, the main class seems to AnimationBuilder and the only meaningful example I could find is in and it didn’t work at all. Using of CSS transition for now.