Neste codelab, você irá aprender como construir componentes usando o Polymer 1.0. Você irá criar um componente simples com o Polymer, um botão de alternância de estados (toggle button). O resultado final será assim:

Este projeto apresentará os principais conceitos para o desenvolvimento com o Polymer.

Não se preocupe se você não compreender todas as etapas. Cada conceito apresentado aqui é descrito com detalhes na documentação do Polymer.

Você fará o download do Chrome Dev Editor e do código de exemplo no próximo passo. Você pode usar qualquer outro editor de texto ao invés do Chrome Dev Editor, mas você precisará fazer o download de algumas ferramentas para o seu terminal.

Como você avalia sua experiência com Polymer?

Iniciante Intermediário Avançado

Instalando o Chrome Dev Editor

Instalando as ferramentas para o seu terminal (opcional)

Para executar o codelab sem o Chrome Dev Editor, você precisará instalar o Node.js, bower (para instalar as dependências) e polyserve (para executar os exemplos).

  1. Faça o download e instale o Node diretamente do site oficial https://nodejs.org/. O Node inclui o comando npm (node package manager).
  2. Instale o bower e o polyserve:
npm install -g bower polyserve

Faça download do código de exemplo

Você pode fazer o download do código de exemplo para o seu computador...

Download Zip

...ou fazer o clone do repositório no GitHub pela linha de comando.

$ git clone https://github.com/googlecodelabs/polymer-first-elements.git

Através do Chrome Dev Editor abra o diretório icon-toggle:

  1. Click e selecione Open Folder.
  2. Navegue através do código de exemplo e escolha a pasta icon-toggle.
  3. Click Select. O Chrome Dev Editor mostrará o diretório.
  4. Click com o botão direito ou CTRL+click no nome do diretório e selecione Bower install.

Fazer o download dos componentes pode demorar caso sua conexão esteja lenta.

Se você não está usando o Chrome Dev Editor, execute o comando bower install no diretório raíz do seu projeto.

bower install

Quando a instalação terminar, o diretório do seu projeto deve estar assim:

project layout

icon-toggle/
  bower_components/ <!-- installed dependencies from Bower -->
  bower.json  <!-- Bower metadata files used for managing deps -->
  icon-toggle.html  <!-- your element-->
  demo/
    icon-toggle-demo.html
    index.html 

Execute o exemplo

Para executar o exemplo:

  1. Click com o botão direito ou CTRL+click no diretório icon-toggle/demo e escolha Run.

O Chrome Dev Editor abrirá o exemplo em uma nova aba do navegador. Você verá algum texto onde o elemento icon toggles deveria aparecer. Não está muito interessante, mas isto mostra que tudo está funcionando.

Execute o exemplo usando o polyserve

Se você não tem o Chrome Dev Editor, você pode usar o polyserve através da linha de comando para executar o exemplo.

Para iniciar o polyserve, execute o comando polyserve dentro do diretório raíz do seu projeto:

 polyserve

O comando polyserve deve produzir algo semelhante ao output abaixo mostrando que está funcionando:

Starting Polyserve on port 8080
Files in this directory are available at localhost:8080/components/icon-toggle/...

Abra o navegador e navegue para o endereço localhost:8080/components/icon-toggle/demo/.

Nessa etapa, você criará um elemento simples que mostra um ícone.

Você poderá usá-lo com um markup bem simples como este:

<icon-toggle></icon-toggle>

Nessa etapa, você irá aprender:

Altere o icon-toggle.html

Click no icon-toggle.html através do painel de navegação do Chrome Dev Editor. Este arquivo contém a estrutura de um custom element. Comece olhando o código que já existe:

icon-toggle.html — código inicial

<link rel="import"
  href="../bower_components/polymer/polymer.html">

<link rel="import" href="../iron-icon/iron-icon.html">

Informações importantes:

O próximo trecho de código mostra a definição do elemento:

icon-toggle.html — código inicial

<dom-module id="icon-toggle">

  <template>

    <style>
      /* local styles go here */
      :host {
        display: inline-block;
      }
    </style>

    <!-- local DOM goes here -->
    <span>Not much here yet.</span>

  </template>

  <script>

    Polymer({
      /* this is the element's prototype */
      is: 'icon-toggle'
    });

  </script>
</dom-module>

Informações importantes:

No final da definição do elemento temos uma tag <script>:

icon-toggle.html

<script>
  Polymer({
    /* this is the element's prototype */
    is: 'icon-toggle'
  });
</script>
</dom-module>

Informações importantes:

Criando a estrutura do local DOM

Encontre o elemento <span> logo abaixo do comentário local DOM goes here:

icon-toggle.html

    <!-- local DOM goes here -->
    <span>Not much here yet.</span>
  </template>

Substitua a tag <span> e seu conteúdo com a tag <iron-icon> abaixo:

icon-toggle.html

    <!-- local DOM goes here -->
    <iron-icon icon="polymer">
    </iron-icon>
  </template>

Informações importantes:

Aplicando estilos ao local DOM

Existem diversos novos seletores CSS específicos para o local DOM. O arquivo icon-toggle.html já inclui o seletor :host, discutido anteriormente, para estilizar o elemento <icon-toggle>.

Para aplicar estilos ao elemento <iron-icon> adicione o seguinte código CSS dentro da tag <style> após o código existente:

icon-toggle.html

  <style>
    /* local styles go here */
    :host {
      display: inline-block;
    }
    iron-icon {
      fill: rgba(0,0,0,0);
      stroke: currentcolor;
    }
    :host([pressed]) iron-icon {
      fill: currentcolor;
    }
  </style>

Informações importantes:

Recarregue a página. Você deve ver os botões de alternância mostrando o ícone definido.

Neste momento, o elemento ainda não faz muita coisa. Nesta etapa, você irá inserir uma API básica, que permitirá a configuração do ícone através do markup.

Primeiro, um pouco de data binding. Encontre o elemento <iron-icon> e substitua o nome do ícone com o seguinte trecho "[[toggleIcon]]".

icon-toggle.html

<!-- local DOM goes here -->
<iron-icon icon="[[toggleIcon]]">
</iron-icon>

Informações importantes:

Se você executar o exemplo agora, você não verá nenhum ícone ainda, pois ainda não existe nenhum valor padrão para a propriedade toggleIcon. Você pode definir programaticamente da seguinte forma:

exemplo

var myToggle = document.querySelector('icon-toggle');
myToggle.toggleIcon = "favorite";

Entretanto, seria muito mais conveniente definir essa propriedade diretamente no markup:

exemplo

<icon-toggle toggle-icon="favorite"></icon-toggle>

Configurar um elemento usando seus atributos é um padrão muito comum no HTML, por isso o Polymer torna isso fácil.

Encontre a tag script e adicione o objeto properties ao protótipo do elemento:

icon-toggle.html

<script>
  Polymer({
    /* this is the element's prototype */
    is: 'icon-toggle',
    properties: {
      toggleIcon: String
    }
  });
</script>
</dom-module>

Informações importantes:

O objeto properties também suporta outras funcionalidades. Inclua as linhas de código a seguir para adicionar o suporte à propriedade pressed:

icon-toggle.html

  Polymer({
    /* this is the element's prototype */
    is: 'icon-toggle',
    properties: {
      toggleIcon: String,
      pressed: {
        type: Boolean,
        value: false,
        notify: true,
        reflectToAttribute: true
      }
    }
  });

Informações importantes:

Agora o seu elemento passa a ter as duas propriedades pressed e icon funcionando corretamente. Você pode definí-las diretamente no markup.

Recarregue a página e você verá os ícones de estrela e coração ao invés do ícone definido hard-coded na etapa anterior:

Se você está curioso de onde as estrelas e os corações vieram, olhe o arquivo demo/icon-toggle-demo.html e veja as linhas a seguir:

<icon-toggle toggle-icon="star"></icon-toggle>
<icon-toggle toggle-icon="star" pressed></icon-toggle>

Claro que um botão não é um botão se você não pode clicar nele. Para alternar os estados do botão, adicione um event listener. Para adicionar event listeners no elemento principal (neste caso, o icon-toggle), adicione um objeto chamado listeners ao protótipo do elemento:

icon-toggle.html

  Polymer({
    /* this is the element's prototype */
    is: 'icon-toggle',
    properties: {
      toggleIcon: String,
      pressed: {
        type: Boolean,
        value: false,
        notify: true,
        reflectToAttribute: true
      }
    },
    listeners: {
      'tap': 'toggle'
    },
    toggle: function() {
      this.pressed = !this.pressed;
    },
  });

Informações importantes:

Salve o arquivo icon-toggle.html e rode o exemplo novamente. Você deve ser capaz de clicar o botão e ver a alteração de estado quando o botão está pressionado ou não.

Você agora tem um botão com uma funcionalidade básica. Mas ainda está usando a mesma cor para os dois estados. E se você quiser ir um pouco além?

O local DOM ajuda a prevenir que usuários apliquem estilos aos elementos internos acidentalmente. Usando propriedades customizadas, seu elemento pode expor um conjunto específico de propriedades que o usuário pode estilizar.

Você aplica uma propriedade customizada dentro do seu elemento usando a função `var`.

background-color: var(--my-custom-property, defaultValue);

Onde --my-custom-property é o nome da propriedade customizada, sempre iniciando com dois traços (--), e defaultValue é um valor CSS opcional que é usado se a propriedade customizada não for definida.

Altere a tag <style> e substitua os valores fill e stroke com as propriedades a seguir:

icon-toggle.html

  <style>
    /* local styles go here */
    :host {
      display: inline-block;
    }
    iron-icon {
      fill: var(--icon-toggle-color, rgba(0,0,0,0));
      stroke: var(--icon-toggle-outline-color, currentcolor);
    }
    :host([pressed]) iron-icon {
      fill: var(--icon-toggle-pressed-color, currentcolor);
    }
  </style>

Por causa dos valores padrão, você ainda pode estilizar o elemento <icon-toggle> apenas definindo o valor color, mas agora você tem outras opções. Abra o arquivo demo/icon-toggle-demo.html e defina as novas propriedades:

icon-toggle-demo.html

    <style>
      :host {
        --icon-toggle-color: lightgrey;
        --icon-toggle-outline-color: black;
        --icon-toggle-pressed-color: red;
      };
    </style>

Execute o exemplo novamente e vejas as cores.

Então é isso! — você chegou ao fim. Você acabou de criar um elemento que tem uma interface básica, API e propriedades de estilo customizadas.

Se você encontrar qualquer problema para fazer o elemento funcionar, veja a versão final.