# Referência ui-bind: cada comando, opção e atributo

> Todos os comandos de ui-bind com o que cada um faz, as opções que controlam quando ele funciona, e os atributos que escolhem o elemento alvo.

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

`<ui-bind>` é o elemento que aplica **comandos** ao DOM quando o valor do seu caminho muda. esta página lista o que cada comando faz, as opções que decidem *quando* ele funciona e os atributos que escolhem *que elemento* ele muda.

O formato é `config="command:expression;command:expression"`. Numa expressão `value` é o valor do caminho e `element` (também `el`) é o elemento que é alterado. Um comando pode ter um seletor (`text .name:value` aplica-o aos elementos `.name` de dentro) e `attr` toma primeiro o nome do atributo (`attr title:value`).

## Comandos que alteram o elemento

| Comando | O que faz |
|---|---|
| `text:expr` | define o texto; um valor vazio mostra o texto de `empty` |
| `html:expr` | define o HTML interno (faça você o escape) |
| `value:expr` | define o valor de um controlo de formulário |
| `title:expr`, `href:expr`, `src:expr` | define esse atributo |
| `attr name:expr` | define qualquer atributo |
| `.class:expr` | acrescenta a classe quando a expressão é verdadeira e remove-a quando é falsa |
| `show:expr` / `hide:expr` | acrescenta ou remove a classe `hidden` |
| `visible:expr` / `invisible:expr` | acrescenta ou remove a classe `invisible` (o elemento mantém o seu espaço) |
| `checked:expr` | marca ou desmarca o `input` de dentro |
| `disabled:expr` / `enabled:expr` | desativa ou ativa os controlos de dentro (`input`, `select`, `textarea`, `button`) e os elementos `ui-component` de dentro |
| `required:expr` | define a opção `required` dos elementos `ui-component` de dentro (não toca num `input` simples) |
| `template` | renderiza o modelo Tangular do elemento (veja a receita dos modelos) |
| `exec:path` / `refresh:path` | chama a função desse caminho com o valor, o caminho e o elemento, por cada `SET` do caminho do binder |

`show` e `hide` correm primeiro, depois `visible` e `invisible`, e `text`, `html` e `template` por último, para que a visibilidade do elemento já seja conhecida quando o conteúdo é escrito. `text`, `html` e `template` só são escritos enquanto o elemento está visível, a menos que `forcerender:true` esteja na mesma configuração: então são escritos mesmo com o elemento oculto.

## Opções: quando os comandos correm

| Opção | O que faz |
|---|---|
| `changes` | salta a atualização quando o valor é igual ao último |
| `strict` | só corre quando mudou o próprio caminho do binder, não quando mudou um caminho filho (`user.name` não executa um binder de `user`) |
| `track:a,b` | só corre quando mudou um desses caminhos (um binder de `user` que segue `user.name` ignora `user.age`); corre de novo por cada `SET` de um caminho seguido, mesmo com o mesmo valor |
| `once` | corre uma vez e depois o binder é removido |
| `check:path` | chama a função desse caminho com `(value, path, element)`; os comandos só correm quando devolve true |
| `delay:ms` | espera esses milissegundos e renderiza uma vez, mesmo que o valor tenha mudado várias vezes entretanto (100 quando não é dado valor) |
| `empty:text` | o texto mostrado em vez de um valor vazio (`---` quando não é dado texto) |
| `format:pattern` | formata o valor de `text`, `html`, `value`, `attr`, `title`, `href` e `src` com `String.format` |
| `class:name` | acrescenta essa classe ao elemento `ui-bind` uma vez, depois da primeira renderização |
| `assign:path` | guarda a instância do binder nesse caminho |
| `helpers:path` | o objeto desse caminho fornece os ajudantes do modelo: com `helpers:hh` e `hh = { shout: fn }`, o modelo pode usar `{{ value | shout() }}` |

## Atributos: que elemento muda

Por omissão os comandos alteram o elemento `ui-bind`. Estes atributos escolhem outro:

- `element="#target"` qualquer elemento da página (um seletor jQuery)
- `child=".inner"` um elemento dentro do `ui-bind`
- `parent=".card"` o antepassado mais próximo que corresponda

O caminho pode começar com `!` (`path="!user.nick"`): o binder ignora então os momentos em que o valor é `null` ou `undefined`. O nome de um comando também pode começar com `!` ou `~`: o prefixo é aceite e ignorado, o comando funciona como sem ele.

## Atribuição de comandos

- **Use um atributo por comando: escreva `title:value` e `alt:value` como dois comandos.**

```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-bind path="user.age" config="visible:value > 17" id="visible"><span>adult</span></ui-bind>
	<ui-bind path="user.age" config="invisible:value > 17" id="invisible"><span>minor</span></ui-bind>
	<ui-bind path="user.name" config="text:value;class:marked" id="classonce"></ui-bind>
	<ui-bind path="user.name" config="text:(window.counter_changes = (window.counter_changes || 0) + 1) && value;changes" id="changes"></ui-bind>
	<ui-bind path="user" config="text:(window.counter_strict = (window.counter_strict || 0) + 1);strict" id="strict"></ui-bind>
	<ui-bind path="user" config="text:value.name;track:user.name" id="track"></ui-bind>
	<ui-bind path="user.name" config="text:value;once" id="once"></ui-bind>
	<ui-bind path="user.name" config="text:value;check:isready" id="check"></ui-bind>
	<ui-bind path="user.name" config="exec:onname" id="exec"></ui-bind>
	<ui-bind path="user.name" config="text:value;assign:binders.main" id="assign"></ui-bind>
	<ui-bind path="!user.nick" config="text:value" id="notnull"></ui-bind>
	<ui-bind path="user.name" config="text:value" element="#target" id="element"></ui-bind>
	<div id="target"></div>
	<ui-bind path="user.name" config="text:value" child=".inner" id="child"><b class="inner"></b></ui-bind>
	<ui-bind path="user.name" config="text .a:value;text .b:value.toUpperCase()" id="selector"><i class="a"></i><i class="b"></i></ui-bind>
	<ui-bind path="user.name" config="show:false;text:value;forcerender:true" id="force"></ui-bind>
	<ui-bind path="user.name" config="show:false;text:value" id="noforce"></ui-bind>
	<ui-bind path="user.admin" config="required:value;disabled:!value" id="flags"><input type="text" /></ui-bind>
	<ui-bind path="user.admin" config="checked:value" id="checked"><input type="checkbox" /></ui-bind>

	<ui-bind path="user.name" config="title+alt:value" id="clone"></ui-bind>
	<ui-bind path="user" config="text:(window.counter_track = (window.counter_track || 0) + 1);track:user.name" id="track2"></ui-bind>
	<ui-bind path="user.name" config="template;helpers:hh" id="helpers"><script type="text/html"><b>{{ value | shout() }}</b></script></ui-bind>
	<ui-bind path="user.none" config="text:value;empty" id="emptydef"></ui-bind>
	<ui-bind path="user.name" config="focus"><input type="text" id="f1" /></ui-bind>
	<ui-bind path="user.name" config="!text:value" id="bang"></ui-bind>
	<ui-bind path="user.name" config="~text:value" id="tilde"></ui-bind>
	<ui-bind path="user.name" config="text:el.attr('id') + '/' + element.attr('id')" id="elvar"></ui-bind>
	<div class="card"><ui-bind path="user.name" config="attr data-n:value" parent=".card" id="parentbind"></ui-bind></div>

	<script>
		window.hh = { shout: s => String(s).toUpperCase() };
		window.isready = function(value, path, element) {
			return value !== 'blocked';
		};
		window.exec_log = [];
		window.onname = function() {
			window.exec_log.push(Array.prototype.slice.call(arguments).map(a => typeof a === 'object' ? (a && a.nodeType ? 'element' : a && a.path ? 'path' : 'object') : String(a)).join('|'));
		};
		SET('user', { name: 'Ann', age: 30, admin: false });
	</script>

</body>
</html>
```