Discourse Docs Card Filtre

[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]

Y a-t-il un moyen de modifier l’ordre de tri des cartes, même si cela nécessite de modifier le code ? Je voudrais que ce soit par ordre alphabétique plutôt que par nombre de sujets. Merci !

[mallen (Mike)]

Salut à tous. Docs et cette extension de Docs sont fantastiques. Juste une chose cependant. Quelqu’un peut-il m’aider à ajouter ces cartes aux sections top_menu ou homepage ? Ce serait génial d’avoir une page d’accueil standard avec ‘Latest’ par défaut, tout en ayant ces cartes en haut. Cliquer sur une carte mènerait ensuite à la page Docs filtrée.

De plus, j’ai un autre plugin (boîte de recherche) dans la section top_menu. Je n’ai pas réussi à comprendre comment changer l’ordre si plusieurs plugins s’affichent dans cette section.

Merci.

[jrgong]

Salut @jordan.vidrine

Nous avons essayé le tc et il fonctionne parfaitement pour votre cas d’utilisation. Nous pouvons maintenant créer une base de connaissances.

Dans ce contexte, j’ai une question : pouvez-vous suggérer une solution de contournement pour ajouter des paramètres à chaque carte de catégorie ou d’étiquette ? De cette façon, nous aimerions ajouter &order=title afin d’affecter le tri pour chaque carte de catégorie ou d’étiquette individuelle.

PS :

[jordan.vidrine]

Hmmm.. Je ne suis pas sûr.

Comment souhaitez-vous que le tri des cartes de catégories et d’étiquettes apparaisse ?

[jrgong]

Salut Jordan

Nous pourrions ajouter un paramètre de tri dans le réglage du thème icônes de catégorie. Par exemple, dans le cas de 6,heart, nous pouvons ajouter une commande de tri supplémentaire, par exemple pour trier par titre de sujet ascendant, ce serait 6,heart,title-asc.

Lors de l’ouverture de la carte de catégorie, cela ajouterait simplement les paramètres de documentation tels que : /docs?ascending=true&category=71&order=title

Qu’en penses-tu ?

[jordan.vidrine]

Bien qu’il soit possible que cela fonctionne bien sur un site, sans beaucoup de retours sur ce sujet axé sur la capacité de trier les cartes, je ne pense pas que le temps passé à faire fonctionner cela correctement soit actuellement justifié.

Cela dit, nous encourageons les PR sur les composants, ainsi que le fork d’un composant pour l’utiliser à votre manière !

N’hésitez pas à faire un PR avec cette fonctionnalité, ou à le forker pour le développer vous-même.

[Ahmed_Gagan]

@jordan.vidrine

Cela dit, nous encourageons les PR sur les composants

Je peux faire une PR pour cette demande car @jrgong sponsorise le travail.

[jrgong]

@Nick_Chomey

Y a-t-il un moyen de changer l’ordre de tri des cartes, même si cela nécessite de modifier le code ? J’aimerais que ce soit par ordre alphabétique plutôt que par nombre de sujets. Merci !

Je fais remonter ce sujet ! Quelqu’un a-t-il trouvé une solution ?

[Nick_Chomey]

Ma solution a été de désactiver les cartes (puisque j’ai trop de catégories pour qu’elles soient utiles de toute façon) et de modifier l’ordre de tri des Docs. Vous pouvez en savoir plus à ce sujet ici Modifying Discourse Docs to only allow for sorting by Title - #2 by Nick_Chomey

[jordan.vidrine]

Nous accueillons certainement les PRs bénéfiques à nos composants !

Si vous ajoutiez la possibilité de trier ces cartes, je suggérerais de créer une nouvelle liste de valeurs où vous pouvez spécifier l’ordre des cartes par ID de catégorie et par ID de balise. Je n’ajouterais pas ces informations à une liste de valeurs déjà existante pour quelque chose d’autre.

[Lishuo_Lin]

@jordan.vidrine Merci d’avoir conçu ce super composant. Y a-t-il un moyen de désactiver le composant sur les appareils mobiles tout en l’affichant sur PC/Mac ?

[jrgong]

Très bien. Mais pourriez-vous au moins changer le paramètre category icons en value-list ? Il est beaucoup plus facile de gérer les cartes dans plusieurs champs de texte plutôt qu’un seul.

Et comme solution de contournement temporaire, il serait très utile que chaque carte de documentation ait une classe CSS avec le slug de catégorie ou de tag respectif.

Avant : \u003ca class=\"docs-card-box category-card\"\u003e
Après : \u003ca class=\"docs-card-box [category-slug] category-card\"\u003e

[jordan.vidrine]

C’est une bonne suggestion

[jrgong]

Faites-moi savoir si vous avez besoin d’aide pour les tests, je serai heureux d’être le cobaye

[jordan.vidrine]

Après y avoir réfléchi davantage, j’ai décidé de ne pas modifier le paramètre category icons en une liste de valeurs car, sans option de repli, cela casserait les composants des utilisateurs actuels.

L’ajout d’un repli consisterait à vérifier si l’utilisateur a défini les icônes dans le champ actuel ou dans le nouveau champ value-list, et je pense que c’est trop compliqué à ajouter à ce composant, car cela ajouterait un autre niveau de paramètres et pourrait prêter à confusion.

Quant aux ajouts de classes, c’est une excellente idée, mais je n’ai pas de calendrier pour savoir quand cela sera ajouté, car il y a des choses plus importantes qui nécessitent mon attention.

Cela dit, lorsque c’est possible, nous accueillons également les PRs pour nos composants, nous sommes après tout open source !