Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Web Development
Code

Compartilhando Componentes do Polymer: Parte 2

by
Difficulty:BeginnerLength:MediumLanguages:

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
Advertisement
Advertisement
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.