# Documentation

## Events

CropGuide fires a selection of events on the `$cropguide` element to make it possible to integrate CropGuide more closely with your webpage.

When applicable the event `target` property on the data object will reference the field that fired the event.

```js
$cropguide.push([
    'on',
    'open',
    function (data) {
        console.log('CropGuide was opened by field', data.target);
    },
]);
```

We can remove an event using the `'off'` command.

```js
// remove all events of type "off"
$cropguide.push(['off', 'open']);
```

Pass the event handler as third argument to only remove the event with that event handler

```js
function onOpen() {
    // handle event here
}

// add event handler for 'open'
$cropguide.push(['on', 'open', onOpen]);

// remove event handler for 'open'
$cropguide.push(['off', 'open', onOpen]);
```

The following events are fired by CropGuide.

* [init](#init)
* [load](#load)
* [open](#open)
* [ready](#ready)
* [close](#close)
* [intercept](#intercept)
* [process](#process)
* [invalid](#invalid)
* [ignore](#ignore)

### Demo

Use the file input field below and see the CropGuide events and their contents logged to your browser developer console and the textarea.

### Events

#### Init

`'init'` is fired when CropGuide initialises, if this event doesn’t fire then either CropGuide is not supported on the browser or the script failed to load.

#### Load

`'load'` is fired when CropGuide is ready. The event handler will also fire if CropGuide has already loaded.

#### Open

`'open'` fires when the editor modal opens.

#### Ready

`'ready'` fires when the editor interface can be interacted with.

#### Close

`'close'` fires when the editor modal closes.

#### Intercept

`'intercept'` fires when CropGuide intercepts a file selection. The `data` param of the event handler receives and object that contains the original event.

```js
$cropguide.push([
    'on',
    'intercept',
    (data) => {
        console.log('The original file input event', data.event);
    },
]);
```

#### Process

`'process'` fires when CropGuide has generated a new image.

The `data` param is set to `{ src, dest }` an object containing both the original file and the resulting image.

```html
<img id="res" />
```

Let’s assign the resulting image to the `<img/>` element.

```js
$cropguide.push([
    'on',
    'process',
    (data) => {
        // Preview the resulting image
        window.res.src = URL.createObjectURL(data.dest);
    },
]);
```

#### Invalid

`'invalid'` fires when CropGuide determines the selected image is too small to process. The `data` param of the event handler receives the `src` containing the original image file.

#### Error

`'error'` fires when an error has occurred. The `data` param of the event handler receives the `src` and `error`.

#### Ignore

`'ignore'` fires when the editor ignores a file, for example when it’s not an image. The `data` param receives the `src` being the file object that is ignored.