# marionette.overlay-view

> A view that covers the app and emits click events.

Latest version **0.0.2** (published 2015-08-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install marionette.overlay-view
pnpm add marionette.overlay-view
yarn add marionette.overlay-view
bun add marionette.overlay-view
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.2 |
| Published | 2015-08-05 |
| First published | 2015-08-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Jmeas |
| Maintainers | jmeas |

## Links

- npm: https://www.npmjs.com/package/marionette.overlay-view
- Repository: https://github.com/jmeas/marionette.overlay-view
- Issues: https://github.com/jmeas/marionette.overlay-view/issues
- npm.io page: https://npm.io/package/marionette.overlay-view

## Dependencies (3)

- [backbone](https://npm.io/package/backbone.md) ^1.2.1
- [underscore](https://npm.io/package/underscore.md) ^1.8.3
- [backbone.marionette](https://npm.io/package/backbone.marionette.md) ^2.4.2

## Recent versions

- 0.0.2 (latest) — 2015-08-05

## README

# marionette.overlay-view

A view that covers your webpage, and is closed when clicked. Useful as backgrounds for
dropdowns, modals, etc.

[![Travis build status](http://img.shields.io/travis/jmeas/marionette.overlay-view.svg?style=flat)](https://travis-ci.org/jmeas/marionette.overlay-view)
[![Code Climate](https://codeclimate.com/github/jmeas/marionette.overlay-view/badges/gpa.svg)](https://codeclimate.com/github/jmeas/marionette.overlay-view)
[![Test Coverage](https://codeclimate.com/github/jmeas/marionette.overlay-view/badges/coverage.svg)](https://codeclimate.com/github/jmeas/marionette.overlay-view)
[![Dependency Status](https://david-dm.org/jmeas/marionette.overlay-view.svg)](https://david-dm.org/jmeas/marionette.overlay-view)
[![devDependency Status](https://david-dm.org/jmeas/marionette.overlay-view/dev-status.svg)](https://david-dm.org/jmeas/marionette.overlay-view#info=devDependencies)

### Installation

The easiest way is through `npm` or `bower`.

```js
npm install marionette.overlay-view
bower install marionette.overlay-view
```

Be sure to iclude both the JS and CSS files in your application.

### Motivation

A common interface element on client side applications is an element that blocks the
user from interacting with the rest of the application. This is typically used when
the user opens, say, a custom dropdown menu or a modal.

Rather than associating a new overlay with each dropdown, I like to use a single view
that any other view in my app can use.

### Basic Usage

```js
// Create a single overlayView for your entire app
var overlayView = new OverlayView();

// Display it
overlayView.display();

// When the user clicks on it, it will hide itself and emit the `hide` event.
// You can use that event to close the modal / dropdown / do whatever.
```

### Child Elements

The OverlayView intentionally has no template, and is intentionally not a LayoutView,
but this doesn't mean that you can't place child views within it.

Rather than using the Region API, which is great for when views need to be swapped,
I recommend that simply use the DOM API to append a child view's element directly
into the overlay view's element. Then, when the overlay is closed, you can destroy
the child view.

The reason I suggest doing this is because adding a region abstraction doesn't seem
to add any benefit in this particular situation over existing DOM APIs.

This may look something like:

```js
// Attach the dropdown element to the overlay view
overlayView.$el.append(dropdownView.$el);

// Destroy the dropdown when the overlayView is hidden
overlayView.once('hide', dropdownView.destroy.bind(dropdownView));

// Show the overlay view
overlayView.display();

// Click the overlay to destroy the dropdown.
```

### Methods

##### `isDisplaying()`

Returns a Boolean indicating whether or not the view is currently displaying. By
default, the view is not displaying.

##### `display()`

Display the view, if it isn't already displayed, by removing the
`.overlay-view-hidden` class.

Returns the view instance.

##### `hide()`

Hide the view, if it's being displayed, by adding the `.overlay-view-hidden`
class.

Returns the view instance.

### `triggerMethod` Events

In addition to the normal Backbone and Marionette events, this View has a handful of
custom events. These are fired with `triggerMethod`, so the corresponding method
will be executed on the view, if it exists.

##### `before:display`

Triggered just before the view is displayed.

##### `display`

Triggered just after the view is displayed.

##### `before:hide`

Triggered jst before the view is hidden.

##### `hide`

Triggered just after the view is hidden.

##### `click`

Triggered when the user clicks the view itself, but not a child of the view. It's
generally safer to use the `hide` event to track when the overlay closes, because it
may not always close due to a click (for instance, when the user completes the task
offered by the modal / dropdown).

##### `click:child`

Triggered when the user clicks a descendant element of the view.

---
_Source: https://npm.io/package/marionette.overlay-view · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._