npm package: @pitaya-components/top-bar
Description: Pitaya-Framework Component Top-Bar.
Author: Pitaya Solutions
Latest version: 0.0.44

<h1 align="center">Topbar Component</h1>
<p align="center"><img height="250" src="https://demo.pitaya-framework.com/media/readme/logo-topbar.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>
Topbars are a container for items such as application title, navigation icon, and action items.

[Pitaya-framework](https://github.com/pitaya-foundation/pitaya-framework) template component.

_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
![Screenshot](https://demo.pitaya-framework.com/media/readme/screenshot-topbar.png "Screenshot")


## [Demo](https://demo.pitaya-framework.com/#/topbar?component=only)

## MDC Design & API Documentation <a name="mdc-design-and-api-documentation"></a>

- [Material Design guidelines: Buttons](https://material.io/go/design-buttons)
- [MDC Top-App-Bar](https://material.io/develop/web/components/top-app-bar/)

## Installation

```bash
npm install @pitaya-components/topbar --save
```

## Basic Usage

### Via plugin (main.js)

##### Simple registration
You can register this component as an aurelia plugin. In that case you don´t have to do anything else.

```ts
export function configure( aurelia: Aurelia )
{
	aurelia.use.standardConfiguration()
		   .plugin( "@pitaya-components/topbar" )
		   .feature( "resources" );

	aurelia.start().then( () => aurelia.setRoot( "app/app", document.body ) );
}
```

##### With plugin configuration
You can optionally specify which sub components you will need and thus want to define to globally available.

```ts
import { PitayaTopbarConfiguration } from "@pitaya-components/topbar";

export function configure( aurelia: Aurelia )
{
	aurelia.use.standardConfiguration()
		   .plugin( "@pitaya-components/topbar", ( pluginConfig: PitayaTopbarConfiguration ) =>
		   {
			   pluginConfig.use(
				   "pitaya-topbar-row.html",
				   "pitaya-topbar-navigation.html",
				   "pitaya-topbar-actions.html",
				   "pitaya-topbar-action-icon.html"
			   );
		   } )
		   .feature( "resources" );

	aurelia.start().then( () => aurelia.setRoot( "app/app", document.body ) );
}
```


### Import
If you don´t want this component to be handled as a plugin you have a few other options when importing a component into your layout:

##### Template
```html
<template>
	<require from="@pitaya-components/topbar/dist/native-modules/pitaya-topbar"></require>
	<require from="@pitaya-components/topbar/dist/native-modules/pitaya-topbar-row.html"></require>
	<require from="@pitaya-components/topbar/dist/native-modules/pitaya-topbar-navigation.html"></require>
	<require from="@pitaya-components/topbar/dist/native-modules/pitaya-topbar-actions.html"></require>
	<require from="@pitaya-components/topbar/dist/native-modules/pitaya-topbar-action-icon.html"></require>
    ...
</template>
```

##### View model
```ts
@viewResources( 
	"@pitaya-components/topbar/dist/native-modules/pitaya-topbar",
	"@pitaya-components/topbar/dist/native-modules/pitaya-topbar-row.html", 
	"@pitaya-components/topbar/dist/native-modules/pitaya-topbar-navigation.html", 
	"@pitaya-components/topbar/dist/native-modules/pitaya-topbar-actions.html", 
	"@pitaya-components/topbar/dist/native-modules/pitaya-topbar-action-icon.html"
)
export class MyView
{
	...
}
```

##### Global resources
```ts
export function configure( config: FrameworkConfiguration )
{
	config.globalResources( [
		PLATFORM.moduleName( "@pitaya-components/master-component/dist/native-modules/master-component" )
	] );
}
```

### 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-topbar
		view-model.ref="topbar"
		on-attached.call="doSomething(component)"
	></pitaya-topbar>
	...
</template>
```

##### View model
```ts
import {PiTopBar} from "@pitaya-components/topbar";

export class MyView
{
	public topbar: PiTopBar;

	public doSomething(component: PiTopBar)
	{
		this.topbar.type = "short";
	}
}
```

## Variants

### Default setup

```html
<pitaya-topbar>
	<pitaya-topbar-row>
		<pitaya-topbar-navigation
			icon="manu"
			on-icon-click.call="openDrawer()"
			title="My Topbar Title"
		></pitaya-topbar-navigation>
		<pitaya-topbar-actions>
			<pitaya-topbar-action-icon
				icon="event"
				on-click.call="openCalendar()"
			></pitaya-topbar-action-icon>
			<pitaya-topbar-action-icon
				icon="more_vert"
				on-click.call="openMenu()"
			></pitaya-topbar-action-icon>
		</pitaya-topbar-actions>
	</pitaya-topbar-row>
</pitaya-topbar>
```

## Event handlers
Attaching an event handler is as simple as adding `on-<event>.call="<function>(<parameters>)"`.

> NOTE: 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-topbar	
	on-navigation.call="topbarNavigated(event, component)"
	on-attached.call="topbarHasBeenAttached(component)"
>
	...
</pitaya-topbar>
```

##### View model
```ts
export class MyView
{
    public topbarNavigated(event: CustomEvent, component: PiTopBar)
    {
	    ...
    }

    public topbarHasBeenAttached(component: PiTopBar)
    {
	    ...
    }
}
```

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-topbar	
	on-attached.call="topbarHasBeenAttached('my custom message')"
>
	...
</pitaya-topbar>
```

##### View model
```ts
export class MyView
{
	public topbarHasBeenAttached(message: string)
	{
		...
	}
}
```

## 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-topbar	
	type="dense"
>
...
</pitaya-topbar>
```

##### View model
```ts
import {PiTopBar} from "@pitaya-components/topbar";

export class MyView
{
	public topbar: PiTopBar;
	
	public someMethod()
	{
		this.topbar.type    = "prominent";
	}
}
```

### Bindable properties
##### `<pitaya-topbar>`
| Attribute | Type | Description
| --- | --- | --- 
| `type` |  `dense \| prominent \| short` | Sets the type
| `on-attached` |  `( component: PiTopBar ) => void` | Is called when the component is attached to the DOM
| `on-navigation` |  `( component: PiTopBar \| event: CustomEvent ) => void` | Is called when the navigation icon has been clicked/tapped

##### `<pitaya-topbar-navigation>`
| Attribute | Type | Description
| --- | --- | --- 
| `icon` |  `string` | Sets the icon (material-icons)
| `onIconClick` |  `( event: CustomEvent ) => void` | Is called when the navigation icon has been clicked/tapped
| `title` |  `string` | Sets the title

##### `<pitaya-topbar-action-icon>`
| Attribute | Type | Description
| --- | --- | --- 
| `icon` |  `string` | Sets the icon (material-icons)
| `onClick` |  `( event: CustomEvent ) => void` | Is called when the action icon has been clicked/tapped

## Methods and properties

##### PiTopBar
| Signature | Description
| --- | --- |
| `container: Container` | The components container object
| `type: dense \| prominent \| short` | Sets the type
| `onAttached: ( component: PiTopBar ) => {}` | Sets a callback that is called when the component is attached to the DOM
| `onNavigation: ( component: PiTopBar \| event ) => void` | Sets a callback that is called when the navigation icon has been clicked/tapped
| `setScrollTarget( target: HTMLElement ) => void` |
| `listen( eventName: TopbarEvent, handler: ( event?: CustomEvent ) => void, options?: AddEventListenerOptions ) => void` |
| `unlisten( eventName: TopbarEvent, handler: ( event?: CustomEvent ) => void, options?: AddEventListenerOptions ) => void` |
| `reinitialize( component \| event ) => void \| Promise< void >` | Reinitializes the component

## Style Customization
### SASS mixins
With this component we are relying on the Top-App-Bar component of [MDC](https://material.io/develop/web/components/top-app-bar/).
Check out the [documentation](https://github.com/material-components/material-components-web/tree/master/packages/mdc-top-app-bar#sass-mixins) to learn how to use their SASS mixins.

> Note: SASS mixins are always applied on the main component `<pitaya-topbar>` by using the `.pitaya-topbar` selector.

## 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.