# casement

> An iFrame comms library for giving your app access to the outside world.

Latest version **4.0.0** (published 2023-10-13) · GPL-3.0-or-later license · 0 weekly downloads

## Install

```sh
npm install casement
pnpm add casement
yarn add casement
bun add casement
```

## Health

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

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2023-10-13 |
| First published | 2023-05-07 |
| Weekly downloads | 0 |
| License | GPL-3.0-or-later |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 97.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | blue linden |
| Maintainers | bluelinden |
| Keywords | iframe, postmate |

## Links

- npm: https://www.npmjs.com/package/casement
- Repository: https://github.com/bluelinden/casement
- Homepage: https://github.com/bluelinden/casement#readme
- Issues: https://github.com/bluelinden/casement/issues
- npm.io page: https://npm.io/package/casement

## Recent versions

- 4.0.0 (latest) — 2023-10-13
- 3.0.6 — 2023-10-12
- 3.0.5 — 2023-05-14
- 3.0.4 — 2023-05-14
- 3.0.3 — 2023-05-14
- 3.0.2 — 2023-05-14
- 3.0.1 — 2023-05-14
- 3.0.0 — 2023-05-14
- 2.2.1 — 2023-05-12
- 2.2.0 — 2023-05-12
- 2.1.2 — 2023-05-12
- 2.1.1 — 2023-05-12
- 2.1.0 — 2023-05-11
- 2.0.3 — 2023-05-11
- 2.0.2 — 2023-05-11
- … 8 more at https://npm.io/package/casement/versions

## README

# Casement: a logical, minimalistic iFrame communication library

## Purpose
I'll explain it this way: An app exists in an iFrame. The app needs to communicate with its container window. The app is sandboxed, so it can't access the container window's APIs. Casement provides a simple API for sending messages between the two, in either direction.

## Installation
Casement is available on NPM. You can install it with `npm install casement`.

## Who is it for?
Casement is very opinionated out of pure simplicity. There are no fancy functions, just Promise-based APIs and automatic event handler management. It's for people who want to get the job done with minimal fuss, and don't need a lot of bells and whistles.

## Usage
Casement is a singleton. You can import it into your app like this:

```javascript
// ES6
import casement from 'casement';
// CommonJS
const casement = require('casement');
```
If you need to only use one part of it, you can just import that part:
```javascript
// ES6
import { Inside } from 'casement';
// CommonJS
const { Inside } = require('casement');
```

The `Inside` and `Outside` classes are almost the same, except the `Outside` class has methods for creation and destruction of the iFrame. The `Inside` class is for the app inside the iFrame, and the `Outside` class is for the container window.

### Outside
The `Outside` class has three methods and a constructor. 

#### Constructor
The constructor takes an object as its argument.
  
  ```javascript
  const outside = new Outside({
    // the name of the casement instance
    name: 'myCasement',
    // the URL of the iFrame, used for iFrame creation, and also for checking the origin of incoming messages
    pageUrl: 'https://example.com',
    // The container for a new iFrame, optional if you're attaching a pre-existing iFrame
    container: document.body,
    // A pre-existing iFrame, if you'd like to attach one instead of using a Casement-created one
    iframe: document.getElementById('myIframe'),
    // What to do when communication is established
    onReady: () => {
      console.log('Casement is ready!');
    },
    // Message handler, technically optional, but you'll want to use it
    onMessage: (message) => {
      console.log(message);
    }
    // 
  })
  ```

#### Sending messages
You can send anything, and there is only one argument allowed for the `send` method. That argument is the content of the message.

```javascript
const outside = new Outside( ... );
outside.send('Hello, world!');
```

#### Requesting things
The `.send()` method is a one-way communication method. If you want to get a response, you'll need to use the `.request()` method. It also takes one argument, same as `.send()`, but it returns a Promise that resolves with the response.

```javascript
const outside = new Outside( ... );
outside.request('What is your name?').then((response) => {
  console.log(response);
});
```

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