From 50ed66ec385e87b0bbc8e1be9dcdfac5e0960c03 Mon Sep 17 00:00:00 2001 From: Chris Garrett Date: Tue, 2 Feb 2021 14:03:09 -0800 Subject: [PATCH] Add deprecation guides for template transforms Adds the deprecation guides for template transformations: - [RFC 689](https://github.com/emberjs/rfcs/blob/master/text/0689-deprecate-has-block.md) - [RFC 690](https://github.com/emberjs/rfcs/blob/master/text/0690-deprecate-attrs-in-templates.md) - [RFC 691](https://github.com/emberjs/rfcs/blob/master/text/0691-deprecate-class-binding-and-class-name-bindings.md) --- content/ember/v3/attrs-arg-access.md | 27 ++++++ ...ing-and-class-name-bindings-in-template.md | 86 +++++++++++++++++++ .../v3/has-block-and-has-block-params.md | 72 ++++++++++++++++ 3 files changed, 185 insertions(+) create mode 100644 content/ember/v3/attrs-arg-access.md create mode 100644 content/ember/v3/class-binding-and-class-name-bindings-in-template.md create mode 100644 content/ember/v3/has-block-and-has-block-params.md diff --git a/content/ember/v3/attrs-arg-access.md b/content/ember/v3/attrs-arg-access.md new file mode 100644 index 00000000..2eab57e2 --- /dev/null +++ b/content/ember/v3/attrs-arg-access.md @@ -0,0 +1,27 @@ +--- +id: attrs-arg-access +title: "Accessing named args via {{attrs}}" +until: '4.0.0' +since: 'Upcoming Features' +--- + +The `{{attrs}}` object was an alternative way to reference named arguments in +templates that was introduced prior to named arguments syntax being finalized. +References to properties on `{{attrs}}` can be converted directly to named +argument syntax. + +Before: + +```hbs +{{attrs.foo}} +{{this.attrs.foo.bar}} +{{deeply (nested attrs.foobar.baz)}} +``` + +After: + +```hbs + {{@foo}} + {{@foo.bar}} + {{deeply (nested @foobar.baz)}} + ``` diff --git a/content/ember/v3/class-binding-and-class-name-bindings-in-template.md b/content/ember/v3/class-binding-and-class-name-bindings-in-template.md new file mode 100644 index 00000000..42d07995 --- /dev/null +++ b/content/ember/v3/class-binding-and-class-name-bindings-in-template.md @@ -0,0 +1,86 @@ +--- +id: class-binding-and-class-name-bindings-in-templates +title: "classBinding and classNameBindings as args in templates" +until: '4.0.0' +since: 'Upcoming Features' +--- + +`classBinding` and `classNameBindings` can currently be passed as arguments to +components that are invoked with curly invocation. These allow users to +conditionally bind values to the `class` argument using a microsyntax similar to +the one that can be defined in a Classic component's class body: + +```js +import Component from '@ember/component'; + +export default Component.extend({ + classNameBindings: ['isValid:is-valid:is-invalid'] +}); +``` + +```hbs +{{my-component classNameBindings="isValid:is-valid:is-invalid"}} +``` + +Each binding is a triplet separated by colons. The first identifier in the +triplet is the value that the class name should be bound to, the second +identifier is the name of the class to add if the bound value is truthy, and the +third value is the name to bind if the value is falsy. + +These bindings are additive - they add to the existing bindings that are on the +class, rather than replacing them. Multiple bindings can also be passed in by +separating them with a space: + +```hbs +{{my-component + classBinding="foo:bar" + classNameBindings="some.boundProperty isValid:is-valid:is-invalid" +}} +``` + + +These bindings can be converted into passing a concatenated string into the +class argument of the component, using inline `if` to reproduce the same +behavior. This is most conveniently done by converting the component to use +angle-bracket invocation at the same time. + +Before: + +```hbs +{{my-component + classBinding="foo:bar" + classNameBindings="some.boundProperty isValid:is-valid:is-invalid" +}} +``` + +After: + +```hbs + +``` + +Note that we are passing in the `class` attribute, not the `class` argument. In +most cases, this should work exactly the same as previously. If you referenced +the `class` argument inside of your component, however, you will need to pass +`@class` instead. + +If you do not want to convert to angle bracket syntax for some reason, the same +thing can be accomplished with the `(concat)` helper in curly invocation. + +```hbs +{{my-component + class=(concat + (if this.foo "bar") + " " + (if this.some.boundProperty "bound-property") + " " + (if this.isValid "is-valid" "is-invalid") + ) +}} +``` diff --git a/content/ember/v3/has-block-and-has-block-params.md b/content/ember/v3/has-block-and-has-block-params.md new file mode 100644 index 00000000..a3e69115 --- /dev/null +++ b/content/ember/v3/has-block-and-has-block-params.md @@ -0,0 +1,72 @@ +--- +id: has-block-and-has-block-params +title: "{{hasBlock}} and {{hasBlockParams}}" +until: '4.0.0' +since: 'Upcoming Features' +--- + +#### `{{hasBlock}}` + +The `{{hasBlock}}` property is true if the component was given a default block, +and false otherwise. To transition away from it, you can use the `(has-block)` +helper instead. + +```hbs +{{hasBlock}} + +{{! becomes }} +{{has-block}} +``` + +Unlike `{{hasBlock}}`, the `(has-block)` helper must be called, so in nested +positions you will need to add parentheses around it: + +```hbs +{{#if hasBlock}} + +{{/if}} + + +{{! becomes }} +{{#if (has-block)}} + +{{/if}} +``` + +You may optionally pass a name to `(has-block)`, the name of the block to check. +The name corresponding to the block that `{{hasBlock}}` represents is "default". +Calling `(has-block)` without any arguments is equivalent to calling +`(has-block "default")`. + +#### `{{hasBlockParams}}` + +The `{{hasBlockParams}}` property is true if the component was given a default block +that accepts block params, and false otherwise. To transition away from it, you can +use the `(has-block-params)` helper instead. + +```hbs +{{hasBlockParams}} + +{{! becomes }} +{{has-block-params}} +``` + +Unlike `{{hasBlockParams}}`, the `(has-block-params)` helper must be called, so in nested +positions you will need to add parentheses around it: + +```hbs +{{#if hasBlockParams}} + +{{/if}} + + +{{! becomes }} +{{#if (has-block-params)}} + +{{/if}} +``` + +You may optionally pass a name to `(has-block-params)`, the name of the block to check. +The name corresponding to the block that `{{hasBlockParams}}` represents is "default". +Calling `(has-block-params)` without any arguments is equivalent to calling +`(has-block-params "default")`.