Component instance reference: properties and methods of self

jComponent 20 · jcomponent@20 jcomponentfrontendcomponentsreference Executed with jComponent 20

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.

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>

Try it in your browser

Edit the example and run it. It runs in an isolated frame in your browser; nothing is sent to our server.

Code

Preview