1 | # Upgrading to 3.0 from 2.x
|
2 |
|
3 | ember-tooltips 3.x replaces the underlying tooltip implementation with the robust
|
4 | and mature [`tooltip.js`](https://popper.js.org/tooltip-examples.html) library
|
5 | powered by [`popper.js`](https://popper.js.org/). It has enabled a simpler
|
6 | ember-tooltips implementation, while providing more functionality and coverage
|
7 | for use cases not easily supported by earlier versions of ember-tooltips.
|
8 |
|
9 | ## Migrating existing code
|
10 |
|
11 | We've done our best to make the upgrade from 2.x to 3.x as smooth as possible,
|
12 | by preserving a similar component API and mostly compatible test helpers.
|
13 |
|
14 | ### 1. Update component names
|
15 |
|
16 | ember-tooltips now provides one component for tooltips, `ember-tooltip`, and one
|
17 | component for popovers, `ember-popover`.
|
18 |
|
19 | For the most part you can find-and-replace all uses of `tooltip-on-component`
|
20 | and `tooltip-on-element` with `ember-tooltip`, and `popover-on-component` and
|
21 | `popover-on-element` with `ember-popover`.
|
22 |
|
23 | ### 2. Remove deprecated options
|
24 |
|
25 | If you have specified these options in the past, you should remove them, as they
|
26 | no longer apply to ember-tooltips 3.x:
|
27 |
|
28 | * `setPin` - No longer needed
|
29 | * `keepInWindow` - All tooltips are now kept in the window by default. See
|
30 | [`popperOptions`](README.md#popper-options) for overriding this behavior via
|
31 | popper.js modifiers.
|
32 | * `enableLazyRendering` - See [What happened to `enableLazyRendering`?](#what-happened-to-enablelazyrendering)
|
33 | * `target` - Use [`targetId`](README.md#targetid) with the ID of the target element
|
34 |
|
35 | e.g.
|
36 |
|
37 | ```patch
|
38 | - {{#tooltip-on-element
|
39 | - class="user-banner__photo__tooltip js-user-photo-tooltip"
|
40 | - enableLazyRendering=true
|
41 | - side="right"}}
|
42 | + {{#ember-tooltip
|
43 | + class="js-user-photo-tooltip"
|
44 | + tooltipClass="user-banner__photo__tooltip"
|
45 | + side="right"}}
|
46 | <img src={{user.photo_url}} alt="User photo" />
|
47 | - {{/tooltip-on-element}}
|
48 | + {{/ember-tooltip}}
|
49 | ```
|
50 |
|
51 | ### 3. Update `class` and `tooltipClass`
|
52 |
|
53 | When specifying `class` with an `ember-tooltip`, this will apply to the tooltip
|
54 | wrapper component, but will not contain the actual tooltip content. `class` may
|
55 | still be used for targeting tooltips using the `ember-tooltips` test helpers.
|
56 |
|
57 | For other uses where you're looking to set a class on the actual tooltip used
|
58 | for display (e.g. changing styling), use `tooltipClass`, which will
|
59 | apply to the `popper.js` tooltip instance in the DOM.
|
60 |
|
61 | e.g.
|
62 |
|
63 | ```hbs
|
64 | {{!-- app/components/some-component.hbs --}}
|
65 | {{ember-tooltip
|
66 | text="Hello"
|
67 | class="js-my-test-tooltip"
|
68 | tooltipClass="tooltip-warning"
|
69 | }}
|
70 | ```
|
71 |
|
72 | ```css
|
73 | /* app/styles/my-tooltips.css */
|
74 | .tooltip-warning {
|
75 | background-color: yellow;
|
76 | color: black;
|
77 | }
|
78 | ```
|
79 |
|
80 | ```javascript
|
81 | // tests/integration/components/some-component-test.js
|
82 | assertTooltipContent(assert, {
|
83 | contentString: 'Hello',
|
84 | selector: '.js-my-test-tooltip',
|
85 | })
|
86 | ```
|
87 |
|
88 | ### 4. Migrating test helpers
|
89 |
|
90 | The test helpers have remained with the same API. However, there are a few notable
|
91 | changes:
|
92 |
|
93 | #### 4.1 Updating test helper import path
|
94 |
|
95 | The test helper import paths have changed. Update `YOUR_APP_MODULE/tests/helpers/ember-tooltips` to `ember-tooltips/test-support`
|
96 |
|
97 | ```patch
|
98 | import {
|
99 | assertTooltipVisible,
|
100 | assertTooltipNotVisible,
|
101 | - findTooltip,
|
102 | - triggerTooltipTargetEvent
|
103 | -} from 'my-cool-app/tests/helpers/ember-tooltips';
|
104 | + findTooltip
|
105 | +} from 'ember-tooltips/test-support';
|
106 | ```
|
107 |
|
108 | #### 4.2 Replace `triggerTooltipTargetEvent` test helper
|
109 |
|
110 | The `triggerTooltipTargetEvent` test helper has been removed.
|
111 | Please use `triggerEvent` from `@ember/test-helpers` (or `ember-native-dom-helpers`,
|
112 | if you're not using the latest test helpers.)
|
113 |
|
114 | ```patch
|
115 | - it('shows the thing I want when condition is true', function() {
|
116 | + it('shows the thing I want when condition is true', async function() {
|
117 | await render(hbs`{{ember-tooltip text='Hello' class="my-tooltip-target"}}`);
|
118 | const someTooltipTarget = this.$('.my-tooltip-target');
|
119 | - triggerTooltipTargetEvent(someTooltipTarget, 'mouseenter');
|
120 | + await triggerEvent(someTooltipTarget[0], 'mouseenter');
|
121 | ```
|
122 |
|
123 | #### 4.3 Specifying `targetSelector` where needed
|
124 |
|
125 | While the test helper APIs remain unchanged, due to DOM structure changes in
|
126 | ember-tooltips, you may need to specify the [`targetSelector`](README.md#test-helper-option-targetselector)
|
127 | option to target the correct tooltip.
|
128 |
|
129 | Luckily, your test suite should let you know where this is needed!
|
130 |
|
131 | ### 5. Updating any CSS Overrides
|
132 |
|
133 | If you were previously overriding CSS styles of `ember-tooltips`, your rules will
|
134 | need to be updated to support 3.x. While by default, the tooltips should look about
|
135 | the same, the underlying DOM structure and CSS classes used have changed.
|
136 |
|
137 | If you were using CSS workarounds for positioning the tooltip, they may no longer
|
138 | be needed, as `popper.js` is smarter about positioning and provides
|
139 | some broader control over it. For example, position variants supported by
|
140 | `popper.js` may supplant the need for some custom positioning CSS. See [`side`](README.md#test-helper-option-side)
|
141 | option for more details.
|
142 |
|
143 |
|
144 | ## FAQ / Gotchas
|
145 |
|
146 | ### My tooltips appear clipped! (use within elements using `overflow: hidden`)
|
147 |
|
148 | One notable difference between the way 2.x renders versus 3.x is that 3.x now
|
149 | renders tooltips as siblings of their target element. Generally, this shouldn't
|
150 | change the appearance of the tooltips. However, when a tooltip exists inside of
|
151 | a parent element with `overflow: hidden` the tooltip may appear clipped in 3.x.
|
152 |
|
153 | There are two ways this can be addressed, but it may depend on your application.
|
154 |
|
155 | 1. Disable `escapeWithReference` for the `preventOverflow` popper.js modifier through
|
156 | [`popperOptions`](https://github.com/sir-dunxalot/ember-tooltips#popper-options)
|
157 | 2. Use the [`popperContainer`](https://github.com/sir-dunxalot/ember-tooltips#popper-container)
|
158 | option to render the tooltip as a child of another element, such as `'body'`
|
159 |
|
160 | ### What happened to `enableLazyRendering`?
|
161 |
|
162 | The use of `popper.js` in 3.x addresses performance in a couple different ways
|
163 | that mostly make the old lazy rendering option unnecessary.
|
164 |
|
165 | 1. It uses `requestAnimationFrame` to handle updates to the DOM, which provides
|
166 | smooth 60FPS updates.
|
167 | 2. It does not update or re-position tooltips that are not shown.
|
168 | 3. Tooltips are only rendered on activation & are torn down when hidden.
|
169 | 4. Content is only rendered into the DOM when the tooltip is activated for the
|
170 | first time (essentially what `enableLazyRendering` did)
|
171 |
|
172 | ### My application assumed tooltips were appended to `<body>` and now all my tests/layout are breaking!
|
173 |
|
174 | In ember-tooltips 3.x, the decision was made to render tooltip content as a
|
175 | sibling to the target element, rather than as a direct child of `<body>`.
|
176 |
|
177 | You can restore the behavior of ember-tooltips 2.x by specifying
|
178 | `popperContainer='body'`, which will direct popper.js to render the tooltip or
|
179 | popover content as a child of `<body>`.
|