fallen v1.0.0-beta.2

Fallen

Responsive mobile-friendly dropdowns.

Still in development.

About

The basic idea of this plugin is smart positioning of dropdown box and arrow. Quite a known problem with the box partially disappeared behind the border of the window is solved. It does not matter what type of css position has the element-switcher. Dropdown box is always at the body root.

• Mobile-friendly;
• Written as ES2015 class;
• CSS Transitions support;
• SCSS mixin and variables;
• Accessibility;
• No dependencies. Pure js solution;

Installation

Via npm:

Run in your console: npm install fallen@1.0.0-beta.2

Via bower:

bower install fallen

Manual installation:

Download the latest release and attach fallen's stylesheet and script to your page:

<link rel="stylesheet" href="dist/css/fallen.min.css">

<script src="dist/js/fallen.min.js"></script>

Usage

Basic

Create some html:

<button type="button" class="awesome-button" data-dropdown="example-box">
  Let`s Go!
</button>
<div id="example-box" class="fallen-dropdown" dropdown-box>
  Rough, misty lubbers calmly pull a gutless, rainy ale.
</div>

Instantiate a new Fallen object:

var el = document.querySelector('.awesome-button');
var dropdown = new Fallen(el);

Options

Options to customize fallen are passed as the second argument to the constructor. Example:

var dropdown = new Fallen(el, {
  // options go here
});

• align: Defines initial horizontal alignment type from the associated element. Values: 'left' | 'center' | 'right'. Default: 'left'
• direction: Defines vertical initial dropdown box position. Values: 'top' | 'bottom'. Default: 'bottom'
• hover: Enables/disables hover behavior. Values: true | false. Default: false
• hoverDelay: Defines delay in ms on mouse enter event at the associated element. Default: 0
• hoverTimeout: Defines timeout in ms on mouse out event from the dropdown box. Default: 0
• windowFrameOffset: Defines window frame offset in px to perform space between dropdown box and viewport. Default: 0

Methods

instance.open()

Opens dropdown box for current instance.

instance.close()

Closes dropdown box for current instance.

instance.toggle()

Toggles dropdown box state for current instance.

instance.reposition()

Initiates dropdown box reposition.

instance.isOpened()

Returns boolean value if dropdown box is opened.

instance.config(key, value)

Dynamically sets value for specified option key.

Example:

var dropdown = new Fallen(el);
dropdown.config('align', 'center');

Events

You can create event listeners:

var el = document.querySelector('.example');
var dropdown = new Fallen(el);

el.addEventListener('fallen:opened', function() {
  console.log('Fallen dropdown is opened!');
}, false);

Available events:

• fallen:open: Triggered at the opening starts
• fallen:close: Triggered at the closing starts
• fallen:opened: Triggered at the opening ends
• fallen:closed: Triggered at the closing ends

Accessibility

This markup helps to do your web app more accessible for screen readers. Fallen toggles aria values automatically.

<button data-dropdown="example-box" aria-controls="example-box" aria-expanded="false">
  Let`s Go!
</button>
<div id="example-box" dropdown-box aria-hidden="true">
  Rough, misty lubbers calmly pull a gutless, rainy ale.
</div>

Customize with Sass

Dropdown boxes can be easily customized using Sass variables. Default values:

$fallen-max-width: 400px;
$fallen-min-width: 240px;
$fallen-max-height: 200px;
$fallen-min-height: 50px;
$fallen-padding: 10px;
$fallen-background-color: white;
$fallen-border-width: 1px;
$fallen-border-style: solid;
$fallen-border-color: #eaeaea;
$fallen-border-radius: 3px;
$fallen-box-shadow: 0 4px 3px -3px rgba(0, 0, 0, .1);
$fallen-transition-property: opacity;
$fallen-transition-timing-function: cubic-bezier(.68, .6, .27, .81);
$fallen-open-transition-duration: .3s;
$fallen-close-transition-duration: .3s;
$fallen-arrow-width: 10px;

Semantic Markup With Sass

You can create your own dropdowns using Sass mixin.

.custom-dropdown-box-class {
  @include dropdown-box();
}

You can customize your dropdowns with the params in the dropdown-box() mixin:

.custom-dropdown-box-class {
  @include dropdown-box(
    // Sets if dropdown has border. Default: true
    $border: true,
    // Sets if dropdown has arrow. Default: true
    $arrow: true
  );
}

Contributing

Code Consistency

We use some helpful tools to create consistent looking code throughout the project.

EditorConfig

We use EditorConfig to maintain consistent coding styles between various editors and IDEs. You can find our settings in the .editorconfig file in the root of the project.

JSHint

We use JSHint on each build to find easy-to-catch errors and potential problems in our js. You can find our JSHint settings in the .jshintrc file in the root of the project.

Development

Fallen development tasks are managed by Gulp. To install all the necessary packages, just invoke:

npm install

To build the dist files, just invoke:

gulp

These are the other available gulp tasks:

• js: runs babel transpiler, jshint and creates minified and concatenated versions of the script;
• css: compiles scss to css, runs autoprefixer and creates minified and concatenated versions of the stylesheets;
• watch: watch for modifications on script and scss files;

The source files are located inside the src directory. Be sure to make changes to these files and not files in the dist directory.

License

MIT. Read full text here.