# 04. __Events__

[![+Professional Support](https://www.totaljs.com/img/badge-support.svg)](https://www.totaljs.com/support/) [![+Chat with contributors](https://www.totaljs.com/img/badge-chat.svg)](https://messenger.totaljs.com)

Events are very important part of jComponent. With events you can capture a specific behaviour.

__Content__:

- [Internal events](#)
- [Custom events](#)

## Internal events

- [`ON('#component-id')`](#event-on-component-id-)
- [`ON('@component-name')`](#event-on-component-name-)
- [`ON('component')`](#event-on-component-)
- [`ON('component.compile')`](#event-on-component-compile-)
- [`ON('component.destroy')`](#event-on-component-destroy-)
- [`ON('cmd')`](#event-on-cmd-)
- [`ON('environment')`](#event-on-environment-)
- [`ON('error')`](#event-on-error-)
- [`ON('exec')`](#event-on-exec-)
- [`ON('import')`](#event-on-import-)
- [`ON('knockknock')`](#event-on-knockknock-)
- [`ON('plugin')`](#event-on-plugin-)
- [`ON('plugin.destroy')`](#event-on-plugin-destroy-)
- [`ON('scroll')`](#event-on-scroll-)
- [`ON('scrollidle')`](#event-on-scroll-)
- [`ON('setter')`](#event-on-setter-)
- [`ON('ready')`](#event-on-ready-)
- [`ON('response')`](#event-on-response-)
- [`ON('request')`](#event-on-request-)

---

### Event: `ON('#component-id')`

This event is emitted when a component with defined `data-jc-id="SOME_ID"` is processed.

```javascript
ON('#your-id-of-component', function(component) {
	// component {Component}
});
```

### Event: `ON('@component-name')`

This event is emitted when a component is processed.

```javascript
ON('@name-of-component', function(component) {
	// component {Component}
});
```

### Event: `ON('component')`

This event is emitted when a component is initialized.

```javascript
ON('component', function(component) {
	// component {Component}
});
```

### Event: `ON('component.compile')`

This event is emitted when a component is compiled.

```javascript
ON('component.compile', function(component) {
	// component {Object}
});
```

### Event: `ON('component.destroy')`

This event is emitted when a component is destroyed.

```javascript
ON('component.destroy', function(component) {
	// component {Component}
});
```

### Event: `ON('cmd')`

`+v18` This event is emitted when the `CMD` method is executed.

```javascript
ON('cmd', function(path, arg1, arg2, arg3) {
	// do something
});
```

### Event: `ON('environment')`

This event is emitted when a value is added/updated in `environment`.

```javascript
ON('environment', function(key, value) {
	// @key {String}
	// @value {Object}
});
```

### Event: `ON('error')`

This event is emitted when a XHR request (AJAX) captures an error. Event is emitted after `ON('response')` event. 

```javascript
ON('error', function(response) {

	// response.data {Object} A request data
	// response.error {Boolean} Is error?
	// response.headers {Object} In the form headerName.headerValue
	// response.method {String} A request method
	// response.process {Boolean} Can disable future processing (default: true)
	// response.response {String} A response body
	// response.status {Number} A response status code
	// response.text {String} A response status text
	// response.upload {Boolean} Determines which the request is multipart/form-data
	// response.url {String} A request URL

	// IMPORTANT:
	// This property can prevent a callback or response processing in all AJAX requests:
	response.process = false;
});
```

### Event: `ON('exec')`

`+v18` This event is emitted when the `EXEC` method is executed.

```javascript
ON('exec', function(path, arg1, arg2, arg3) {
	// do something
});
```

### Event: `ON('import')`

`+v14.0.0` This event is emitted if `IMPORT()` is performed.

```javascript
ON('import', function(url, target) {
	// @url {String}
	// @target {Element}
});
```

### Event: `ON('knockknock')`

This event is emitted every 60 seconds.

```javascript
ON('knockknock', function(counter) {
	// @counter {Number}
});
```

### Event: `ON('plugin')`

`+v15` This event is emitted when some plugin is initialized.

```javascript
ON('plugin', function(plugin) {
	// plugin {Plugin}
});
```

### Event: `ON('plugin.destroy')`

`+v15` This event is emitted when a plugin is destroyed.

```javascript
ON('plugin.destroy', function(plugin) {
	// plugin {Plugin}
});
```

### Event: `ON('scroll')`

`+v18` This event is emitted when a user scrolls in some `SCROLLBAR()` element.

```javascript
ON('scroll', function(area) {
	// @area {jQuery element}
});
```

### Event: `ON('scrollidle')`

`+v18` This event is emitted when a scrollbar is idle.

```javascript
ON('scrollidle', function(area) {
	// @area {jQuery element}
});
```

### Event: `ON('setter')`

`+v18` This event is emitted when the `SETTER` method is executed.

```javascript
ON('setter', function(selector, name, arg1, arg2) {
	// do something
});
```

### Event: `ON('ready')`

This event is emitted when the jComponent is ready.

```javascript
ON('ready', function() {
	// your code
});
```

### Event: `ON('response')`

This event is emitted when a XHR request (AJAX) gets a response.

```javascript
ON('response', function(response) {

	// response.data {Object} A request data
	// response.error {Boolean} Is error?
	// response.headers {Object} In the form headerName.headerValue
	// response.method {String} A request method
	// response.process {Boolean} Can disable future processing (default: true)
	// response.response {String} A response body
	// response.status {Number} A response status code
	// response.text {String} A response status text
	// response.upload {Boolean} Determines multipart/form-data
	// response.url {String} A request URL
	// +v18: response.scope {String} Current scope 

	// IMPORTANT:
	// This property can prevent a callback or response processing in all AJAX requests:
	response.cancel = true;
});
```

### Event: `ON('request')`

`+v14.3.1` This event is emitted before a XHR request (AJAX) is performed.

```javascript
ON('request', function(options) {

	// options.data {Object} A request data
	// options.headers {Object} In the form headerName.headerValue
	// options.method {String} A request method
	// options.url {String} A request URL

	// IMPORTANT:
	// This property can prevent performing of request:
	options.cancel = true;

	// +v18 The property below can enable XHR with credentials (cookies) to external resources
	// options.credentials {Boolean}

	// ========================================================================
	// +v18 supports two methods which respond without creating of real request
	// ========================================================================
	
	// IMPORTANT: response will be processed via preddefined callback of caller.

	// Returns error
	// options.throw(responsedata, [headers], [http_code]);
	// @responsedata {Object/String}
	// @headers {Object} custom response headers (default: {})
	// @http_code {Number} custom http code (default: 999)
	
	// Returns response:
	// options.respond(responsedata, [headers]);
	// @responsedata {Object/String}
	// @headers {Object} custom response headers (default: {})
});
```

## Custom events

You can define your own events within jComponent library. Implementation is very easy:

__Register event__:

```javascript
ON('my-custom-event', function(arg1, arg2) {
	console.log('My custom event is triggered with these arguments:', arg1, arg2);
});
```

__Emit custom event__:

```javascript
// This method emits your custom event within your app
EMIT('my-custom-event', 'Argument 1', 'Argument 2');
```

__Read more about global methods__:

- [`ON()`](@17092620450002mpt0#method-on-)
- [`OFF()`](@17092620450002mpt0#method-off-)
- [`EMIT()`](@17092620450002mpt0#method-emit-)