# Component instance reference: properties and methods of self

> The declaration of a jComponent 20 component and what its instance (self) offers: properties, value methods, DOM helpers, events, watchers and commands.

Framework: jcomponent20
Product: jComponent 20 (jcomponent@20)
Language: en
Content-SHA256: 33a85f3da8d2937168f5392eef1f0018b207e7f63c15b0a4e71d55753f94e6b8
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: jcomponent20@3fedd009a277f50fddc608b97afbec553b67c51b
Review: not-recorded

A component is declared with `COMPONENT(name, defaultConfig, function(self, config, cls) { ... })`. The declaration runs once for every `<ui-component name="...">` of the page and receives the instance (`self`), its configuration (`config`, the same object as `self.config`) and the class prefix (`cls`). This page lists what `self` has.

## Hooks you define

| Member | When it runs |
|---|---|
| `self.make` | once, when the element is ready: build the DOM here |
| `self.setter(value, path, flags)` | every time the value of the path changes, and when the component starts; `flags` is an object |
| `self.destroy` | after the element was removed (see the lifecycle recipe) |

## Properties

| Property | Value |
|---|---|
| `self.name` | the name of the component (`probe`) |
| `self.path.path` | the path as a string (`form.name`) |
| `self.element` | the `<ui-component>` element as a jQuery collection |
| `self.dom` | the same element as a DOM node |
| `self.config` | the configuration: the defaults of the declaration, then the `config` attribute of the element. It also holds the state flags: `invalid` from the start, `modified` and `touched` once the value is modified |
| `self.id` | a unique id of the instance |
| `self.ready` | `true` after `make` |

## The value

| Method | What it does |
|---|---|
| `self.get()` | reads the value of the path |
| `self.set(value)` | writes the value and runs the `setter` of every component of that path, this one too |
| `self.update()` | runs the `setter` again with the current value, without changing it |
| `self.rewrite(value)` | writes the value **without** running the `setter` of this component (the others are notified) |
| `self.modify(value)` | writes the value and marks the component as modified and touched: `config.modified` and `config.touched` become 1 |
| `self.reset()` | clears those flags: `config.modified` and `config.touched` go back to 0 |
| `self.GET(path)`, `self.SET(path, value)` | read and write any path of the state |
| `self.EXEC(name, a)` | calls the global function `name` |

## The DOM of the component

`self.html(html)`, `self.text(text)`, `self.append(html)` and `self.empty()` change the content. `self.find(selector)` returns the elements inside as jQuery. `self.css(name, value)` sets a style, `self.attr(name, value)` an attribute and `self.attrd(name, value)` a `data-` attribute (`self.attrd('x')` reads `data-x`). The classes: `self.aclass(name)` adds, `self.rclass(name)` removes, `self.hclass(name)` tells whether it has it, and `self.tclass(name, [state])` toggles it or sets it to `state`. `self.width()` and `self.height()` return numbers.

## Events, watchers and commands

| Method | What it does |
|---|---|
| `self.on(name, fn)` / `self.emit(name, a)` | listens to and sends a named event of the page |
| `self.watch(path, fn, [autoinit])` | calls `fn(value, flags, path)` when that path changes; with `autoinit` also once at the start. `+` joins several paths |
| `self.reconfigure('size:9')` | changes the configuration at runtime: `self.config.size` is 9 |
| `self.command(name, fn)` / `self.CMD(name, a)` | registers a command of this instance and calls it |

## Do not rely on these

- **`self.unwatch(path, [fn])` does not remove the watcher** in jComponent 20: it compares the parsed path of the watcher with a string, so nothing matches. The watcher keeps running after `unwatch`. If you need to stop a watcher, check a flag inside `fn`.
- **The global `CMD(name)` did not call a command registered with `self.command`**: only `self.CMD(name)` did.

```html public/index.html
<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8" />
	<title>jComponent</title>
	<link rel="stylesheet" href="//cdn.componentator.com/spa.min@20.css" />
	<script src="//cdn.componentator.com/spa.min@20.js"></script>
</head>
<body>
	<ui-component name="probe" path="form.name" config="size:3;title:Hello" id="probe"></ui-component>
	<script>
		window.log = {};
		window.events = [];
		COMPONENT('probe', 'size:1;flag:false', function(self, config, cls) {
			window.inst = self;
			self.make = function() {
				self.html('<p class="a">one</p><p class="b">two</p>');
				self.event('click', '.a', function() { window.events.push('click'); });
			};
			self.setter = function(value, path, type) {
				window.events.push('setter:' + value + ':' + path + ':' + type);
			};
		});
		SET('form.name', 'Ann');
	</script>
</body>
</html>
```