Criando um tema para o Mephisto utilizando Liquid (Tradução)

Criando um tema Mephisto utilizando Liquid - Uma tradução do post original de Jon Milet Baker mantenedor do blog Clockwork Objects.

-----

Mephisto é uma excelente plataforma de blog escrita em Ruby on Rails por Rick Olsen e Justim Palmer, ambos estão por trás do excelente Lighthouse Issue Traking Software. Este artigo / tutorial guiará você passo a passo através do processo de criação de um tema / template customizado.

Em sua extensão eu assumirei que você já está familiarizado com a linguagem Ruby e o com o Framework Rails de Desenvolvimento Web, mas tentarei manter as coisas simples sempre que possível.

Primeiro de tudo, um dos melhores caminhos para aprender como criar um tema / template customizado é fazendo o download de um tema existente no Mephisto Themes Gallery e olhando dentro do arquivo .zip vendo como o autor implementou os temas.

Para iniciar você vai precisar de uma cópia do Mephisto para testar os temas. Você pode facilmente fazer o checkout da última versão do subversion. Siga as instruções do Site do Mephisto. Os temas do Mephisto ficam aramazenados no diretório /themes/ do diretório base da sua aplicação Rails. Se você tiver uma instalação padrão simples, você precisará criar uma nova pasta vazia em /themes/site1/. Você pode chamar a pasta como você queira, este é o local onde criaremos nosso tema.

Temas Mephisto são feitos com aquivos de template Liquid (basicamente arquivos html com marcações de tags extras que injetam conteúdo ao seu template), imagens usadas por seu template, CSS e arquivos Javascript.


Entendendo arquivos Liquid

Os arquivos Liquid foram criados pelos desenvolvedores do Shopify, eles usaram para customizar os shoppins dos seus usuários. Estes templates trabalham exatamente como os arquivos .rhtml do Rails, no entanto eles são salvos de forma que se uma variável for nula ou indefinida ele não levanta uma exceção ou erro no servidor, ele simplesmente não gera qualquer conteúdo. Para desenvolvedores não Rails, arquivos .rhtml armazenam o html para páginas e contém tags especiais <% > onde o código Ruby pode ser inserido e tags <= %> onde podemos colocar saídas para as páginas. Arquivos Liquid são bem parecidas, entretanto ao invés de tags < > não temos { } e ao invés de <= %> nós teremos tags {{ }}.

Mais informações podes ser encontradas no site do Shopify, e eu recomendo essa leitura em adição a esse artigo.

Mephisto provê uma variedade de variáveis que podem ser usadas não apenas para colocar conteúdo na página, mas também para gerar navegação de links entre páginas. Por exemplo, no template isso é usado para mostrar um artigo tais como este, nós temos uma tag {{ }} que especifica a saída de texto do corpo do artigo como isso {{ article.body }}.


Iteração

Se um ítem é um array nós podemos fazer um loop através de cada elemento usando o seguinte:

1. {% for blog_section in site.blog_sections }
2. {{ blog_section.name }}
3. { endfor %}

Condições

Nós podemos também testar valores nestas variáveis Liquid e condicionalmente mostrar seu conteúdo:

1. {% if section.is_home }
2. Welcome to the site…
3. { endif %}

Referência de Variáveis

Antes de nós iniciarmos a criação de templates, existem dois lugares disponíveis para olharmos as variáveis Liquid disponíveis no Mephisto, diretamente no site do Mephisto e também no velho Wiki do Mephisto.

Existem vários examplos de como fazer coisas como formatação de datas etc., especialmenten no link citado anteriormente.

Estrutura do Mephisto

Em adição a exitência de um simples blog, o Mephisto provê um Sistema de Gerenciamento de Conteúdo - CMS (Content Management System), isto permite você criar o conteúdo das páginas, tais como uma página "sobre" ou portifólio.

Quando nós desenhamos um tema, nós precisamos produzir diferentes tipos de conteúdo (blog / páginas) em mente.


Arquivos Liquid Requeridos

Para fazer um tema, o Mephisto olha para o mínimo de arquivos, os quais precisam ser armazenados em uma pasa chamada "templates", no interior das pastas você pode criar ela sobre /themes/site1/. Você precisa ter cuidado de como a pasta estar exatamente ecrita, pois é onde o Mephisto irá olhar.

• section.liquid - Esse template é usado para as seções do blog e normalmente mostram muitos artigos, este template também é geralmente usado como template da sua home page.
• single.liquid - Esse template é usado para mostrar um simples artigo, frequentemente nós mostramos somente pequenos resumos dos artigos na seção blog mostrada acima.
• tag.liquid - Esse template é usado para mostrar artigos para uma tag particular.
• search.liquid - Esse template é usado para mostrar resultados de pesquisa.
• archive.liquid - Esse template é usado para mostrar artigos de um determinado mês.
• error.liquid - Esse template é usado para mostra um erro customizado, quando um artigo ou pesquisa não for encontrado.

layout.liquid
Em adição aos templates acima, nós temos um template chamado "layout.liquid" que abrange tudo, o qual provê conteúdo para cada página, onde podemos colocar nosso principal design (look and feel). Este arquivo está localizado não em "templates" como mostrado acima, mas em uma subpasta (novamente na parte de dentro do tema) chamada "layouts".


Criando um layout template (layout.liquid)

Como mencionado acima, este arquivo é localizado dentro da pasta do nosso tema. O arquivo usado não tem tanta importância pois neste ponto nós estamos no blog, então nós podemos usá-lo para colocar qualquer conteúdo para aparecer em todas as páginas, por exemplo, o cabeçalho com logos e em meu caso um formulário de busca, barras laterais e rodapé. Está pagina é também a única página que engloba o cabeçalho html e o corpo com tags, então isso é o mínimo que nós precisamos.

1. <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”>
2. <html>
3. <head>
4. <title>My Blog</title>
5. </head>
6. <body>
7. {{ content_for_layout }}
8. </body>
9. </html>

Seção Head
Em vez de ter um título em uma página estática, nós podemos inserir dinamicamente o título do site ou se nós estivermos olhando para um artigo de um blog, o título do artigo é mostrado. Isto não só trás aos usuários uma melhor experiência, como também mostra o título em listas de buscadores e serviços de estatísticas como o Feedburner.

1. <title>{{ site.title }} {% if article } – {{ article.title }} { else } {{ site.subtitle }} { endif %}</title>

Acima nós mostramos o título do site, e se nós estivermos vendo um artigo, o objeto artigo é avaliado, então nós podemos mostrar o título ou mostrar o subtítulo do site, como setado nas Configurações Administrativas.

Nós também precisamos ter certeza que nossos browsers podem descobrir automaticamente nosso Feed RSS, então nós precisamos adicionar o seguinte na nossa seção head.

1. {{ head.feed }}
2. <!— If you are using feed burner, set it up with your RSS feed http://yourdomain/feed then use the feedburner address —>
3. <link href=“http://feeds.feedburner.com/miletbaker“ title=“Jon Milet Baker’s Blog“ type=“application/rss+xml“ rel=“alternate“/>

Nós também precisamos referenciar qualquer arquivo Javascript ou Stylesheet externo usando as seguintes tags:

1. {{ ‘stylesheetfilename’ | stylesheet }}
2. {{ ‘javascriptfilename’ | javascript }}

Seção Body
Em layout.liquid nós precisamos criar nossos links de navegação para acessar diferentes páginas ou seções do blog. Eu geralmente crio a navegação usando lista de tags não encomendadas, modelando elas usando CSS. Eu posso então gerar uma lista de items usando uma iteração Liquid como essa abaixo:

1. <ul>
2. {% for section in site.page_sections }
3. <li><a href=“{{ section.url }}“>{{ section.name }}</a></li>
4. { endfor %}
5. </ul>

Acima são criados links para nossas seções de páginas, nós podemos criar links para a seção blog alterando a linha 2 para:

1. {% for section in site.blog_sections %}

Nós também podemos adicionar de forma parecida uma caixa de procura em cada página, para isso nós adicionamos o seguinte:

1. <form method=“get“ action=“/search“>
2. <input type=“text“ class=“search“ value=““ name=“q“ id=“q“ size=“15“/>
3. </form>

Como nós gostaríamos de ter uma barra lateral definida nesse arquivo, nós precisaremos usar uma técnica que usamos para mostrar condicionalmente o título, para mostrar condicionalmente o conteúdo da barra lateral. Um exemplo para isso é mostrar artigos relacionados ao artigo corrente. Minha técnica de artigos relacionados lista outros artigos marcados com as mesmas tags. Nós podemos fazer isso assim:

1. {% if article }
2. {{ article.tags | tagged_articles | assign_to: ‘rel_articles’}}
3. { for rel_article in rel_articles limit: 5 }
4. <a href=‘{{rel_article.url}}‘>{{ rel_article.title }}
5. { endfor }
6. { endif %}

O código acima somente é mostrado quando um artigo está sendo visualizado, nós passamos todas as tags para o artigo corrente e enviamos isso para uma função do Mephisto que retorna uma coleção de artigos, que nós armazenamos em uma variável chamada rel_articles.

Em adição ao que está sendo mostrado relacionado aos artigos nós podemos também mostrar nossos links de arquivos usando o seguinte (neste caso nós precisamos somente disso para mostrar uma seção)

1. {% for month in section.months }
2. {{ section | monthly_articles: month | size | assign_to: ‘articles_count’ }}
3. { if articles_count > 0 }
4. <a href=“{{ section.path }}/{{ section.archive_path }}/{{ month | strftime: “Y/m“ }}“>{{ month | strftime: “%B %Y” }} ( {{ articles_count }} )</a>
5. { endif }
6. { endfor %}

Você poderá também fazer isso para adicionar uma lista de tags aqui. Meu site usa o Plugin de Nuvens Tag criado por Hank (Mephisto Tag Cloud plugin by Hank) para gerar diferentes tamanhos de links tag baseados no seu uso, você pode usar o Technorati Widget ou simplesmente listar todas as tags do site usando:

1. {{ site | linked_tag_list }}

Agora você já tem um template básico, ele contém nossa página de conteúdo comum, agora nós podemos dar prosseguimento aos templates individuais.


Seção template (section.liquid)

Essa seção template como mencionada anteriormente, age como o index ou contém a página para seus itens de blog de cada seção do blog, incluindo a seção home. Aqui você terá acesso não apenas ao nível de variáveis, mas também de variáveis de seção.

1. {% if articles.size > 0 }
2. <h1>Articles</h1>
3. { for article in articles }
4. <!— Within this loop we have access to the article variables. We will need to display each article and some useful properties
5. of the article variable are shown below:—>
6. {{ article | link_to_article }}
7. {{ article.published_at | date: ‘%b %d’ }}
8. {{ article.author.login }}
9. {{ article | linked_tag_list }}
10. <a href=“{{ article.url }}#comments“>{{ article.comments_count | pluralize: ‘comment’ }}</a>
11. {{ article.body | textilize }}
12. { endfor }
13. { else }
14. <p>No articles found.</p>
15. { endif %}

A linha 10 nos permite habilitar a mostrar o número de comentários com um link para parte da página onde nossos comentários estão localizados, note que usamos o pluralizador automático para trabalhar o comentário, baseado no número de comentários, isto é: "1 comentário" ou "2 comentários"

Isso também é nosso conteúdo de página e nós podemos ter artigos longos, em vez de usar o {{ article.body | textilize }} da linha 11, o Mephisto nos provê a funcionalidade de escrever um resumo. Nós podemos escrever um enunciado para as saídas dos resumos dos artigos (se não existir) ou um corpo para os artigos curtos. Isso então requer que você adicione um resumo quando estiver escrevendo um artigo longo, por exemplo, este artigo tem todo texto acima para "Entender arquivos Liquid", isso pode ficar no cabeçalho. O resto do texto fica no corpo.

Nós podemos então substituir {{article.body | textilize }} por:

1. {% if article.excerpt.size > 0 }
2. {{ article.excerpt | textilize }}
3. <a href=‘{{ article.url }}‘ >More…</a><br/><br/>
4. { else }
5. {{ article.body | textilize }}
6. { endif %}

Nota: Eu encontrei no Mephisto saídas que alimentam o article.excerpt seguindo de article.body para cada artigo. Então eu achei que o melhor caminho para fazer isso é usar um resumo para criar um divisor de artigos longos e não ter um texto no resumo repetido no artigo. Entretanto é bom saber como implementar isso, você poderá ter saídas de resumos para o artigo entre aspas no topo do seu artigo, literalmente como um resumo no corpo do texto.


Template Simples (single.liquid)

O template single.layout é usado para mostrar um ítem particular do blog. Isso também é usado por default para mostrar itens de página.

Nessa página nós temos o acesso a variáveis do objeto artigo e queremos ter o seguinte na saída de página:

1. <h1>{{ article.title }}</h1>
2. <p>Posted: {{ article.published_at | date: ‘%d %B %Y’ }}, by {{ article.author.login }}<br/>
3. Tags: {{ article | linked_tag_list }}<br/>
4. Comments: <a href=“{{ article.url }}#comments“>{{ article.comments_count | pluralize: ‘comment’ }}</a></p>
5. {{ article.excerpt | textilize }}
6. {{ article.body | textilize }}

Acima nós listamos o título do artigo, quando, e por quem ele foi publicado, juntamente com as tags. Como eu estou usando um resumo em sepadado do artigos grandes, eu simplesmente mostrei a saída do resumo imediatamente seguida do corpo do texto. Se não tiver resumo somente o texto é mostrado.

Em adição ao código acima nós precisaremos habilitar as pessoas adicionarem comentários aos nossos artigos (e eu sugiro você assinar e usar Askimet).

Nós precisamos adicionar o seguinte código para mostrar nossos comentários:

1. <a name=‘comments‘></a>
2. {% if article.comments.size != 0 }
3. { for comment in article.comments }
4. {{ comment.author_link }}
5. {{ comment.published_at | date: ‘%d %B %Y’ }}
6. {{ comment.body | textilize }}
7. { endfor }
8. { endif %}

A tag do topo é usada quando um usuário navega para a URL de comentário de um artigo, ele pega diretamente a localização da página. Você também pode incluir o Gravatar do comentarista, se ele possuir. Com isso podemos usar o seguinte código para o loop acima:

1. {{ comment | gravatar: 80, “/images/mephisto/avatar.gif” }}

O valor numérico 80 é o tamanho que será mostrado o gravatar, você pode especificar qualquer tamanho acima de 80px.

Nós também precisamos prover o usuário de um formulário para adicionar comentários, se nós estaremos aceitando comentários no artigo, nós faremos o seguinte:

1. {% commentform }
2. <!- comment form ->
3. <label for=“comment_author“>Nick Name</label><br/>{{ form.name }}<br/>
4. <label for=“comment_author_email“>Email (optional)</label><br/>{{ form.email }}<br/>
5. <label for=“comment_author_url“>Website (optional)</label><br/>{{ form.url }}<br/>
6. <label for=“comment_body“>Let the thoughts flow….</label><br/>{{ form.body }}<br/>
7. <input type=“submit“ value=“Add“ />
8. { endcommentform %}

Templade de Tag (tag.liquid), Template de Arquivo (archive.liquid) & Templante de Busca (search.liquid)

Existem três caminhos que para encontrar artigos no seu blog usando Mephisto. Usando a facilidade das tags para encontrar artigos que possuem tags particulares à pesquisa, usando a facilidade dos arquivos, que podem encontrar artigos por data facilmente, e a faciliade da pesquisa.

Todos estes serão geralmente olhados de forma parecida, listando simplesmente o título e data das páginas e talvez o corpo ou o resumo do conteúdo, como nós fizemos como o section.layout.template.

Continuando nós podemos desejar listar o número de artigos, usando por exemplo:

1. {{articles.size | pluralize: ‘article’ }} found.

Paginando
Mephisto mostrará somente o número de ítens especificados nas Configurações Administrativas. Desafortunadamente o Mephisto só implementa paginação no template de busca quando usado juntamente com a procura. Aqui nós podemos adicionar no arquivo search.liquid o seguinte código para habilitar os usuários navegarem pelas páginas.

1. {% if previous_page != “” }<a href=“{{ previous_page }}“>< href="“{{"></a>{ endif %}

Por conta do articles.size conter o número de artigos da saída de página, com buscas que retornam múltiplas páginas, nós podemos não querer mostrar o número total de artigos encontrados. Neste caso nós precisamos alterar o exemplo acima de articles.size para search_count como o seguinte:

1. {{search_count | pluralize: ‘article’ }} found.

Template de Erro (error.liquid)

O último template que nós precisamos criar é o error.liquid template, ele é mostrado sempre que o usuário requisitar um artigo ou um recurso que não exista. Isso é uma boa prática para pegar as opções de usuários para encontrar o que eles estão olhando, então primeiramente é mostrado os artigos mais recentes, mas também é disponibilizado um formulário de busca (veja layout.liquid), permitindo o usuário procurar o conteúdo requerido.


Partials

Assim como no Rails, se nós temos o conteúdo que será usado em mais de um template Liquid, nós podemos armazenar em uma "partial" e incluir nos templates quando precisarmos, por exemplo nossa tag, arquivos e buscas, toda lista de nossos artigos são listados da mesma forma. Neste caso, em vez de repetir nós mesmos cada arquivo, nós podemos incluir no cabeçalho dos arquivos de tag, arquivo e busca, e para a listagem atual colocamos o código que é repetido em um arquivo chamado _article.liquid, isto é:

1. {{ article | link_to_article }}
2. {{ article.published_at | date: ‘%b %d’ }}
3. {{ article.author.login }}
4. {{ article | linked_tag_list }}
5. <a href=“{{ article.url }}#comments“>{{ article.comments_count | pluralize: ‘comment’ }}</a>

e então na tag.liquid, archive.liquid e search.liquid incluiremos o arquivo para cada artigo em nossos objetos de artigos como o seguinte:

1. {% include ‘article’ with articles %}

Distribuindo Templates

Finalmente, se nós quisermos distribuir nossos templates, ou se você acha ter um bom template, porque não faz o upload para o Mephisto Theme Gallery. Para fazer isso nós precisamos empacotar o conteúdo de nosso diretório de tema dentro de um arquivo .zip, mas antes de fazermos isso, nos precisamos primeiramente criar um uma imagem de pré-visualização do nosso tema chamada preview.png na raiz do diretório do nosso tema e também criar um arquivo de descrição que inclui quem é você, como o tema é chamado etc. Isso é armazenado em um arquivo chamado about.yml e é definido em YAML como os seguinte:

1. title: ClockObj Theme
2. author: Jon Milet Baker
3. version: 1.0
4. homepage: http://clockobj.co.uk
5. summary: THe theme for clockobj.co.uk

Este artigo é apenas um rápida introdução à como criar você mesmo um tema Mephisto. Existem muitos outros recursos não apenas no site do Mephisto mas também no seu Wiki.


Mais Informações

Blog Mephisto
Wiki Mephisto


-----

A tradução acima necessita de ajustes, visto que essa é uma das primeiras traduções que faço para tentar aprimorar meu Inglês. Se você quer contribuir melhorando essa tradução deixe um comentário ou envie um email para jackson.pires [at] gmail.com.

Desde já eu agradeço sua contribuição.