Advertisement
  1. Code
  2. Web Development

Compartilhando Componentes do Polymer: Parte 2

Scroll to top
Read Time: 9 min

Portuguese (Português) translation by Erick Patrick (you can also view the original English article)

Na parte um dessa série, mostrei como configurar o ótimo modelo untitled-element, que a equipe do Polymer criou para tornar a criação e compartilhamento de componentes, substancialmente, mais fácil.

No tutorial a seguir, aprofundarei nos itens que o untitled-element inclui, como a funcionalidade de auto-geração de documentação, e como preparar seu componente para distribuição via Bower. Continuarei usando o componente Reddit que criei no primeiro tutorial.

Uma Melhor Olhada No untitled-element

Dentro do seu projeto modelo, há alguns arquivos chave que você usará:

  • bower.json - Permite especificar configurações e dependências do seu componente
  • untitled-element-master.html - Layout do seu novo componente
  • untitled-element-master.css - Folha de estilo que estilizará o modelo do seu novo componente
  • index.html - Arquivo HTML que inclui a base do Polymer para a geração de documentação
  • demo.html - Arquivo HTML que permitirá seus usuários testar seu componente

Esses são os arquivos base que estão presentes quando você baixa o modelo a partir do repositório PolymerLabs no GitHub, e servirão como a fundação do seu novo componente. Na parte um, nós renomeamos o arquivo untitled-element-master.html para reddit-element.html, e o arquivo untitled-element-master.css para reddit-element.css, uma vez que eles precisam ser nomeados tal qual nosso componente. Nós também atualizamos as referências a untitled-element nos arquivos, para garantir que referenciam o nome correto do componente.

Olhemos o código do arquivo reddit-element.html:

Fora o básico, da ligação com a base do Polymer, definição dos atributos e adição de um espaço reservad para a inclusção de JavaScript em seu componente, o ponto chave a notar é que as referências de recursos externos usam o caminho canônico mencionado antes. É por isso que a parte de preparação do Bower, na parte um desse tutorial, é tão importante. Ela garante que todas as dependências imitem o seu ambiente de desenvolvimento, tal qual seria se você já estivesse compartilhando seu componente.

Também note o monte de meta-documentação inclusa no componente. Há um motivo importante para isso. O modelo lança mão do elemento core-component-page para extrair a documentação do seu elemento para poder criar uma página de documentação no estilo do JSDoc! Se abrir o arquivo index.html, poderá ver a referência lá:

De cara, sem adicionar qualquer código, só executando o index.html, obtenho uma página de documentação da minha API, como essa:

Então, garantindo que você comenta adequadamente seu componente, o modelo oferece as facilidades necessárias para criar essa documentação de API incrivelmente útil.

E, também, se olhar para o canto esquerdo da página de documentação, logo ao lado do nome do elemento, há um botão com o nome demo:

Clicá-lo fará uma chamada ao arquivo demo.html. Essa é uma outra característica importante porque, quando você publicar seu componente, os outros, além de uma ótima documentação para seguir, terão a possibilidade de testar seu componente imediatamente, para ver se satisfaz as necessidades deles. Falaremos sobre isso já-já.

É assim que o componente Reddit parece, depois que passei o código do componente para o modelo:

As principais diferenças são que, agora, lança mão dos comentários a la JSDoc e o uso dos caminhos canônicos para acessar os componentes irmãos necessários. Também adicionei algumas poucas regras de estilo no arquivo reddit-element.css para melhorar um pouco as coisas:

E, claro, agora, tenho uma bela página de documentação para o meu componente:

Enviando Para o GitHub

Para distribuir seu componente através do Bower, é necessário que haja acesso online via Git e que haja um rótulo Git com um número de versão correspondente, para que os usuários saibam que versão eles estão instalando. Para esse tutorial, usaremos o GitHub.

Os passos iniciais são relativamente fáceis e comuns para qualquer pessoa familiarizada com o Git, uma vez que basta criar um repositório local, adicionar e entregar (commit) seus arquivos do projeto atual e, então, enviá-los para o GitHub. Assumirei que usará o Terminal, que tem o Git instalado e que já possui uma conta no GitHub:

  1. Certifique-se que está no diretório do seu componente (ex: reddit-element)
  2. Digite git init para inicializar um repositório local no diretório em questão
  3. Digite git add . para adicionar todos os seus arquivos
  4. Digite git commit -am ‘Meu primeiro commit' para entregar seus arquivos ao repositório
  5. Crie um novo repositório no GitHub, com o nome do seu componente (ex: reddit-element)
  6. Digite git remote add origin https://github.com//reddit-element.git para indicar que o local remoto do seu repositório é o repositório recém criado no GitHub.
  7. Digite git push -u origin master para enviar os arquivos para o GitHub.

Se você recarregar a página do seu repositório no GitHub, você deverá ver todos os arquivos do seu componente.

Quando você tiver feito todas as mudanças necessárias e achar que já pode liberar seu componente, será preciso que você crie um rótulo de lançamento para ele. Isso é feito criando um rótulo via Git que marca um ponto específico na história do seu repositório. Você pode fazer isso pela linha de comando, porém, a forma mais fácil de fazer isso é através do GitHub, clicando no link "releases" link:

Isso mostrará o processo de como criar um lançamento para seu componente:

Clicando no botão "Create a new release" levará você a um formulário que permitirá definir informações sobre esse lançamento em específico, incluindo o número da versão, o ramo (branch) alvo e informações gerais sobre o lançamento. O Bower segue o modelo de versionamento semântico e você deveria seguir o mesmo caminho. Por exemplo, no arquivo bower.json, listei o número de versão do componente como "0.0.1", então, seguirei a mesma técnica para o meu lançamento.

Daqui, basta, simplesmente, apertar o botão publishing e, pronto! Um novo lançamento:

Novamente, esse é um passo importante que ajudará seus usuários a encontrar uma versão específica no histórico do seu componente.

A última coisa que precisamos fazer no GitHub é publicar uma página para o componente. A página será a página da documentação que é gerada automaticamente pelo modelo, tornando a documentação e a versão de demonstração disponíveis para você compartilhar facilmente. Para fazer isso, a equipe do Polymer criou um código simples que lida com a criação do ramo para páginas no GitHub, para seu repositório. Você precisará baixar o arquivo do respositório do Polymer no GitHub e executá-lo dentro do diretório pai do componente. Dei enfaze a isso para que você possa executá-lo no lugar exato. Eis os passos:

  1. Volte para o diretório pai do componente
  2. Digite git clone git://github.com/Polymer/tools.git para baixar/clonar o código
  3. Digite mkdir temp && cd temp para criar um novo diretório e ir para ele
  4. Digite ../tools/bin/gp.sh test-element substituindo com o seu nome de usuário do GitHub
  5. Volte para o diretório pai e remova o diretório temp (ex: rm -rf temp)

O ramo da página foi criado:

Isso, agora, permite compartilhar o componente através do seguinte link:

http://reybango.github.io/reddit-element/components/reddit-element/

Bem simples!

Tornando-o Instalável Através do Bower

O passo final para tornar seu componente disponível para o mundo é registrá-lo na Listagem do Bower. Vários do passos até aqui foram realizado, explicitamente, para ajudar a chegar nesse ponto.

O Bower usa um arquivo manifesto para descobrir as informações correspondentes ao pacote que está instalado. É aqui que o arquivo bower.json entra em ação. Ele é o arquivo manifesto que o Bower usará. Eis o conteúdo atual:

Precisamos atualizá-lo com informações adicionais que a Listagem do Bower usará para mostrar quando algum usuário estiver avaliando seu componente. Entre as informações estão:

  • Nome do auto
  • Descrição do componente
  • Palavras-chave que descrevem o componente
  • Tipo de licença que o componente foi lançado
  • A página do componente (ex: a página no GitHub que acabamos de criar)

Com essas mudanças no lugar, o arquivo bower.json parece com isso, agora:

As palavras-chave são importantes para a descoberta, então, esforce-se um pouco nelas.

Finalmente, estamos no último passo para poder ser listado. Usaremos o comando bower register, através do Terminal, para registrar nosso componente. Isso requererá o nome do componente e o endereço Git (em nosso caso, no GitHub) do repositório online:

Isso tornará o componente disponível e pesquisável através da Listagem do Bower, bem como atravpes do comando bower search:

Agora posso instalar meu novo componente e todas suas dependências através do comando a seguir:

Isso o instalará no diretório bower_components, que é, exatamente, onde ele precisa ficar:

O Novo Modelo É Ótimo

Sou muito grato à equipe do Polymer pela criação desse modelo, do qual podemos iniciar nossos próprios componentes. Transformaram a tediosa tarefa de lidar com caminhos em algo simples. E, ao incluir o elemento core-component-page, criar documentações e prover uma versão de demonstração é, incrivelmente, fácil de se fazer.

Espero que esse tutorial tenha demonstrado o quão fácil é para documentar, empacotar, registrar e distribuir seu componente. O Bower é, definitivamente, aquilo que você deveria usar para tornar o processo mais fácil para seus usuários e para você mesmo.

Seja o primeiro a saber sobre novas traduções–siga @tutsplus_pt no Twitter!

Advertisement
Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.