Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mobify/bellows
A responsive, mobile-first accordion UI module for progressive disclosure on the web.
https://github.com/mobify/bellows
Last synced: 19 days ago
JSON representation
A responsive, mobile-first accordion UI module for progressive disclosure on the web.
- Host: GitHub
- URL: https://github.com/mobify/bellows
- Owner: mobify
- License: mit
- Archived: true
- Created: 2013-07-20T21:07:10.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2016-10-23T22:10:00.000Z (about 8 years ago)
- Last Synced: 2024-10-12T15:31:26.384Z (about 1 month ago)
- Language: JavaScript
- Homepage:
- Size: 1.1 MB
- Stars: 140
- Watchers: 86
- Forks: 25
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Mobify Bellows
A mobile-first accordion UI module for progressive disclosure on the web.
[](https://nodei.co/npm/bellows-ui/)
[](https://www.versioneye.com/user/projects/53ff9b7deab62a5003000009)
[](https://circleci.com/gh/mobify/bellows)
## Demo
You can find a simple demo on [the Documentation page](http://mobify.github.io/bellows). More demos can be found inside the `examples` folder in the repo. Run `grunt examples` to see them in Chrome (mobile device emulation is recommended).
## Requirements
* [jQuery](http://jquery.com/)
* [Velocity.js](http://julian.com/research/velocity/)
* [Mobify's Plugin Factory](https://www.npmjs.com/package/mobify-plugin/)
### Zepto Support
Bellows supports Zepto up until v5.1.2 but is not actively developed for it. While we don't actively support Zepto for Bellows, we welcome any and all issues and PRs to help us make it work.
## Installation
Bellows can be installed using NPM:
```
npm install bellows-ui
```
## Usage with Require.js
To use with require.js, after installing through NPM you merely have to reference bellows in your require config file (**Note**: If your project already has these external dependencies, and the versions are compatible, it's recommended that you use the one in your project to reduce duplication):
```config.js
{
'paths': {
'$': 'node_modules/bellows-ui/node_modules/jquery/dist/jquery.min',
'plugin': 'node_modules/bellows-ui/node_modules/mobify-plugin/dist/plugin.min',
'velocity': 'node_modules/bellows-ui/node_modules/velocity-animate/velocity'
'bellows': 'node_modules/bellows-ui/dist/bellows.min',
}
}
```
And then require bellows in as needed:
```
define(
['$', 'bellows'],
function($) {
$('.bellows').bellows();
}
);
```
## Usage
At a bare minimum, your markup structure should follow the above structure. You should have at least one `bellows__item`. Content within `bellows__header` and `bellows__content` can be whatever you want. You may also style either of those however you need. Our default theme will give you some standard styling for those sections but, if you want to theme Bellows yourself, we recommend not including the theme file and starting from scratch.
```html
Header
Content
Header
Content
$('.bellows').bellows()
```
## Initializing the plugin
### bellows()
Initializes the bellows.
```js
$('.bellows').bellows();
```
### bellows(options)
Initialize with options.
```js
$('.bellows').bellows({
singleItemOpen: false,
duration: 200,
easing: 'swing',
open: function(e, ui) {},
opened: function(e, ui) {},
close: function(e, ui) {},
closed: function(e, ui) {}
});
```
#### Options
##### singleItemOpen
default: `false`
When set to `true` will force only one item open at a time.
```js
$('.bellows').bellows({
singleItemOpen: true
});
```
##### duration
default: `200`
Sets the duration for the animation.
```js
$('.bellows').bellows({
duration: 600
});
```
##### easing
default: `swing`
Sets the easing for the animation. Bellows takes all of the same easing properties that [Velocity.js](http://julian.com/research/velocity) accepts.
> * [jQuery UI's easings](http://easings.net/) and CSS3's easings ("ease", "ease-in", "ease-out", and "ease-in-out"), which are pre-packaged into Velocity. A bonus "spring" easing (sampled in the CSS Support pane) is also included.
* CSS3's bezier curves: Pass in a four-item array of bezier points. (Refer to [Cubic-Bezier.com](http://cubic-bezier.com/) for crafing custom bezier curves.)
* Spring physics: Pass a two-item array in the form of [ tension, friction ]. A higher tension (default: 600) increases total speed and bounciness. A lower friction (default: 20) increases ending vibration speed.
* Step easing: Pass a one-item array in the form of [ steps ]. The animation will jump toward its end values using the specified number of steps.
For more information, check out [Velocity's docs on easing](http://julian.com/research/velocity/#easing).
```js
$('.bellows').bellows({
easing: 'ease-in-out'
});
```
##### open
default: `function(e, ui) {}`
Triggered every time the selected bellows item is starting to open.
**Parameters**
| Parameter name | Description |
|----------------|-------------|
| **e** | An Event object passed to the callback |
| **ui** | An object containing any associated data for use inside the callback |
```js
$('.bellows').bellows({
open: function(e, ui) {
// ui.item contains the item opening
}
});
```
##### opened
default: `function(e, ui) {}`
Triggered every time the selected bellows item has finished opening.
**Parameters**
| Parameter name | Description |
|----------------|-------------|
| **e** | An Event object passed to the callback |
| **ui** | An object containing any associated data for use inside the callback |
```js
$('.bellows').bellows({
opened: function(e, ui) {
// ui.item contains the item that opened
}
});
```
##### close
default: `function(e, ui) {}`
Triggered every time an bellows item is starting to close.
| Parameter name | Description |
|----------------|-------------|
| **e** | An Event object passed to the callback |
| **ui** | An object containing any associated data for use inside the callback |
```js
$('.bellows').bellows({
close: function(e, ui) {
// ui.item contains the item closing
}
});
```
##### closed
default: `function(e, ui) {}`
Triggered every time an bellows item is finished closing.
| Parameter name | Description |
|----------------|-------------|
| **e** | An Event object passed to the callback |
| **ui** | An object containing any associated data for use inside the callback |
```js
$('.bellows').bellows({
closed: function(e, ui) {
// ui.item contains the item that closed
}
});
```
## Methods
### open
Open the selected bellows item by element reference
```js
$bellows.bellows('open', $('.bellows__item'));
```
or by index
```js
$bellows.bellows('open', 1);
```
### openAll
Opens all the bellows items
```js
$bellows.bellows('openAll');
```
### close
Close the selected bellows item by element reference
```js
$bellows.bellows('close', $('.bellows__item'));
```
or by index
```js
$bellows.bellows('close', 1);
```
### closeAll
Closes all the bellows items
```js
$bellows.bellows('closeAll');
```
### toggle
Toggle the selected bellows item by element reference
```js
$bellows.bellows('toggle', $('.bellows__item'));
```
or by index
```js
$bellows.bellows('toggle', 1);
```
### toggleAll
Toggles all the bellows items
```js
$bellows.bellows('closeAll');
```
### add
Adds new items to bellows, and correctly wraps their content elements. Optional third parameter allows you to replace all existing elements with the ones specified.
```js
$bellows.bellows('add', items);
```
or replacing existing elements
```js
$bellows.bellows('add', items, true);
```
## Known Issues and Workarounds
When the `singleItemOpen` configuration option is selected and the bellows items contain content that is larger than the overall viewport, closing an item can leave the user disoriented. This is due to the way `singleItemOpen` works; it closes all open items, then animates the selected one open. This can cause the positioning of the active item in the viewport to shift either up or down, resulting it it not being in the same position as when it was clicked.
To get around this, you can scroll to the item once the animation finishes. To do so, you just need to add the following to the `opened` event:
```
$('.bellows').bellows({
singleItemOpen: true,
opened: function(e, ui) {
Velocity.animate(ui.item, 'scroll');
}
});
```
This will scroll the viewport to the opened bellows item, restoring its position in the viewport.
## Browser Compatibility
| Browser | Version | Support |
|-------------------|---------|----------------------------|
| Mobile Safari | 4.0.x | Degraded. No transitions. |
| Mobile Safari | 5.0+ | Supported. |
| Android Browser | 4.0+ | Supported. |
| Android Browser | 2.3.x | Degraded. No transitions. |
| Chrome (Android) | 1.0+ | Supported. |
## Building a distribution
### Requirements
* [Node.js v4.x LTS + NPM v2.x](https://nodejs.org/en/download/) (Mobify recommends [NVM](https://github.com/creationix/nvm) for installing Node + NPM)
* [Grunt](http://gruntjs.com/)
* Install with `npm install -g grunt-cli`
### Steps
1. `npm install`
1. `grunt build`
The `dist` directory will be populated with minified versions of the css and javascript files for distribution and use with whatever build system you might use. The `src` directory has our raw unminified Sass and Javascript files if you prefer to work with those.
## License
_MIT License. Bellows is Copyright © 2016 Mobify. It is free software and may be redistributed under the terms specified in the LICENSE file._