Update outdated references to <script>-based js/hbs themes (#64)

Author: davidtaylorhq

docs/03-code-internals/12-pluginapi.md

@@ -1,24 +1,23 @@
 ---
-title: Using the PluginAPI in Site Customizations
-short_title: PluginAPI
+title: Using the JS API
+short_title: JS API
 id: pluginapi
 ---
 
-Using the [client side Plugin API](https://meta.discourse.org/t/a-new-versioned-api-for-client-side-plugins/40051) is the safest way to build Discourse Javascript plugins and themes while respecting backwards compatibility.
+Discourse's JavaScript API allows themes and plugins to make extensive customizations to the user experience. The simplest way to use it is to create a new theme from the admin panel, click "Edit Code", and then head to the JS tab.
 
-However, some people have made simple customizations using the Admin > Customization > CSS/HTML and dropping some Javascript into a `<script>` tag. Previously, it was very difficult to use the `withPluginApi` to access objects using the Discourse container.
+For file-based themes, the API can be used by creating a file in the `api-initializers` directory. For theme's that's `{theme}/javascripts/api-initializers/init-theme.gjs`, and for plugins, it's `{plugin}/assets/javascripts/discourse/api-initializers/init-plugin.js`. The content should be:
 
-In the latest tests-passed build of Discourse I've added the ability to use the pluginAPI via a site customization.
+```gjs
+import { apiInitializer } from "discourse/lib/api";
 
-To use it, you just need to add some attributes to a script tag in your `</HEAD>` customization:
-
-```html
-<script type="text/discourse-plugin" version="0.1">
-  // you can use the `api` object here!
-  api.decorateCooked($elem => $elem.css({ backgroundColor: 'yellow' }));
-</script>
+export default apiInitializer((api) => {
+  // Your code here
+});
 ```
 
-When you save the customization, Discourse will transpile the ES2015 code within the tag so you can use the latest Javascript features. Additionally, it wraps the code in an initializer and runs it through `withPluginApi` so you don't have to bother with that. Just specify the version of the `api` object you want and Discourse will give it to you, providing safe backwards compatibility.
+All the available APIs are listed in the [`plugin-api.gjs` source code](https://github.com/discourse/discourse/blob/main/app/assets/javascripts/discourse/app/lib/plugin-api.gjs) in Discourse core, along with a short description and examples.
+
+For a full tuturial, including examples of JS API usage, check out:
 
-If the compilation of the ES2015 fails for some reason, when you view source on your page you'll see the error in a `<script type='text/discourse-js-error'>` block. Fix what it says and re-save your customization and you'll be good to go.
+https://meta.discourse.org/t/theme-developer-tutorial-1-introduction/357796

docs/03-code-internals/13-plugin-outlet-connectors.md

@@ -62,22 +62,6 @@ If you need custom logic as well, see the other ℹ️ sections below.
 [/details]
 [/quote]
 
-[quote]
-[details=ℹ️ Defining template via theme </head>]
-We recommend using a dedicated file for your connector template. However, Discourse does still support defining a template via a `<script>` tag in your theme's `</head>` section. In that case, a definition would look like
-
-```html
-<script
-  type="text/x-handlebars"
-  data-template-name="/connectors/{outlet-name}/{connector-name}"
->
-  Template content here
-</script>
-```
-
-[/details]
-[/quote]
-
 # Using outlet arguments
 
 Plugin Outlets provide information about the surrounding context via `@outletArgs`. The arguments passed to each outlet vary. An easy way to view the arguments is to add this to your template:

docs/05-themes-components/02-quick-reference.md

@@ -70,38 +70,19 @@ javascripts/
 
 ### Javascript <small>[read more](https://meta.discourse.org/t/using-the-pluginapi-in-site-customizations/41281)</small>
 
-```html
-<!-- Define in </head> section of theme-->
-<script type="text/discourse-plugin" version="0.8">
-  console.log("I am ", api.getCurrentUser().username);
-</script>
+```gjs
+// {theme}/javascripts/api-initializers/init-theme.gjs
+import { apiInitializer } from "discourse/lib/api";
+
+export default apiInitializer((api) => {
+  // Your code here
+});
 ```
 
 [:link: JS Plugin API](https://github.com/discourse/discourse/blob/main/app/assets/javascripts/discourse/app/lib/plugin-api.gjs)
 
 [:link: Multi-file Javascript](https://meta.discourse.org/t/splitting-up-theme-javascript-into-multiple-files/119369)
 
-### Templates <small>[read more](https://meta.discourse.org/t/adding-plugin-outlets-using-a-theme/32727)</small>
-
-```html
-<!-- Define in </head> section of theme-->
-
-<!-- Plugin Outlet -->
-<script
-  type="text/x-handlebars"
-  data-template-name="/connectors/below-footer/arbitrary-unique-name"
->
-  This is displayed below the footer
-</script>
-
-<!-- Override Core -->
-<script type="text/x-handlebars" data-template-name="list/topic-list-item.raw">
-  This used to be a topic list item
-</script>
-```
-
-[:link: Locate outlets](https://meta.discourse.org/t/plugin-outlet-locations-theme-component/100673)
-
 ### Settings <small>[read more](https://meta.discourse.org/t/how-to-add-settings-to-your-discourse-theme/82557)</small>
 
 `settings.yml`:
@@ -121,10 +102,10 @@ Access from JavaScript:
 console.log(settings.fruit);
 ```
 
-Access from templates:
+Access from gjs templates:
 
-```hbs
-{{theme-setting "fruit"}}
+```gjs
+<template>{{settings.fruit}}</template>
 ```
 
 Access from scss:
@@ -152,12 +133,17 @@ en:
 Access from JavaScript:
 
 ```js
-I18n.t(themePrefix("my_translation_key"));
+import { i18n } from "discourse-i18n";
+i18n(themePrefix("my_translation_key"));
 ```
 
-Access from templates:
+Access from gjs templates:
+
+```gjs
+import { i18n } from "discourse-i18n";
 
-```hbs
-{{theme-i18n "my_translation_key"}}
-{{d-button label=(theme-prefix "my_translation_key")}}
+<template>
+  {{i18n (themePrefix "my_translation_key")}}
+  <DButton @label={{theme-prefix "my_translation_key"}} />
+</template>
 ```

docs/05-themes-components/07-multiple-js-files.md

@@ -6,52 +6,40 @@ id: multiple-js-files
 
 Complex theme javascript can be split into multiple files, to keep things nicely organised.
 
-To use this functionality, simply add files to the `/javascripts` folder in your theme directory. Currently, these files can not be edited from the Discourse UI, so you must use the [Theme CLI](https://meta.discourse.org/t/discourse-theme-cli-console-app-to-help-you-build-themes/82950) or [source the theme from git](https://meta.discourse.org/t/how-to-source-a-theme-from-a-private-git-repository/82584).
+To use this functionality, simply add files to the `/javascripts` folder in your theme directory. These files can not be edited from the Discourse UI, so you must use the [Theme CLI](https://meta.discourse.org/t/discourse-theme-cli-console-app-to-help-you-build-themes/82950) or [source the theme from git](https://meta.discourse.org/t/how-to-source-a-theme-from-a-private-git-repository/82584).
 
 Javascript files are treated exactly the same as they are in core/plugins, so you should follow the same file/folder structure. Theme files are loaded after core/plugins, so if the filenames match, the theme version will take precedence.
 
 ---
 
 As an example, you can now accomplish https://meta.discourse.org/t/adding-to-plugin-outlets-using-a-theme/32727 by adding a single file to your theme:
 
-**`/javascripts/my-theme/connectors/discovery-list-container-top/add-header-message.hbs`**
+**`/javascripts/my-theme/connectors/discovery-list-container-top/add-header-message.gjs`**
 
 ```hbs
-Welcome
-{{currentUser.username}}. Please visit
-<a class="nav-link" href="http://google.com" target="_blank">My Site</a>
-```
-
-To add a connector class, add another file
-
-**`/javascripts/my-theme/connectors/discovery-list-container-top/add-header-message.js`**
-
-```js
-import { isAppleDevice } from "discourse/lib/utilities";
-
-export default {
-  shouldRender(args, component) {
-    return isAppleDevice();
-  },
-};
+import Component from "@glimmer/component"; import { service } from
+"@ember/service"; export default class HeaderMessage extends Component {
+@service currentUser;
+
+<template>
+  Welcome
+  {{this.currentUser.username}}
+</template>
+}
 ```
 
 ---
 
-If you want to simply move some existing theme javascript out of a `<script type="text/discourse-plugin"` block, you should wrap it in an initializer like this:
+To use the JS API, create an initializer:
 
-**`/javascripts/my-theme/initializers/initialize-stuff.js`**
+**`/javascripts/discourse/api-initializers/init-theme.gjs`**
 
 ```js
-import { withPluginApi } from "discourse/lib/plugin-api";
-export default {
-  name: "my-initializer",
-  initialize() {
-    withPluginApi("0.8.7", (api) => {
-      // Do something with the API here
-    });
-  },
-};
+import { apiInitializer } from "discourse/lib/api";
+
+export default apiInitializer((api) => {
+  // Your code here
+});
 ```
 
 ---

docs/05-themes-components/09-theme-settings.md

@@ -205,14 +205,19 @@ If your user tries to enter a value that's not within the allowed range, they'll
 
 <h3 id='heading--settings-js-css'>Access to settings in your JS/CSS/Handlebars</h3>
 
-To have access to setting in your theme JS code, the `script` tag that wraps your code must have a `type="text/discourse-plugin"` attribute as well as `version` specified like so:
+Theme settings are made available globally as a `settings` variable in theme JavaScript files. For example:
 
-```hbs
-<script type="text/discourse-plugin" version="0.8.13">
-  alert(settings.integer_setting + 1); console.log(settings.string_setting);
-</script>
+```gjs
+// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
+import { apiInitializer } from "discourse/lib/api";
+
+export default apiInitializer((api) => {
+  console.log("settings are", settings);
+});
 ```
 
+This `settings` object is also usable as normal within `.gjs` `<template>` tags.
+
 In CSS, you'll get a variable created for every setting of your theme and each variable will have the same name as the setting it represents.
 
 So if you had a float setting called `global_font_size` and a string setting called `site_background`, you could do something like this in your theme CSS:
@@ -224,137 +229,6 @@ html {
 }
 ```
 
-Similarly, theme settings are available in handlebars templates that you define in your theme whether you're overriding a core template, or creating your own. For example if you have something like this in your theme:
-
-```hbs
-<script type="text/x-handlebars" data-template-name="my-template">
-  <h1>{{theme-setting "your_setting_key"}}</h1>
-</script>
-```
-
-It'll render with your setting value.
-
-You may want to use a boolean setting as a condition for an `{{#if}}` block in your template, this is how you can do that:
-
-```hbs
-<script type="text/x-handlebars" data-template-name="my-template">
-  {{#if (theme-setting "my_boolean_setting")}}
-    <h1>Value is true!</h1>
-  {{else}}
-    <h1>Value is false!</h1>
-  {{/if}}
-</script>
-```
-
----
-
-If you have a question about this or there is something unclear, feel free to ask - I'll try to answer/clarify as much as I can. Also this is a wiki post, so contributions to improve this are greatly appreciated! :sunflower:
-
----
-
-## :question: Frequently Asked Questions
-
-[quote="p0fi, post:27, topic:82557"]
-Can I combine javascript and handlebars in there somehow too? I would like to get the current year using javascript to put it in the string too.
-[/quote]
-
-Not directly; you’ll need to use the `registerConnectorClass` plugin API to add an attribute that has the current year to the connector instance behind your connector template. See an [example](https://github.com/OsamaSayegh/discourse-tab-bar-theme/blob/c05adce3274ffee821eadac8f81ffb54b85e5045/mobile/head_tag.html#L91) from my theme.
-
-My theme sets the `tabs` attributes which is then referenced in the Handlebars template at the end of the file. You can do something like `this.set("year", compute current year here)` in the `setupComponent` method and then in your template you can access the year value like this `{{year}}`.
-
-[quote="Jay Pfaffman, post:29, topic:82557, full:true, username:pfaffman"]
-What if I have a setting like
-
-```yaml
-my_text:
-  type: string
-  default: "<a href='https://google.com/'>Google!</a>"
-```
-
-and then want to do
-
-```hbs
-<script type="text/x-handlebars" data-template-name="my-template">
-  {{theme-setting "my_text"}}
-</script>
-```
-
-It doesn’t give me my link but instead displays all the HTML. Is there a way to fix that?
-[/quote]
-
-You can use the Ember's `html-safe` helper here and it will render the HTML instead of the text.
-
-```hbs
-{{html-safe (theme-setting "my_text")}}
-```
-
-[quote="Alex P., post:33, topic:82557, full:true, username:Alex_P"]
-[quote]
-the `script` tag that wraps your code must have a `type="text/discourse-plugin"` attribute as well as `version` specified like so:
-[/quote]
-
-What’s that version value? Is it supposed to be the version of my plugin?
-[/quote]
-
-No, that’s the version of our [Plugin API](https://github.com/discourse/discourse/blob/e6b5b6eae348aa0f6148589a07e9ade0f08bae59/app/assets/javascripts/discourse/app/lib/plugin-api.js#L112)
-
-We bump that every time a new method is added to the API so that themes / plugins which relay on methods that were recently added to the plugin API don’t end up breaking sites which haven’t been updated.
-
-You don’t really need to worry about this a lot because:
-
-1. We don’t add new methods very often
-2. Most sites that use Discourse are updated very frequently.
-
-[quote="Marcus Baw, post:44, topic:82557, username:pacharanero"]
-Is it possible to access the theme settings from within the Ruby code as opposed to the JS?
-[/quote]
-
-To access theme settings in Ruby you need to call the `settings` method on a theme like so: `Theme.find(<id>).settings`. It will return an array which contains a [`ThemeSettingsManager`](https://github.com/discourse/discourse/blob/66151d805609839a333500248149da4cc5e9cae3/lib/theme_settings_manager.rb#L1) instance for each setting and from it you can get the setting name and value by calling the `name` and `value` methods respectively.
-
-[quote="Heddson, post:47, topic:82557"]
-Could things break if I don’t prefix my setting names with something like my theme name?
-[/quote]
-
-In JavaScript and hbs templates, there is no way this can happen. The `settings` variable that you use to access your theme settings is local to your theme and only contains your theme settings. In hbs templates, the settings of each theme are namespaced with their theme’s primary key in the database, so conflicts are impossible.
-
-[quote="Manuel, post:50, topic:82557, full:true, username:nolo"]
-When I use a list in settings, I get the values as:
-
-```
-value1,value2,value3|value1,value2,value3
-```
-
-Is it possible to modify this output by declaring a different list_type? I’d like to use values from a list in Scss, but I think I could only de-structure the list if the output is formatted as
-
-```
-value1 value2 value3,
-value1 value2 value3;
-```
-
-[/quote]
-
-You can create custom SCSS functions to transform settings values into whatever format you want. E.g., in your case I think all you need is a string replace function that replaces commas with whitespace and pipes with commas? Here is an implementation of a string replace function in SCSS: [Str-replace Function | CSS-Tricks](https://css-tricks.com/snippets/sass/str-replace-function/)
-
-[quote="Jonathan Shaw, post:60, topic:82557, full:true, username:JonathanShaw"]
-Is it possible to access settings from another theme or component. e.g. if you have the category icons theme component installed, can you access information about the icons defined in its settings in a different custom theme component?
-[/quote]
-
-There is not a supported way to access the settings of another theme/component.
-
-[quote="Alex, post:62, topic:82557, username:daemon"]
-Is it possible to divide the settings into sections, e.g. with horizontal lines in between?
-
-And is it possible to integrate some kind of heading?
-[/quote]
-
-No, neither of those things are possible at the moment.
-
----
-
 ## :link: Related Topics
 
 - https://meta.discourse.org/t/developer-s-guide-to-discourse-themes/93648
-
----
-
-_Last Reviewed by @keegan on [date=2022-10-06 timezone="America/Vancouver"]_