Skip to content

Latest commit

 

History

History
244 lines (173 loc) · 10.2 KB

README.md

File metadata and controls

244 lines (173 loc) · 10.2 KB
Raw

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.