Later today I am going to be merging our new post rendering engine into master. Swapping out Ember/HTMLBars for a virtual-dom based renderer provides us with a huge performance increase, but it also has the side effect of being incompatible with how plugins were previously made. While doing this work, it occurred to me that we made a fairly big mistake in the past by not providing a mechanism for versioning the public APIs used by client side code. We used to encourage people to just dump in whatever Javascript they wanted in an Ember initializer, which works great and is fast to develop, but it has major issues if we ever want to deprecate or update those APIs. The good news is the latest version of Discourse has a new versioned API for plugins and extensibility. The bad news is most plugins will need to be updated. To ease in this transition, I spent the last two weeks going through the most popular discourse plugins and updating them so that they’d be compatible with both versions of discourse. If your plugin was open source, you might have received a pull request from me! If you are a plugin author, please check your plugin against the tests-passed of discourse! I have provided deprecation warnings for old APIs that are migrated to the new system. I’ve also tried wherever possible to always boot discourse, even if code is using old objects or functions. The odds are good that even if you coded directly against an internal Discourse object, your plugin will not stop Discourse from loading (but it will not add or change functionality!) Using the new API To use the new client side API, you must ask Discourse for an instance of a PluginAPI object. You can do this in an initializer by importing withPluginApi and calling it like so: // assets/javascripts/discourse/initializers/with-plugin-sample.js.es6 import { withPluginApi } from 'discourse/lib/plugin-api'; export default { name: 'with-plugin-sample', initialize() { withPluginApi('0.1', api => { api.onPageChange(() => console.log('user navigated!')); }); } } The idea here is you tell Discourse you want an instance of the Plugin API object for a particular version of the API. Since this is the first release, I’ve specified the version 0.1. The cool thing here is that Discourse can provide backwards compatible API objects, even if things behind the scene change. We could be up to version 1.3, for example, but still know how to provide an API compatible object for 0.1. Additionally, if the API you used is so old that we can’t provide a backwards compatibility layer (likely due to a very severe refactor down the line) we just won’t call the function and your plugin code will not be executed at all. The idea here is it’s better to do nothing at all, rather than have a Javscript error that would interrupt Discourse from starting up safely. Plugin API Documentation The documentation for the PluginAPI version 0.1 can be found in plugin-api.gjs. I’ve documented the public surface area of the API there. The easiest thing to do when developing a plugin is to open that file and look for the latest hooks and methods you can consume. Also, don’t be afraid to ask questions on meta! All the Discourse developers read this forum daily and we can offer guidance and support. Providing Backwards Compatiblity New plugin authors will be able to use the withPluginApi as specified above. However, for older plugins that must co-exist with versions of Discourse that exist before the new API was added it’s a little more involved. I have backported the withPluginApi call to the beta and stable branches of Discourse, so that call is safe to make in all currently supported releases. As mentioned previously, if no api is available for the version you requested, that code will not run, so you can use it to gate the code that works with the new API safely. However, you’ll still need a way to run your old code, so I’ve added a noApi option to help with this. This is how I’ve ported all the plugins I’ve done so far. Here’s an example of that approach: // assets/javascripts/discourse/initializers/backwards-example.js.es6 import { withPluginApi } from 'discourse/lib/plugin-api'; function oldCode() { // migrate your old plugin code here. It will only be run if no PluginAPI is present } function initializePlugin(api) { // do stuff with plugin API! } export default { name: 'backwards-example', initialize() { withPluginApi('0.1', api => initializePlugin(api), { noApi: () => oldCode() }); } } In the above example, if version 0.1 of the plugin API is available, initializePlugin will be called and can use it. If no API is present, oldCode will be called. You can paste your old plugin code there and it should work. If you want a more involved example, you can see here how I updated the solved plugin to use this approach. Using the versioned API in a Site Customization See this write up for information on how to use the plugin API safely within a Site Customization. Final Thoughts Again, I’d like to apologize for not having a versioned API in place in the past and the difficulties this will introduce. However, in the long run I believe this change will be worth it, and will drastically prevent developer pain as we continue to update Discourse.

[תמונה] eviltrout: To ease in this transition, I spent the last two weeks going through the most popular discourse plugins and updating them so that they’d be compatible with both versions of discourse. If your plugin was open source, you might have received a pull request from me! This is what sets an awesome opensource project from the rest. Thanks, and this make me much more likely to code plugins for Discourse.

Will you be updating the Beginner’s Guide to Creating Discourse Plugins?

Thanks, I thought I had tried that, but I must have had a typo or something, as I know it failed initially, but it definitely works now. :slightly_smiling: Cool, this isn’t too bad, I shouldn’t have to do too much reworking.

I am writing a private plugin for a customer right now. I’ll try to move to the new API right now. Hopefully I can write up some reflections after that. Right after the reading, it’s hard to understand the version “0.1” here. It’s not connected with Discourse version. Why? It just sounds wrong… I am doing monkey patch a lot because I create a dialect which affects different controller’s behaviour. For sure, it’s rely upon on some version of client’s code which plugin version doesn’t help (?) BTW, new decorateCooked is so nice! Can we have a nice site_setting helper?

To be clear this change only affects plugins that have an “initialize” ? if a plugin needed to be changed to comply, there would be a Deprecation in the Ember Inspector ? [תמונה]

For the Checklist Plugin, I need to add click events to certain cooked content. I’m trying to figure out what api call to use to perform that. api.decorateWidget('post-contents:after-cooked', function (dec) { var post = dec.getModel(); console.log(post); if (!post.can_edit) { return; }; // code to find checkbox syntax using jQuery selectors occurs before it is rendered, so I’m not sure I can embed click events. I feel like maybe I’m approaching this all wrong. As I feel the above is too early, but I don’t know what call is “just right”. Edit: Disregard, I solved it. Just needed a goodnights sleep to wake me up :slightly_smiling:

Thanks for the update @eviltrout . Topics are now rendering much faster. I can only imagine how much work was involved, especially considering your efforts to support legacy code. I do appreciate that code injected client side via the Admin panel isn’t your focus right now, but it would save client side devs a lot of time if you could show how the following deprecated event (or equivalent) is now being generated and how we should hook into it. var topicView = require('discourse/views/topic').default; //get a reference to the topic view topicView.reopen({ //access view object didInsertElement : function(){ this._super(); Ember.run.scheduleOnce('afterRender', this, this.afterRenderEvent); }, afterRenderEvent : function(){ //after view has been rendered do this: //console.dir(this); //Use this to to get a good overview of what's available console.dir("Category ID: " + this._controller.model.category.id + " - Category Name: " + this._controller.model.category.name); } }); It’s only a token example, but help with this, coupled to the new API document should be sufficient to get to grips with the new topic architecture. A final question. Is the new virtual DOM architecture limited to topics only, or are there plans to expands its use elsewhere?

@ccdw, depending on what you are attempting, you may want to look at the Solved Plugin, which interacts with a Topic, and to get to the first post uses https://github.com/discourse/discourse-solved/blob/master/assets/javascripts/discourse/initializers/extend-for-solved-button.js.es6#L144-L151 dec.getModel() by itself returns a post object, which is why it then requests the topic using .get('topic')

API ממוחשבת עם גרסאות לתוספי צד לקוח

מפתח

cpradio (cpradio) 23 בפברואר,‏ 2016,‏ 10:31pm 4

@eviltrout, previously I had initialize(container) so I could access siteSettings to enable/disable the showing of a toolbar button. In the new API, that seems to be via api.container, which is fine, but how do I do it with noApi?

נושא		תגובות	צפיות
Theme-Component v Plugin: What's the difference Development	22	6207	9 ביוני,‏ 2020
Developing Discourse Plugins - Part 1 - Create a basic plugin Developer Guides plugin-guides , tutorial	32	85774	8 ביולי,‏ 2025
Case study of an amateur plugin author Development	11	689	4 במאי,‏ 2026
Upcoming post menu changes - How to prepare themes and plugins Development dev-news	12	1368	1 באפריל,‏ 2025
Modernizing inline script tags for templates & JS API Development dev-news	46	6299	25 במרץ,‏ 2026

API ממוחשבת עם גרסאות לתוספי צד לקוח

נושאים קשורים