From 332cd5ccdaf860282c3af94ba7e14bf63fb92abd Mon Sep 17 00:00:00 2001 From: Miguel Camba Date: Sun, 8 Dec 2019 21:59:09 +0100 Subject: [PATCH 1/6] Adding Numeric Comparison Operators to Templates --- text/0000-add-numeric-comparison-operators.md | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 text/0000-add-numeric-comparison-operators.md diff --git a/text/0000-add-numeric-comparison-operators.md b/text/0000-add-numeric-comparison-operators.md new file mode 100644 index 0000000000..59975bfcb8 --- /dev/null +++ b/text/0000-add-numeric-comparison-operators.md @@ -0,0 +1,66 @@ +- Start Date: 2019-12-08 +- Relevant Team(s): (fill this in with the [team(s)](README.md#relevant-teams) to which this RFC applies) +- RFC PR: https://github.com/emberjs/rfcs/pull/561 +- Tracking: (leave this empty) + +# Adding Numeric Comparison Operators to Templates + +## Summary + +Add new built-in template `{{lt}}` and `{{gt}}` helpers to perform basic numeric comparison operations in templates, similar to those included in `ember-truth-helpers`. + +This RFC is a subset of the changes proposed in #388. + +## Motivation + +It is a very common need in any sufficiently complex Ember app to perform some numeric comparison operations and often the most convenient place to do it is right in the templates. +Because of that, [ember-truth-helpers](https://github.com/jmurphyau/ember-truth-helpers) is one of the most installed addons out there, either directly by apps or indirectly by +other addons that those apps consume. + +The fact that `ember-truth-helpers` is so popular is a good signal that this it is filling a perceived gap in Ember's functionality. + +A second reason is that it might help make Ember more approachable to newcomers that have some experience in other frameworks. +Most if not all web frameworks have some way of comparing numbers in the templates and it's surprising that Ember requires an third party package to perform +even the most basic operations. + + +## Detailed design + +Add `{{lt}}` and `{{gt}}` helpers. + +#### `{{lt}}` +Binary operation. Throws an error if not called with exactly two arguments. +Equivalent of < +This is identical to the `{{lt}}` helper in `ember-truth-helpers` + +#### `{{gt}}` +Binary operation. Throws an error if not called with exactly two arguments. +Equivalent of > +This is identical to the `{{gt}}` helper in `ember-truth-helpers`, except for the name. + +This RFC intentionally leaves the implementation details unspecified, those could be implemented in Glimmer VM or +in a higher level in Ember itself. + +## How we teach this + +The introduction of these helpers does not impact the current mental model for Ember applications. + +In addition to API and Guides documentation with illustrative examples of usage of the various helpers. + +## Drawbacks + +Adding new helpers increases the surface area of the framework and the code the core team commits to support long term. + +## Alternatives + +One alternative path is don't do anything and let users continue to define their own helpers (or install `ember-truth-helpers`). + +## Unresolved questions + +- The proposed version of those helpers mimic the behavior of the `<` and `>` operators in Javascript. While this is the + least surprising thing to do, one could argue that we could add extra logic to protect users from the usual pitfalls + and edge cases of those operators, **like throwing exceptions if any of the values is `NaN` or a value other than a number**. +- We must decide if it's worth adding `{{lte}}` and `{{gte}}` helpers, equivalent to `<=` and `>=` respectively. +- `BigInt` support. The BigInt proposal has recently reached stage 4 and will be part of ECMASCRIPT 2020. According to + the spec comparisons using `<` and `>` work as expected and I don't anticipate problems, but ensure we explicitly + test for those numbers. \ No newline at end of file From 14dd924a9356ca3decb0b63c1f39b626f15d8f24 Mon Sep 17 00:00:00 2001 From: Chris Garrett Date: Thu, 28 Jan 2021 15:10:38 -0800 Subject: [PATCH 2/6] update filename and frontmatter --- ... => 0561-add-numeric-comparison-operators.md} | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) rename text/{0000-add-numeric-comparison-operators.md => 0561-add-numeric-comparison-operators.md} (92%) diff --git a/text/0000-add-numeric-comparison-operators.md b/text/0561-add-numeric-comparison-operators.md similarity index 92% rename from text/0000-add-numeric-comparison-operators.md rename to text/0561-add-numeric-comparison-operators.md index 59975bfcb8..e98c35f544 100644 --- a/text/0000-add-numeric-comparison-operators.md +++ b/text/0561-add-numeric-comparison-operators.md @@ -1,7 +1,13 @@ -- Start Date: 2019-12-08 -- Relevant Team(s): (fill this in with the [team(s)](README.md#relevant-teams) to which this RFC applies) -- RFC PR: https://github.com/emberjs/rfcs/pull/561 -- Tracking: (leave this empty) +--- +Stage: Accepted +Start Date: 2019-12-08 +Release Date: Unreleased +Release Versions: + ember-source: vX.Y.Z + ember-data: vX.Y.Z +Relevant Team(s): Ember.js +RFC PR: https://github.com/emberjs/rfcs/pull/561 +--- # Adding Numeric Comparison Operators to Templates @@ -63,4 +69,4 @@ One alternative path is don't do anything and let users continue to define their - We must decide if it's worth adding `{{lte}}` and `{{gte}}` helpers, equivalent to `<=` and `>=` respectively. - `BigInt` support. The BigInt proposal has recently reached stage 4 and will be part of ECMASCRIPT 2020. According to the spec comparisons using `<` and `>` work as expected and I don't anticipate problems, but ensure we explicitly - test for those numbers. \ No newline at end of file + test for those numbers. From 481b64309cbdc634b769d7485b3d4a1a43385ade Mon Sep 17 00:00:00 2001 From: Chris Garrett Date: Thu, 28 Jan 2021 15:14:04 -0800 Subject: [PATCH 3/6] add gte and lte, change to keywords --- text/0561-add-numeric-comparison-operators.md | 21 ++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/text/0561-add-numeric-comparison-operators.md b/text/0561-add-numeric-comparison-operators.md index e98c35f544..38375171a2 100644 --- a/text/0561-add-numeric-comparison-operators.md +++ b/text/0561-add-numeric-comparison-operators.md @@ -9,11 +9,11 @@ Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/561 --- -# Adding Numeric Comparison Operators to Templates +# Adding Comparison Operators to Templates ## Summary -Add new built-in template `{{lt}}` and `{{gt}}` helpers to perform basic numeric comparison operations in templates, similar to those included in `ember-truth-helpers`. +Add new built-in template `{{lt}}`, `{{lte}}`, `{{gt}}`, and `{{gte}}` keywords to perform basic numeric comparison operations in templates, similar to those included in `ember-truth-helpers`. This RFC is a subset of the changes proposed in #388. @@ -32,20 +32,31 @@ even the most basic operations. ## Detailed design -Add `{{lt}}` and `{{gt}}` helpers. +The new comparison operators will be made keywords, so they are easily accessible in current and future templates without needing to be imported. #### `{{lt}}` + Binary operation. Throws an error if not called with exactly two arguments. Equivalent of < This is identical to the `{{lt}}` helper in `ember-truth-helpers` +#### `{{lte}}` + +Binary operation. Throws an error if not called with exactly two arguments. +Equivalent of <= +This is identical to the `{{lte}}` helper in `ember-truth-helpers` + #### `{{gt}}` + Binary operation. Throws an error if not called with exactly two arguments. Equivalent of > This is identical to the `{{gt}}` helper in `ember-truth-helpers`, except for the name. -This RFC intentionally leaves the implementation details unspecified, those could be implemented in Glimmer VM or -in a higher level in Ember itself. +#### `{{gte}}` + +Binary operation. Throws an error if not called with exactly two arguments. +Equivalent of >= +This is identical to the `{{gte}}` helper in `ember-truth-helpers`, except for the name. ## How we teach this From eea283006396b50618a15a6af15f0dc3e1d4021d Mon Sep 17 00:00:00 2001 From: Chris Garrett Date: Tue, 2 Feb 2021 14:03:26 -0800 Subject: [PATCH 4/6] add API docs --- text/0561-add-numeric-comparison-operators.md | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/text/0561-add-numeric-comparison-operators.md b/text/0561-add-numeric-comparison-operators.md index 38375171a2..35a01dd130 100644 --- a/text/0561-add-numeric-comparison-operators.md +++ b/text/0561-add-numeric-comparison-operators.md @@ -64,6 +64,52 @@ The introduction of these helpers does not impact the current mental model for E In addition to API and Guides documentation with illustrative examples of usage of the various helpers. +### API Docs + +#### `{{lt}}` + +The `{{lt}}` helper can be used to compare two values in a template. It returns `true` if the first value is +less than the second value, and `false` otherwise. It is equivalent to the `<` operator in JavaScript. + +```hbs +{{#if (lt @number 5)}} + The number is less than 5! +{{/if}} +``` + +#### `{{lte}}` + +The `{{lte}}` helper can be used to compare two values in a template. It returns `true` if the first value is +less than or equal to the second value, and `false` otherwise. It is equivalent to the `<=` operator in JavaScript. + +```hbs +{{#if (lte @number 5)}} + The number is less than or equal to 5! +{{/if}} +``` + +#### `{{gt}}` + +The `{{gt}}` helper can be used to compare two values in a template. It returns `true` if the first value is +greater than the second value, and `false` otherwise. It is equivalent to the `>` operator in JavaScript. + +```hbs +{{#if (gt @number 5)}} + The number is greater than 5! +{{/if}} +``` + +#### `{{gte}}` + +The `{{gte}}` helper can be used to compare two values in a template. It returns `true` if the first value is +greater than or equal the second value, and `false` otherwise. It is equivalent to the `>=` operator in JavaScript. + +```hbs +{{#if (gte @number 5)}} + The number is greater than or equal to 5! +{{/if}} +``` + ## Drawbacks Adding new helpers increases the surface area of the framework and the code the core team commits to support long term. From af8dda8d0ecb294211bd8ef57668f0bc5895ac1e Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Fri, 5 Feb 2021 17:36:30 +0000 Subject: [PATCH 5/6] copy teaching section from other related RFCs --- text/0561-add-numeric-comparison-operators.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/text/0561-add-numeric-comparison-operators.md b/text/0561-add-numeric-comparison-operators.md index 35a01dd130..66f2190552 100644 --- a/text/0561-add-numeric-comparison-operators.md +++ b/text/0561-add-numeric-comparison-operators.md @@ -60,9 +60,13 @@ This is identical to the `{{gte}}` helper in `ember-truth-helpers`, except for t ## How we teach this -The introduction of these helpers does not impact the current mental model for Ember applications. +While the introduction of these helpers doesn't introduce new concepts, as helpers like these could be written and in fact were written for a long time, it might affect slightly how we frame some concepts in the guides. -In addition to API and Guides documentation with illustrative examples of usage of the various helpers. +Previously users were encouraged to put computed properties in the JavaScript file of the components, even for the most simple tasks like comparing if a value is less than another using `computed.lt`. + +With the addition of these helpers users don't have to resort to computed properties for simple operations, which sometimes forced users to create JavaScript files for what could have been template-only components. + +In addition to documenting the new helpers in the API docs, the Guides should be updated to favour the usage of helpers over computed properties where it makes more sense, adding illustrative examples and stressing out where the definition of truthiness of handlebars differs from the one of Javascript. ### API Docs From 97548e70850a4bec3a552e1ac8446a7d4ce66052 Mon Sep 17 00:00:00 2001 From: Robert Jackson Date: Fri, 5 Feb 2021 14:06:23 -0500 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Matthew Beale --- text/0561-add-numeric-comparison-operators.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/text/0561-add-numeric-comparison-operators.md b/text/0561-add-numeric-comparison-operators.md index 66f2190552..c8d897ac3d 100644 --- a/text/0561-add-numeric-comparison-operators.md +++ b/text/0561-add-numeric-comparison-operators.md @@ -49,14 +49,14 @@ This is identical to the `{{lte}}` helper in `ember-truth-helpers` #### `{{gt}}` Binary operation. Throws an error if not called with exactly two arguments. -Equivalent of > -This is identical to the `{{gt}}` helper in `ember-truth-helpers`, except for the name. +Equivalent of ` > ` +This is identical to the `{{gt}}` helper in `ember-truth-helpers`. #### `{{gte}}` Binary operation. Throws an error if not called with exactly two arguments. -Equivalent of >= -This is identical to the `{{gte}}` helper in `ember-truth-helpers`, except for the name. +Equivalent of ` >= `. +This is identical to the `{{gte}}` helper in `ember-truth-helpers`. ## How we teach this