An API that will help us implement Search Tips and Search Interventions (referenced in https://mozilla.invisionapp.com/share/S5SQCACBVAF#/screens/367251846_Photon_Design_Update )

https://docs.google.com/document/d/13AzkHD_WLAM_-_vyRf2Lhd49WOmFBN2Q2CBnWFxzwGA/edit

Proposing changes to the contextual tip API

I spoke with Drew earlier today about making some changes to the contextual tip api and the following is a list of changes we think would be good to make for the contextual tip API:

1. Remove defaults from the manifest

Currently, a web extension can set defaults for the contextual tip’s default icon, theme icons, title, button title, and link title. If there are defaults defined in the manifest, then a contextual tip is set in all existing and new windows. We don’t seem to have a use case for using defaults set in the manifest, and we don’t anticipate a use case, so we can remove this.

2. Changes to icon support

Currently, icons for higher/lower res screens and light/dark themes are set in the manifest defaults. An icon can be set programmatically by providing a path to an icon when calling setContextualTip.

If we’re removing the defaults, then icons for higher/lower res screens and light/dark themes should also be set programmatically through setContextualTip.

3. Remove the “contextual_tip” permission from the manifest

In my most recent revision at https://phabricator.services.mozilla.com/D37809?id=136085 , I added a permission called “contextual_tip”. A web extension that wants to use a contextual tip would have to add “contextual_tip” to the list of permissions in its manifest and an error is thrown if it’s missing. Ultimately, it would’ve been used to ensure that only one web extension can use the contextual tip (one possible solution to “what happens if multiple extensions try to set a contextual tip?”) but that has not been written and is not part of the revision.

Handling multiple extensions is something to think about and eventually address but not a top priority at the moment. So I think the “contextual_tip” permission can be removed for now (but we’ll still require the “urlbar” permission).

4. Change the way setContextualTip behaves and remove the show/hide functions

Currently, the setContextualTip function accepts two arguments: a details object and a window id. The details object represents the details of the contextual tip (icon, title, etc.) and the window id is the corresponding window’s contextual tip to set. So if a web extension wants to set the contextual tip on a specific window, they could call setContextualTip({…details}, window.id). If the web extension omits the windowId then the contextual tip’s details would be set for all windows. All existing windows’ contextual tips would be updated with the given details. New windows would have contextual tips with the given details too. Unless hide is called, the tip always appears when the user clicks in the urlbar input field.

Given that the contextual tip is shown only on the current window, only one urlbar popup is open at a time, and we don’t have a use case for setting a contextual tip across all windows (especially since we’re removing the defaults from the manifest), we can change the setContextualTip function to only accept a details object. We would set the contextual tip only for the current window. We can remove code for handling existing and new windows in the current contextual tip API.

Our current use cases, search tips and interventions, require setting a contextual tip once. So setContextualTip should open the current window’s (or most recent window’s) urlbar’s popup panel, display a tip with the given details, and the tip should be removed/hidden when the popup closes. If the popup is already open then setContextualTip should just display/update the tip then be removed/hidden when the popup closes. This fits the use case for search tips where a user should see a contextual tip in the popup panel without having to click in the urlbar’s input field. For search interventions, this works but we’ll want to be able to set and hide the contextual tip as the user is typing. We already support setting the tip through setContextualTip but to support hiding the contextual tip, the search intervention web extension could pass null to setContextualTip which would tell setContextualTip to hide the tip (we currently don’t accept null so this would be another change). With these changes, there would be no need to make a browser.urlbar.onViewShowing event or browser.urlbar.openPopup function accessible to web extensions (both of which are needed for search tips with the current contextual tip API). Using the contextual tip API would be more intuitive for developers since they don’t need to keep track of whether there’s a tip already set and they don’t need to use show/hide, in addition to setContextualTip, to ensure that the tip is visible only when they want it to be visible.

All blocking bugs have been either fixed or wontfixed (in favor of tip results), so I'll mark this bug as fixed.