carbon-components-angular
Version:
Next generation components
980 lines (815 loc) • 36.8 kB
HTML
<html class="no-js" lang="">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<title>carbon-components-angular documentation</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" type="image/x-icon" href="../images/favicon.ico">
<link rel="stylesheet" href="../styles/style.css">
<link rel="stylesheet" href="../styles/dark.css">
</head>
<body>
<div class="navbar navbar-default navbar-fixed-top d-block d-sm-none">
<a href="../" class="navbar-brand">carbon-components-angular documentation</a>
<button type="button" class="btn btn-default btn-menu ion-ios-menu" id="btn-menu"></button>
</div>
<div class="xs-menu menu" id="mobile-menu">
<div id="book-search-input" role="search"><input type="text" placeholder="Type to search"></div> <compodoc-menu></compodoc-menu>
</div>
<div class="container-fluid main">
<div class="row main">
<div class="hidden-xs menu">
<compodoc-menu mode="normal"></compodoc-menu>
</div>
<!-- START CONTENT -->
<div class="content injectable">
<div class="content-data">
<ol class="breadcrumb">
<li class="breadcrumb-item">Injectables</li>
<li class="breadcrumb-item" >DropdownService</li>
</ol>
<ul class="nav nav-tabs" role="tablist">
<li class="nav-item">
<a href="#info"
class="nav-link"
class="nav-link active"
role="tab" id="info-tab" data-bs-toggle="tab" data-link="info">Info</a>
</li>
<li class="nav-item">
<a href="#source"
class="nav-link"
role="tab" id="source-tab" data-bs-toggle="tab" data-link="source">Source</a>
</li>
</ul>
<div class="tab-content">
<div class="tab-pane fade active in" id="info">
<p class="comment">
<h3>File</h3>
</p>
<p class="comment">
<code>src/dropdown/dropdown.service.ts</code>
</p>
<section data-compodoc="block-index">
<h3 id="index">Index</h3>
<table class="table table-sm table-bordered index-table">
<tbody>
<tr>
<td class="col-md-4">
<h6><b>Properties</b></h6>
</td>
</tr>
<tr>
<td class="col-md-4">
<ul class="index-list">
<li>
<span class="modifier">Protected</span>
<a href="#_offset" >_offset</a>
</li>
<li>
<span class="modifier">Protected</span>
<a href="#animationFrameSubscription" >animationFrameSubscription</a>
</li>
<li>
<span class="modifier">Protected</span>
<a href="#menuInstance" >menuInstance</a>
</li>
</ul>
</td>
</tr>
<tr>
<td class="col-md-4">
<h6><b>Methods</b></h6>
</td>
</tr>
<tr>
<td class="col-md-4">
<ul class="index-list">
<li>
<a href="#appendToBody" >appendToBody</a>
</li>
<li>
<a href="#appendToDropdown" >appendToDropdown</a>
</li>
<li>
<a href="#ngOnDestroy" >ngOnDestroy</a>
</li>
<li>
<span class="modifier">Protected</span>
<a href="#positionDropdown" >positionDropdown</a>
</li>
<li>
<a href="#updatePosition" >updatePosition</a>
</li>
</ul>
</td>
</tr>
<tr>
<td class="col-md-4">
<h6><b>Accessors</b></h6>
</td>
</tr>
<tr>
<td class="col-md-4">
<ul class="index-list">
<li>
<a href="#offset" >offset</a>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
</section>
<section data-compodoc="block-constructor">
<h3 id="constructor">Constructor</h3>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<code>constructor(placeholderService: <a href="../injectables/PlaceholderService.html" target="_self">PlaceholderService</a>, animationFrameService: <a href="../injectables/AnimationFrameService.html" target="_self">AnimationFrameService</a>)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="30" class="link-to-prism">src/dropdown/dropdown.service.ts:30</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div>
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
</tr>
</thead>
<tbody>
<tr>
<td>placeholderService</td>
<td>
<code><a href="../injectables/PlaceholderService.html" target="_self" >PlaceholderService</a></code>
</td>
<td>
No
</td>
</tr>
<tr>
<td>animationFrameService</td>
<td>
<code><a href="../injectables/AnimationFrameService.html" target="_self" >AnimationFrameService</a></code>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</div>
</td>
</tr>
</tbody>
</table>
</section>
<section data-compodoc="block-methods">
<h3 id="methods">
Methods
</h3>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="appendToBody"></a>
<span class="name">
<span ><b>appendToBody</b></span>
<a href="#appendToBody"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<code>appendToBody(parentRef: HTMLElement, menuRef: HTMLElement, classList)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="44"
class="link-to-prism">src/dropdown/dropdown.service.ts:44</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Appends the menu to the body, or a <code>cds-placeholder</code> (if defined)</p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>parentRef</td>
<td>
<code>HTMLElement</code>
</td>
<td>
No
</td>
<td>
<p>container to position relative to</p>
</td>
</tr>
<tr>
<td>menuRef</td>
<td>
<code>HTMLElement</code>
</td>
<td>
No
</td>
<td>
<p>menu to be appended to body</p>
</td>
</tr>
<tr>
<td>classList</td>
<td>
</td>
<td>
No
</td>
<td>
<p>any extra classes we should wrap the container with</p>
</td>
</tr>
</tbody>
</table>
</div>
<div>
</div>
<div class="io-description">
<b>Returns : </b> <code>HTMLElement</code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="appendToDropdown"></a>
<span class="name">
<span ><b>appendToDropdown</b></span>
<a href="#appendToDropdown"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<code>appendToDropdown(hostRef: HTMLElement)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="77"
class="link-to-prism">src/dropdown/dropdown.service.ts:77</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Reattach the dropdown menu to the parent container</p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>hostRef</td>
<td>
<code>HTMLElement</code>
</td>
<td>
No
</td>
<td>
<p>container to append to</p>
</td>
</tr>
</tbody>
</table>
</div>
<div>
</div>
<div class="io-description">
<b>Returns : </b> <code>HTMLElement</code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="ngOnDestroy"></a>
<span class="name">
<span ><b>ngOnDestroy</b></span>
<a href="#ngOnDestroy"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<code>ngOnDestroy()</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="102"
class="link-to-prism">src/dropdown/dropdown.service.ts:102</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description">
<b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >void</a></code>
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="positionDropdown"></a>
<span class="name">
<span class="modifier">Protected</span>
<span ><b>positionDropdown</b></span>
<a href="#positionDropdown"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="modifier-icon icon ion-ios-reset"></span>
<code>positionDropdown(parentRef, menuRef)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="106"
class="link-to-prism">src/dropdown/dropdown.service.ts:106</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Optional</td>
</tr>
</thead>
<tbody>
<tr>
<td>parentRef</td>
<td>
No
</td>
</tr>
<tr>
<td>menuRef</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</div>
<div>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >void</a></code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="updatePosition"></a>
<span class="name">
<span ><b>updatePosition</b></span>
<a href="#updatePosition"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<code>updatePosition(parentRef)</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="98"
class="link-to-prism">src/dropdown/dropdown.service.ts:98</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>position an open dropdown relative to the given parentRef</p>
</div>
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Optional</td>
</tr>
</thead>
<tbody>
<tr>
<td>parentRef</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</div>
<div>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >void</a></code>
</div>
<div class="io-description">
</div>
</td>
</tr>
</tbody>
</table>
</section>
<section data-compodoc="block-properties">
<h3 id="inputs">
Properties
</h3>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="_offset"></a>
<span class="name">
<span class="modifier">Protected</span>
<span ><b>_offset</b></span>
<a href="#_offset"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<i>Default value : </i><code>defaultOffset</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="30" class="link-to-prism">src/dropdown/dropdown.service.ts:30</a></div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="animationFrameSubscription"></a>
<span class="name">
<span class="modifier">Protected</span>
<span ><b>animationFrameSubscription</b></span>
<a href="#animationFrameSubscription"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<i>Default value : </i><code>new Subscription()</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="28" class="link-to-prism">src/dropdown/dropdown.service.ts:28</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>Maintains an Event Observable Subscription for the global requestAnimationFrame.
requestAnimationFrame is tracked only if the <code>Dropdown</code> is appended to the body otherwise we don't need it</p>
</div>
</td>
</tr>
</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="menuInstance"></a>
<span class="name">
<span class="modifier">Protected</span>
<span ><b>menuInstance</b></span>
<a href="#menuInstance"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<i>Type : </i> <code>HTMLElement</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="22" class="link-to-prism">src/dropdown/dropdown.service.ts:22</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description"><p>reference to the body appended menu</p>
</div>
</td>
</tr>
</tbody>
</table>
</section>
<section data-compodoc="block-accessors">
<h3 id="accessors">
Accessors
</h3>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="offset"></a>
<span class="name"><b>offset</b><a href="#offset"><span class="icon ion-ios-link"></span></a></span>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="accessor"><b>get</b><code>offset()</code></span>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="16" class="link-to-prism">src/dropdown/dropdown.service.ts:16</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<span class="accessor"><b>set</b><code>offset(value: literal type)</code></span>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="12" class="link-to-prism">src/dropdown/dropdown.service.ts:12</a></div>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-description">
<b>Parameters :</b>
<table class="params">
<thead>
<tr>
<td>Name</td>
<td>Type</td>
<td>Optional</td>
</tr>
</thead>
<tbody>
<tr>
<td>value</td>
<td>
<code>literal type</code>
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</div>
<div>
</div>
<div class="io-description">
<b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >void</a></code>
</div>
</td>
</tr>
</tbody>
</table>
</section>
</div>
<div class="tab-pane fade tab-source-code" id="source">
<pre class="line-numbers compodoc-sourcecode"><code class="language-typescript">import { Injectable, ElementRef, OnDestroy } from "@angular/core";
import { PlaceholderService } from "carbon-components-angular/placeholder";
import { Subscription } from "rxjs";
import { position } from "@carbon/utils-position";
import { AnimationFrameService } from "carbon-components-angular/utils";
import { closestAttr } from "carbon-components-angular/utils";
const defaultOffset = { top: 0, left: 0 };
@Injectable()
export class DropdownService implements OnDestroy {
public set offset(value: { top?: number, left?: number }) {
this._offset = Object.assign({}, defaultOffset, value);
}
public get offset() {
return this._offset;
}
/**
* reference to the body appended menu
*/
protected menuInstance: HTMLElement;
/**
* Maintains an Event Observable Subscription for the global requestAnimationFrame.
* requestAnimationFrame is tracked only if the `Dropdown` is appended to the body otherwise we don't need it
*/
protected animationFrameSubscription = new Subscription();
protected _offset = defaultOffset;
constructor(
protected placeholderService: PlaceholderService,
protected animationFrameService: AnimationFrameService
) {}
/**
* Appends the menu to the body, or a `cds-placeholder` (if defined)
*
* @param parentRef container to position relative to
* @param menuRef menu to be appended to body
* @param classList any extra classes we should wrap the container with
*/
appendToBody(parentRef: HTMLElement, menuRef: HTMLElement, classList): HTMLElement {
// build the dropdown list container
menuRef.style.display = "block";
const dropdownWrapper = document.createElement("div");
dropdownWrapper.className = `dropdown ${classList}`;
dropdownWrapper.style.width = parentRef.offsetWidth + "px";
dropdownWrapper.style.position = "absolute";
dropdownWrapper.appendChild(menuRef);
// append it to the placeholder
if (this.placeholderService.hasPlaceholderRef()) {
this.placeholderService.appendElement(dropdownWrapper);
// or append it directly to the body
} else {
document.body.appendChild(dropdownWrapper);
}
this.menuInstance = dropdownWrapper;
this.animationFrameSubscription = this.animationFrameService.tick.subscribe(() => {
this.positionDropdown(parentRef, dropdownWrapper);
});
// run one position in sync, so we're less likely to have the view "jump" as we focus
this.positionDropdown(parentRef, dropdownWrapper);
return dropdownWrapper;
}
/**
* Reattach the dropdown menu to the parent container
* @param hostRef container to append to
*/
appendToDropdown(hostRef: HTMLElement): HTMLElement {
// if the instance is already removed don't try and remove it again
if (!this.menuInstance) { return; }
const instance = this.menuInstance;
const menu = instance.firstElementChild as HTMLElement;
// clean up the instance
this.menuInstance = null;
menu.style.display = "none";
hostRef.appendChild(menu);
this.animationFrameSubscription.unsubscribe();
if (this.placeholderService.hasPlaceholderRef() && this.placeholderService.hasElement(instance)) {
this.placeholderService.removeElement(instance);
} else if (document.body.contains(instance)) {
document.body.removeChild(instance);
}
return instance;
}
/**
* position an open dropdown relative to the given parentRef
*/
updatePosition(parentRef) {
this.positionDropdown(parentRef, this.menuInstance);
}
ngOnDestroy() {
this.animationFrameSubscription.unsubscribe();
}
protected positionDropdown(parentRef, menuRef) {
if (!menuRef) {
return;
}
let leftOffset = 0;
const boxMenu = menuRef.querySelector(".cds--list-box__menu");
if (boxMenu) {
// If the parentRef and boxMenu are in a different left position relative to the
// window, the the boxMenu position has already been flipped and a check needs to be done
// to see if it needs to stay flipped.
if (parentRef.getBoundingClientRect().left !== boxMenu.getBoundingClientRect().left) {
// The getBoundingClientRect().right of the boxMenu if it were hypothetically flipped
// back into the original position before the flip.
const testBoxMenuRightEdgePos =
parentRef.getBoundingClientRect().left - boxMenu.getBoundingClientRect().left + boxMenu.getBoundingClientRect().right;
if (testBoxMenuRightEdgePos > (window.innerWidth || document.documentElement.clientWidth)) {
leftOffset = parentRef.offsetWidth - boxMenu.offsetWidth;
}
// If it has not already been flipped, check if it is necessary to flip, ie. if the
// boxMenu is outside of the right viewPort.
} else if (boxMenu.getBoundingClientRect().right > (window.innerWidth || document.documentElement.clientWidth)) {
leftOffset = parentRef.offsetWidth - boxMenu.offsetWidth;
}
}
// If cds-placeholder has a parent with a position(relative|fixed|absolute) account for the parent offset
const closestMenuWithPos = closestAttr("position", ["relative", "fixed", "absolute"], menuRef.parentElement);
const topPos = closestMenuWithPos ? closestMenuWithPos.getBoundingClientRect().top * -1 : this.offset.top;
const leftPos = closestMenuWithPos ? closestMenuWithPos.getBoundingClientRect().left * -1 : this.offset.left + leftOffset;
let pos = position.findAbsolute(parentRef, menuRef, "bottom");
pos = position.addOffset(pos, topPos, leftPos);
position.setElement(menuRef, pos);
}
}
</code></pre>
</div>
</div>
</div><div class="search-results">
<div class="has-results">
<h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
<ul class="search-results-list"></ul>
</div>
<div class="no-results">
<h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
</div>
</div>
</div>
<!-- END CONTENT -->
</div>
</div>
<label class="dark-mode-switch">
<input type="checkbox">
<span class="slider">
<svg class="slider-icon" viewBox="0 0 24 24" fill="none" height="20" stroke="#000" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" width="20" xmlns="http://www.w3.org/2000/svg">
<path d="M21 12.79A9 9 0 1111.21 3 7 7 0 0021 12.79z"></path>
</svg>
</span>
</label>
<script>
var COMPODOC_CURRENT_PAGE_DEPTH = 1;
var COMPODOC_CURRENT_PAGE_CONTEXT = 'injectable';
var COMPODOC_CURRENT_PAGE_URL = 'DropdownService.html';
var MAX_SEARCH_RESULTS = 15;
</script>
<script src="../js/libs/custom-elements.min.js"></script>
<script src="../js/libs/lit-html.js"></script>
<script src="../js/menu-wc.js" defer></script>
<script nomodule src="../js/menu-wc_es5.js" defer></script>
<script src="../js/libs/bootstrap-native.js"></script>
<script src="../js/libs/es6-shim.min.js"></script>
<script src="../js/libs/EventDispatcher.js"></script>
<script src="../js/libs/promise.min.js"></script>
<script src="../js/libs/zepto.min.js"></script>
<script src="../js/compodoc.js"></script>
<script src="../js/tabs.js"></script>
<script src="../js/menu.js"></script>
<script src="../js/libs/clipboard.min.js"></script>
<script src="../js/libs/prism.js"></script>
<script src="../js/sourceCode.js"></script>
<script src="../js/search/search.js"></script>
<script src="../js/search/lunr.min.js"></script>
<script src="../js/search/search-lunr.js"></script>
<script src="../js/search/search_index.js"></script>
<script src="../js/lazy-load-graphs.js"></script>
</body>
</html>