Documentação do widget.json¶

O widget.json é o arquivo que define o widget. Ele serve como uma forma de especificar como seu widget funcionará, incluindo o local de onde dados externos serão retornados, os parâmetros que os usuários poderão configurar e a frequência de atualização.

A lista abaixo apresenta a estrutura do arquivo, onde cada item será detalhado em sua própria seção mais abaixo.

name
title
description
version
author
update
- interval
- uri
- module
- headers
params
- name
- condition
- field
  - type
  - label
  - required
  - checked
  - defaultValue
  - title
  - helperText
  - placeholder
  - tooltip
  - options
  - multiple
  - maxlength
  - min
  - max
  - step

`name`¶

Tipo: string

Obrigatório: sim

Identificador único do widget na plataforma. Seu valor pode ser qualquer coisa.

Exemplo

"name" : "my-clock-widget"

`title`¶

Tipo: string

Obrigatório: sim

Título do widget. É o nome pelo qual o widget será reconhecido na plataforma. Não precisa ser único, mas é interessante que o usuário consiga distinguí-lo de outros widgets.

Exemplo

"title" : "Meu Widget"

`description`¶

Tipo: string

Obrigatório: sim

Breve descrição do widget. Deve ser direto e claro para que os usuários saibam exatamente o que o widget faz.

Exemplo

"description" : "Exibe o horário e data atual em um formato elegante."

`version`¶

Tipo: string

Obrigatório: sim

Versão do widget. Pode ser informada em qualquer formato.

Exemplo

"version" : "1.0.0"

`author`¶

Tipo: string

Obrigatório: sim

Nome do autor do widget. Adicionalmente um link pode ser inserido utilizando a notação nome <URI>.

Exemplo

"author" : "DSME"

ou

"author" : "DSME <https://dsme.tv>"

`update`¶

Tipo: object

Obrigatório: não

Este bloco especifica a forma e a frequência com a qual o widget terá seu conteúdo atualizado.

Se não for informado, o widget será compilado uma vez e nunca será atualizado. Abaixo você pode ver um exemplo de um widget "estático", isto é, seu conteúdo nunca é atualizado a partir de uma fonte externa:

Exemplo

{
    "title" : "Relógio",
    "name" : "my-clock-widget",
    "description" : "Exibe a data e a hora em um formato elegante.",
    "author" : "DSME <https://dsme.tv>",
    "version" : "1.0.0"
}

Agora se o parâmetro update for informado, o widget será periodicamnete atualizado de acordo com os parâmetros informados. Veja o exemplo abaixo:

Exemplo

{
    "title" : "Previsão meteorológica",
    "name" : "my-weather-widget",
    "description" : "Previsão meteorológica para os próximos 3 dias.",
    "author" : "DSME <https://dsme.tv>",
    "version" : "1.0.0",
    "update" : {
        "interval" : 6,
        "uri" : "http://weather.example.com/forecast.json"
    }
}

Neste exemplo, o conteúdo do widget será atualizado a cada 6 horas.

Caso update seja informado, será obrigatório informar também os parâmetros interval e uri ou module, de forma que você deve informar interval e uri ou interval e module. Não informe uri e module ao mesmo tempo. Para mais detalhes veja a descrição de cada um mais abaixo.

Independente do uso de uri ou module, os dados atualizados do widget poderão ser recuperados da seguinte forma:

Exemplos de como recuperar os dados do widget

```javascript tab="RAW" var widget = document.querySelector('.widget'); var str = widget.dataset.widgetData; // string com os dados brutos

```javascript tab="JSON"
var widget = document.querySelector('.widget');
var obj = JSON.parse(widget.dataset.widgetData); // objeto JSON

javascript tab="XML" var widget = document.querySelector('.widget'); var parser = new DOMParser; var xml = parser.parseFromString(widget.dataset.widgetData, 'text/xml'); // árvore DOM

Codificação dos dados

A plataforma DSME trabalha com codificação UTF-8 por padrão. Por isso, o conteúdo do widget sempre será retornado em UTF-8, independente de como a sua fonte de dados o retorna. Certifique-se salvar seus arquivos na mesma codificação, e espere receber os dados nela também. Assim você evita erros como símbolos e acentos exibidos de forma errada.

Para outros formatos de dados, você deve implementar o processamento adequado.

Abaixo estão listados todos os parâmetros disponíveis para configurar a atualização do conteúdo do widget.

`update.interval`¶

Tipo: integer

Obrigatório: sim

Define o intervalo de atualização do conteúdo do widget. O valor é expresso em horas e o mínimo é 1 (uma hora). Não é possível definir horas em decimal, como 1.5. Apenas valores inteiros são aceitos.

Esta propriedade basicamente diz que a cada X horas a plataforma DSME deve atualizar o conteúdo do widget, fazendo com que ele seja recompilado e baixado novamente pelos players.

Nota

Toda a atualização de conteúdo é feita pelo DSME Manager, e não pelos players. Os players apenas baixam o arquivo final já atualizado para exibí-lo. Portanto não espere que o conteúdo seja atualizado enquanto o widget é exibido na tela.

Também vale notar que pode haver um delay entre o momento em que o conteúdo é atualizado e o momento em que o player faz o download do widget novamente.

Exemplo

"interval" : 2

Neste caso o conteúdo do widget será atualizado a cada 2 horas. E a cada 2 horas os players farão o download do widget novamente.

`update.uri`¶

Tipo: string

Obrigatório: sim (se module não for informado)

URI válido da fonte de dados do widget.

Em conjunto com o parâmetro interval, este parâmetro diz para a plataforma DSME que o conteúdo do widget deve ser baixado deste endereço na frequência de horas especificada. O formato do conteúdo pode ser qualquer um (JSON, XML, HTML, CSV etc). Sendo assim o processamento e a apresentação destes dados na tela do player é de inteira responsabilidade do widget.

Exemplo

"uri" : "https://api.example.com/some-service.json"

Após requisitar a URI, o conteúdo será inserido no widget e estará disponível no atributo data-widget-data do elemento raiz.

`update.module`¶

Tipo: string

Obrigatório: sim (se uri não for informado)

Este parâmetro especifica uma fonte de dados especial, disponibilizada pela própria plataforma DSME.

Com esta configuração você não precisa se preocupar em onde consultar os dados de que precisa, e pode se concentrar apenas em apresentá-los.

No entanto, a disponibilidade destes módulos é limitada. Os módulos atualmente disponíveis estão listados na tabela abaixo (a estrutura dos dados retornados está documentada na página específica de cada módulo).

Módulo	Descrição
weather	Retorna informações sobre a previsão meteorológica de uma localidade para o dia atual e os próximos 3 dias.

Exemplo

"module" : "weather"

O conteúdo do módulo será inserido no widget e estará disponível no atributo data-widget-data do elemento raiz, sempre no formato JSON.

`update.headers`¶

Tipo: object

Obrigatório: não

Coleção de cabeçalhos HTTP que devem ser enviados quando o parâmetro uri for utilizado.

Se o endpoint especificado em uri necessitar de algum cabeçalho especial, como um Authorization, você pode configurá-lo utilizando este parâmetro. Qualquer cabeçalho pode ser informado.

Exemplo

"headers" : {
    "Authorization" : "bearer YWhhISBwZWdhZGluaGEgZG8gbWFsYW5kcm8h",
    "X-Foo" : "bar"
}

`params`¶

Tipo: array

Obrigatório: não

Este bloco define todos os campos que podem ser configuradas pelo usuário, chamados de parâmetros de usuário.

Cada item da lista define um parâmetro de usuário, que poderá ser renderizado como um campo de formulário para que o usuário especifique um valor, e que resultará em uma variável que poderá ser utilizada em alguns locais dentro do widget.

Vamos deixar mais claro. Veja o bloco de código abaixo:

Exemplo

"params" : [
    {
        "name" : "local",
        "field" : {
            "type" : "text",
            "label" : "Cidade",
            "required" : true,
            "placeholder" : "Nome da cidade",
            "helperText" : "Você deve informar o nome de uma cidade, como Brasília ou Rio de Janeiro"
        }
    }
]

Bem simples, não? No exemplo acima nós definimos um único parâmetro chamado local, que resultará em um campo de formulário do tipo text com um label chamado Cidade. E o campo será obrigatório.

Você pode especificar quantos parâmetros de usuário quiser, e a plataforma DSME fará o trabalho pesado de renderizar estas opções para o usuário, coletar os dados selecionados e retornar para o seu widget, junto com o conteúdo da fonte de dados ou do módulo configurado. Desta forma você terá tudo o que for necessário para exibir a informação correta na tela do player.

Para um exemplo mais completo consulte a página sobre como criar um widget.

`param.name`¶

Tipo: string

Obrigatório: sim

Define o nome do parâmetro de usuário.

Cada parâmetro está automaticamente associado a uma variável que poderá ser inserida em alguns locais, sendo eles:

O parâmetro update.uri, para montar o endereço final do endpoint;
Os cabeçalhos do parâmetro update.headers, para personalizar os cabeçalhos e adicionar a possibilidade de uma autenticação (se necessário);
As condições de parâmetros;
O HTML do widget.

A variável tem o formato {var}, portanto se o seu parâmetro se chama myparam, você poderá utilizá-lo como {myparam} nos locais indicados acima. Veja o exemplo a seguir:

Exemplo

```json hl_lines="3 5" tab="widget.json" "update" : { "interval" : 6, "uri" : "https://api.example.com/rest/{query}.json", "headers" : { "Authorization" : "bearer {auth-token}" } }, "params" : [ { "name" : "sponsor", "field" : { "type" : "text", "label" : "Patrocinador", "required" : true, "placeholder" : "Informe o nome do patrocinador" } }, { "name" : "query", "field" : { "type" : "text", "label" : "Termo de consulta", "required" : true, "placeholder" : "Informe um termo de consulta" } }, { "name" : "auth-token", "field" : { "type" : "text", "label" : "Token de autorização", "required" : true, "placeholder" : "Informe o seu token de autorização", "helperText" : "Você pode conseguir um token aqui" } } ]

```html hl_lines="14" tab="index.html"
<!DOCTYPE html>
<html lang="pt-BR">
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="generator" content="DSME">
        <title>Meu Widget</title>
        <link href="css/widget.css" type="text/css" rel="stylesheet">
    </head>
    <body>
        <section class="widget">
            <!-- conteúdo do widget -->
            <div class="sponsor">Um oferecimento<br>{sponsor}</div>
        </section>
        <script src="js/widget.js"></script>
    </body>
</html>

`param.condition`¶

Tipo: string

Obrigatório: não

Define uma condição para a apresentação do parâmetro para o usuário.

Se uma condição for informada, o parâmetro associado a ela só será exibido caso a condição seja satisfeita.

A condição deve ser especificada utilizando uma pseudo-linguagem criada especificamente para este proprósito. A notação é value1 operator value2 [and|or...], onde operator é uma das palavras-chave definidas na tabela mais abaixo.

Exemplo

"params" : [
    {
        "name" : "foo",
        "field" : {
            "type" : "checkbox",
            "label" : "Foo"
        }
    },
    {
        "name" : "bar",
        "condition" : "{foo} eq false",
        "field" : {
            "type" : "text",
            "label" : "Bar",
            "required" : true
        }
    }
]

Neste exemplo o campo bar (text) só será exibido se o campo foo (checkbox) estiver desmarcado. Note que mesmo que bar tenha sido configurado como obrigatório, ele só será realmente obrigatório se foo não estiver marcado.

A pseudo-linguagem utilizada nas condições é definida pelas palavras-chave abaixo:

Palavra-chave	Descrição
`eq`	Indica igualdade entre os valores. Equivalente JS: `==` Ex.: `"{foo} eq 'a'"`
`lt`	Indica que o valor da esquerda é menor que o da direita. Equivalente JS: `<` Ex.: `"{foo} lt 10"`
`lte`	Indica que o valor da esquerda é menor ou igual que o da direita. Equivalente JS: `<=` Ex.: `"{foo} lte 10"`
`gt`	Indica que o valor da esquerda é maior que o da direita. Equivalente JS: `>` Ex.: `"{foo} gt 10"`
`gte`	Indica que o valor da esquerda é maior ou igual que o da direita. Equivalente JS: `>=` Ex.: `"{foo} gte 10"`
`and`	Operador lógico "E". A condição é verdadeira se ambas as sentenças da esquerda e da direita forem verdadeiras. Equivalente JS: `&&` Ex.: `"{foo} gte 10 and {bar} eq 'x'"`
`or`	Operador lógico "OU". A condição é verdadeira se a sentença da esquerda ou da direita for verdadeira. Equivalente JS: `\|\|` Ex.: `"{foo} gte 10 or {bar} eq 'x'"`
`not`	Operador de negação. Inverte o sentido da sentença. Deve ser posicionado antes do operador que terá seu sentido invertido. Equivalente JS: `!` Ex.: `"{foo} not eq 'x'"`

Campos checkbox

Para campos do tipo checkbox, o valor sempre será um boolean, true se estiver marcado ou false se estiver desmarcado. Portanto as condições devem usar valores boolean na comparação, como no exemplo acima.

Comparação de strings

Na comparação de strings, deve-se sempre utilizar áspas simples ('), uma vez que o formato JSON requer que sejam utilizadas áspas duplas (") na definição dos campos.

Certo

"condition" : "{foo} not eq 'success'"

Errado

"condition" : "{foo} not eq "success""

Errado

"condition" : '{foo} not eq "success"'

Errado

"condition" : "{foo} not eq success"

`param.field`¶

Tipo: object

Obrigatório: sim

Determina como o campo de formulário associado ao parâmetro de usuário será renderizado.

Exemplos

```json tab="text" { "name" : "param1", "field" : { "type" : "text", "label" : "Campo de texto" } }

```json tab="select"
{
    "name" : "param2",
    "field" : {
        "type" : "select",
        "label" : "Campo select",
        "options" : [
            {"id" : 1, "text": "Opção A"},
            {"id" : 2, "text": "Opção B"},
            {"id" : 3, "text": "Opção C"},
            {"id" : 4, "text": "Opção D"}
        ]
    }
}

```json tab="checkbox" { "name" : "param3", "field" : { "type" : "checkbox", "label" : "Campo checkbox", "checked" : true } }

```json tab="textarea"
{
    "name" : "param4",
    "field" : {
        "type" : "textarea",
        "label" : "Campo textarea"
    }
}

`param.field.type`¶

Tipo: string

Obrigatório: sim

Especifica o tipo do campo de formulário.

Possíveis valores são:

text
select
checkbox
radio
textarea
tel
number
email
url
range

Exemplo

"type" : "text"

Dica

Para criar um select multiple, adicione também a opção "multiple" : true. Exemplo:

{
    "name" : "foo",
    "field" : {
        "type" : "select",
        "label" : "Foo",
        "multiple" : true,
        "options" : [
            {"id" : 1, "text": "X"},
            {"id" : 2, "text": "Y"},
            {"id" : 3, "text": "Z"}
        ]
    }
}

`param.field.label`¶

Tipo: string

Obrigatório: sim

Define o texto do label associado ao campo de formulário.

Exemplo

"label" : "Cidade"

`param.field.required`¶

Tipo: boolean

Obrigatório: não

Valor padrão: false

Define se o campo de formulário é obrigatório.

Atenção

A obrigatoriedade do campo depende também das regras estabelecidades no parâmetro param.condition.

Exemplo

"required" : true

`param.field.checked`¶

Tipo: boolean

Obrigatório: não

Valor padrão: false

Define se o campo está marcado por padrão. Só tem utilidade se o campo for um checkbox ou radio.

Exemplo

"type" : "checkbox",
"checked" : true

`param.field.defaultValue`¶

Tipo: string

Obrigatório: não

Valor inicial do campo de formulário. Não tem utilidade se o campo for um select, checkbox ou radio.

Exemplo

"defaultValue" : "Algum valor"

`param.field.title`¶

Tipo: string

Obrigatório: não

Define o texto do atributo title do campo de formulário.

O texto será exibido ao passar o mouse sobre o campo.

Exemplo

"title" : "Você deve informar o nome de uma cidade, como Brasília ou Rio de Janeiro"

`param.field.helperText`¶

Tipo: string

Obrigatório: não

Define um texto de ajuda que será exibido após o label do campo.

Deve ser utilizado para disponibilizar uma descrição mais detalhada do campo e dos valores que ele aceita. É equivalente à opção param.field.title, com a diferença que o usuário não precisa passar o mouse sobre o campo para ver a descrição.

Exemplo

"helperText" : "Você deve informar o nome de uma cidade, como Brasília ou Rio de Janeiro"

`param.field.placeholder`¶

Tipo: string

Obrigatório: não

Define o valor do atributo placeholder do campo de formulário.

Exemplo

"placeholder" : "Nome da cidade"

`param.field.tooltip`¶

Tipo: boolean

Obrigatório: não

Valor padrão: false

Define se o atributo title deve ser exibido como um tooltip. Só tem efeito se o parâmetro param.field.title for informado.

Exemplo

"title" : "Você deve informar o nome de uma cidade, como Brasília ou Rio de Janeiro",
"tooltip" : true

`param.field.options`¶

Tipo: array

Obrigatório: não

Define a lista de opções do campo de formulário. Só tem utilidade se o campo for um select.

Cada opção da lista é representada por um objeto com as seguintes propriedades:

Propriedade	Tipo	Descrição
`id`	`string \| number`	Valor da opção, equivalente ao atributo `value` de um `<option>`.
`text`	`string`	Texto da opção que será exibido para o usuário.

Exemplo

"type" : "select",
"options" : [
    {"id" : "a", "text" : "Alpha"},
    {"id" : "b", "text" : "Beta"},
    {"id" : "g", "text" : "Gama"},
    {"id" : "d", "text" : "Delta"}
]

Suporte a optiongroup

Atualmente não há suporte para optiongroup, de forma que o select deve ser uma lista simples de valores.

`param.field.multiple`¶

Tipo: boolean

Obrigatório: não

Valor padrão: false

Define se o campo de formulário é de múltipla escolha. Só tem utilidade se o campo for um select.

Caso seja true, o valor retornado para o widget será um array com todas as opções selecionadas pelo usuário. Se o usuário não tiver selecionado opção alguma, será um array vazio. Mas se for false o valor retornado será uma string.

Exemplo

```json tab="widget.json" "name" : "codes", "type" : "select", "label" : "Códigos", "multiple" : true, "options" : [ {"id" : "a", "text" : "Alpha"}, {"id" : "b", "text" : "Beta"}, {"id" : "g", "text" : "Gama"}, {"id" : "d", "text" : "Delta"} ]

```js tab="widget.js"
var widget = document.querySelector('.widget');
var obj = JSON.parse(widget.dataset.widgetConfig); // objeto JSON
var codes = obj.codes; // array com as opções selecionadas, ex ['b', 'd']

`param.field.maxlength`¶

Tipo: number

Obrigatório: não

Define o total de caracteres que o campo de formulário deverá aceitar. Só tem utilidade em campos text, tel, email, url, number, range e textarea.

Exemplo

"type" : "text",
"maxlength" : 14

`param.field.min`¶

Tipo: number

Obrigatório: não

Define o valor mínimo que o campo de formulário deverá aceitar. Só tem utilidade em campos number e range.

Exemplo

"type" : "number",
"min" : 1

`param.field.max`¶

Tipo: number

Obrigatório: não

Define o valor máximo que o campo de formulário deverá aceitar. Só tem utilidade em campos number e range.

Exemplo

"type" : "number",
"max" : 100

`param.field.step`¶

Tipo: number

Obrigatório: não

Define o intervalo entre os valores de um campo de formulário numérico. Só tem utilidade se o campo for number ou range.

Exemplo

"type" : "range",
"min" : 1,
"max" : 10,
"step" : .5

Documentação do widget.json¶

name¶

title¶

description¶

version¶

author¶

update¶

update.interval¶

update.uri¶

update.module¶

update.headers¶

params¶

param.name¶

param.condition¶

param.field¶

param.field.type¶

param.field.label¶

param.field.required¶

param.field.checked¶

param.field.defaultValue¶

param.field.title¶

param.field.helperText¶

param.field.placeholder¶

param.field.tooltip¶

param.field.options¶

param.field.multiple¶

param.field.maxlength¶

param.field.min¶

param.field.max¶

param.field.step¶

`name`¶

`title`¶

`description`¶

`version`¶

`author`¶

`update`¶

`update.interval`¶

`update.uri`¶

`update.module`¶

`update.headers`¶

`params`¶

`param.name`¶

`param.condition`¶

`param.field`¶

`param.field.type`¶

`param.field.label`¶

`param.field.required`¶

`param.field.checked`¶

`param.field.defaultValue`¶

`param.field.title`¶

`param.field.helperText`¶

`param.field.placeholder`¶

`param.field.tooltip`¶

`param.field.options`¶

`param.field.multiple`¶

`param.field.maxlength`¶

`param.field.min`¶

`param.field.max`¶

`param.field.step`¶