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

Name	Description	Type	Required
bbdropzone	Turns any element into a dropzone. Requires a value.	string	yes
bbdropzoneHoverClass	Optional class to apply to a dropzone when a valid dropper hovers over it.	string	no
bbdropzoneId	Optional unique identifier for a specific dropzone.	string	no

Event Emitters

Name	Description	Output
bbenter	Emitted when a dragged item enters a valid target area. Requires bbdropzoneId.	Dropzone Identifier: string
bbleave	Emitted when a dragged item leaves a valid target area. Requires bbdropzoneId.	Dropzone Identifier: string
bbdrop	Emitted when a dragged item is dropped into a valid target area. Requires bbdropzoneId.	Dropzone Identifier: string
bbdata	Emitted when a dragged item with a payload is dropped into a valid target area	Payload: string

Dropper API Reference:

Inputs

Name	Description	Type	Required
bbdropper	Turns any element into a dropper. Requires a value. Must match value of bbdropzone on associated dropzones.	string	yes
bbholdingClass	Optional class to apply to a dropper when it is grabbed.	string	no
bbdropperId	Optional unique identifier for a specific dropper.	string	no
bbpayload	Optional value to pass to the dropzone. If set, valid dropzones will emit a bbdata event with the payload	string	no

Event Emitters

Name	Description	Output
bbstart	Emitted when dragging an item starts. Requires bbdropperId.	Dropper Identifier: string
bbend	Emitted when a draggable item is released, regardless of where it is released. Requires bbdropperId.	Dropper Identifier: string

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

Name	Description	Type	Required
bbsortable	Turns any element into a sortable widget. Requires a value. All immediate children will become sortable elements.	string	yes
bboptions	An object containing one or both of the following: holdingClass:string - Optional class to apply to a sortable item while dragging it. hoverClass:string - Optional class to apply to a sortable item while another sortable item is hovering over it.	object	no

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

Name	Description	Output
bbstart	Emitted when sorting an item starts	Index of selected item: number
bbend	Emitted when a sortable item is released, regardless of whether it is released in a new location	Index of selected item: number
bbenter	Emitted when a sortable item is dragged into a valid target area	Index of target area: number
bbleave	Emitted when a sortable item is dragged out of a valid target area	Index of target area: number
bbdrop	Emitted when a sortable item is dropped into a valid target area	Index of target area: number
orderChanged	Emitted when a sortable's order has been changed by a successful drop. Binding this event is required for successful sorting.	Object: { draggedItem:number, newPosition:number }

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

Name	Description	Type	Required
bbtab	Turns any element into a tab. Requires a value. All immediate children will become sortable elements.	string	yes
bbtabset	Specify the tabset each tab belongs to	string	yes
bbactiveclass	Optional class to apply to a tab when it is active	string	no

Event Emitters

Name	Description	Output
bbshowstart	Emitted the moment a tab is clicked.	Tab name (value of bbtab):string
bbshowend	Emitted when a tab's associated tabcontent is visible	Tab name (value of bbtab):string

Tabcontent API Reference:

Inputs

Name	Description	Type	Required
bbtabcontent	Turns any element into a tab. Requires a value, which must match bbtab for the associated tab.	string	yes
bbtabset	Specify the tabset each tab belongs to	string	yes
bbdisplaystyle	Specify the visible display style. Not compatible with bbhiddenclass. Defaults is 'block'	string	no
bbhiddenclass	Specify the class to apply on hiding. Not compatible with bbdisplaystyle. Default is undefined.	string	no

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.