WebModules - Escrever um Módulo

Instalação

Para escrever um módulo, faça um fork do repositório webmodules.github.io em sua conta no GitHub e faça um clone de seu fork em sua máquina local:

          
            $ git clone git@github.com:meufork/webmodules.github.io.git

A pasta baixada do repositório tem a seguinte estrutura:

          
/webmodules.github.io
  ├ index.html
  ├ index.css
  ├ README.md
  ├ wm-doc.html
  ├ /.git
  ├ /modules
    ├ /global
      ├ /highlight
      ├ global.css
      ├ imports.html
    ├ /moduloTeste
      ├ /assets
      ├ index.html
      ├ style.css
      ├ script.js

Onde:

index.html: Página inicial listando os módulos
index.css: Estilo CSS da página inicial
README.md: Arquivo README padrão do GitHub, contendo a descrição do projeto
wm-doc.html: Página HTML contendo a documentação do WebModules
/.git: Página com arquivos de configuração do Git, não toque nela!
/modules: Pasta contendo os módulos
/modules/global: Pasta para recursos usados por todos os módulos
/modules/global/highlight: Plugin para apresentação visual de pedaços de código, mais detalhes em https://highlightjs.org/
/modules/global/imports.html: HTML que importa os recursos usados para a apresentação de todos os módulos
/modules/moduloTeste: Pasta de um módulo de teste, nomeada em letra minúscula, sem caracteres especiais e usando a convenção CamelCase
/modules/moduloTeste/assets: Pasta contendo recursos usados pelo módulo que não sejam arquivos CSS ou JavaScript, como imagens, SVGs etc.
/modules/moduloTeste/index.html: Arquivo para apresentação do módulo e sua documentação
/modules/moduloTeste/style.css: Arquivo CSS do módulo
/modules/moduloTeste/script.js: Arquivo JavaScript do módulo (opcional)

Estrutura de arquivos

Dentro da pasta modules do projeto, crie uma pasta com o nome do módulo escrito sem caracteres especiais e usando a convenção lowerCamelCase.
Dentro da pasta crie os arquivos index.html, style.css e script.js, onde:

index.html: Marcação HTML contendo uma demonstração do módulo e sua documentação
style.css: Estilos CSS do módulo
script.js: Script JavaScript utilizado pelo módulo. Mesmo que o módulo não utilize JavaScript, é necessária a criação desse arquivo vazio.

Estrutura de arquivos — Árvore de pastas na criação de um novo módulo.

Caso o módulo utilize recursos externos como imagens, SVGs, fontes etc, crie uma pasta chamada assets dentro da pasta do módulo para guardar esses arquivos.

Marcação HTML

O arquivo index.html do módulo deve ter o seguinte template:

          
<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <title>Nome do Módulo</title>
  <link rel="stylesheet" href="style.css">
  <link rel="import" href="../global/imports.html">
</head>
<body>
  <header id="header">
    <h2>Nome do Módulo v0.1</h2>
    <nav>
      <h2>Índice</h2>
      <li><a href="#modulo">Módulo</a></li>
      <li><a href="#descricao">Descrição</a></li>
      <li><a href="#uso">Uso</a></li>
      <li><a href="#comportamento">Comportamento</a></li>
      <li><a href="#log">Log das versões</a></li>
    </nav>
  </header>
  <main class="global main">
    <section id="modulo">
      <h2>Módulo</h2>
      <!-- Marcação HTML do módulo -->
    </section>
    <section id="descricao">
      <h2>Descrição</h2>
      <p>Descrição do módulo.</p>
    </section>
    <section id="uso">
      <h2>Uso</h2>
      <p>Instruções para o uso do módulo, com exemplo de uso do código:</p>
      <pre>
        <code class="code html">
  <head>
    <link rel="stylesheet" href="caminho/para/WebModules.css">
  </head>
        </code>
      </pre>
      ...
    </section>
    <section id="comportamento">
      <h2>Comportamento</h2>
      <p>Descrição do comportamento do módulo, ou seja, como ele reage a interação com o usuário, o contexto em que ele está inserido e como ele pode ser configurado, se necessário utilizando exemplos em código.</p>
    </section>
    <section id="log">
      <h2>Log de versões</h2>
      <ul>
        <li>
          <h2>0.1</h2>
          <ul class="no-list">
            <li>Criado o módulo.</li>
          </ul>
        </li>
      </ul>
    </section>
  </main>
  <footer class="global footer">
    <h2><a href="http://epicentrotec.github.io/webmodules.github.io/">WebModules</a></h2>
  </footer>
</body>
</html>

A marcação HTML do módulo deve estar dentro da <section id="modulo">, como indicado na linha 25. Caso seja necessário utilizar um exemplo de código, coloque-o dentro de uma tag <code> com um valor de classe code mais outro que indique a linguagem do código, os valores suportados são html, css, javascript, scss, http, makefile, markdown, sql, xml, json, bash e php. A tag <code> por sua vez deve estar dentro de uma tag <pre> como indicado no código entre as linhas 34 e 40. Caso o código seja HTML, CSS, PHP ou JavaScript e seus derivados, você deve escapar seus caracteres especiais antes de inseri-los na tag <code>. Para fazer isso recomendamos o site opinionatedgeek.com.

O conteúdo das <section> deve ser preenchido de acordo com o módulo.

Versionamento

Os módulos devem utilizar o modelo de versão <versão>.<subversão> - <XX/XX/XXXX>, sendo a última informação a data de lançamento. A versão representa uma versão funcional com novas funcionalidades e mudanças estruturais em relação a uma versão anterior do módulo e a subversão representa ajustes e correções dentro de uma versão, sem nenhuma mudança significativa.

O log de versões mostra as mudanças da nova versão em relação à versão anterior. A primeira versão (versão 1.0) deve conter apenas o lançamento do módulo.

Estilo CSS

O estilo CSS referente ao módulo deve ser escrito no arquivo style.css.
Os estilos devem começar com a classe do módulo, que deve ser composta pela combinação wm-<nomeDoModulo>. Exemplo do módulo Jumbotron:

          
.wm-jumbotron {
  background-color: rgba(0, 0, 0, .1);
  max-height: 100vh;
  overflow-y: hidden;
  width: 100%;
}

.wm-jumbotron img {
  display: block;
  width: 100%;
}

Além de seu estilo exclusivo, os módulos herdam alguns estilos globais, contidos no arquivo global.css. Verifique este arquivo antes de criar os estilos do módulo.

JavaScript

Caso seu módulo utilize scripts JavaScript, escreva-os no arquivo script.js com o seguinte template:

          
window.onload = function() {
  // Código JavaScript
}