As part of our ongoing quest to standardise the rendering systems across Discourse’s codebase, we’re replacing the implementation of the topic-list. Previously, this used a ‘raw handlebars’ (.hbr) approach, and could be customized via template overrides and raw-plugin-outlets. The new implementation of the topic-list uses modern Glimmer components, and has been built from the ground-up to to be customizable in sustainable ways. The new implementation is now available behind the glimmer_topic_list_mode setting. disabled: use the legacy “raw handlebars” topic-list auto: will detect the compatibility of your current plugins and themes. If any are incompatible, it will use the legacy system; otherwise it will use the new implementation. enabled: will use the new topic-list implementation. If you have any incompatible plugins or themes, your site may be broken. We’ve already updated most of our official themes and plugins to be compatible with the new menu. But, if you run any third-party plugins, themes, or theme components which customize the topic list, upgrading them will be required. Warnings will be printed in the browser console identifying the source of the incompatibility. :timer_clock: Roll-out Timeline These are rough estimates subject to change Q4 2024: :white_check_mark: core implementation finished :white_check_mark: updating official themes/plugins (in progress) :white_check_mark: enabled on Meta :white_check_mark: published upgrade advice Q1 2025: :white_check_mark: updating official themes/plugins :white_check_mark: glimmer_topic_list_mode default to auto; console deprecation messages enabled :white_check_mark: deprecations will trigger an admin warning banner for any remaining issues third-party plugins and themes should be updated :white_check_mark: 1st March - enable the new topic-list for all sites. The default for the site setting will be switched to enabled, but it will still be possible to switch back to ‘disabled’ Q2 2025 :white_check_mark: after 1st April - final removal of the legacy mode & associated code :eyes: What does it mean for me? If your plugin or theme has any ‘raw handlebars’ files (named .hbr or .raw.hbs) then those will need to be updated for compatibility with the new version. Regular .hbs files for Ember components/routes are unaffected by this change. Upgrades will also be required if you use modifyClass on component:topic-list or component:topic-list-item. If your site has any of these incompatible customizations, warning messages will be printed to the browser developer console, including information about which theme/plugin is the cause. What are the replacements? Some of the old raw-plugin-outlets have been converted to regular Plugin Outlets. Those can be updated in a 1:1 fashion. More advanced customizations will need to be assessed on a case-by-case basis. The new topic-list has a number of new APIs for easy and robust customization. Find out more here: [image] Customizing the topic list Developer Guides The topic-list is one of the most-used and most-customized user-interfaces in Discourse. There are many different tools available to theme and plugin developers to achieve this customization, each with their own advantages, disadvantages and maintenance considerations. CSS-based Customization The safest and most common customization method is CSS. As with any other Discourse customization: the more complex your changes, the more maintenance is likely to be required in your theme or plugin. Gen… Here are some examples: discourse-assign introduces a new column to a specific topic-list discourse-calendar uses one of the new plugin outlets to display the event date badge discourse-solved uses a new valueTransformer to replace the previous modifyClass :sos: What about other customizations? If your customization cannot be achieved using the new APIs we’ve introduced, please let us know by creating a new #dev topic to discuss. :sparkles: I am a plugin/theme author. How do I update a theme/plugin to support both old and new topic list during the transition? The new plugin outlets are rendered in both the old and new implementations of the topic list. So: when you’ve implemented the new one, simply delete the old raw-plugin-outlet connector. For DAG-based customizations which replace template-overrides or non-modernized outlets, you will need to maintain both implementations during the transition period. Once your theme/plugin supports both old and new implementations, you can add this magic comment at the top of all your .hbr files: {{!-- has-modern-replacement --}} This will silence the deprecation messages, and allow the new implementation to be used when in “auto” mode.

[image] Robert: Q: Is it possible to assign complete Component to a Cell, not just a ? Yup! Technically, a bare tag is technically creating a “Template Only Component”. Similar to the type of component you get when you drop a bare .hbs file under the components/ directory. So yes, importing and passing a normal component class will work just the same. It’ll even work with classic components! (although obviously we’d recommend using the more modern Glimmer components).

that’s completely awesome! that changes … a lot! :exploding_head:

Dumb question, maybe. But how to apply changes to … mobile topic-list?

For mobile, we have a bunch of new plugin outlets (including wrapper outlets). Or alternatively, you can use a valueTransformer to force the desktop view everywhere (we do this for topic-thumbnails). I’m planning to write a more detailed “how to customize the topic list” #developer-guides next week, so will be sure to include that info in there.

Sorry to eat into your weekend David, yes, just saw the API, thanks app/assets/javascripts/discourse/app/components/topic-list/item.gjs 9f41ce7fc if ( e.key === "Enter" && (e.target.classList.contains("post-activity") || e.target.classList.contains("badge-posts")) ) { e.preventDefault(); this.navigateToTopic(this.args.topic, e.target.href); } } get useMobileLayout() { return applyValueTransformer( "topic-list-item-mobile-layout", this.site.mobileView, { topic: this.args.topic } ); } get additionalClasses() { return applyValueTransformer("topic-list-item-class", [], { topic: this.args.topic, javascripts/discourse/initializers/topic-thumbnails-init.gjs 4e4fc54ac } return columns; }); api.renderInOutlet("topic-list-before-link", {{#if ttService.displayList}} {{/if}} ); api.registerValueTransformer("topic-list-item-mobile-layout", ({ value }) => { if (ttService.enabledForRoute && !ttService.displayList) { // Force the desktop layout return false; } return value; }); api.registerValueTransformer( "topic-list-item-class", ({ value, context: { index } }) => {

Hi, I’ve tried to use value transformer for “topic-list-columns” like this: export default { name: "assignment-topic-list-column-modifier", initialize(container) { const router = container.lookup("service:router"); withPluginApi("1.39.0", (api) => { api.registerValueTransformer( "topic-list-columns", ({ value: columns }) => { if (ASSIGN_LIST_ROUTES.includes(router.currentRouteName)) { columns.add("posters-recent", { header: AssignHeaderCell, item: AssignCell, after: "posters", }); } return columns; } ); }); }, }; The goal is to insert new column item and header after “posters” column, it works for the item, but the header still not in the right place, it was placed after “activity” column. Is there something missing in my code? and is there any documentation that explain how to do this correctly?

There is a new guide: [image] Using Transformers to customize client-side values and behavior Developer Guides Discourse core includes a number of “transformer” hooks which can be used to customize client behavior. These fall into two categories: Value Transformers take an output from Discourse core, and optionally modify it, or replace it with something else Behavior Transformers can replace a particular piece of logic in Discourse core, and optionally call the original implementation. Each transformer hook is referenced by a name, and multiple plugins/themes can register transformers against t… However, it may not be very useful in this case.

@NateDhaliwal thanks for the info, i will check it.

I think the code should look like: columns.add( "posters-recent", { header: AssignHeaderCell, item: AssignCell } { after: "posters"} }); And you might need to specify a before: {after: "posters", before: "replies"}

@Arkshine thanks a lot, your code works !!! awesome :+1:

Upcoming topic-list changes - how to prepare themes and plugins

Development

NateDhaliwal (Nate Dhaliwal) February 2, 2025, 6:20am 24

There is a new guide:

However, it may not be very useful in this case.

Topic		Replies	Views
MD Topic List component Theme component	73	11389	September 7, 2025
MD Topic List Mobile component Theme component	67	8431	July 21, 2026
Upcoming Header Changes - Preparing Themes and Plugins Development dev-news	36	4800	September 8, 2024
Upgrading Discourse to Ember 4 Development ember	19	3533	December 19, 2024
Upcoming post menu changes - How to prepare themes and plugins Development dev-news	12	1365	April 1, 2025

Upcoming topic-list changes - how to prepare themes and plugins

Related topics