<x-deck>s are components that act similarly to slideshows or galleries where cards can be cycled independently of order with a variety of different transitions.
Basic usage
-
For basic transitions between <x-card>s, simply call the .shufflePrev() and .shuffleNext() methods of the <x-deck>.
-
Users can also call .shuffleTo(index) if they already know the index of the target card in the deck.
+
For basic transitions between <x-card>s, simply call the .previousCard() and .nextCard() methods of the <x-deck>.
+
Users can also call .showCard(index) if they already know the index of the target card in the deck.
+
The loop attribute option allows the deck to loop around after reaching the first or last index.
-
-
+
+
0I'm the first card!
@@ -80,46 +81,47 @@
x-deck
-
+
+
Markup
JavaScript
-
// assume prevButton, nextButton, toButton, and deck //are already defined as their respective DOM elements prevButton.addEventListener("click", function(){ deck.shufflePrev(); }); nextButton.addEventListener("click", function(){ deck.shuffleNext(); }); toButton.addEventListener("click", function(){ deck.shuffleTo(1); });
+
// assume prevButton, nextButton, toButton, and deck //are already defined as their respective DOM elements prevButton.addEventListener("click", function(){ deck.previousCard(); }); nextButton.addEventListener("click", function(){ deck.nextCard(); }); toButton.addEventListener("click", function(){ deck.showCard(1); });
The .shufflePrev(), .shuffleNext(), and .shuffleTo() methods can also be called with an optional direction parameter of either "forward" or "reverse" to specify how animations should progress.
+
The .previousCard(), .nextCard(), and .showCard() methods can also be called with an optional direction parameter of either "forward" or "reverse" to specify how animations should progress.
-
If this parameter is "auto" or not given, we automatically choose an animation direction depending on whether the new card is ahead of or behind the current card in the deck.
+
If this parameter is omitted, the animation direction defaults to "forward" if the new index is greater than the previously selected index, and "reverse" if less than the previously selected index.
// assume transitionButton and deck are already // defined as their respective DOM elements var types = [ "scrollLeft", "scrollUp", "scrollRight", "scrollDown", "flipX", "flipY", "coverLeft", "coverUp", "coverRight", "coverDown", "uncoverLeft", "uncoverUp", "uncoverRight", "uncoverDown", "none" ]; transitionButton.addEventListener("click", function(){ var oldType = deck.transitionType; deck.transitionType = types[(types.indexOf(oldType)+1) % type.length];
// force animation to make visible for demo deck.shuffleNext("forward"); });
+
// assume transitionButton and deck are already // defined as their respective DOM elements var types = [ "slide-up", "slide-down", "slide-left", "slide-right", "scale-fade", "none" ]; transitionButton.addEventListener("click", function(){ var oldType = deck.transitionType; deck.transitionType = types[(types.indexOf(oldType)+1) % type.length];
// force animation to make visible for demo deck.nextCard("forward"); });
While the <x-deck>'s transition-type attribute changes the animation of all cards, it is also possible to specify how a specific <x-card> animates when entering the deck with the transition-override attribute (also accessible through the .transitionOverride property.
-
An <x-card>'s transition-override attribute can take any of the same values as the <x-deck>'s transition-type attribute.
-
While the <x-deck>'s transition-type attribute changes the animation of all cards, it is also possible to specify how a specific <x-card> animates by specifying a transition-type attribute on individual <x-card> elements
-
- 0
- 1
+
+ 0
+ 12
@@ -215,7 +205,7 @@
Markup
- 0
+ 012
@@ -231,7 +221,7 @@
Markup
Markup
JavaScript
-
// assume addButton, removeButton, and deck //are already defined as their respective DOM elements // also assume that .randomColor simply returns a random color rgb string addButton.addEventListener("click", function(){ // deck.numCards retrieves the number of cards currently in the deck var newIndex = deck.numCards; var newCard = document.createElement("x-card"); newCard.style.backgroundColor = randomColor(); newCard.textContent = newIndex; deck.appendChild(newCard); // for demo, shuffle to newly inserted card deck.shuffleTo(newIndex); }); removeButton.addEventListener("click", function(){ if(deck.numCards > 0){ //deck.getCardAt retrieves the <x-card> at the given index var lastCard = deck.getCardAt(deck.numCards-1); deck.removeChild(lastCard); } });
+
// assume addButton, removeButton, and deck //are already defined as their respective DOM elements // also assume that .randomColor simply returns a random color rgb string addButton.addEventListener("click", function(){ // deck.numCards retrieves the number of cards currently in the deck var newIndex = deck.numCards; var newCard = document.createElement("x-card"); newCard.style.backgroundColor = randomColor(); newCard.textContent = newIndex; deck.appendChild(newCard); // for demo, shuffle to newly inserted card deck.showCard(newIndex); }); removeButton.addEventListener("click", function(){ if(deck.numCards > 0){ //deck.getCardAt retrieves the <x-card> at the given index var lastCard = deck.getCardAt(deck.numCards-1); deck.removeChild(lastCard); } });
Styling the <x-deck> and <x-card> elements can be done like any other DOM elements. (By default, the deck attempts to be 100% width and height of its parent element, but this can be overridden.)
However, the deck also provides some CSS selectors to customize how cards appear during animations.
-
To style how a card appears as it is transitioning out of the deck, apply styles to x-card[leaving]
+
To style how a card appears as it is transitioning out of the deck, apply styles to x-card[hide]
To style how a card appears when it is specifically selected in the deck, apply styles to x-card[selected]
Handling events: shufflestart, shuffleend, cardadd, and cardremove
+
Handling card switching events: show, hide
When the deck is transitioning cards, it fires events in order to signal different stages of the animation.
-
The <x-deck> fires a shufflestart event when it has finished setting all attributes of the deck and is about to start a transition animation. This event also provides the following information in e.detail:
-
{
- 'oldCard': the previously selected x-card that the transition is animating away from,
- 'newCard': the x-card that the transition is animating towards
-}
-
The <x-deck> fires a shuffleend event when a transition animation has completed. Much like a transitionend event, the shuffleend event will not fire if interrupted by another transition, and will thus only fire on a full animation completion. This event also provides the following information in e.detail:
-
{
- 'oldCard': the previously selected x-card that the transition just animated away from,
- 'newCard': the x-card that the transition animated towards (ie: the now-selected card)
-}
-
In addition, when a deck's <x-card>s are added or removed, the deck fires the cardadd and cardremove, respectively. Both of these events also provide the following information in e.detail:
-
{
- 'card': the x-card that was just added or removed
-}
-
+
An show event is fired from a card target after it has completed its show animation, and the show state has been finalized.
+
An hide event is fired from a card target after it has completed its hide animation, and the hide state has been finalized.
An <x-slidebox> is similar to an <x-deck>, in that it can slide between different slides of content.
-
However, the main difference is that <x-slidebox> treats the slides as a coherent filmstrip instead of as independent cards, so transitioning from one slide to another displays all slides in between during the animation.
-
-
<x-tabbar> elements are essentially containers for <x-tabbar-tab> elements.
-
By default, whenever an <x-tabbar-tab> element is clicked, it will fire a show event on its targeted elements. It is up to the element to respond to this event, but some components bundled in Brick have built in responses to show events.
+
By default, whenever an <x-tabbar-tab> element is clicked, it will fire a reveal event on its targeted elements. It is up to the element to respond to this event, but some components bundled in Brick have built in responses to reveal events.
Users can specify target elements by modifying the target-selector attribute or the .targetSelector property of the tabbar's tab with a document-relative CSS selector. This will essentially act as a delegation, so any elements matching the selector at the time of clicking the tab will be receive the event.
However, we can also provide an unchanging list of elements to target by editing the .targetElems propery of the tabbar's tab.
In its most basic form, place the <x-tooltip> in the markup immediately after the element that should trigger it. (You can specify the target element with an attribute, but the default is the previous sibling.)
-
By default, the <x-tooltip> will trigger on a click event, and will be auto-oriented.
-
Note that the tooltip is not removed from its markup location, and will thus retain the same nesting and DOM ancestors that it started in.
By default, the orientation is "auto", meaning that the <x-tooltip> will attempt to place itself in the best position that doesn't overlap the triggering element.
trigger-style: Specifying how to trigger a tooltip
-
This specifies what kind of interaction with a target element will
- trigger the element. You can either specify hover or
- any native event type.
-
-
You can also specify trigger-style="custom" to turn off built-in handlers and use the tooltip's .show, .hide, and .toggle methods to build your own triggers.
-
-
-
- Click this button!
-
- Click somewhere else to hide!
-
-
-
-
-
-
-
Markup
-
-
Custom trigger JavaScript
-
var toggleButton = document.getElementById("custom-toggle-button"); toggleButton.addEventListener("click", function(){ var tooltip = document.getElementById("trigger-style-demo-tip"); tooltip.toggle(); });
Using any of Brick's components is as simple as including the respective tag in your HTML markup. (See individual component docs for details.)
Important: To run code relying on any of Brick's tags, make sure to wait until the x-tags library's "DOMComponentsLoaded" event instead of just window.onload:
A box in which <x-card> elements can be cycled independently of order with a variety of different transitions
Attributes
-
transition-type
-
Defines the kind of transition animation that is used when cycling cards. Valid options: 'scrollLeft', 'scrollUp', 'scrollRight', 'scrollDown', 'flipX', 'flipY', 'coverLeft', 'coverUp', 'coverRight', 'coverDown', 'uncoverLeft', 'uncoverUp', 'uncoverRight', 'uncoverDown', 'none'. Defaults to 'scrollLeft'
+
loop
+
A boolean attribute that turns on/off the auto-looping feature when the x-deck has reached the beginning or end of its card index
-
selected-index
-
Defines which card index will be displayed. If set in the initial markup, this will initialize the given card as the selected card. Defaults to 0.
-
-
-
-
history-cap
-
Defines how many cards to keep in history to allow developers to simply return to the previously displayed card. Defaults to 10.
+
transition-type
+
Allows the user to set a default animation type for cards. If this attribute is added to an individual single <x-card> element, the animation specified will be used in place of the <x-deck>'s default card animation. Valid options are the same as the <x-deck>'s transition-type attribute.
-
x-card: transition-override
-
If transition-override is defined on a card, the animation used to transition to this card will be what is given here instead of the deck's animation. Valid options are the same as the <x-deck>'s transition-type attribute.
+
selected-index
+
Defines which card index will be displayed. If set in the initial markup, this will initialize the given card as the selected card.
@@ -392,48 +413,23 @@
Attributes
Methods
-
shuffleTo([progressType])
-
Transitions to the x-card at the given index. If given a progressType of 'forward', will perform the forwards animation. If given 'reverse', will performs the reverse animation. If the progressType is 'auto' or omitted, will perform forward animation if going to a larger index, and will perform reverse animation if going to a smaller index.
+
showCard(index||element, [direction])
+
Transitions an x-card element to the shown state via index or card element reference. If given a direction of 'forward', will perform the forwards animation. If given 'reverse', will performs the reverse animation.
-
shuffleNext([progressType])
-
Transitions to the next x-card in the deck. Takes an optional progressType of 'forward', 'reverse', or 'auto'. Also takes an optional callback function.
+
hideCard(index||element, [direction])
+
Transitions an x-card element to the hidden state via index or card element reference. If given a direction of 'forward', will perform the forwards animation. If given 'reverse', will performs the reverse animation.
-
shufflePrev([progressType])
-
Transitions to the previous x-card in the deck. Takes an optional progressType of 'forward', 'reverse', or 'auto'. Also takes an optional callback function.
+
nextCard(index||element, [direction])
+
Transitions to the next x-card in the deck. Takes an optional direction of 'forward' or 'reverse'.
-
getAllCards()
-
Returns a list of all x-card elements in the deck.
-
-
-
-
getSelectedCard()
-
Returns the currently selected x-card in the deck.
-
-
-
-
getCardIndex(cardEl)
-
Given an x-card element, returns its index in this deck, if it is a child element.
-
-
-
-
getCardAt(index)
-
Returns the x-card at the given index.
-
-
-
-
historyBack([progressType])
-
Transitions to the previously displayed card in the deck's history. progressType parameter acts similarly to shuffleTo's progressType parameter.
-
-
-
-
historyForward([progressType])
-
Transitions to the more recently displayed card in the deck's history. progressType parameter acts similarly to shuffleTo's progressType parameter.
+
previousCard(index||element, [direction])
+
Transitions to the previous x-card in the deck. Takes an optional direction of 'forward' or 'reverse'.
@@ -442,28 +438,13 @@
Methods
Events
-
shufflestart
-
A shufflestart event is fired by the <x-deck> element when, during the process of transitioning between cards, the two cards are in position to start animating, but have not yet begun the actual animation.
The event also receives the following custom datamap in `e.detail`: { 'oldCard': the previously selected x-card node that the transition is animating away from, 'newCard': the x-card node that the transition is animating towards }
-
-
-
-
shuffleend
-
A `shuffleend` event is fired by the <x-deck> element when a cycle from one card to another has been completed.
**Note:** Much like the `transitionend` event, this is not guaranteed to fire after every transition that fires a shufflestart. For example, if two transitions are queued up, with the second occurring during the first transition, only the second transition's `shuffleend` will fire, due to the first transition being interrupted.
The event also receives the following custom datamap in `e.detail`:
{ 'oldCard': the previously selected x-card node that the transition is animating away from, 'newCard': the x-card node that the transition is animating towards }
-
-
-
-
cardadd
-
Fired by the x-deck whenever an x-card is added.
Receives the following datamap in `e.detail`:
{ 'card': the x-card that was just added }
+
show
+
Fired from a card target after it has completed its show animation, and the show state has been finalized.
-
cardremove
-
Fired by the x-deck whenever an x-card is removed.
Receives the following datamap in `e.detail`:
{ 'card': the x-card that was just removed }
-
-
-
-
show
-
If an <x-card> element receives a 'show' event, the deck will automatically transition to the card that received the event. This event is not fired by the x-deck itself.
+
hide
+
Fired from a card target after it has completed its hide animation, and the hide state has been finalized.
@@ -472,8 +453,8 @@
Events
Getters
-
numCards
-
Returns the number of cards currently in the deck.
+
cards
+
Returns an array of all <x-card> elements within the <x-deck>.
@@ -481,11 +462,6 @@
Getters
Returns the <x-card> currently displayed in the deck.
-
-
cards
-
Returns an array of all <x-card>s in the deck.
-
-
transitionType
Returns the value of the 'transition-type' attribute.
@@ -496,48 +472,23 @@
Getters
Returns the value of the 'selected-index' attribute.
-
-
historyCap
-
Returns the value of the 'history-cap' attribute.
-
-
-
-
currHistorySize
-
Returns the number of cards currently stored in the deck's history.
-
-
-
-
currHistoryIndex
-
Returns the deck's current index in its history stack.
-
-
-
-
transitionOverride (on element)
-
Returns the transition override of the card.
-
-
Setters
-
transitionType
-
Sets the value of the 'transition-type' attribute.
+
selectedCard
+
Sets the provided <x-card> element as the selected card, and shows the element.
selectedIndex
-
Sets the value of the 'selected-index' attribute.
-
-
-
-
historyCap
-
Sets the value of the 'history-cap' attribute.
+
Sets the value of the 'selected-index' attribute, and shows the card at that index
Flips between two content elements with a CSS Animation, similar to flipping a playing card. The front face defaults to the first direct child element of the <x-flipbox>, and the back face defaults to the last direct child element.
A container that allows animated transitions between content panes, displaying all slides along the way. Think of the component as a filmstrip of slides that moves around in a viewport.
-
-
-
Attributes
-
-
-
orientation
-
Slide axis. Set as 'x' for horizontal animations, and set as 'y' for vertical animations.
Tab bars are used to display an app-level navigation/tabbing bar (usually at the bottom of the UI) that shows different content depending on which tab is selected.
@@ -877,7 +807,7 @@
Attributes
Events
-
show
+
reveal
The default event that a x-tabbar-tab will fire on its selected elements if not overridden by 'target-event'
A polyfill merging radiobutton/checkbox inputs into a single tag to provide a consistent UI and simplify markup. Automatically switches between radiobutton and checkbox depending on name attribute.
Content callout that appears in current context to point at an element and is associated with a triggering element and interaction-style in the underlying content
-
-
-
Attributes
-
-
-
orientation
-
Determines where the tooltip appears in relation to the triggering element. Valid options are 'top', 'bottom', 'left', 'right'. If not provided, or if invalid, defaults to auto placement of tooltip.
-
-
-
-
trigger-style
-
Indicates how the tooltip is triggered. Valid presets are 'hover' and 'custom'. When set to 'hover', the tooltip is triggered when the user moves their cursor over a triggering element, and dismissed when moved off. When set to 'custom', no default behavior is implemented for triggering the tooltip. This is useful when you want to define your own triggering system using the .show(), .hide(), and .toggle() API calls without any default behaviors getting in the way. If set to anything else, the tooltip will use this as the event name to listen for on targeted elems to show the tooltip. (defaults to 'click')
-
-
-
-
trigger-selector
-
Indicates how to select elements that would trigger the tooltip. If given a selector of '_previousSibling', the tooltip will use the immediately preceding sibling element in the DOM tree as its triggering element. Similarly, when set to '_nextSibling', the tooltip will use its next DOM sibling as its triggering element. Otherwise, the selector will be applied to the tooltip's parent node as a search query, and any elements that are not part of the tooltip itself will act as triggering elements for the tooltip. (For example, if you were to provide '.fancy-selector' as this attribute's value, and foo is your tooltip element, the elements you would get back would be same as those found from foo.parentNode.querySelectorAll('.fancy-selector').)
-
-
-
-
ignore-outer-trigger
-
If present, for non-'hover' and non-'custom' trigger styles, indicates whether an event firing outside of a targeting element should close the tooltip. Has no effect on preset trigger styles
-
-
-
-
ignore-tooltip-pointer-events
-
If present, pointer events on the tooltip will be ignored, keeping it from blocking interaction with underlying elements.
-
-
-
-
allow-overflow
-
By default, the tooltip will always try to place the tooltip in a way that is constrained by both the container element and the window's viewport (ie: accounting for scrolling).
If `allow-overflow` set, this will instead allow the tooltip to be placed freely, even if it overflows the containing element (However, the tooltip will still be constrained by the window's viewport).
-
-
-
-
-
-
Methods
-
-
-
refreshPosition()
-
This method immediately repositions the tooltip to recenter on the triggering element. This is useful if the tooltip's contents are changed and need to be immediately visually repositioned.
-
-
-
-
show()
-
This method forces the tooltip to display (this will fire a 'tooltipshown' event).
-
-
-
-
hide()
-
This method forces the tooltip to hide (this will fire a 'tooltiphidden' event).
-
-
-
-
toggle()
-
This method forces the tooltip to toggle whether it is visible or not (this will fire a 'tooltipshown' or 'tooltiphidden' event, whichever is appropriate).
-
-
-
-
-
-
Events
-
-
-
tooltipshown
-
Fired by the x-tooltip element when tooltip is shown
-
-
-
-
tooltiphidden
-
Fired by the x-tooltip element when tooltip is hidden
-
-
-
-
-
-
Getters
-
-
-
presetTriggerStyles
-
Returns a list of the valid preset style types for the 'trigger-style' attribute.
-
-
-
-
targetElems
-
Returns a list of all DOM elements currently selected as a target of the tooltip.
-
-
-
-
orientation
-
This will provide the current value of the orientation attribute.
-
-
-
-
triggerStyle
-
This will provide the current value of the trigger-style attribute.
-
-
-
-
triggerSelector
-
This will provide the current value of the trigger-selector attribute.
-
-
-
-
content
-
This will provide the DOM element that is acting as the content area of the tooltip.
-
-
-
-
ignoreOuterTrigger
-
This will provide the current value of the ignore-outer-trigger attribute.
-
-
-
-
ignoreTooltipPointerEvents
-
This will provide the current value of the ignore-tooltip-pointer-events attribute.
-
-
-
-
-
-
Setters
-
-
-
orientation
-
This will change the value of the tooltip's orientation attribute.
-
-
-
-
triggerStyle
-
This will change the value of the tooltip's trigger-style attribute.
-
-
-
-
triggerSelector
-
This will change the value of the tooltip's trigger-selector attribute.
-
-
-
-
content
-
This will replace the DOM element for the tooltip's content area with an entirely new DOM element, destroying the old one.
-
-
-
-
ignoreOuterTrigger
-
This will change the current value of the ignore-outer-trigger attribute.
-
-
-
-
ignoreTooltipPointerEvents
-
This will change the current value of the ignore-tooltip-pointer-events attribute.
- Brick 0.10.0
+ Brick 0.11.0
- Brick 0.10.0
+ Brick 0.11.0