Moving away from Discourse.SiteSettings: An upgrading guide

Dev
1

In the most recent releases of Discourse, we’ve completely removed Discourse.SiteSettings from the Javascript application. The only places you’ll find it are for backwards compatibility.

We’re doing this as part of our migration to Ember CLI, but also because it’s the right thing to do - Discourse.XYZ is essentially a global variable which means our dependencies are all over the place.

If you are a plugin or theme developer and use Discourse.SiteSettings in your code, now is the time to start thinking of migrating away.

How to update your Javascript code:

  • If your reference is an Controller, Route, Model, Component or Widget, you can use this.siteSettings instead.

  • If your file is in an initializer, you can look up the site settings using the container parameter: let siteSettings = container.lookup('site-settings:main');

  • If your file is a qunit test, you can use this.siteSettings but NOTE your test method will need to be a proper function and not an arrow function so that this is correct:

    QUnit.test("test something", function(assert) { 
  this.siteSettings; // will work
});

QUnit.test("test something", assert => { 
  this.siteSettings; // will NOT work
});

    In most cases you should be able to replace assert => { with function(assert) { and it will work fine.

  • If your code is in a helper, there is a new function helperContext() which you can import and use to get the site settings in your helper function. Please only use this in actual helpers!

    import { helperContext } from "discourse-common/lib/helpers";

function myHelper(x) {
   let siteSettings = helperContext().siteSettings;
}

  • If you are embedding discourse code via a script tag, you can access site settings via the container:

    <script type="text/discourse-plugin" version="0.1">
  let siteSettings = api.container.lookup('site-settings:main');
</script>

I have not added Deprecation warnings to Discourse.SiteSettings yet because I think right now there would be too many warnings to be actually useful due to all the existing themes and plugins that have not been updated yet. Once a considerable amount of that code has been updated I’ll add the warnings to make them easier to catch.

31 Likes