Contact us
Get started

Directory

← Back

button

Polymer-based web components for D2L buttons

Author

Contributors

Rating

Links

[ This description is mirrored from README.md at github.com/BrightspaceUI/button on 2019-05-22 ]

d2l-button

Published on webcomponents.org Bower version Build status

A series of Polymer-based web components and Sass mixins for D2L buttons.

screenshot of button component

screenshot of subtle button component

screenshot of icon button component

For further information on this and other components, refer to The Brightspace UI Guide.

Installation

d2l-button can be installed from Bower:

bower install d2l-button

Usage

Include the webcomponents.js "lite" polyfill (for browsers who don't natively support web components), then import d2l-button.html:

Button

<head>
    <script src="../webcomponentsjs/webcomponents-lite.js"></script>
    <link rel="import" href="../d2l-button/d2l-button.html">
</head>

The <d2l-button> element can be used just like the native button element, but also supports the primary attribute for denoting the primary button.

Normal button:

screenshot of normal buttons

Primary button:

screenshot of primary buttons

<d2l-button primary>Primary</d2l-button>
<d2l-button>Secondary</d2l-button>
<d2l-button disabled>Disabled</d2l-button>

As an alternative to the web component, a Sass mixin can be used to apply button styles to your button elements:

@import 'bower_components/d2l-button/d2l-button.scss';

.my-button {
    @include d2l-button();
}

The primary and disabled attributes work the same way as they do with the web component.

Subtle Button

<head>
    <script src="../webcomponentsjs/webcomponents-lite.js"></script>
    <link rel="import" href="../d2l-button/d2l-button-subtle.html">
</head>

The subtle button shows text with an optional icon, and can be added by using the <d2l-button-subtle> custom element. It should be used for advanced or de-emphasized actions.

  • It is strongly recommended to use text and icon as opposed to putting content in the slot to ensure that the recommended subtle button style is maintained.

Without icon:

screenshot of subtle buttons without icons

With icon:

screenshot of subtle buttons with icons

With icon on right:

screenshot of subtle buttons with icon on the right

Alignment (bottom uses h-align="text")

screenshot of subtle buttons with different alignments

<d2l-button-subtle text="Subtle Button"></d2l-button-subtle>
<d2l-button-subtle icon="d2l-tier1:bookmark-hollow" text="Subtle Button with Icon"></d2l-button-subtle>
<d2l-button-subtle icon="d2l-tier1:bookmark-hollow" text="Subtle Button with Right Icon" icon-right></d2l-button-subtle>
<d2l-button-subtle icon="d2l-tier1:gear" text="Disabled Button" disabled></d2l-button-subtle>
<d2l-button-subtle icon="d2l-tier1:gear" text="Text Aligned" h-align="text"></d2l-button-subtle>

As an alternative to the web component, a Sass mixin can be used to apply button styles to your button elements:

@import 'bower_components/d2l-button/d2l-button.scss';

.my-button {
    @include d2l-button-subtle();
}

Usage is slightly different in that the text and icon attributes are not used, and instead their content is added within the button. For example:

<button class="my-button">
    <d2l-icon icon="d2l-tier1:gear"></d2l-icon>
    Subtle Button with icon
</button>

Icon Button

<head>
    <script src="../webcomponentsjs/webcomponents-lite.js"></script>
    <link rel="import" href="../d2l-button/d2l-button-icon.html">
</head>

The icon button shows an icon with an aria-label, and can be added by using the <d2l-button-icon> custom element. It should be used when icons perform a clickable action.

screenshot of icon buttons

Alignment (bottom uses h-align="text")

screenshot of icon buttons with different alignments

Translucent (for use on rich/busy backgrounds, specify the translucent attribute)

screenshot of icon buttons with different alignments

<d2l-button-icon icon="d2l-tier1:bookmark-hollow" text="Bookmark"></d2l-button-icon>
<d2l-button-icon icon="d2l-tier1:gear" text="Translucent" translucent></d2l-button-icon>
<d2l-button-icon icon="d2l-tier1:gear" text="Settings (disabled)" disabled></d2l-button-icon>
<d2l-button-icon icon="d2l-tier1:gear" text="Text Aligned" h-align="text"></d2l-button-icon>

As an alternative to the web component, a Sass mixin can be used to apply button styles to your button elements:

@import 'bower_components/d2l-button/d2l-button.scss';

.my-button-icon {
    @include d2l-button-icon();
}

Usage is slightly different in that the text and icon attributes are not used. Instead, the icon is added within the button and the aria-label is added as a button attribute. For example:

<button class="my-button-icon" aria-label="Settings">
    <d2l-icon icon="d2l-tier1:gear"></d2l-icon>
</button>

Floating Workflow Buttons

Floating workflow buttons behavior can be added by using the <d2l-floating-buttons> custom element. When the normal position of the workflow buttons is below the bottom edge of the view-port, they'll dock at the bottom edge. When the normal position becomes visible, they'll undock.

screenshot of floating buttons

<head>
    <script src="../webcomponentsjs/webcomponents-lite.js"></script>
    <link rel="import" href="../d2l-button/d2l-button.html">
    <link rel="import" href="../d2l-button/d2l-floating-buttons.html">
</head>

Include the <d2l-floating-buttons> container at the bottom of the page, and add your workflow button elements:

<d2l-floating-buttons>
    <d2l-button primary>Save</d2l-button>
    <d2l-button>Cancel</d2l-button>
</d2l-floating-buttons>

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:

polymer test --skip-plugin sauce

To lint AND run local unit tests:

npm test

Versioning

Commits and PR merges to master will automatically do a minor version bump which will:

  • Update the version in package.json
  • Add a tag matching the new version
  • Create a github release matching the new version

By using either [increment major] or [increment patch] notation inside your merge message, you can overwrite the default version upgrade of minor to the position of your choice.

Compatibility

(Loading compatibility data...)

Last updated: 2018-01-11

Was this helpful? Need more help?
Leave a comment or a question below. You can also join the chat on Discord or ask questions on StackOverflow.

Version

Dependencies

  • d2l-colors#^2.4.0
  • polymer#^1.9.0
  • iron-media-query#^1.0.8
Released
2017-06-21
Maturity
IMPORTED
License
Apache License 2.0

Compatibility

Framework
Polymer 1.0+
Polymer 2.0+ in 4.0.0
Browser
Browser Independent

Vaadin Add-on Directory

Find open-source widgets, add-ons, themes, and integrations for your Vaadin application. Vaadin Add-on Directory
The channel for finding, promoting, and distributing Vaadin add-ons.
Online