# Widgets no CMS do Total.js: use-os numa página e escreva os seus
> Como aparece um widget no HTML de uma página (o atributo data-cms e o seu JSON), as partes de um ficheiro de widget, o marcador CLASS, renderizar um widget no servidor com exports.render e instalar widgets pela API.
Framework: cms
Product: CMS (cms@8071e48)
Language: pt
Content-SHA256: 3a90ba22c88e3ea672201d2db5ba9ad590d03ce47c7ab5b8729b9bffc90d7c7c
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources:
Review: not-recorded
Um **widget** é um bloco que coloca numa página: um título, um aviso, uma galeria. Leva o seu próprio estilo, um formulário para o configurar no editor e, opcionalmente, código que o renderiza no servidor. Um widget é um ficheiro HTML, como um componente do [Flow](/en/flow/write-a-component/), e o CMS guarda-o nos seus metadados.
## Um widget dentro de uma página
No HTML de uma página, um widget é um `div` com dois atributos:
```html
```
- `data-cms` é `__`, em que a configuração é um objeto JSON escrito com `encodeURIComponent`. O editor escreve-o; pode escrevê-lo você quando gera páginas.
- `data-cms-id` é o identificador da instância na página.
Quando a página é servida, o CMS remove o atributo `data-cms`, mantém o HTML que está dentro e acrescenta ao head o estilo de cada widget da página. Se o widget não estiver instalado, o seu bloco é descartado.
## As partes de um ficheiro de widget
| Parte | Para que serve |
|---|---|
| `
Hello world
```
`opt.config` é a configuração da instância, `opt.html` o HTML que estava dentro do bloco, e `opt.id`, `opt.uid` e `opt.body` descrevem-no. `next(html, replace)` entrega o HTML a servir; com `true` como segundo argumento substitui o bloco todo. Guardámos este ficheiro num CMS local e uma página com `data-cms="hello__..."` e `{"text":"mundo"}` saiu como `Hello MUNDO
`, com `.w-hello{color:#07c}` no head. O widget oficial `picture` usa a mesma função para acrescentar `loading="lazy"` à sua imagem, e `code` para imprimir o código das suas definições.
`exports.install` e `exports.uninstall` correm com a base de dados do CMS quando o widget é adicionado, alterado ou removido.
## Instalar e remover widgets
O plugin *Widgets* do admin importa um ficheiro; pela API é `widgets_save` com `{ "html": "", "singleton": true }` (`singleton` ignora o widget se já existir), `widgets_list`, `widgets_read`, `widgets_detail` e `widgets_remove`. Precisam da permissão `widgets` (veja [a API do admin](/en/cms/the-admin-api/)). Os 43 widgets oficiais estão em [o repositório de widgets](/en/cms/the-widgets-repository/).