Skip to content

Latest commit

 

History

History
70 lines (44 loc) · 3.07 KB

0000-template.md

File metadata and controls

70 lines (44 loc) · 3.07 KB
Raw
  • Start Date: 2019-02-13
  • Relevant Teams: Ember.js, Learning
  • RFC PR: #445
  • Tracking: (leave this empty)

Deprecate {{with}}, introduce {{if-let}}

Summary

The {{with}} helper has always had slightly confusing conditional semantics, this was one of the motivators for introducing the easier to understand {{let}} helper. Now that {{let}} exists, the remaining use case for using {{with}} is for its unique conditional semantics. The name {{with}} doesn't accurately represent the helpers behavior, we should rename it to {{if-let}}.

Motivation

The difference between {{let}} and {{with}} is with how they handle conditional arguments. The {{let}} helper's block content is always rendered, regardless of its parameters. In contrast, {{with}} only renders its main block when the first position parameter is truthy. For example:

{{#with "Alex" as |value|}}
  {{value}} is truthy
{{else}}
  The first positional param was falsy
{{/with}}

Will render "[Alex] is truthy".

{{#with false as |value|}}
  {{value}} is truthy
{{else}}
  The first positional param was falsy
{{/with}}

Will render "The first positional param was falsy".

As the naming of {{with}} doesn't give any indication of its behavior, we should deprecate it and introducing the better named {{if-let}} helper. Doing do will make Ember easier to learn and use.

Detailed design

We'll create a new {{if-let}} helper which will have the same behavior to the current {{with}} helper.

We'll create an AST transform in packages/ember-template-compiler which will emit a deprecation warning for all uses of {{with}}. The deprecation warning will be something like:

Using `{{with}}` is deprecated, please use the `{{let}}` or `{{if-let}}` helpers instead.

This new deprecation warning should link to some docs which clearly describe when you should use {{let}} and when you should use {{let-if}}.

How we teach this

We'll add {{if-let}} documentation to the Ember.Templates.helpers API docs. The new documentation should make the unique use cases of {{if-let}} clear.

We'll mentiton the new {{if-let}} helper in an Ember point release blog post.

The deprecation message will link to good docs which describe why {{with}} was deprecated and give clear guidlines on how to migrate to using either {{let}} or {{if-let}}.

Drawbacks

This adds a litte API and documentation churn.

Alternatives

We could leave {{with}} as is. I don't believe that this is a good option as the name {{with}} is far from ideal.

We could deprecate {{with}} and introduce {{if-let}} in an addon instead of Ember core.

Unresolved questions

None