Polymer-based web component for a D2L dropdown
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo
screenshots
test
.editorconfig
.eslintrc.json
.gitignore
.travis.yml
CODEOWNERS
LICENSE
README.md
all-imports.html
bower.json
d2l-dropdown-button-subtle.html
d2l-dropdown-button.html
d2l-dropdown-content-behavior.html
d2l-dropdown-content.html
d2l-dropdown-context-menu.html
d2l-dropdown-menu.html
d2l-dropdown-more.html
d2l-dropdown-opener-behavior.html
d2l-dropdown.html
index.html
package.json
polymer.json
wct.conf.json

README.md

Looking for SASS-based vui-dropdown? It's over here.

d2l-dropdown

Published on webcomponents.org Bower version Build status

A Polymer-based web component for dropdown/flyouts.

Installation

d2l-dropdown can be installed from Bower:

bower install d2l-dropdown

Usage

Include the webcomponents.js "lite" polyfill (for browsers who don't natively support web components), then import the opener and content components as needed:

<head>
  <script src="../webcomponentsjs/webcomponents-lite.js"></script>
</head>

Dropdown Openers

Generic Opener

d2l-dropdown is a generic opener for dropdown content (d2l-dropdown-content or d2l-dropdown-menu) enabling alternate opener implementation using existing elements/components. Provide and indicate your own opener element with the class attribute value d2l-dropdown-opener. Wire-up is automatic.

<d2l-dropdown>
  <button class="d2l-dropdown-opener">Open!</button>
  <d2l-dropdown-content>
    Some content...
  </d2l-dropdown-content>
</d2l-dropdown>

If the dropdown is initially empty when it's opened, the dropdown pointer will not be positioned correctly. In such cases, the no-auto-open attribute may be added to the opener, enabling you to take control of when the dropdown is actually opened:

<d2l-dropdown no-auto-open>
  ...
</d2l-dropdown>
dropdown.addEventListener('click', function() {
  // fetch some content
  ...
  // take control of when the dropdown is actually opened
  dropdown.toggleOpen();
});

Button Opener

d2l-dropdown-button is a d2l-button opener for dropdown content (d2l-dropdown-content or d2l-dropdown-menu). Provide text for the button and content component as needed.

<d2l-dropdown-button text="Open!" primary>
  <d2l-dropdown-content>
    Some content...
  </d2l-dropdown-content>
</d2l-dropdown-button>
  • primary - optionally render button as primary button

Subtle Button Opener

d2l-dropdown-button-subtle is a d2l-button-subtle opener for dropdown content (d2l-dropdown-content or d2l-dropdown-menu). Provide text for the button and content component as needed.

<d2l-dropdown-button-subtle text="Open!">
  <d2l-dropdown-content>
    Some content...
  </d2l-dropdown-content>
</d2l-dropdown-button-subtle>

Context Menu Opener

d2l-dropdown-context-menu is a simple/minimal opener for dropdown content (d2l-dropdown-content or d2l-dropdown-menu). Provide text for accessibility and content component as needed. Optionally, specify the translucent attribute for busy/rich backgrounds.

<d2l-dropdown-context-menu text="Open!">
  <d2l-dropdown-content>
    Some content...
  </d2l-dropdown-content>
</d2l-dropdown-context-menu>

More Opener

d2l-dropdown-more is a simple/minimal opener for dropdown content (d2l-dropdown-content or d2l-dropdown-menu). Provide text for accessibility and content component as needed. Optionally, specify the translucent attribute for busy/rich backgrounds.

<d2l-dropdown-more text="Open!">
  <d2l-dropdown-content>
    Some content...
  </d2l-dropdown-content>
</d2l-dropdown-more>

Visible on Ancestor Behavior

For busy/rich backgrounds, the d2l-dropdown-more and d2l-dropdown-context-menu openers support the VisibleOnAncestorBehavior that can be enabled by specifying the visible-on-ancestor attribute. See VisibleOnAncestorBehavior for more details on configuring that behavior.

<div class="translucent-container d2l-visible-on-ancestor-target">
  <img alt="" src="https://s.brightspace.com/course-images/images/e4fbb461-4cd9-4512-8304-44f2c2b741f1/tile-low-density-max-size.jpg"/>
  <d2l-dropdown-more text="Open!" translucent visible-on-ancestor>
    <d2l-dropdown-content>
      Some content...
    </d2l-dropdown-content>
  </d2l-dropdown-more>
</div>

Dropdown Contents

Generic Content

d2l-dropdown-content is a generic container for dropdown content. It provides behavior such as sizing, positioning, and managing focus gain/loss.

<d2l-dropdown-button text="Open!" primary>
  <d2l-dropdown-content min-width="150" max-width="400">
    <a href="https://www.google.com">Google</a>
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
    <a href="http://www.desire2learn.com">D2L</a>
  </d2l-dropdown-content>
</d2l-dropdown-button>
  • min-width (number) - optionally override default min-width
  • max-width (number) - optionally override default max-width
  • no-auto-fit - optionally opt out of auto-sizing
  • no-padding - optionally render with no padding
  • no-pointer - optionally render without a pointer
  • render-content - optionally stamp contents into DOM immediately
  • vertical-offset - optionally provide custom offset, positive or negative
  • align (enum) - optionally align dropdown. Valid values are "start","end". If not set, the dropdown will attempt be centred
  • boundary (object) - optionally provide boundaries to where the dropdown will appear. Valid properties are "above", "below", "left", "right"
// triggered when dropdown opened
content.addEventListener('d2l-dropdown-open', () => { ... });

// triggered when dropdown closed
content.addEventListener('d2l-dropdown-close', () => { ... });

Menu Content

d2l-dropdown-menu is a container for a d2l-menu component. It provides behavior in addition to the basic behavior of d2l-dropdown-content such as closing the menu when menu items are selected, resetting to the root of nested menus when reopening, etc.

<d2l-dropdown-button text="Open!" primary>
  <d2l-dropdown-menu id="dropdown">
    <d2l-menu label="Astronomy">
      <d2l-menu-item text="Introduction" id="first-item" ></d2l-menu-item>
      <d2l-menu-item text="Searching for the Heavens "></d2l-menu-item>
      <d2l-menu-item text="The Solar System">
        <d2l-menu>
          <d2l-menu-item text="Formation"></d2l-menu-item>
          <d2l-menu-item text="Modern Solar System"></d2l-menu-item>
          <d2l-menu-item text="Future Solar System"></d2l-menu-item>
          <d2l-menu-item text="The Planets"></d2l-menu-item>
          <d2l-menu-item text="The Sun"></d2l-menu-item>
          <d2l-menu-item text="Solar &amp; Lunar Eclipses"></d2l-menu-item>
          <d2l-menu-item text="Meteors &amp; Meteorites"></d2l-menu-item>
          <d2l-menu-item text="Asteroids"></d2l-menu-item>
          <d2l-menu-item text="Comets"></d2l-menu-item>
        </d2l-menu>
      </d2l-menu-item>
      <d2l-menu-item text="Stars &amp; Galaxies"></d2l-menu-item>
      <d2l-menu-item text="The Night Sky"></d2l-menu-item>
      <d2l-menu-item text="The Universe" id="last-item"></d2l-menu-item>
    </d2l-menu>
  </d2l-dropdown-menu>
</d2l-dropdown-button>

Developing, Testing and Contributing

After cloning the repo, run npm install to install dependencies.

If you don't have it already, install the Polymer CLI globally:

npm install -g polymer-cli

To start a local web server that hosts the demo page and tests:

polymer serve

To lint (eslint and Polymer lint):

npm run lint

To run unit tests locally using Polymer test:

npm run test:polymer:local

To lint AND run local unit tests:

npm test