Skip to content

A platform for community discussion. Free, open, simple.

DEV: Replace remaining `.hbs` references with `.gjs` in dev docs (#39706)

David Taylor8b6502966dbf
diff --git a/docs/developer-guides/docs/03-code-internals/01-ember-components.md b/docs/developer-guides/docs/03-code-internals/01-ember-components.md
index 5c0fde79891..7868ba7d4d9 100644
--- a/docs/developer-guides/docs/03-code-internals/01-ember-components.md
+++ b/docs/developer-guides/docs/03-code-internals/01-ember-components.md
@@ -6,7 +6,7 @@ id: ember-components
In the [previous tutorial](https://meta.discourse.org/t/creating-routes-in-discourse-and-showing-data/48827) I showed how to configure both the server and the client side parts of Discourse to respond to a request.
-We now recommend you to read the Ember component documentation: https://guides.emberjs.com/v5.8.0/components/introducing-components/
+We now recommend you to read the Ember component documentation: https://guides.emberjs.com/release/components/introducing-components/
[details="Old tutorial"]
In this tutorial, I’m going to create a new [Ember Component](https://guides.emberjs.com/v2.7.0/components/defining-a-component/) as a way to wrap third party Javascript. This is going to be similar to a [YouTube](https://www.youtube.com/watch?v=S_l_DL8ysQQ) video I made a while back, which you may find informative, only this time it’s specific to Discourse and how we lay out files in our project.
diff --git a/docs/developer-guides/docs/03-code-internals/03-acceptance-tests.md b/docs/developer-guides/docs/03-code-internals/03-acceptance-tests.md
index 4fc0e1a8d69..4882a02fdb8 100644
--- a/docs/developer-guides/docs/03-code-internals/03-acceptance-tests.md
+++ b/docs/developer-guides/docs/03-code-internals/03-acceptance-tests.md
@@ -77,7 +77,7 @@ It’s worth noting that you don’t need to test every little thing in a compon
### Acceptance Tests
-[Acceptance tests](https://guides.emberjs.com/v1.12.0/testing/acceptance/) are often easier to write, and can be more powerful than component tests as they test your application the same way a user would in their browser. I often start with acceptance tests, and then if I am making a complicated component I’ll add tests for it too.
+[Acceptance tests](https://guides.emberjs.com/release/testing/acceptance/) are often easier to write, and can be more powerful than component tests as they test your application the same way a user would in their browser. I often start with acceptance tests, and then if I am making a complicated component I’ll add tests for it too.
Here’s how we can write an acceptance test that will visit our `/admin/snack` route and confirm that the snack was rendered:
diff --git a/docs/developer-guides/docs/03-code-internals/08-ci-with-github-actions.md b/docs/developer-guides/docs/03-code-internals/08-ci-with-github-actions.md
index b3de7a47d25..65869da49e7 100644
--- a/docs/developer-guides/docs/03-code-internals/08-ci-with-github-actions.md
+++ b/docs/developer-guides/docs/03-code-internals/08-ci-with-github-actions.md
@@ -45,7 +45,7 @@ For plugin and components tests to work effectively, its important that you writ
For details on how to write front-end tests with EmberJS see:
- https://meta.discourse.org/t/write-ember-acceptance-and-component-tests-for-discourse/49167
-- https://guides.emberjs.com/v3.28.0/testing/
+- https://guides.emberjs.com/release/testing/
For more details on writing test RSpec tests with Rails see:
diff --git a/docs/developer-guides/docs/03-code-internals/11-dmodal-api.md b/docs/developer-guides/docs/03-code-internals/11-dmodal-api.md
index aea21884d5e..12be6982958 100644
--- a/docs/developer-guides/docs/03-code-internals/11-dmodal-api.md
+++ b/docs/developer-guides/docs/03-code-internals/11-dmodal-api.md
@@ -37,14 +37,16 @@ This example will create a simple Modal like this:
Before introducing any more complexity, it's usually best to wrap up your new Modal in its own Component definition. Let's move the `<DModal>` stuff inside a new `<MyModal />` component
-```hbs
-{{! components/my-modal.hbs }}
-<DModal @title="My Modal" @closeModal={{@closeModal}}>
- Hello world, this is some content in a modal
-</DModal>
+```gjs
+// components/my-modal.gjs
+<template>
+ <DModal @title="My Modal" @closeModal={{@closeModal}}>
+ Hello world, this is some content in a modal
+ </DModal>
+</template>
```
-Introducing a companion `.js` component file will allow you to introduce more complex logic and state.
+Upgrading this `.gjs` file to a class-based component will allow you to introduce more complex logic and state.
To make use of the new component, update the call site to reference it, making sure to pass in a `@closeModal` argument.
@@ -79,7 +81,7 @@ Many modals have some kind of call-to-action. In Discourse these tend to be loca
## Rendering a modal from a non-hbs context
-Ideally, `<DModal>` instances should be rendered from within an Ember handlebars template using the declarative technique demonstrated above. If that's not feasible for your use case (e.g. you need to trigger a modal from Discourse's legacy 'raw-hbs' or 'widget' rendering systems) then it can be done by injecting the `modal` service and calling `modal.show()`.
+Ideally, `<DModal>` instances should be rendered from within an Ember template using the declarative technique demonstrated above. If that's not feasible for your use case, it can be done by injecting the `modal` service and calling `modal.show()`.
Make sure you've wrapped up your modal in its own component as described above. Then, trigger the modal by passing a reference of your component class to `showModal`:
diff --git a/docs/developer-guides/docs/03-code-internals/13-plugin-outlet-connectors.md b/docs/developer-guides/docs/03-code-internals/13-plugin-outlet-connectors.md
index 217d9f3ebc3..92c8a260f42 100644
--- a/docs/developer-guides/docs/03-code-internals/13-plugin-outlet-connectors.md
+++ b/docs/developer-guides/docs/03-code-internals/13-plugin-outlet-connectors.md
@@ -24,41 +24,34 @@ Defining a connector for this kind of 'wrapper' outlet will replace the core imp
For wrapper plugin outlets, you can render the original core implementation using the `{{yield}}` keyword. This can be helpful if you only want to replace the core implementation under certain conditions, or if you would like to wrap it in something.
-# Defining the template
+# Defining the connector
Once you've chosen an outlet, decide on a name for your connector. This needs to be unique across all themes / plugins installed on a given community. e.g. `brand-official-topics`
-In your theme / plugin, define a new handlebars template with a path formatted like this:
+In your theme / plugin, define a new `.gjs` connector with a path formatted like this:
-> :art: `{theme}/javascripts/discourse/connectors/{outlet-name}/{connector-name}.hbs`
+> :art: `{theme}/javascripts/discourse/connectors/{outlet-name}/{connector-name}.gjs`
>
-> :electric_plug: `{plugin}/assets/javascripts/discourse/connectors/{outlet-name}/{connector-name}.hbs`
+> :electric_plug: `{plugin}/assets/javascripts/discourse/connectors/{outlet-name}/{connector-name}.gjs`
-The content of these files will be rendered as an Ember Component. For general information on Ember / Handlebars, check out [the Ember guides](https://guides.emberjs.com/release/components/).
+The content of these files will be rendered as an Ember Component. For general information on Ember and the `.gjs` format, check out [the Ember guides](https://guides.emberjs.com/release/components/).
-For our hypothetical "brand official topics" connector, the template might look like
+For our hypothetical "brand official topics" connector, the file might look like
-```hbs
-<div class="alert alert-info">
- This topic was created by a member of the
- <a href="https://discourse.org/team">Discourse Team</a>
-</div>
+```gjs
+<template>
+ <div class="alert alert-info">
+ This topic was created by a member of the
+ <a href="https://discourse.org/team">Discourse Team</a>
+ </div>
+</template>
```
-Some plugin outlets will automatically wrap your content in an HTML element. The element type is defined by `@connectorTagName` on the `<PluginOutlet>`.
-
[quote]
-[details=ℹ️ Removing the automatic wrapper element]
-Modern plugin outlets (with `defaultGlimmer=true`) render connectors as 'template only glimmer components', which are significantly faster to render and have no wrapper element. Eventually, this will be used everywhere.
-
-To use this new rendering technique on existing plugin outlets, create an adjacent JS file with this content:
+[details=ℹ️ Legacy wrapper elements]
+In the past, connectors were authored using `.hbs` files. When these files are used, the plugin outlet may automatically introduce a wrapper element. The element type is defined by `@connectorTagName` on the `<PluginOutlet />`.
-```js
-import templateOnly from "@ember/component/template-only";
-export default templateOnly();
-```
-
-If you need custom logic as well, see the other ℹ️ sections below.
+Modern `.gjs`-based connectors have full control of their DOM. No automatic wrapper element will be introduced.
[/details]
[/quote]
@@ -74,13 +67,15 @@ This will log the arguments to your browser's developer console. They will appea
In our `topic-above-posts` example, the rendered topic is available under `@outletArgs.model`. So we can add the username of the team member like this:
-```hbs
-<div class="alert alert-info">
- This topic was created by
- {{@outletArgs.model.details.created_by.username}}
- (a member of the
- <a href="https://discourse.org/team">Discourse Team</a>)
-</div>
+```gjs
+<template>
+ <div class="alert alert-info">
+ This topic was created by
+ {{@outletArgs.model.details.created_by.username}}
+ (a member of the
+ <a href="https://discourse.org/team">Discourse Team</a>)
+ </div>
+</template>
```
[quote]
@@ -93,15 +88,13 @@ New plugin outlets (with `@defaultGlimmer={{true}}`) render connectors as 'templ
# Adding more complex logic
-Sometimes, a simple handlebars template is not enough. To add Javascript logic to your connector, you can define a Javascript file adjacent to your handlebars template. This file should export a component definition. This functions just the same as any other component definition, and can include service injections.
+Sometimes, a simple template is not enough. To add Javascript logic to your connector, upgrade your `.gjs` file to export a class-based component. This functions just the same as any other component definition, and can include service injections.
-Defining a component like this will remove the automatic `connectorTagName` wrapper element, so you may want to re-introduce an element of the same type in your hbs file.
+In our `topic-above-posts` example, we may want to render the user differently based on the 'prioritize username in ux' site setting. The `.gjs` file might look something like this:
-In our `topic-above-posts` example, we may want to render the user differently based on the 'prioritize username in ux' site setting. A component definition for that might look something like this:
+`.../connectors/topic-above-posts/brand-official-topic.gjs`:
-`.../connectors/topic-above-posts/brand-official-topic.js`:
-
-```js
+```gjs
import Component from "@glimmer/component";
import { service } from "@ember/service";
@@ -116,23 +109,21 @@ export default class BrandOfficialTopics extends Component {
return user.name;
}
}
-}
-```
-We can then update the template to reference the new getter:
-
-```hbs
-<div class="alert alert-info">
- This topic was created by
- {{this.displayName}}
- (a member of the
- <a href="https://discourse.org/team">Discourse Team</a>)
-</div>
+ <template>
+ <div class="alert alert-info">
+ This topic was created by
+ {{this.displayName}}
+ (a member of the
+ <a href="https://discourse.org/team">Discourse Team</a>)
+ </div>
+ </template>
+}
```
[quote]
[details=ℹ️ Legacy ways to define complex logic]
-In older versions of Discourse, it wasn't possible to export a custom component definition. Instead, you could export an object with `setupComponent(args, component)` and `teardownComponent(component)` functions. This older technique is not officially deprecated yet, but we recommend switching to the new component-export approach going forwards.
+In older versions of Discourse, connectors were defined as a `.hbs` template plus an adjacent `.js` file, and it wasn't possible to export a custom component definition. Instead, you could export an object with `setupComponent(args, component)` and `teardownComponent(component)` functions. These older techniques are not officially deprecated yet, but we recommend switching to a single `.gjs` file with a class-based component going forwards.
[/details]
[/quote]
@@ -140,11 +131,10 @@ In older versions of Discourse, it wasn't possible to export a custom component
If you only want your content to be rendered under certain conditions, it's often enough to wrap your template with a handlebars `{{#if}}` block. If that's not enough, you may want to use the `shouldRender` hook to control whether your connector template is rendered at all.
-Firstly, ensure you have a `.js` connector definition as described above. Then, add a `static shouldRender()` function. Extending our example:
+Firstly, ensure you have a class-based `.gjs` connector as described above. Then, add a `static shouldRender()` function. Extending our example:
-```js
+```gjs
import Component from "@glimmer/component";
-import { getOwner } from "discourse-common/lib/get-owner";
export default class BrandOfficialTopics extends Component {
static shouldRender(outletArgs, helper) {
@@ -152,6 +142,8 @@ export default class BrandOfficialTopics extends Component {
return firstPost.primary_group_name === "team";
}
// ... (any other logic)
+
+ <template>{{! ... }}</template>
}
```
@@ -159,23 +151,6 @@ Now the connector will only be rendered when the first post of the topic was cre
`shouldRender` is evaluated in a Glimmer autotracking context. Future changes to any referenced properties (e.g. `outletArgs`) will cause the function to be re-evaluated.
-[quote]
-[details=ℹ️ shouldRender for templateOnly connectors]
-If you'd like to define a `shouldRender` function without the overhead of a full component, you can do something like this:
-
-```js
-import templateOnly from "@ember/component/template-only";
-
-export default Object.assign(templateOnly(), {
- shouldRender(outletArgs, helper) {
- // Logic here
- },
-});
-```
-
-[/details]
-[/quote]
-
[quote]
[details=ℹ️ Legacy shouldRender implementations]
**Autotracking:** Before Discourse 3.1, `shouldRender` would only be evaluated during initial render. Changes to referenced properties would not cause the function to be re-evaluated.
diff --git a/docs/developer-guides/docs/03-code-internals/15-creating-routes.md b/docs/developer-guides/docs/03-code-internals/15-creating-routes.md
index 9040e4f0507..02a8fc43acf 100644
--- a/docs/developer-guides/docs/03-code-internals/15-creating-routes.md
+++ b/docs/developer-guides/docs/03-code-internals/15-creating-routes.md
@@ -54,16 +54,18 @@ Of course, as you build your feature to add more complexity you likely wouldn’
### The Client Side (Ember.js)
-If you open up your browser and visit `/admin/snack` (without the .json) you’ll see that Discourse says “Oops! That page doesn’t exist.” — that’s because there’s nothing in our front end Ember application to respond to the route. Let’s add a [handlebars template](https://guides.emberjs.com/v1.10.0/templates/handlebars-basics/) to show our snack:
+If you open up your browser and visit `/admin/snack` (without the .json) you’ll see that Discourse says “Oops! That page doesn’t exist.” — that’s because there’s nothing in our front end Ember application to respond to the route. Let’s add a `.gjs` template to show our snack:
-**app/assets/javascripts/admin/templates/snack.hbs**
+**app/assets/javascripts/admin/templates/snack.gjs**
-```hbs
-<h1>{{model.name}}</h1>
+```gjs
+<template>
+ <h1>{{@controller.model.name}}</h1>
-<hr />
+ <hr />
-<p>{{model.description}}</p>
+ <p>{{@controller.model.description}}</p>
+</template>
```
And, like on the Rails API side we need to wire up the route. Open the file `app/assets/javascripts/admin/routes/admin-route-map.js` and look for the `export default function()` method. Add the following line:
@@ -72,7 +74,7 @@ And, like on the Rails API side we need to wire up the route. Open the file `app
this.route("snack");
```
-We have one final thing left to do in Ember land, and that’s to have the Ember application perform an AJAX request to fetch our JSON from the server. Let’s create one last file. This will be an [Ember Route](https://guides.emberjs.com/v1.10.0/routing/specifying-a-routes-model/). Its `model()` function will be called when the route is entered, so we’ll make our `ajax` call in there:
+We have one final thing left to do in Ember land, and that’s to have the Ember application perform an AJAX request to fetch our JSON from the server. Let’s create one last file. This will be an [Ember Route](https://guides.emberjs.com/release/routing/specifying-a-routes-model/). Its `model()` function will be called when the route is entered, so we’ll make our `ajax` call in there:
**app/assets/javascripts/admin/routes/admin-snack.js**
@@ -100,7 +102,7 @@ Now, you can open your browser to `/admin/snack` and you should see the details
- The `admin_snack_controller` returns JSON
-- The Ember application gets the JSON and renders the Handlebars template
+- The Ember application gets the JSON and renders the `.gjs` template
### Where to go from here
diff --git a/docs/developer-guides/docs/03-code-internals/18-overriding-templates.md b/docs/developer-guides/docs/03-code-internals/18-overriding-templates.md
index 9fac1e2d630..6a109549db4 100644
--- a/docs/developer-guides/docs/03-code-internals/18-overriding-templates.md
+++ b/docs/developer-guides/docs/03-code-internals/18-overriding-templates.md
@@ -36,14 +36,6 @@ Overriding route templates (i.e. all the non-component templates under [`templat
:electric_plug: `{plugin}/assets/javascripts/discourse/templates/discovery.hbs`
-## Overriding 'Raw' Templates (`.hbr`)
-
-Discourse's "raw" template system will soon be replaced by regular Ember components. But in the meantime, overriding raw templates works in the same way as Ember templates. For example, to override `topic-list-item.hbr` in core, you could create a file like:
-
-:art: `{theme}/javascripts/discourse/templates/list/topic-list-item.hbr`
-
-:electric_plug: `{plugin}/assets/javascripts/discourse/templates/list/topic-list-item.hbr`
-
## Interaction between multiple themes / plugins
If multiple installed themes/plugins override the same template, the 'winner' is the one with the lowest-numbered ranking in this list:
diff --git a/docs/developer-guides/docs/03-code-internals/21-form-kit.md b/docs/developer-guides/docs/03-code-internals/21-form-kit.md
index d4734a1590a..b4534320a7d 100644
--- a/docs/developer-guides/docs/03-code-internals/21-form-kit.md
+++ b/docs/developer-guides/docs/03-code-internals/21-form-kit.md
@@ -1943,10 +1943,12 @@ FormKit works seamlessly with `<PluginOutlet />`. You can use plugin outlets ins
Then, in your connector, you can use the outlet arguments to add custom fields:
-```hbs title="connectors/above-foo-form/bar-input.hbs"
-<@outletArgs.form.Field @name="bar" @title="Bar" @type="input" as |field|>
- <field.Control />
-</@outletArgs.form.Field>
+```gjs title="connectors/above-foo-form/bar-input.gjs"
+<template>
+ <@outletArgs.form.Field @name="bar" @title="Bar" @type="input" as |field|>
+ <field.Control />
+ </@outletArgs.form.Field>
+</template>
```
## Styling
diff --git a/docs/developer-guides/docs/04-plugins/02-plugin-outlet.md b/docs/developer-guides/docs/04-plugins/02-plugin-outlet.md
index e40863bee3f..20569e2bca7 100644
--- a/docs/developer-guides/docs/04-plugins/02-plugin-outlet.md
+++ b/docs/developer-guides/docs/04-plugins/02-plugin-outlet.md
@@ -10,7 +10,7 @@ Previous tutorial: https://meta.discourse.org/t/developing-discourse-plugins-par
### Getting Started: Handlebars Templates
-Discourse's client application is written using the Ember.js Javascript framework. Ember uses [Handlebars](https://guides.emberjs.com/v4.12.0/components) for all HTML templates. There's a great introduction to the templating language at that link, so definitely read it thoroughly.
+Discourse's client application is written using the Ember.js Javascript framework. Ember uses [Handlebars](https://guides.emberjs.com/release/components) for all HTML templates. There's a great introduction to the templating language at that link, so definitely read it thoroughly.
### The Problem: Adding elements to the Discourse User Interface
@@ -36,7 +36,7 @@ You can also display the plugin outlets on a Discourse site by turning on the [D
### Connecting to a Plugin Outlet
-Once you've found the plugin outlet you want to add to, you have to write a `connector` for it. A connector is really just a handlebars template whose filename includes `connectors/<outlet name>` in it.
+Once you've found the plugin outlet you want to add to, you have to write a `connector` for it. A connector is a `.gjs` component whose filename includes `connectors/<outlet name>` in its path.
For example, if the Discourse handlebars template has:
@@ -44,20 +44,22 @@ For example, if the Discourse handlebars template has:
<PluginOutlet @name="evil-trout" />
```
-Then any handlebars files you create in the `connectors/evil-trout` directory
+Then any `.gjs` files you create in the `connectors/evil-trout` directory
will automatically be appended. So if you created the file:
-`plugins/hello/assets/javascripts/discourse/connectors/evil-trout/hello.hbs`
+`plugins/hello/assets/javascripts/discourse/connectors/evil-trout/hello.gjs`
With the contents:
-```hbs
-<b>Hello World</b>
+```gjs
+<template>
+ <b>Hello World</b>
+</template>
```
Discourse would insert `<b>Hello World</b>` at that point in the template.
-Note that we called the file `hello.hbs` -- The final part of the filename does not matter, but it must be unique across every plugin. It's useful to name it something descriptive of what you are extending it to do. This will make debugging easier in the future.
+Note that we called the file `hello.gjs` -- The final part of the filename does not matter, but it must be unique across every plugin. It's useful to name it something descriptive of what you are extending it to do. This will make debugging easier in the future.
### Troubleshooting
diff --git a/docs/developer-guides/docs/04-plugins/05-admin-interface.md b/docs/developer-guides/docs/04-plugins/05-admin-interface.md
index 24216b84980..0020bf00151 100644
--- a/docs/developer-guides/docs/04-plugins/05-admin-interface.md
+++ b/docs/developer-guides/docs/04-plugins/05-admin-interface.md
@@ -42,23 +42,27 @@ The lines below that set up the server side mapping of routes for our plugin. On
Next, we'll add a template that will be displayed when the user visits the `/admin/plugins/purple-tentacle` path. It will just be a button that shows an animated gif of purple tentacle when the user clicks a button:
-**`assets/javascripts/discourse/templates/admin/plugins-purple-tentacle.hbs`**
-
-```hbs
-{{#if tentacleVisible}}
- <div class="tentacle">
- <img src="https://eviltrout.com/images/tentacle.gif" />
+**`assets/javascripts/discourse/templates/admin/plugins-purple-tentacle.gjs`**
+
+```gjs
+import DButton from "discourse/components/d-button";
+
+<template>
+ {{#if @controller.tentacleVisible}}
+ <div class="tentacle">
+ <img src="https://eviltrout.com/images/tentacle.gif" />
+ </div>
+ {{/if}}
+
+ <div class="buttons">
+ <DButton
+ @label="purple_tentacle.show"
+ @action={{@controller.showTentacle}}
+ @icon="eye"
+ @id="show-tentacle"
+ />
</div>
-{{/if}}
-
-<div class="buttons">
- <DButton
- @label="purple_tentacle.show"
- @action={{action "showTentacle"}}
- @icon="eye"
- @id="show-tentacle"
- />
-</div>
+</template>
```
If you've learned the basics of handlebars the template should be pretty simple to understand. The `<DButton />` is a component in Discourse we use for showing a button with a label and icon.
@@ -77,7 +81,7 @@ export default {
};
```
-A route map is something we added to discourse to make it so that plugins could add routes to the ember application. The syntax within `map()` is very similar to [Ember's router](https://guides.emberjs.com/v3.28.0/routing/defining-your-routes/). In this case our route map is very simple, it just declares one route called `purple-tentacle` under `/admin/plugins`.
+A route map is something we added to discourse to make it so that plugins could add routes to the ember application. The syntax within `map()` is very similar to [Ember's router](https://guides.emberjs.com/release/routing/defining-your-routes/). In this case our route map is very simple, it just declares one route called `purple-tentacle` under `/admin/plugins`.
Finally, let's add our translation strings:
@@ -103,12 +107,12 @@ If you look at your developer console, you should see an error that provides a c
Uncaught Error: Nothing handled the action 'showTentacle'`
```
-Ah yes, the reason is in our handlebars template we are depending on a couple of things:
+Ah yes, the reason is in our template we are depending on a couple of things:
-1. That when the user clicks the button, `showTentacle` will be called.
+1. That when the user clicks the button, `showTentacle` will be called on the controller.
2. `showTentacle` should set the property `tentacleVisible` to `true` so that the image shows up.
-If you haven't read the [Ember Guides on Controllers](https://guides.emberjs.com/v3.28.0/routing/controllers/) now is a good time to do so, because we'll implement a controller for our `purple-tentacle` template that will handle this logic.
+If you haven't read the [Ember Guides on Controllers](https://guides.emberjs.com/release/routing/controllers/) now is a good time to do so, because we'll implement a controller for our `purple-tentacle` template that will handle this logic.
Create the following file:
diff --git a/docs/developer-guides/docs/05-themes-components/02-quick-reference.md b/docs/developer-guides/docs/05-themes-components/02-quick-reference.md
index 9796a6f9c75..1e2caa81b68 100644
--- a/docs/developer-guides/docs/05-themes-components/02-quick-reference.md
+++ b/docs/developer-guides/docs/05-themes-components/02-quick-reference.md
@@ -39,7 +39,7 @@ assets/
stylesheets/
(arbitrarily named files, can be imported from each other, and common/desktop/mobile.scss)
javascripts/
- (arbitrarily named files. Supports .js .hbs and .raw.hbs)
+ (arbitrarily named files. Supports .js, .gjs and .hbs)
```
### about.json <small>[structure info](https://meta.discourse.org/t/structure-of-themes-and-theme-components/60848), [available metadata](https://meta.discourse.org/t/adding-metadata-to-a-theme/119205)</small>
diff --git a/docs/developer-guides/docs/05-themes-components/06-theme-structure.md b/docs/developer-guides/docs/05-themes-components/06-theme-structure.md
index 68e47eacc69..cd37c8af611 100644
--- a/docs/developer-guides/docs/05-themes-components/06-theme-structure.md
+++ b/docs/developer-guides/docs/05-themes-components/06-theme-structure.md
@@ -49,8 +49,8 @@ locales/{locale}.yml
stylesheets/{anything}/{anything}/{anything}.scss
javascripts/{anything}.js
+javascripts/{anything}.gjs
javascripts/{anything}.hbs
-javascripts/{anything}.hbr
assets/{asset_filename}
diff --git a/docs/developer-guides/docs/05-themes-components/14-localizable-strings.md b/docs/developer-guides/docs/05-themes-components/14-localizable-strings.md
index 061aeb77d20..7085172e3e9 100644
--- a/docs/developer-guides/docs/05-themes-components/14-localizable-strings.md
+++ b/docs/developer-guides/docs/05-themes-components/14-localizable-strings.md
@@ -37,25 +37,17 @@ In the background, these translations are stored alongside the core translations
theme_translation.{theme_id}.sidebar.welcome
```
-You should never hardcode the theme_id in your theme code, so there are a few ways to help you access the translations.
-
-In `.hbs` files, you can use the dedicated helper
-
-```hbs
-{{theme-i18n "my_translation_key"}}
-```
-
-Or, if you need to pass the translation key into another component, you can use the `theme-prefix` helper:
-
-```hbs
-<DButton @label={{theme-prefix "my_translation_key"}} />
-```
-
-In Javascript, or in `.gjs` files, you can use the themePrefix function. This is automatically injected, and does not need to be imported:
+You should never hardcode the theme_id in your theme code. To dynamically build the translation key, use the `themePrefix` helper:
```gjs
-const result = I18n.t(themePrefix("my_translation_key"));
+import { i18n } from "discourse-i18n";
+import { themePrefix } from "virtual:theme";
+
+// In JS code:
+const result = i18n(themePrefix("my_translation_key"));
+console.log("From Javascript", result);
+// In a template tag:
<template>{{i18n (themePrefix "blah")}}</template>
```
diff --git a/docs/developer-guides/docs/05-themes-components/25-homepage-content.md b/docs/developer-guides/docs/05-themes-components/25-homepage-content.md
index fee5896022b..1e46cd9e989 100644
--- a/docs/developer-guides/docs/05-themes-components/25-homepage-content.md
+++ b/docs/developer-guides/docs/05-themes-components/25-homepage-content.md
@@ -17,11 +17,11 @@ In your Discourse theme you'll need to setup the following directory structure:
From here we're going to create an Ember component. You can find more about Ember components from their documentation: https://guides.emberjs.com/release/
-But for now this will be a simple component. The component will consist of two files, one containing the logic and another the template.
+But for now this will be a simple component, written as a single `.gjs` file containing both the logic and the template.
-:page_facing_up: `javascripts/discourse/components/custom-homepage-content.js`
+:page_facing_up: `javascripts/discourse/components/custom-homepage-content.gjs`
-```js
+```gjs
import Component from "@glimmer/component";
import { service } from "@ember/service";
import { defaultHomepage } from "discourse/lib/utilities";
@@ -33,22 +33,16 @@ export default class CustomHomepageContent extends Component {
const { currentRouteName } = this.router;
return currentRouteName === `discovery.${defaultHomepage()}`;
}
-}
-```
-
-This creates a `isHomepage` getter, which checks the router service for the `currentRouteName` — if the route name matches your homepage (as dictated by site settings) then it will return `true`
-
-Now we need our template
-:page_facing_up: `javascripts/discourse/components/custom-homepage-content.hbs`
-
-```hbs
-{{#if this.isHomepage}}
- <h1>This is my homepage HTML content</h1>
-{{/if}}
+ <template>
+ {{#if this.isHomepage}}
+ <h1>This is my homepage HTML content</h1>
+ {{/if}}
+ </template>
+}
```
-The template checks the `isHomepage` getter, and will display your content if it's `true`. You can add any HTML you want between the `{{#if}}` blocks.
+This creates a `isHomepage` getter, which checks the router service for the `currentRouteName` — if the route name matches your homepage (as dictated by site settings) then it will return `true`. The template inside `<template>...</template>` checks that getter and only displays your content when it's `true`. You can add any HTML you want between the `{{#if}}` blocks.
Now that our component is created, we need to add it to Discourse somewhere. For this step you'll need to decide which plugin outlet to utilize. These are areas throughout Discourse where we've added a little code for developers to hook into. You can [search Discourse for these on Github](https://github.com/search?q=repo%3Adiscourse%2Fdiscourse+%3CPluginOutlet&type=code), or browse for them using the https://meta.discourse.org/t/plugin-outlet-locations-theme-component/100673/1/.
@@ -56,10 +50,12 @@ For custom homepages, [above-main-container](https://github.com/discourse/discou
We need to create our connector file in the correct directory:
-:page_facing_up: `javascripts/discourse/connectors/above-main-container/custom-homepage-connector.hbs`
+:page_facing_up: `javascripts/discourse/connectors/above-main-container/custom-homepage-connector.gjs`
+
+```gjs
+import CustomHomepageContent from "../../components/custom-homepage-content";
-```hbs
-<CustomHomepageContent />
+<template><CustomHomepageContent /></template>
```
:point_up: and that's all, it just needs a single line calling for your component :tada: