Skip to content

Navigation Drawer Specification

Viktor Aladzhov edited this page Oct 5, 2020 · 5 revisions

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

  1. Have container element, representing different view states.
  2. Have buttons to manipulate navigation drawer visibility.
  3. Handle events to handle and track user interactions.
  4. 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.

Component Content

Query for various HTML elements using the Query: https://angular.io/docs/ts/latest/api/core/QueryMetadata-class.html Query for child components

ARIA support

Clone this wiki locally