As part of our project to upgrade Discourse to the latest version of Ember, we’ve been working on a significant refactoring of the Discovery (a.k.a. the ‘topic list’) routes.
This topic is targeted at theme/plugin developers, and aims to list the kinds of theme/plugin activities which may be affected by the refactoring.
Background
This refactoring is necessary because modern Ember no longer supports ‘named outlets’ like {{outlet "topics"}}, which we were using extensively on these routes. Essentially, all the controllers/templates which were previously rendered into named outlets have been converted into Components.
Along the way, we’ve taken the opportunity to modernize and consolidate the relevant code (e.g. all types of discovery route now share the same controller and template)
The implementation of the change in core isn’t finalised yet, but a work-in-progress can be found on this branch. We don’t have a specific date for merging, but we expect it to be within the next few weeks. If you have any questions or concerns, please let us know!
Which theme/plugin activities are affected?
This refactoring predominantly affects the ‘controller’ layer. Routes are largely unchanged, and everything from the <TopicList /> component downwards is also unaffected.
We expect the only impact will to themes/plugins which are reaching deep into core code (e.g. via modifyClass and template overrides). Defined APIs and outlets are unaffected.
Template Overrides
These templates have been refactored into components. Any existing overrides will stop working silently
navigation/categoriesnavigation/categorynavigation/defaultnavigation/filterdiscovery/topics
These templates have been heavily refactored. Any existing template overrides are likely to cause catastophic errors on the site.
discoverytag/showuser-topics-listuser/messagesdiscovery/categoriescomponents/basic-topic-listcomponents/d-navigation
Technically, it is possible to override the new templates introduced by this change. However, template overrides are not recommended and are on the way out.
Therefore, all template overrides should be removed and replaced with more robust extension APIs (e.g. plugin outlets). If there’s anything you’re doing which doesn’t seem possible with Discourse’s existing extension points, please let us know!
modifyClass and lookup() calls
These classes no longer exist. modifyClass will stop working silently. Lookups will return null (and therefore might lead to errors). In the most popular cases, we have introduced shims for backwards-compatibility (see footnotes)
controller:discoverycontroller:discovery/topics[1]controller:discovery-sortable( →controller:discovery/list)controller:discovery-filter( →controller:discovery/filter)controller:navigation/categoriescontroller:navigation/category[2]controller:navigation/defaultcontroller:tag/show[3]controller:discovery.*( →controller:discovery/list)
These classes have undergone significant refactoring. modifyClass and lookup calls may require refactoring:
route/discoveryroute/discovery.*route/tag-show
Routes
Route names (i.e. router.currentRouteName) are unchanged
Discovery route model() hooks (i.e. router.currentRoute.attributes) are mostly unchanged
Plugin Outlets
All plugin outlets and their arguments are unchanged.
HTML / CSS
HTML structure and classes are largely unaffected