Skip to content

Overlay Specification

Milko Venkov edited this page Sep 13, 2019 · 59 revisions

Overlay Specification

Contents

  1. Revision history

  2. Overview

  3. User Stories

  4. Functionality

    4.1 End user experience

    4.2 Developer experience

  5. Assumptions and Limitations

  6. Test scenarios

  7. References

1. Revision History

Version User Date Notes
0.1 Milko Venkov May 14, 2018 Initial Draft
0.2 Plamena Miteva May 16, 2018 Test Scenarios
0.3 Milko Venkov May 22, 2018 Update API
0.4 Milko Venkov May 23, 2018 Update References and API
0.5 Ivaylo Ganchev May 29, 2018 Add Strategy Based Test Scenarios
0.6 Milko Venkov Jun 12, 2018 Update API
0.7 Milko Venkov Jun 14, 2018 Update scroll strategies
0.8 Milko Venkov Jun 19, 2018 Update API and test scenarios
0.9 Milko Venkov Jul 05, 2018 Update the specification
0.10 Milko Venkov Aug 24, 2018 Update the limitations
0.11 Milko Venkov Sep 13, 2018 onAnimation event added
0.12 Milko Venkov Dec 06, 2018 Elastic positioning startegy
0.13 Milko Venkov Feb 05, 2019 Remove caching of the element height
1.0 Milko Venkov Feb 26, 2019 API update. Attach method added
1.1 Milko Venkov Apr 12, 2019 Functionality section updated
1.2 Milko Venkov Apr 17, 2019 Remove cancelable events
1.3 Milko Venkov Sep 13, 2019 Container position strategy

2. Overview

Objectives

The igx-overlay should be able to display and position provided Component/ElementRef above all other elements.

The igx-overlay should be able to handle specific mouse and keyboard interactions.

3. User Stories

As an end user, I want

  • there is no end users stories as igx-overlay should be an Angular Service.

Developer Stories

As a developer, I want to

  • show a drop down at desired position above all other page elements
  • show a date picker at desired position above all other page elements
  • show a time picker at desired position above all other page elements
  • show context menu at desired position above all other page elements
  • show tool tip at desired position above all other page elements
  • show dialog at desired position above all other page elements
  • handle mouse scroll depending on the scroll strategy used
  • force an element to show at specific positions (Top, Bottom, Center and so on)
  • force an element to show at specific position related to an anchor element (Top, Bottom, Left, Right and so on)
  • force the overlay to be or not in modal state
  • show an element positioned globally into outlet element

4. Functionality

In order to show any content in igx-overlay developer should provide igx-overlay service as dependency injection. Then developer should call attach method of the igx-overlay instance. This will generate unique id. attach method accepts ElementRef/Component. When Component is provided igx-overlay will create the component trough ComponentFactoryResolver. Then igx-overlay will take the ElementRef of created component and will use it when should show its content. With the id in hand developer may call show method of the igx-overlay instance. show method will take the nativeElement of the ElementRef and will show it depending on the provided OverlaySettings. After the content is shown in the overlay developer may reposition the content by calling reposition method. Finally developer may hide the content by calling hide method. If several overlays are shown developer may hide all of them by calling hideAll method.

The way content will be shown in the overlay depends on the provided OverlaySettings. Here is how each setting affects the overlay:

  • closeOnOutsideClick - this is a boolean property with default value true. When set to true if user clicks outside of the content shown in the overlay, the overlay will close itself. When set to false outside clicks will have no effect.

  • modal - this is boolean property with default value true. When set to true igx-overlay will draw dimmed layer over the entire screen and behind the shown content. igx-overlay will also prevent all possible interaction with all the elements on the screen, but content shown in the overlay. Note: when set to true and closeOnOutsideClick is set to false developer should provide a way to the end user to close the overlay via interaction with shown content. When set to false the page content will remain interactable.

  • outlet - this is a property of IgxOverlayOutletDirective or ElementRef type. By default outlet is undefined. When overlay is shown it attaches its main element as last child of the document's body. If outlet is provided igx-overlay will attach the overlay as last child of provided outlet's nativeElement.

  • positionStrategy - this is property of IPositionStrategy type. By default positionStrategy is set to GlobalPositionStrategy. Position strategy determines how shown in overlay content will be positioned on the screen. There are five positioning strategies:

    • GlobalPositionStrategy - positions the content based on directions provided in PositionSettings. The content may be shown to the left, center or right in horizontal direction, and to the top, middle and bottom in vertical direction. By default the content is shown centered on the screen;
    • ContainerPositionStrategy - positions the content as GlobalPositionStrategy. Instead of position related to the screen ContainerPositionStrategy positions the content related to the provided in OverlaySettings outlet.
    • ConnectedPositioningStrategy - positions the content related to provided HTMLElement or screen point provided in PositionSettings. The content is shown in direction also provided in PositionSettings. By default the content is shown starting from the bottom left point of provided target in bottom right direction. If target is not provided content is shown starting from top left corner of the screen;
    • AutoPositionStrategy - positions the content as ConnectedPositioningStrategy. If content does not fit on the screen tries to fit it. Initially it will try to flip the content, e.g. if direction is set to right it will try to show the content to the left. If after the flip the content is still out of the screen igx-overlay will try to push the content on the screen by translating it. If push does not succeed, e.g. content is wider/taller than the screen, igx-overlay will show the content starting from the left/top border of the screen;
    • ElasticPositionStrategy - positions the content as ConnectedPositioningStrategy. If the content does not fit on the screen igx-overlay will try to fit it by reducing the content's wrapper size. The size of reduction is limited by the minSize provided in PositionSettings.

    Each position strategy accepts PositionSettings parameter when is initialized and also expose setting property of PositionSettings type. PositionSettings determines how position strategy will position overlay's content. These are all the properties of PositionSettings:

    • target - this property is of HTMLElement or Point type. It determines the place where the shown content will be attached to. This property has no effect when GlobalPositionStrategy is used;
    • horizontalDirection and verticalDirection - these properties are of HorizontalAlignment/VerticalAlignment type. These properties determines the direction in which the content will be shown. When GlobalPositionStrategy is used these properties determines location of the content related to the screen. When ContainerPositionStrategy is used these properties determines location of the content related to the provided in OverlaySettings outlet.
    • horizontalStartPoint and verticalStartPoint - these properties are of HorizontalAlignment/VerticalAlignment type. These properties determines the starting point of the target related to which the content will be shown. These properties has no effect when GlobalPositionStrategy or ContainerPositionStrategy are used, as well as when target is Point.
    • openAnimation and closeAnimation - these properties are of AnimationReferenceMetadata type. When provided they determine whit what animation the content will be shown/hidden.
    • minSize - this property is of Size type. It has effect only when ElasticPositionStrategy is used. This property determines the minimum size the shown content can be reduced to.
  • scrollStrategy - this is a property of IScrollStrategy type. By default it is set to NoOpScrollStrategy. Scroll strategy determines how overlay will react to scrolling. There are four scroll strategies:

    • NoOpScrollStrategy - this scroll strategy does nothing. If end user scrolls the page overlay will not react and will stay in place;
    • BlockScrollStrategy - this scroll strategy will prevent any scrolling on the page. If end user tries to scroll nothing will happen;
    • CloseScrollStrategy - this scroll strategy will close the overlay if a tolerance is exceeded. If end user scrolls the scrollContainer (document.body by default) the overlay will close;
    • AbsoluteScrollStrategy - this scroll strategy will scroll the page content together with content shown in the overlay. If end user scrolls the scrollContainer (document.body by default) the overlay content will reposition together with page content.

When showing content in the overlay several events will fire. Here is when each of them happens:

  • onOpening - fires just before the content is shown on the screen and before opening animation, if any, starts.
  • onOpened - fires after content is shown on the screen. If opening animation is provided this event will fire after animation is over.
  • onClosing - fires just before the content starts to hide from the screen and before closing animation, if any, starts.
  • onClosed - fires after content is completely hidden from the screen. If closing animation is provided this event will fire after animation is over.
  • onAnimation - fires before open or close animation starts.

4.1. End User Experience

4.2. Developer Experience

Developers are able to show a Component or ElementRef at desired position.

4.3. API

Properties

IPositionStrategy

Name Description Type
positionSettings Settings to apply to this position strategy PositionSettings

OverlaySettings

Name Description Type
positionStrategy Position strategy to use with this settings IPositionStrategy
scrollStrategy Scroll strategy to use with this settings IScrollStrategy
modal Set if the overlay should be in modal mode boolean
closeOnOutsideClick Set if the overlay should closed on outside click boolean
outlet IgxOverlayOutletDirective or ElementRef Set the outlet container to attach the overlay to

PositionSettings

Name Description Type
target Attaching target for the component to show Point
horizontalDirection Direction in which the component should show HorizontalAlignment
verticalDirection Direction in which the component should show VerticalAlignment
horizontalStartPoint Target's starting point HorizontalAlignment
verticalStartPoint Target's starting point VerticalAlignment
openAnimation Animation applied while overlay opens AnimationReferenceMetadata
closeAnimation Animation applied while overlay closes AnimationReferenceMetadata
minSize The size up to which element could be reduced Size

Methods

IgxOverlayService

Name Description Parameters
attach Generates Id. Provide this Id when call show(id, settings?) method element, overlaySettings?
attach Generates Id. Provide this Id when call show(id, settings?) method component, overlaySettings?, moduleRef?
show Shows the overlay for provided id id, overlaySettings?
hide Remove the provided native element of for the component with provided id id
hideAll Remove the all native elements and hides the overlay -
reposition Repositions the native element of the component with provided id id

IPositionStrategy

Name Description Parameters
position Positions provided element element, size?, document?, initialCall?

IScrollStrategy

Name Description Parameters
initialize Initialize the strategy. Should be called once document, overlayService, id
attach Attaches the strategy -
detach Detaches the strategy -

static methods

Name Description Parameters
getPointFromPositionsSettings Calculates the point from which the overlay should start showing settings

Events

IgxOverlayService

Name Description Cancelable Parameters
onOpening Emitted before overlay shows false
onOpened Emitted after overlay shows false
onClosing Emitted before overlay hides false
onClosed Emitted after overlay hides false
onAnimation Emitted before animation is started false

5. Assumptions and Limitations

If you show the overlay in an outlet, and if the outlet is child of element with transform, perspective or filter css set you will not be able to show modal overlay. The reason for this is when one of above mentioned css properties is set the browser creates a new containing block and the overlay is limited to this containing block, as described here.

If you need to set scroll position of shown component you can achieve this in onOpening event. However, if you use ElasticPositionStrategy shown component could be resized and as a result scroll position will be incorrect.

If you try to show element with height set to 100%, the element will shrink its height to its content. If you need to retain element height and set height to 100% you need to set also min-height to some reasonable value.

6. Test Scenarios

Automated

Test with several different fixed window sizes.

I. Positioning Strategy

  1. GlobalPositioningStrategy (show components, by default, in the window center).
  • igx-overlay is rendered on top of all other views/components (any previously existing html on the page) etc.
  • igx-overlay covers the whole window 100% width and height.
  • The shown component is inside the content div, which is inside wrapper div as a last child.
  • The shown component, by default, is in the center of igx-overlay (visible window).
  • When adding more than one component to show in igx-overlay:
    • When adding a new instance of a component with the same options, it is rendered exactly on top of the previous one.
    • When adding a component near the visible window borders (left, right, up, down), it should be rendered, by default, in the center of igx-overlay (visible window) and no scrollbars should appear.
  • If the shown component is bigger than the visible window, by default it should be centered and no scrollbars should appear.
  1. ConnectedPositioningStrategy (show components based on a specified target (point or Html element), horizontal and vertical alignment, and horizontal and vertical starting directions)
  • igx-overlay is rendered on top of all other views/components (any previously existing html on the page) etc.
  • igx-overlay covers the whole window 100% width and height.
  • The shown component is child element of the content div, which is inside wrapper div.
  • the shown component is positioned according to the options passed (target / alignment / starting position / animations).
  • If using a ConnectedPositioningStrategy without passing options, the omitted default to (Window top left corner shown in bottom right direction).
  • When adding more than one component to show in igx-overlay:
    • When adding a new instance of component with the same options, it is rendered exactly on top of the previous one.
    • When adding a new component it should be rendered where expected based on the options.
    • When adding a component near the visible window borders (left, right, up, down) it should be partially hidden and depending on the scroll strategy used:
      • for NoOpScrollStrategy: scrolling should not be affected in any way.
      • for CloseScrollStrategy: on a scroll the component should hide.
      • for BlockScrollStrategy: it should be partially hidden. When scrolling, no scrolling should happen.
      • for AbsoluteScrollStrategy: it should be partially hidden but can scroll it into view. Component persist state. (example: expanded DropDown remains expanded).
  1. AutoPositionStrategy (fit the shown component into the visible window.)
  • igx-overlay is rendered on top of all other views/components (any previously existing html on the page) etc.
  • igx-overlay covers the whole window 100% width and height.
  • The shown component is inside content div, which is inside wrapper div.
  • igx-overlay displays each shown component based on the options specified if the component fits into the visible window.
  • The component repositioned and rendered correctly in the window even when the rendering options passed should result in otherwise a partially hidden component. No scrollbars should appear.
  • igx-overlay margins should be rendered correctly
  • igx-overlay displays each shown component in the browser’s visible window and tries to fit it in case of AutoPosition.
  • When adding more than one component to show in igx-overlay:
    • When the options used fit the component in the window - adding a new instance of the component with the same options will render it on top of the previous one.
    • When the options used will not fit the component in the window and AutoPosition is used - adding a new instance of the component with the same options, will render it on top of the previous one.(For both scenarios when options used fit the component in the window and when AutoPosition is used to fit the component)
  • When adding a component like Menu that has a sub-menu near the visible window, upon opening the submenu, no scrollbar will appear but the submenus are rearranged in order to fit in the visible window.
  • If the width/height allows, the submenu should be show in the window and if not, it should be positioned in the window.
  1. ElasticPositionStrategy (resize the shown component to fit into the visible window.)
  • igx-overlay is rendered on top of all other views/components (any previously existing html on the page) etc.
  • igx-overlay covers the whole window 100% width and height.
  • The shown component is inside content div, which is inside wrapper div.
  • igx-overlay displays each shown component based on the options specified if the component fits into the visible window.
  • The component repositioned and rendered correctly in the window even when the rendering options passed should result in otherwise a partially hidden component.
  • igx-overlay margins should be rendered correctly
  • igx-overlay displays each shown component in the browser’s visible window and tries to fit it in case of ElasticPosition.
  • When adding more than one component to show in igx-overlay:
    • When the options used fit the component in the window - adding a new instance of the component with the same options will render it on top of the previous one.
    • When the options used will not fit the component in the window and ElasticPosition is used - adding a new instance of the component with the same options, will render it on top of the previous one.(For both scenarios when options used fit the component in the window and when ElasticPosition is used to fit the component)
  • When adding a component like Menu that has a sub-menu near the visible window, upon opening the submenu, no scrollbar will appear but the submenus are rearranged in order to fit in the visible window.
  • If the width/height allows, the submenu should be show in the window and if not, it should be positioned in the window.
  1. ContainerPositionStrategy
  • The shown component, by default, is in the center of the outlet.

II. Scroll Strategy

  1. NoOperation
  • Does nothing.
  1. Block
  • The component do not scroll with the window. The event is canceled. No scrolling happens.
  • The component shown in igx-overlay do not change its state. For example, an expanded DropDown stays expanded during a scrolling attempt.
  1. Close (Uses a tolerance and closes an expanded component upon scrolling if the tolerance is exceeded.(example: DropDown or Dialog component collapses/closes after scrolling 10px.)
  • Till tolerance scrolling happens.
  • The component shown in igx-overlay do not change its state until it exceeds the scrolling tolerance set.
  • The component shown in igx-overlay changes its state when it exceeds the scrolling tolerance set (an expanded DropDown, Menu, DatePicker, etc. collapses).
  1. Absolute
  • Scrolls everything.
  • Components persist open state.

III. Interaction

  1. Modal
  • When igx-overlay is set as modal, the igx-overlay applies a greyed out mask layer and interaction is allowed only for the shown component (dialog window only). This includes mouse and keyboard interactions (Tab allows changing focus only through the component shown inside igx-overlay and it’s children. Esc key closes the dialog. PageUp/PageDown/Home/End keys do nothing. --> behavior example.
  • When reaching the last focusable element start from the first one again (looping).
  • When igx-overlay is set as not a modal, the igx-overlay do not apply a greyed out mask layer and interactions via mouse and keyboard for the window are allowed. Tab allows changing focus to other components/elements on the window which are not shown via the igx-overlay (For example, set focus on existing links).
  • Clicking outside the component may or may not close the overlay depending on closeOnOutSide click settings.

IV. Keyboard interaction:

  1. Escape - closes overlay if it is in modal mode and does nothing when in no modal mode (DropDown, DIalog, etc.).

V. General:

1) Css:

  • All appropriate css classes should be applied on igx-overlay initialization. (“class overlay”, incl. position, width, height, etc.)
  • All css properties set should be actually applied.

Manual

7. References

Angular Material CDK - overlay and portal categories https://material.angular.io/cdk/categories

Angular Material GitHub repository https://github.com/angular/material2

Angular Material Overlay https://github.com/angular/material2/tree/master/src/cdk/overlay

Angular Material Portal https://github.com/angular/material2/tree/master/src/cdk/portal

Clone this wiki locally
You can’t perform that action at this time.