npm package: @pitaya-components/master-component
Description: Aurelia component which helps building faster views and provides additional utility functionality.
Author: Mariachi Team
Latest version: 0.0.1

<h1 align="center">Button Component</h1>

<p align="center"><img height="250" src="_readme/pitaya-logo-button.svg"></p>

<p align="center">
<a href="https://npmcharts.com/compare/@pitaya-components/topbar?minimal=true"><img alt="npm" src="https://img.shields.io/npm/dw/@pitaya-components/topbar"></a>
<a href="https://www.npmjs.com/package/@pitaya-components/topbar"><img alt="npm" src="https://img.shields.io/npm/v/@pitaya-components/topbar"></a>
<a href="https://www.npmjs.com/package/@pitaya-components/topbar"><img alt="NPM" src="https://img.shields.io/npm/l/@pitaya-components/topbar"></a>
</p>
<!-- https://shields.io -->

## Description <a name="description"></a>

Aurelia component implementation of a [MDC button](https://github.com/material-components/material-components-web/tree/master/packages/mdc-button) for usage with the [pitaya-framework](https://github.com/pitaya-foundation/pitaya-framework).

_This documentation assumes you are at least slightly familiar with [aurelia](https://aurelia.io/) and its usage. If not, we highly suggest you take a look at its [Quick Start](https://aurelia.io/docs/tutorials/creating-a-todo-app) section first to get a better understanding of the approaches that are presented it here._

## Screenshot

![Buttons](./_readme/screenshot.png)

## [Demo](https://demo.pitaya-framework.com/#/button)

## MDC Design & API Documentation <a name="mdc-design-and-api-documentation"></a>

- [Material Design guidelines: Buttons](https://material.io/go/design-buttons)
- [MDC Button Demo](https://material-components.github.io/material-components-web-catalog/#/component/button)
- [MDC Button Documentation](https://material.io/develop/web/components/buttons/)
- [MDC Button Github Source](https://github.com/material-components/material-components-web/tree/master/packages/mdc-button)

## Installation

```bash
npm install @pitaya-components/button --save
```

## Basic Usage

### Import
You have a few options when importing a component into your layout:

##### Template
```html
<template>
	<require from="@pitaya-components/button/dist/pitaya-button"></require>
    ...
</template>
```

##### View model
```ts
@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
```html
<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
```ts
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.

```html
<pitaya-button>
	SIMPLE BUTTON LABEL
</pitaya-button>
```

### Dense Button
To style a dense button, add the `dense` attribute.

```html
<pitaya-button	
	dense
>
	DENSE BUTTON LABEL
</pitaya-button>
```

### Outlined Button
To style a outlined button, add `variant="outlined"`.

```html
<pitaya-button	
	variant="outlined"
>
	OUTLINED BUTTON LABEL
</pitaya-button>
```

###  Unelevated Button
To style a unelevated button, add `variant="unelevated"`.

```html
<pitaya-button	
	variant="unelevated"
>
	UNELEVATED BUTTON LABEL
</pitaya-button>
```

###  Raised Button
To style a raised button, add `variant="raised"`.

```html
<pitaya-button	
	variant="raised"
>
	RAISED BUTTON LABEL
</pitaya-button>
```

### Shaped Button
To style a shaped button, add the `rounded` attribute.

```html
<pitaya-button	
	rounded
>
	SHAPED BUTTON LABEL
</pitaya-button>
```

### Icons
This component makes use of the [Material Icons Font](https://material.io/tools/icons) by [Google](https://google.github.io/material-design-icons)

Every icon has a corresponding name.<br>
For example: `favorite` will be displayed as a &hearts;

#### Leading Icon
Displaying a leading icon can be accomplished by adding `icon="<icon-name>"`. 

```html
<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.

```html
<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.

```html
<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"`.

```html
<pitaya-button	
	color-base="secondary"
>
	SECONDARY BUTTON LABEL
</pitaya-button>
```
The `color-base` attribute can be combined with other attributes like `variant="raised"`.

```html
<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
```html
<pitaya-button	
	on-click.call="myButtonHasBeenClicked(event)"
>
	BUTTON LABEL
</pitaya-button>
```

##### View model
```ts
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
```html
<pitaya-button	
	on-click.call="myButtonHasBeenClicked('my custom message')"
>
	BUTTON LABEL
</pitaya-button>
```

##### View model
```ts
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
```html
<pitaya-button	
	type="submit"
	rounded
>
	BUTTON LABEL
</pitaya-button>
```

##### View model
```ts
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](https://github.com/aurelia/framework) |
| `@material/button` | [mdc-button](https://github.com/material-components/material-components-web/tree/master/packages/mdc-button) |
| `@material/ripple` | [mdc-ripple](https://github.com/material-components/material-components-web/tree/master/packages/mdc-ripple) |
| `pitaya-framework` | [pitaya-framework](https://github.com/pitaya-foundation/pitaya-framework) |

## Changes

The main repository uses tagged [Releases](https://github.com/pitaya-components/master-component/releases) to communicate changes between versions.

## FAQ

**Q:** Why another JavaScript framework? \
**A:** Read [this article](https://github.com/pitaya-components/master-component) for a detailed overview of ours goals.

## Reach Out!

Find us on [Twitter](https://twitter.com/...) for the latest news, and please consider giving us a ?? star on [GitHub](https://github.com/pitaya-components/master-component)!

## Support



For contributions in the form of bug fixes and changes, feel free to use [Pull Requests](https://github.com/pitaya-components/master-component/pulls) 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.