Filtro de Cartão Discourse Docs

[Discourse]

	Summary	Discourse Docs Card Filter is to be used with the Discourse Docs Plugin and allows you to place “Cards” that act as a clickable filter for quicker filter results upon entering the /docs page by your users.
	Preview	Preview on Discourse Theme Creator
	Repository Link	https://github.com/discourse/discourse-docs-card-filter
	New to Discourse Themes?	Beginner’s guide to using Discourse Themes

Install this theme component

As this is an official theme component maintained by the Discourse team, support, bug, ux, and feature requests can be made in the respective categories here on Meta, and tagged with the appropriate theme component tag. Click on a link below to get one started.

 Support  Bug  UX  Feature

Features

The above would be rendered with these settings in the docs plugin:

Settings

You can select custom icons for each category or tag card filter. You can also allow category descriptions to be rendered in the category card filters.

Name	Description
category icons	Choose icons & topics order for corresponding category IDs. ex. ‘6,heart,title-asc’ would assign the heart icon to category 6 & will order topic list by ascending activity. NOTE: order can be (title,activity)-(asc/desc)
category description	Enable the category description to be displayed in the category card filters for the docs page.
tag icons	Choose icons & topics order for corresponding tag slugs. ex. ‘featured,heart,activity-desc’ would assign the heart icon to featured tag & will order topic list by ascending activity. NOTE: order can be (title,activity)-(asc/desc)

Translation	Default
topics	Topics
topic	Topic

Hosted by us? Theme components are available to use on our Standard, Business, and Enterprise plans.

Last edited by @JammyDodger 2024-06-12T08:47:57Z

Check document

Perform check on document:

[downey (Michael Downey)]

Thanks for building this! Is it the case that if a user doesn’t have view permissions on a (private) category, the card for that private category won’t appear above the search box? (Or I suppose on the sidebar, but just want to confirm the behavior is consistent.)

[jordan.vidrine]

This should be the case as we are getting the category info from

@discourseComputed("category")
  categoryInfo(category) {
    return this.site.categories.findBy("id", category.id);
  },

To my knowledge, this.site.categories will only return those the current user can view.

[downey (Michael Downey)]

Excellent. That will make it a real easy-to-use tool for people in our multiple workgroups who want quick access to their group(s) reference materials, and quickly filter our Group A from Group B, etc. Thanks!

[MarcP]

Is it possible that the counter on /docs does not count topics moved into that category after it is already created?

I just made a new category, added in docs, moved a few topics but the counter still says “0 topic”.

EDIT: seems it just takes a while to update.

[Nick_Chomey]

Existe uma maneira de alterar a ordem de classificação dos cartões, mesmo que isso exija a modificação do código? Eu gostaria que fosse alfabética em vez de por contagem de tópicos. Obrigado!

[mallen (Mike)]

Olá a todos. Docs e esta extensão de Docs são fantásticos. Só uma coisa. Alguém pode me ajudar a adicionar esses cartões às seções top_menu ou homepage? Seria ótimo ter uma página inicial padrão com ‘Mais recentes’ por padrão, mas com esses cartões no topo. Então, clicar em um cartão levaria para a página de Docs filtrada.

Além disso, tenho outro plugin (Caixa de pesquisa) na seção top_menu. Não consegui descobrir como mudar a ordem se vários plugins estiverem aparecendo nesta seção.

Obrigado.

[jrgong]

Olá @jordan.vidrine

Tentamos o tc e ele funciona muito bem para o seu caso de uso. Agora podemos criar uma base de conhecimento (KB).

Neste contexto, tenho uma pergunta: você pode sugerir alguma solução alternativa para adicionar alguns parâmetros a cada cartão de categoria ou tag? Dessa forma, gostaríamos de anexar &order=title para afetar a classificação de cada cartão de categoria ou tag individual.

PS:

[jordan.vidrine]

Hmm.. Não tenho certeza.

Como você gostaria que a ordenação dos cards de categoria e tag aparecesse?

[jrgong]

Olá Jordan

Poderíamos adicionar um parâmetro de ordenação na configuração do tema ícones de categoria. Por exemplo, no caso de 6,heart, podemos adicionar um comando de ordenação adicional, por exemplo, para ordenar por título do tópico ascendente, seria 6,heart,title-asc.

Ao abrir o cartão da categoria, ele apenas anexaria os parâmetros de documentação, como: /docs?ascending=true&category=71&order=title

O que você acha disso?

[jordan.vidrine]

Embora seja possível que isso funcione bem em um site, sem muito feedback sobre este tópico focado na capacidade de classificar os cartões, não sinto necessariamente que o tempo gasto para fazer isso funcionar corretamente seja atualmente justificado.

Dito isso, encorajamos PRs em componentes, bem como a criação de forks de um componente para usá-lo da sua maneira!

Sinta-se à vontade para fazer um PR com esta funcionalidade, ou criar um fork para desenvolvê-la para si mesmo.

[Ahmed_Gagan]

@jordan.vidrine

Dito isso, nós incentivamos PRs em componentes

Posso fazer um PR para esta solicitação, pois @jrgong está patrocinando o trabalho.

[jrgong]

@Nick_Chomey

Existe uma maneira de alterar a ordem de classificação dos cartões, mesmo que exija a modificação do código? Eu gostaria que fosse alfabética em vez de por contagem de tópicos. Obrigado!

Aumentando este tópico! Alguém conseguiu descobrir?

[Nick_Chomey]

Minha solução foi desativar os cartões (já que tenho muitas categorias para torná-los úteis de qualquer maneira) e modificar a ordem de classificação dos Docs. Você pode ver mais sobre isso aqui Modifying Discourse Docs to only allow for sorting by Title - #2 by Nick_Chomey

[jordan.vidrine]

Nós definitivamente aceitamos PRs benéficos para nossos componentes!

Se você fosse adicionar a capacidade de classificar esses cartões, eu sugeriria criar uma nova lista de valores onde você pode colocar a ordem dos cartões por ID de categoria e ID de tag. Eu não os adicionaria a uma lista de valores já existente para algo não relacionado.

[Lishuo_Lin]

@jordan.vidrine Obrigado por projetar o ótimo componente. Existe alguma maneira de desabilitar o componente em dispositivos móveis, mas mostrá-lo em PC/Mac?

[jrgong]

Entendido. Mas você poderia pelo menos mudar a configuração de ícones de categoria para lista de valores? É muito mais fácil gerenciar os cards em vários campos de texto em vez de um único. ;)\n\nE como uma solução alternativa temporária, seria super útil se cada card de documentação tivesse uma classe CSS com o respectivo slug da categoria ou tag.\n\nAntes: \u003ca class=\"docs-card-box category-card\"\u003e\nDepois: \u003ca class=\"docs-card-box [category-slug] category-card\"\u003e

[jordan.vidrine]

Esta é uma boa sugestão

[jrgong]

Me avise se precisar de ajuda com testes, ficarei feliz em ser o rato de laboratório

[jordan.vidrine]

Depois de pensar melhor, decidi não alterar a configuração de ícones de categoria para uma lista de valores, pois sem uma opção de fallback, isso quebraria os componentes dos usuários atuais.

Adicionar um fallback seria verificar se o usuário definiu os ícones no campo atual ou no novo campo lista de valores, e acho que isso é muito complicado de adicionar a este componente, pois adicionaria outro nível de configurações e causaria possível confusão.

Quanto às adições de classe, é uma ótima ideia, mas não tenho um cronograma para quando isso será adicionado, pois há coisas mais pertinentes que precisam da minha atenção.

Dito isso, quando possível, também recebemos PRs para nossos componentes, afinal, somos open source!