From 9cb8cf51fdacedc2fab7498177be42f20fc6ef23 Mon Sep 17 00:00:00 2001 From: Edward Faulkner Date: Wed, 7 Aug 2024 15:07:52 -0400 Subject: [PATCH] Cleaning up references to action modifier in API docs This removes mentions of the `{{action}}` modifier from API docs text in places other than the docs for `{{action}}` itself (which is deprecated but not removed). --- .../-internals/glimmer/lib/component.ts | 97 +++++++------------ .../-internals/glimmer/lib/helpers/action.ts | 1 + packages/@ember/component/template-only.ts | 27 +----- packages/@ember/object/index.ts | 71 +++----------- packages/@ember/routing/hash-location.ts | 3 - packages/@ember/routing/history-location.ts | 2 +- packages/@ember/routing/none-location.ts | 3 - 7 files changed, 48 insertions(+), 156 deletions(-) diff --git a/packages/@ember/-internals/glimmer/lib/component.ts b/packages/@ember/-internals/glimmer/lib/component.ts index ff20bec1c32..f8f50b16e49 100644 --- a/packages/@ember/-internals/glimmer/lib/component.ts +++ b/packages/@ember/-internals/glimmer/lib/component.ts @@ -205,8 +205,8 @@ declare const SIGNATURE: unique symbol; default for older editions of Ember (pre 3.15). Below is the documentation for Classic components. If you are looking for the - API documentation for Template-only or Glimmer components, it is - [available here](/ember/release/modules/@glimmer%2Fcomponent). + API documentation for Template-only or Glimmer components, it is [available + here](/ember/release/modules/@glimmer%2Fcomponent). ## Defining a Classic Component @@ -404,9 +404,9 @@ declare const SIGNATURE: unique symbol;
``` - If you want to add a class name for a property which evaluates to true and - and a different class name if it evaluates to false, you can pass a binding - like this: + If you want to add a class name for a property which evaluates to true and and + a different class name if it evaluates to false, you can pass a binding like + this: ```app/components/my-widget.js import Component from '@ember/component'; @@ -467,9 +467,9 @@ declare const SIGNATURE: unique symbol; ### Other HTML Attributes The HTML attribute section of a component's tag can be set by providing an - `attributeBindings` property set to an array of property names on the component. - The return value of these properties will be used as the value of the component's - HTML associated attribute: + `attributeBindings` property set to an array of property names on the + component. The return value of these properties will be used as the value of + the component's HTML associated attribute: ```app/components/my-anchor.js import Component from '@ember/component'; @@ -488,8 +488,8 @@ declare const SIGNATURE: unique symbol; ``` - One property can be mapped on to another by placing a ":" between - the source property and the destination property: + One property can be mapped on to another by placing a ":" between the source + property and the destination property: ```app/components/my-anchor.js import Component from '@ember/component'; @@ -522,9 +522,9 @@ declare const SIGNATURE: unique symbol; ``` - Note that the `href` attribute is ultimately set to `http://bing.com`, - despite it having attribute binidng to the `url` property, which was - set to `http://google.com`. + Note that the `href` attribute is ultimately set to `http://bing.com`, despite + it having attribute binidng to the `url` property, which was set to + `http://google.com`. Namespaced attributes (e.g. `xlink:href`) are supported, but have to be mapped, since `:` is not a valid character for properties in Javascript: @@ -662,27 +662,33 @@ declare const SIGNATURE: unique symbol; ## Handling Browser Events - Components can respond to user-initiated events in one of three ways: passing - actions with angle bracket invocation, adding event handler methods to the - component's class, or adding actions to the component's template. + There are two ways to handle user-initiated events: - ### Passing Actions With Angle Bracket Invocation + ### Using the `on` modifier to capture browser events - For one-off events specific to particular instance of a component, it is possible - to pass actions to the component's element using angle bracket invocation syntax. + In a component's template, you can attach an event handler to any element with the `on` modifier: ```handlebars - - - + - ``` - - When the user clicks the button, Ember will invoke the `hello` action, - passing in the current value of `@person.name` as an argument. - - See [Ember.Templates.helpers.action](/ember/release/classes/Ember.Templates.helpers/methods/action?anchor=action). - @class Component @extends Ember.CoreView @uses Ember.TargetActionSupport diff --git a/packages/@ember/-internals/glimmer/lib/helpers/action.ts b/packages/@ember/-internals/glimmer/lib/helpers/action.ts index 015cea88b24..6344eb92915 100644 --- a/packages/@ember/-internals/glimmer/lib/helpers/action.ts +++ b/packages/@ember/-internals/glimmer/lib/helpers/action.ts @@ -275,6 +275,7 @@ export const ACTIONS = new WeakSet(); ``` @method action + @deprecated @for Ember.Templates.helpers @public */ diff --git a/packages/@ember/component/template-only.ts b/packages/@ember/component/template-only.ts index 8c2b923356f..461a5e88b54 100644 --- a/packages/@ember/component/template-only.ts +++ b/packages/@ember/component/template-only.ts @@ -34,32 +34,9 @@ import { type Opaque } from '@ember/-internals/utility-types'; import { templateOnlyComponent as glimmerTemplateOnlyComponent } from '@glimmer/runtime'; /** - * Template-only components have no backing class instance, so this in their + * Template-only components have no backing class instance, so `this` in their * templates is null. This means that you can only reference passed in arguments - * via named argument syntax (e.g. `{{@arg}}`): - * - * ```hbs - * {{!-- - * This does not work, since `this` does not exist - * --}} - * - * - * ``` - * - * Additionally, the mut helper generally can't be used for the same reason: - * - * ```hbs - * {{!-- This does not work --}} - * - * ``` - * - * Since Octane, a template-only component shares a subset of features that are - * available in `@glimmer/component`. Such component can be seamlessly - * "upgraded" to a Glimmer component, when you add a JavaScript file alongside - * the template. + * (e.g. `{{@arg}}`). */ // eslint-disable-next-line @typescript-eslint/no-empty-interface export interface TemplateOnlyComponent extends Opaque {} diff --git a/packages/@ember/object/index.ts b/packages/@ember/object/index.ts index 8eb36b1b938..f4030c8093f 100644 --- a/packages/@ember/object/index.ts +++ b/packages/@ember/object/index.ts @@ -54,31 +54,21 @@ export default EmberObject; ```js import Component from '@ember/component'; - import { action, set } from '@ember/object'; + import { tracked } from '@glimmer/tracking'; + import { action } from '@ember/object'; export default class Tooltip extends Component { + @tracked isShowing = false; + @action toggleShowing() { - set(this, 'isShowing', !this.isShowing); + this.isShowing = !this.isShowing; } } ``` ```hbs - - - {{#if isShowing}} -
- I'm a tooltip! -
- {{/if}} - ``` - - Decorated actions also interop with the string style template actions: - - ```hbs - - + {{#if isShowing}}
@@ -90,27 +80,10 @@ export default EmberObject; It also binds the function directly to the instance, so it can be used in any context and will correctly refer to the class it came from: - ```hbs - - - - {{#if isShowing}} -
- I'm a tooltip! -
- {{/if}} - ``` - - This can also be used in JavaScript code directly: - ```js import Component from '@ember/component'; - import { action, set } from '@ember/object'; + import { tracked } from '@glimmer/tracking'; + import { action } from '@ember/object'; export default class Tooltip extends Component { constructor() { @@ -121,37 +94,15 @@ export default EmberObject; document.addEventListener('click', this.toggleShowing); } + @tracked isShowing = false; + @action toggleShowing() { - set(this, 'isShowing', !this.isShowing); + this.isShowing = !this.isShowing; } } ``` - This is considered best practice, since it means that methods will be bound - correctly no matter where they are used. By contrast, the `{{action}}` helper - and modifier can also be used to bind context, but it will be required for - every usage of the method: - - ```hbs - - - - {{#if isShowing}} -
- I'm a tooltip! -
- {{/if}} - ``` - - They also do not have equivalents in JavaScript directly, so they cannot be - used for other situations where binding would be useful. - @public @method action @for @ember/object diff --git a/packages/@ember/routing/hash-location.ts b/packages/@ember/routing/hash-location.ts index ce86f98d3fa..2305e3d964c 100644 --- a/packages/@ember/routing/hash-location.ts +++ b/packages/@ember/routing/hash-location.ts @@ -146,9 +146,6 @@ export default class HashLocation extends EmberObject implements EmberLocation { Given a URL, formats it to be placed into the page as part of an element's `href` attribute. - This is used, for example, when using the {{action}} helper - to generate a URL based on an event. - @private @method formatURL @param url {String} diff --git a/packages/@ember/routing/history-location.ts b/packages/@ember/routing/history-location.ts index 8c819e36e82..709c344a03f 100644 --- a/packages/@ember/routing/history-location.ts +++ b/packages/@ember/routing/history-location.ts @@ -246,7 +246,7 @@ export default class HistoryLocation extends EmberObject implements EmberLocatio } /** - Used when using `{{action}}` helper. The url is always appended to the rootURL. + Formats url to be placed into href attribute. @private @method formatURL diff --git a/packages/@ember/routing/none-location.ts b/packages/@ember/routing/none-location.ts index 17f950adec8..eba122bad9b 100644 --- a/packages/@ember/routing/none-location.ts +++ b/packages/@ember/routing/none-location.ts @@ -110,9 +110,6 @@ export default class NoneLocation extends EmberObject implements EmberLocation { Given a URL, formats it to be placed into the page as part of an element's `href` attribute. - This is used, for example, when using the {{action}} helper - to generate a URL based on an event. - @private @method formatURL @param {String} url