Renamed the helpers by dropping the cq prefix #146

ijlee2 · 2023-01-03T15:20:34Z

Description

In light of strict mode template support (#130), I decided to rename the helpers by dropping the cq prefix. This lets us (1) minimize the syntax difference (e.g. in documentation) and (2) write templates that are easier to read and understand:

{{! Option 1: app/components/tracks.hbs }}

<ContainerQuery
  @features={{hash
    small=(width max=480)
    medium=(width min=480 max=640)
    large=(width min=640)
    tall=(height min=320)
  }}
  as |CQ|
>
  ...
</ContainerQuery>

/* Option 2: app/components/tracks.gts */

import { hash } from '@ember/helper';
import { ContainerQuery, height, width } from 'ember-container-query';

<template>
  <ContainerQuery
    @features={{hash
      small=(width max=480)
      medium=(width min=480 max=640)
      large=(width min=640)
      tall=(height min=320)
    }}
    as |CQ|
  >
    ...
  </ContainerQuery>
</template>

One downside is, the names height and width are less unique. More search results (e.g. from a whole string match) will be produced and it is up to the end-developer to sift the results.

To be clear, this pull request does not introduce a breaking change. The old helpers ({{cq-aspect-ratio}}, {{cq-height}} and {{cq-width}}) continue to be available, but now produce a deprecation message. They will be removed in the v4.0.0 release.

Migration strategy for end-developers

The helpers have been renamed by dropping the cq prefix. As a result, you can use your text editor's find-and-replace-all to update the helper names.

Step	Find	Replace with
1	`cq-aspect-ratio`	`aspect-ratio`
2	`cq-height`	`height`
3	`cq-width`	`width`

The three steps are demonstrated in commits 3-5 of this pull request.

How to fix name collisions

Scenario 1

You may be using the names height and width for arguments or properties of a component. If so, follow the Octane syntax and clearly mark them as arguments (@) or properties (this.). Linters (e.g. ember-template-lint, eslint-plugin-ember, and glint) can help you fix these name collisions.

Here is an extreme example:

{{! app/components/edge-case.hbs }}

<div>
  Arguments:
  {{@aspectRatio}},
  {{@height}},
  {{@width}}
</div>

<div>
  {{#let
    (hash
      aspect-ratio=(aspect-ratio) height=(height) width=(width)
    )
    as |obj|
  }}
    {{! template-lint-disable no-log }}
    {{log obj.aspect-ratio obj.height obj.width}}
  {{/let}}
</div>

Scenario 2

When you have another addon that provides helpers named {{aspect-ratio}}, {{height}}, and {{width}}, you will need to decide which addon gets to keep the name.

This scenario is unlikely according to ember-observer:

{{aspect-ratio}} - no matches
{{height}} - 1 match (false positive)
{{width}} - 1 match (in a demo app)

…sages.

…oughout the documentation

…documentation

…cumentation

… to be fixed

…llisions to be fixed" This reverts commit 8df608b.

ijlee2 · 2023-01-03T15:30:46Z

addon/template-registry.ts

+  'cq-aspect-ratio': typeof AspectRatioHelper;
+  'cq-height': typeof HeightHelper;
+  'cq-width': typeof WidthHelper;


reminder

Remove these lines in the future pull request, which will remove {{cq-aspect-ratio}}, {{cq-height}}, and {{cq-width}} helpers.

ijlee2 · 2023-01-03T15:31:07Z

app/helpers/cq-aspect-ratio.js

+import { deprecate } from '@ember/debug';
+
+deprecate(
+  'The {{cq-aspect-ratio}} helper has been renamed to {{aspect-ratio}}. Please update the helper name in your template.',
+  false,
+  {
+    for: 'ember-container-query',
+    id: 'ember-container-query.rename-cq-aspect-ratio-helper',
+    since: {
+      available: '3.2.0',
+      enabled: '3.2.0',
+    },
+    until: '4.0.0',
+    url: 'https://github.com/ijlee2/ember-container-query/tree/3.2.0#api',
+  }
+);
+
+export { default } from 'ember-container-query/helpers/aspect-ratio';


reminder

Remove these lines in the future pull request, which will remove {{cq-aspect-ratio}}, {{cq-height}}, and {{cq-width}} helpers.

ijlee2 · 2023-01-03T15:31:15Z

app/helpers/cq-height.js

+import { deprecate } from '@ember/debug';
+
+deprecate(
+  'The {{cq-height}} helper has been renamed to {{height}}. Please update the helper name in your template.',
+  false,
+  {
+    for: 'ember-container-query',
+    id: 'ember-container-query.rename-cq-height-helper',
+    since: {
+      available: '3.2.0',
+      enabled: '3.2.0',
+    },
+    until: '4.0.0',
+    url: 'https://github.com/ijlee2/ember-container-query/tree/3.2.0#api',
+  }
+);
+
+export { default } from 'ember-container-query/helpers/height';


reminder

Remove these lines in the future pull request, which will remove {{cq-aspect-ratio}}, {{cq-height}}, and {{cq-width}} helpers.

ijlee2 · 2023-01-03T15:31:25Z

app/helpers/cq-width.js

+import { deprecate } from '@ember/debug';
+
+deprecate(
+  'The {{cq-width}} helper has been renamed to {{width}}. Please update the helper name in your template.',
+  false,
+  {
+    for: 'ember-container-query',
+    id: 'ember-container-query.rename-cq-width-helper',
+    since: {
+      available: '3.2.0',
+      enabled: '3.2.0',
+    },
+    until: '4.0.0',
+    url: 'https://github.com/ijlee2/ember-container-query/tree/3.2.0#api',
+  }
+);
+
+export { default } from 'ember-container-query/helpers/width';


reminder

Remove these lines in the future pull request, which will remove {{cq-aspect-ratio}}, {{cq-height}}, and {{cq-width}} helpers.

ijlee2 · 2023-01-03T15:32:21Z

tests/integration/helpers/cq-aspect-ratio-test.ts

 import { setupRenderingTest } from 'dummy/tests/helpers';
 import { hbs } from 'ember-cli-htmlbars';
 import { module, test } from 'qunit';

 module('Integration | Helper | cq-aspect-ratio', function (hooks) {
  setupRenderingTest(hooks);

-  test('can return a hash with default values', async function (this: TestContext, assert) {
+  test('provides a deprecation message', async function (this: TestContext, assert) {


reminder

Delete this file in the future pull request, which will remove {{cq-aspect-ratio}}, {{cq-height}}, and {{cq-width}} helpers.

ijlee2 · 2023-01-03T15:32:28Z

tests/integration/helpers/cq-height-test.ts

 import { setupRenderingTest } from 'dummy/tests/helpers';
 import { hbs } from 'ember-cli-htmlbars';
 import { module, test } from 'qunit';

 module('Integration | Helper | cq-height', function (hooks) {
  setupRenderingTest(hooks);

-  test('can return a hash with default values', async function (this: TestContext, assert) {
+  test('provides a deprecation message', async function (this: TestContext, assert) {


reminder

Delete this file in the future pull request, which will remove {{cq-aspect-ratio}}, {{cq-height}}, and {{cq-width}} helpers.

ijlee2 · 2023-01-03T15:32:35Z

tests/integration/helpers/cq-width-test.ts

 import { setupRenderingTest } from 'dummy/tests/helpers';
 import { hbs } from 'ember-cli-htmlbars';
 import { module, test } from 'qunit';

 module('Integration | Helper | cq-width', function (hooks) {
  setupRenderingTest(hooks);

-  test('can return a hash with default values', async function (this: TestContext, assert) {
+  test('provides a deprecation message', async function (this: TestContext, assert) {


reminder

Delete this file in the future pull request, which will remove {{cq-aspect-ratio}}, {{cq-height}}, and {{cq-width}} helpers.

ijlee2 added the enhance: code Issue asks for new feature or refactor label Jan 3, 2023

ijlee2 added 7 commits January 3, 2023 16:26

chore: Renamed the helpers by dropping the cq prefix

70db951

chore: Re-introduced helpers with old names. Provided deprecation mes…

96a23e9

…sages.

chore: Renamed the {{cq-aspect-ratio}} helper to {{aspect-ratio}} thr…

869784a

…oughout the documentation

chore: Renamed the {{cq-height}} helper to {{height}} throughout the …

9c42cf9

…documentation

chore: Renamed the {{cq-width}} helper to {{width}} throughout the do…

140476f

…cumentation

chore: Checked that renaming the helpers still allows name collisions…

8df608b

… to be fixed

Revert "chore: Checked that renaming the helpers still allows name co…

20dc3b4

…llisions to be fixed" This reverts commit 8df608b.

ijlee2 force-pushed the rename-helpers branch from 0182fe2 to 20dc3b4 Compare January 3, 2023 15:28

ijlee2 commented Jan 3, 2023

View reviewed changes

ijlee2 marked this pull request as ready for review January 3, 2023 15:32

ijlee2 merged commit b9d3dc8 into main Jan 3, 2023

ijlee2 deleted the rename-helpers branch January 3, 2023 16:41

This was referenced Jan 3, 2023

Plans for v4 release #144

Closed

Add easier imports from strict mode users #130

Merged

ijlee2 mentioned this pull request Jan 17, 2023

Removed the deprecated helpers #152

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Renamed the helpers by dropping the cq prefix #146

Renamed the helpers by dropping the cq prefix #146

ijlee2 commented Jan 3, 2023 •

edited

Loading

ijlee2 Jan 3, 2023

ijlee2 Jan 3, 2023

ijlee2 Jan 3, 2023

ijlee2 Jan 3, 2023

ijlee2 Jan 3, 2023

ijlee2 Jan 3, 2023

ijlee2 Jan 3, 2023

Renamed the helpers by dropping the cq prefix #146

Renamed the helpers by dropping the cq prefix #146

Conversation

ijlee2 commented Jan 3, 2023 • edited Loading

Description

Migration strategy for end-developers

How to fix name collisions

Scenario 1

Scenario 2

ijlee2 Jan 3, 2023

Choose a reason for hiding this comment

ijlee2 Jan 3, 2023

Choose a reason for hiding this comment

ijlee2 Jan 3, 2023

Choose a reason for hiding this comment

ijlee2 Jan 3, 2023

Choose a reason for hiding this comment

ijlee2 Jan 3, 2023

Choose a reason for hiding this comment

ijlee2 Jan 3, 2023

Choose a reason for hiding this comment

ijlee2 Jan 3, 2023

Choose a reason for hiding this comment

ijlee2 commented Jan 3, 2023 •

edited

Loading