Button Component

Description

Aurelia component implementation of a MDC button for usage with the pitaya-framework.

This documentation assumes you are at least slightly familiar with aurelia and its usage. If not, we highly suggest you take a look at its Quick Start section first to get a better understanding of the approaches that are presented it here.

Screenshot

Demo

MDC Design & API Documentation

• Material Design guidelines: Buttons
• MDC Button Demo
• MDC Button Documentation
• MDC Button Github Source

Installation

npm install @pitaya-components/button --save

Basic Usage

Import

You have a few options when importing a component into your layout:

Template

<template>
    <require from="@pitaya-components/button/dist/pitaya-button"></require>
    ...
</template>

View model

@viewResources( "@pitaya-components/button/dist/pitaya-button" )
export class MyView
{
    ...
}

Initialization

Our components are usually initialized by defining them in your views HTML. And can be accessed afterwards in the corresponding view model.

Template

<template>
    <pitaya-button
        view-model.ref="button"
        icon="favorite"
        variant="outlined"
        on-click.call="_openSnackbar('Outlined Button')"
        right-icon
    >
        BUTTON LABEL
    </pitaya-button>
    ...
</template>

View model

import {PitayaButton} from "@pitaya-components/button";

export class MyView
{
    public button: PitayaButton;

    public doSomething()
    {
        this.button.rightIcon = true;
    }
}

Variants

Text Button

Simple button with only a label.

<pitaya-button>
    SIMPLE BUTTON LABEL
</pitaya-button>

Dense Button

To style a dense button, add the dense attribute.

<pitaya-button	
    dense
>
    DENSE BUTTON LABEL
</pitaya-button>

Outlined Button

To style a outlined button, add variant="outlined".

<pitaya-button	
    variant="outlined"
>
    OUTLINED BUTTON LABEL
</pitaya-button>

Unelevated Button

To style a unelevated button, add variant="unelevated".

<pitaya-button	
    variant="unelevated"
>
    UNELEVATED BUTTON LABEL
</pitaya-button>

Raised Button

To style a raised button, add variant="raised".

<pitaya-button	
    variant="raised"
>
    RAISED BUTTON LABEL
</pitaya-button>

Shaped Button

To style a shaped button, add the rounded attribute.

<pitaya-button	
    rounded
>
    SHAPED BUTTON LABEL
</pitaya-button>

Icons

This component makes use of the Material Icons Font by Google

Every icon has a corresponding name.
For example: favorite will be displayed as a ♥

Leading Icon

Displaying a leading icon can be accomplished by adding icon="<icon-name>".

<pitaya-button	
    icon="favorite"
>
    BUTTON WITH HEART ICON
</pitaya-button>

Trailing Icon

Certain icons make more sense to appear after the button's text label rather than before. This can be accomplished by adding the right-icon attribute.

<pitaya-button	
    icon="favorite"
    right-icon
>
    BUTTON WITH HEART ICON RIGHT 
</pitaya-button>

Disabled

To disable a button, add the disabled attribute. Disabled buttons cannot be interacted with and also receive styles to indicate that they are inactive.

<pitaya-button	
    disabled
>
    DISABLED BUTTON LABEL
</pitaya-button>

Color Base

The default color scheme is primary. To switch to the secondary color add the color-base="secondary".

<pitaya-button	
    color-base="secondary"
>
    SECONDARY BUTTON LABEL
</pitaya-button>

The color-base attribute can be combined with other attributes like variant="raised".

<pitaya-button	
    variant="raised"
    color-base="secondary"
>
    RAISED SECONDARY BUTTON LABEL
</pitaya-button>

Event handlers

Attaching an event handler is as simple as adding on-<event>.call="<function>(<parameters>)". The function that you specify has to be defined as a method on the view model class, so that aurelias template engine can use it.

Template

<pitaya-button	
    on-click.call="myButtonHasBeenClicked(event)"
>
    BUTTON LABEL
</pitaya-button>

View model

export class MyView
{
    public myButtonHasBeenClicked(event: CustomEvent)
    {
        console.log("Event detail:", event.detail);
    }
}

You also can pass any parameter you like. Specifying event just tells the component that you wish to receive the event object, but if you define something else, it will be passed down to your function just like one would expect.

Template

<pitaya-button	
    on-click.call="myButtonHasBeenClicked('my custom message')"
>
    BUTTON LABEL
</pitaya-button>

View model

export class MyView
{
    public myButtonHasBeenClicked(message: string)
    {
        console.log(message);
    }
}

Bindables

A bindable is part of a core functionality of aurelia which basically allows you to configure a component from within your HTML code. They can be set/accessed via HTML attribute and also programmatically.

Template

<pitaya-button	
    type="submit"
    rounded
>
    BUTTON LABEL
</pitaya-button>

View model

import {PitayaButton} from "@pitaya-components/button";

export class MyView
{
    public button: PitayaButton;
    
    public someMethod()
    {
        this.button.type    = "submit";
        this.button.rounded = true;
    }
}

Bindable properties

Attribute / Property	Type
variant	"outlined" \| "unelevated" \| "raised"
color-base	"primary" \| "secondary"
type	string
name	string
icon	string
icon-right	boolean
dense	boolean
rounded	boolean
disabled	boolean
on-click	( event ) => {}
on-ready	( component ) => {}

Methods and properties

Method Signature	Description
reload() => void	Reinitializes the component

SASS mixins

Dependencies

Package	Url
aurelia-framework	aurelia-framework
@material/button	mdc-button
@material/ripple	mdc-ripple
pitaya-framework	pitaya-framework

Changes

The main repository uses tagged Releases to communicate changes between versions.

FAQ

Q: Why another JavaScript framework?
A: Read this article for a detailed overview of ours goals.

Reach Out!

Find us on Twitter for the latest news, and please consider giving us a ?? star on GitHub!

Support

For contributions in the form of bug fixes and changes, feel free to use Pull Requests or send us a DM on Twitter to discuss how best to approach your issue.

License

The Master component source code is licensed under the MIT license.