Criando um widget: estrutura e configuração

Download do widget deste exemplo

Se você quiser pular toda a explicação abaixo e colocar a mão na massa, pode fazer o download do widget que nós criaremos neste tutorial.

Download do widget

Neste passo-a-passo nós mostraremos como construir um widget que exiba a previsão meteorológica de uma localidade, passando por todas as etapas até a execução do widget no DSME Player.

Estrutura do widget

Nosso widget contará com a estrutura de arquivos mostrada abaixo:

Estrutura do widget

previsao-meteorologica/
  |_ css/
  |_ font/
  |_ js/
  |_ media/
  |_ index.html
  |_ preview.png
  |_ widget.json

De todos estes arquivos e diretórios, os únicos obrigatórios para o funcionamento do widget são index.html, widget.json e preview.png. Nesta página nós falaremos sobre o widget.json.

Configurando o widget.json

Vamos em primeiro lugar criar o arquivo widget.json, que é o arquivo que define as principais propriedades do widget. Mas vamos por partes.

widget.json

{
    "title" : "Previsão Meteorológica",
    "name" : "previsao-meteorologica",
    "description" : "Informações atualizadas sobre o clima para uma determinada localidade",
    "author" : "DSME <https://dsme.tv>",
    "version" : "1.0.0"
}

O bloco acima é o mínimo que um widget tem que ter para poder ser registrado na plataforma DSME. Nele nós definimos:

• "title": o título do nosso widget, que no caso é Previsão Meteorológica;
• "name": o identificador único, que no caso é previsao-meteorologica;
• "description": uma breve descrição;
• "author": o author do widget;
• "version": a versão do nosso widget.

Dica

Você pode conferir todos os parâmetros disponíveis na página do widget.json.

No entanto, esta configuração define um widget estático, isto é, que não é atualizado dinamicamente. E não é isto que nós queremos. Nós estamos criando um widget que exibe informações sobre o clima, e este tipo de informação tem que ser atualizada constantemente.

Para que o nosso widget passe a ser dinâmico, nós precisamos configurar a propriedade update.

widget.json

{
    "title" : "Previsão Meteorológica",
    "name" : "previsao-meteorologica",
    "description" : "Informações atualizadas sobre o clima para uma determinada localidade",
    "author" : "DSME <https://dsme.tv>",
    "version" : "1.0.0",
    "update" : {
        "interval" : 6,
        "module" : "weather"
    }
}

Agora sim. Com a configuração acima o nosso widget será atualizado a cada 6 horas, recebendo a informação meteorológica do módulo weather.

Mas está faltando um detalhe importante: para usar o módulo weather nós precisamos informar de qual lugar nós queremos ver a previsão meteorológica. Para isto é preciso definir um parâmetro de usuário, que neste caso é o parâmetro local.

widget.json

{
    "title" : "Previsão Meteorológica",
    "name" : "previsao-meteorologica",
    "description" : "Informações atualizadas sobre o clima para uma determinada localidade",
    "author" : "DSME <https://dsme.tv>",
    "version" : "1.0.0",
    "update" : {
        "interval" : 6,
        "module" : "weather"
    },
    "params" : [
        {
            "name" : "local",
            "field" : {
                "type" : "text",
                "label" : "Local",
                "required" : true,
                "placeholder" : "Cidade ou coordenadas lat/long",
                "helperText" : "Você pode informar o nome de uma cidade, como Brasília ou Rio de Janeiro, ou uma coordenada geográfica, como -15.799989, -47.884510"
            }
        }
    ]
}

O que nós acabamos de fazer foi definir um parâmetro de usuário chamado local. Este parâmetro será renderizado como um campo de texto no DSME Manager para que o usuário informe de que local ele quer ver a previsão meteorológica. Ele pode informar o nome de uma cidade, o código de um aeroporto ou uma coordenada geográfica.

Acontece que este parâmetro de usuário, além de renderizar um campo de texto, também cria uma variável com o mesmo nome, {local}. E é aí que a mágica acontece: o módulo weather recebe esta variável e a partir daí pode consultar a informação solicitada.

Mas além de passar o local para o módulo weather, nós precisamos exibir na tela do DSME Player um nome amigável para este mesmo local, para que as pessoas saibam de que lugar é aquela previsão climática que elas estão vendo.

Para isto nós precisamos de outro campo:

widget.json

{
    "title" : "Previsão Meteorológica",
    "name" : "previsao-meteorologica",
    "description" : "Informações atualizadas sobre o clima para uma determinada localidade",
    "author" : "DSME <https://dsme.tv>",
    "version" : "1.0.0",
    "update" : {
        "interval" : 6,
        "module" : "weather"
    },
    "params" : [
        {
            "name" : "local",
            "field" : {
                "type" : "text",
                "label" : "Local",
                "required" : true,
                "placeholder" : "Cidade ou coordenadas lat/long",
                "helperText" : "Você pode informar o nome de uma cidade, como Brasília ou Rio de Janeiro, ou uma coordenada geográfica, como -15.799989, -47.884510"
            }
        },
        {
            "name" : "name",
            "field" : {
                "type" : "text",
                "label" : "Nome de exibição",
                "required" : true,
                "placeholder" : "Brasília",
                "helperText" : "Nome que será exibido na tela do player"
            }
        }
    ]
}

Este segundo parâmetro de usuário vai disponibilizar uma variável chamada {name}, que não será passada para o módulo weather. Ao invés disto, nós a usaremos no nosso front-end um pouco mais a frente.

Próximo passo

Agora que nós já especificamos de onde e como receber a informação que precisamos, vamos criar o front-end para apresentá-la.