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

Dev
1

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
  • :recycle: official themes/plugins updated (in progress)
  • :white_check_mark: enabled on Meta
  • :white_check_mark: published upgrade advice

Q1 2025:

  • :soon: glimmer_post_menu_mode default to auto; console deprecation messages enabled
  • third-party plugins and themes should be updated
  • deprecations will trigger an admin warning banner for any remaining issues
  • enabled the new topic-list by default

Q2 2025

  • removal of the feature flag setting and legacy 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.

To add, remove, reorder or replace columns in the topic-list, we’ve introduced a new topic-list-columns value transformer.

The value transformer provides a DAG object which allows adding, replacing removing, or reordering the columns. When introducing new columns, regular Ember components can be passed in to the DAG.

Every customization is different, but here are some examples:

We’ll continue to update this section with more examples over the coming weeks.

: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.

8 Likes
2

Sorry to be picky, but doesn’t this really mean something more lke “if your plugin of theme has any ‘raw handlebars’ files that have anything to do with topic-list then they need to be updated”

My raw handlebars files that have to do with other models are going to continue to be fine, right? Or are raw handlebars files going away entirely? (I think they are required for additional models/routes, right?)

1 Like
3

“Raw handlebars” means our discourse-specific templates, which have the file extension .hbr (or historically .raw.hbs). We only used this system for the topic-list, and some ‘autocomplete’ internals.

Other .hbs files (e.g. for Ember components, or routes) are unaffected.

I’ll update the OP to make that clearer. Thanks @pfaffman!

Edit: here we go:

1 Like
4

Oh. You really did try to make it clear. You explicitly stated the extensions. I don’t think you can make it clearer. I think this one is on me. :person_shrugging:

But maybe adding the extra sentence would have helped me be able to read.

1 Like
5

Thanks for sharing. I’ve been afraid of this for a long time and it’s coming…:grimacing: It will not seems to be an easy run… :sweat_smile: But value transformer probably will make it easier.:crossed_fingers:

1 Like