ngx-bearbones v0.0.9

Ngx-Bearbones

A project to create bare-bones Angular widgets ready to be used with any CSS framework. (Bootstrap, Material, SemanticUI, etc.)

Note: The ngx-bearbones package currently contains three completed widgets, a drag-and-drop, a sortable, and tabs. I'm working as fast as I can to add more!

Table of contents

1. Bearbones Manifesto
2. Installation instructions
3. Documentation
4. Contributing

Bearbones Manifesto

There are dozens of Angular widget libraries for multiple CSS frameworks, but there are very few entirely unthemed, functional widgets that allow you to easily implement your own custom styles or test different CSS frameworks without extensively rewriting your components for them.

Enter Bearbones, which gives you complete widgets that are not integrated with any CSS framework, but can work with any of them.

• Easily create your own classes for widget components, without having to override existing styles.
• Switch between CSS frameworks as easily as switching class names on a <div>.
• Test components without flashy styles getting in the way, while still being fully functional.
• Apply Bearbones directives to nearly any HTML element, instead of being locked into specific templates.

Installation instructions

Install ngx-bearbones from npm:

npm install ngx-bearbones --save

Import the Bearbones module:

import { BearbonesModule } from 'ngx-bearbones';

@NgModule({
  ...
  imports: [ BearbonesModule, ... ]
  ...
})

Documentation

Drag and drop

The BearBones drag-and-drop widgets consist of two directives, one for "dropzones" and one for "droppers."

Dropzones and droppers must always be assigned the same value for the bbdropzone and bbdropper inputs, or the dropper will not identify the dropzone as a valid drop target. For example, if your dropper's bbdropper attribute is set to dragdrop1, the bbdropzone attribute on a dropzone must also be "dragdrop1" for it to be a valid target.

Droppers can be assigned a payload (bbpayload), which consists of a string that will be emitted by whichever valid dropzone it is dropped on.

You may also set a Dropzone Identifier (bbdropzoneId) to uniquely identify individual dropzones. If you do this, you can take advantage of event emitters for dropzones (see below). If bbdropzoneId is not set, dropzones will not emit events, with the exception of the bbdata event.

Similarly, Dropper Identifiers (bbdropperId) can be used to enable event emitters for droppers.

Important Note: Droppers don't have to start inside a dropzone. They can appear anywhere in a page.

Dropzone API Reference:

Inputs

Event Emitters

Dropper API Reference:

Inputs

Event Emitters

Example:

Unstyled, with payload

<ul>
	<li bbdropzone="unstyled" (bbdata)="logPayload($event)">
    	<div bbdropper="unstyled" bbpayload="test data">Unstyled dropper</div>
    </li>
    <li bbdropzone="unstyled" (bbdata)="logPayload($event)"></li>
    <li bbdropzone="unstyled" (bbdata)="logPayload($event)"></li>
</ul>

Sortable

Similar, but not identical, to the drag-and-drop widgets, the sortable widget acts as a container for re-orderable items. Since you are placing elements where they exist already, the sortable does NOT do the work of re-ordering. Instead, it emits an event when a new ordering has been made, and it is up to the component logic to sort the associated array.

Sortable API Reference:

Inputs

Note: As the API standardizes, setting the individual options in a manner similar to the rest of NGX-Bearbones will become an option, as will using an options object for all other widgets. Please remember this is a work in progress.

Event Emitters

Example:

Custom styled

<!-- html template -->
<ul bbsortable="styled" (orderChanged)="orderChangedCustomStyled($event)" [bboptions]="sortOptionsFruit">
	<li *ngFor="let fruit of fruits" [class]="fruit.color">
		<span class="dropper">{{fruit.name}}</span>
	</li>
</ul>

// component.ts
...
fruits = [
	{name: 'Apple', color: 'red'},
	{name: 'Banana', color: 'yellow'},
	{name: 'Orange', color: 'orange'},
	{name: 'Kiwi', color: 'green'}
];

sortOptionsFruit = {
	restingClass: 'dropzone',
	hoverClass: 'dropzone-hover',
	holdingClass: 'dropper-holding'
};

// Example function to reorder the array bound to the sortable
orderChangedCustomStyled(event: any) {
	const { draggedItem, newPosition } = event;
    this.fruits.splice(newPosition, 0, this.fruits.splice(draggedItem, 1)[0]);
}

Tabs

BearBones tabs allow you to display tabular data. It consists of two directives, bbtab and bbtabcontent, which can be placed anywhere on the page independently of one another - i.e., without needing a container for any particular part of the tab. In addition, it is also capable of accepting custom classes for active tabs, using the input bbactiveclass.

If you place all of your tabs in the same container, you can set bbactiveclass on the container, rather than the tabs themselves. If you do, the active class will be applied to whichever tab is active automatically.

You can also set bbactiveclass on the first child of the tab.

Custom classes take precedence as follows (in ascending order):

• Parent
• Tab
• Child

For example, if you have a custom active class set for a child, and one set at the parent, the child class will be applied.

You must also specify which tabset each tab and tabcontent element belongs to, using the input bbtabset. This allows you to use multiple tabsets on a single page.

For each tabset, use bbactive=true to indicate the default open tab.

Tab API Reference:

Inputs

Event Emitters

Tabcontent API Reference:

Inputs

Event Emitters

None at this time. Use the tab's event emitters to handle showing and hiding tab content.

Example:

<nav>
    <a bbtab="tab1" bbactive="true" bbtabset="tabset1">Tab 1</a>
    <a bbtab="tab2" bbtabset="tabset1">Tab 2</a>
</nav>
<br/>
<div bbtabcontent="tab1" bbtabset="tabset1">
    Tab 1 contents
</div>

<div bbtabcontent="tab2" bbtabset="tabset1">
    Tab 2 contents
</div>

Contributing

Feel free to create pull requests and submit issues.