Skip to content

Post Filtering

Jump to bottom
Neylon Santos edited this page Jun 17, 2025 · 1 revision

🔍 Filtragem de Posts

O Sistema de Filtragem de Posts é um componente-chave da arquitetura modular do Contramaré, responsável por exibir ou ocultar automaticamente conteúdo com base nas funcionalidades ativas.

📋 O que é a Filtragem de Posts?

É um sistema otimizado que:

  • Filtra automaticamente posts baseado em categorias mapeadas
  • Protege posts individuais de funcionalidades desativadas
  • Garante uma experiência consistente para os usuários
  • Otimiza performance ao reduzir processamento de conteúdo desnecessário

⚙️ Como Funciona

A filtragem acontece em dois momentos distintos:

1️⃣ Durante o Build (Ruby)

Um plugin Jekyll customizado processa os posts durante a fase de build:

# _plugins/feature_filter.rb

# Hook executado após carregar todos os posts
Jekyll::Hooks.register :site, :post_read do |site|
  process_posts_by_features(site)
end

Este plugin:

  • Analisa todas as categorias de posts
  • Verifica quais funcionalidades estão ativas
  • Pré-computa uma lista de posts que devem ser exibidos
  • Armazena resultados em site.data para acesso rápido

2️⃣ Nos Templates (Liquid)

Filtros Liquid personalizados aplicam a filtragem nos templates:

<!-- Filtrar posts em listas -->
{% assign filtered_posts = site.posts | posts_by_active_features %}

<!-- Verificar se uma categoria específica está ativa -->
{% assign category_active = "Frases" | category_is_active %}

<!-- Verificar em posts individuais -->
{% assign post_category = page.categories | first %}
{% assign is_active = post_category | category_is_active %}

🧠 Lógica de Filtragem

O algoritmo segue estas regras:

  1. Posts sem categoria são sempre exibidos
  2. Posts com categorias não mapeadas são sempre exibidos
  3. Posts com categorias mapeadas são exibidos somente se a funcionalidade correspondente estiver ativa
  4. Posts com múltiplas categorias são exibidos se pelo menos uma categoria estiver ativa ou não for mapeada

🛠️ Filtros Disponíveis

posts_by_active_features

Filtra uma coleção de posts mantendo apenas os que pertencem a funcionalidades ativas:

{% assign filtered_posts = site.posts | posts_by_active_features %}

Também pode ser usado com subcoleções:

{% assign recent_posts = site.posts | limit: 10 | posts_by_active_features %}

category_is_active

Verifica se uma categoria específica está ativa:

{% assign frases_ativa = "Frases" | category_is_active %}
{% if frases_ativa %}
  <!-- A categoria Frases está ativa -->
{% endif %}

feature_stats

Retorna estatísticas sobre posts filtrados:

{% assign stats = "" | feature_stats %}
<p>Total de posts: {{ stats.total_posts }}</p>
<p>Posts ativos: {{ stats.active_posts }}</p>
<p>Posts filtrados: {{ stats.filtered_count }}</p>

📊 Implementação na Estrutura do Site

Listas de Posts

Em páginas que listam múltiplos posts:

<!-- _includes/last_publications.html -->
{% assign filtered_posts = site.posts | posts_by_active_features %}

<div class="posts-list">
  {% for post in filtered_posts limit:5 %}
    <div class="post-card">
      <h3>{{ post.title }}</h3>
      <p>{{ post.excerpt }}</p>
    </div>
  {% endfor %}
</div>

Posts Individuais

Em layouts que exibem posts individuais:

<!-- _layouts/post.html -->
{% assign post_category = page.categories | first %}
{% assign category_active = post_category | category_is_active %}

{% if category_active %}
  <article>
    <h1>{{ page.title }}</h1>
    {{ content }}
  </article>
{% else %}
  {% include content_unavailable.html %}
{% endif %}

Página de Blog

Na página principal do blog:

<!-- pages/blog.html -->
{% assign blog_posts = site.posts | where_exp: "post", "post.categories contains 'Blog' or post.categories contains 'Reflexões'" | posts_by_active_features %}

{% for post in blog_posts %}
  <!-- Exibição do post -->
{% endfor %}

🚀 Performance Otimizada

A filtragem é otimizada para performance:

  1. Pré-computação: A lista de posts filtrados é calculada uma única vez durante o build
  2. Set para comparações O(1): Usa estrutura de dados eficiente para categorias ativas
  3. Cache em site.data: Os resultados são armazenados para acesso rápido
  4. Filtro lazy: Quando passada uma coleção específica, filtra apenas o necessário

🧪 Casos de Uso Avançados

Filtragem em Cascata

Combine com outros filtros:

{% assign recent_special_posts = site.posts | where: "special", true | posts_by_active_features | limit: 3 %}

Filtragem por Tag

Filtre por tag e garanta que a funcionalidade está ativa:

{% assign featured_posts = site.tags.destaque | posts_by_active_features %}

Filtragem com Ordenação Personalizada

Ordene após filtrar:

{% assign popular_posts = site.posts | posts_by_active_features | sort: "views" | reverse %}

🛠️ Solução de Problemas

Posts não são filtrados corretamente

Verificações:

  1. Plugin feature_filter.rb está presente em _plugins/
  2. Categorias estão corretamente mapeadas em category_feature_map
  3. Nome das categorias corresponde exatamente ao usado nos posts

Funcionalidade ativa, mas posts não aparecem

Verificações:

  1. O post tem a categoria correta (case sensitive)
  2. O mapeamento está correto
  3. O post não tem outra categoria inativa que esteja interferindo

Filtro não funciona em ambientes de produção

Os plugins Jekyll podem não funcionar em ambientes como GitHub Pages que executam no modo seguro. Nesse caso:

  1. Use build local e faça deploy dos arquivos gerados
  2. Ou migre para Netlify/Vercel que permitem builds customizados

📊 Debug e Monitoramento

Verificar Categorias Ativas

<div class="debug">
  <h4>Categorias Ativas:</h4>
  <ul>
    {% for category in site.data.active_categories %}
      <li>{{ category }}</li>
    {% endfor %}
  </ul>
</div>

Verificar Estatísticas de Filtragem

{% assign stats = "" | feature_stats %}
<div class="debug">
  <h4>Estatísticas:</h4>
  <ul>
    <li>Posts totais: {{ stats.total_posts }}</li>
    <li>Posts ativos: {{ stats.active_posts }}</li>
    <li>Posts filtrados: {{ stats.filtered_count }}</li>
    <li>% Visível: {{ stats.active_posts | times: 100 | divided_by: stats.total_posts }}%</li>
  </ul>
</div>

📚 Implementação Técnica

O plugin de filtragem usa uma abordagem em duas fases:

Fase 1: Pré-processamento no Build

def self.process_posts_by_features(site)
  features = site.config['features'] || {}
  category_map = site.config['category_feature_map'] || {}

  # Pré-computa categorias ativas
  active_categories = Set.new
  category_map.each do |category, feature_key|
    active_categories << category if features[feature_key] == true
  end

  # Filtra posts
  active_posts = site.posts.docs.select do |post|
    post_categories = extract_categories(post)
    next true if post_categories.empty?
    post_categories.any? do |category|
      !category_map.key?(category) || active_categories.include?(category)
    end
  end

  # Disponibiliza dados
  site.data['filtered_posts'] = active_posts
  site.data['active_categories'] = active_categories.to_a
end

Fase 2: Filtros Liquid para Templates

module FeatureFilterLiquid
  def posts_by_active_features(posts = nil)
    # Usa dados pré-computados ou filtra uma coleção específica
  end

  def category_is_active(category)
    # Verifica se categoria está ativa
  end

  def feature_stats
    # Retorna estatísticas do processo de filtragem
  end
end

🔄 Próximos Passos

Custom footer

Clone this wiki locally