Source code

Revision control

Other Tools

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
"use strict";
var EXPORTED_SYMBOLS = ["UITour"];
const { AppConstants } = ChromeUtils.import(
);
const { Services } = ChromeUtils.import("resource://gre/modules/Services.jsm");
const { TelemetryController } = ChromeUtils.import(
);
const { XPCOMUtils } = ChromeUtils.import(
);
XPCOMUtils.defineLazyGlobalGetters(this, ["URL"]);
ChromeUtils.defineModuleGetter(
this,
"CustomizableUI",
);
ChromeUtils.defineModuleGetter(
this,
"fxAccounts",
);
ChromeUtils.defineModuleGetter(
this,
"FxAccounts",
);
ChromeUtils.defineModuleGetter(
this,
"PageActions",
);
ChromeUtils.defineModuleGetter(
this,
"ProfileAge",
);
ChromeUtils.defineModuleGetter(
this,
"AboutReaderParent",
);
ChromeUtils.defineModuleGetter(
this,
"ResetProfile",
);
ChromeUtils.defineModuleGetter(
this,
"UpdateUtils",
);
ChromeUtils.defineModuleGetter(
this,
"BrowserUsageTelemetry",
);
ChromeUtils.defineModuleGetter(
this,
"PanelMultiView",
);
// See LOG_LEVELS in Console.jsm. Common examples: "All", "Info", "Warn", & "Error".
const PREF_LOG_LEVEL = "browser.uitour.loglevel";
const BACKGROUND_PAGE_ACTIONS_ALLOWED = new Set([
"forceShowReaderIcon",
"getConfiguration",
"getTreatmentTag",
"hideHighlight",
"hideInfo",
"hideMenu",
"ping",
"registerPageID",
"setConfiguration",
"setTreatmentTag",
]);
const MAX_BUTTONS = 4;
// Prefix for any target matching a search engine.
const TARGET_SEARCHENGINE_PREFIX = "searchEngine-";
// Create a new instance of the ConsoleAPI so we can control the maxLogLevel with a pref.
XPCOMUtils.defineLazyGetter(this, "log", () => {
let ConsoleAPI = ChromeUtils.import("resource://gre/modules/Console.jsm", {})
.ConsoleAPI;
let consoleOptions = {
maxLogLevelPref: PREF_LOG_LEVEL,
prefix: "UITour",
};
return new ConsoleAPI(consoleOptions);
});
var UITour = {
url: null,
/* Map from browser chrome windows to a Set of <browser>s in which a tour is open (both visible and hidden) */
tourBrowsersByWindow: new WeakMap(),
// Menus opened by api users explictly through `Mozilla.UITour.showMenu` call
noautohideMenus: new Set(),
availableTargetsCache: new WeakMap(),
clearAvailableTargetsCache() {
this.availableTargetsCache = new WeakMap();
},
_annotationPanelMutationObservers: new WeakMap(),
highlightEffects: ["random", "wobble", "zoom", "color"],
targets: new Map([
[
"accountStatus",
{
query: aDocument => {
let id = UITour.protonEnabled
? "appMenu-fxa-label2"
: "appMenu-fxa-label";
let statusButton = PanelMultiView.getViewNode(aDocument, id);
if (!UITour.protonEnabled) {
// Use the sync setup icon.
return statusButton.querySelector(".toolbarbutton-icon");
}
return statusButton;
},
// This is a fake widgetName starting with the "appMenu-" prefix so we know
// to automatically open the appMenu when annotating this target.
widgetName: "appMenu-fxa-label",
},
],
[
"addons",
{
query: aDocument => {
return UITour.protonEnabled
? UITour.getNodeFromDocument(
aDocument,
"#appMenu-extensions-themes-button"
)
: UITour.getNodeFromDocument(aDocument, "#appMenu-addons-button");
},
},
],
[
"appMenu",
{
addTargetListener: (aDocument, aCallback) => {
let panelPopup = aDocument.defaultView.PanelUI.panel;
panelPopup.addEventListener("popupshown", aCallback);
},
query: "#PanelUI-button",
removeTargetListener: (aDocument, aCallback) => {
let panelPopup = aDocument.defaultView.PanelUI.panel;
panelPopup.removeEventListener("popupshown", aCallback);
},
},
],
["backForward", { query: "#back-button" }],
["bookmarks", { query: "#bookmarks-menu-button" }],
[
"devtools",
{
query: "#appMenu-developer-button",
widgetName: "appMenu-developer-button",
},
],
[
"forget",
{
allowAdd: true,
query: "#panic-button",
widgetName: "panic-button",
},
],
["help", { query: "#appMenu-help-button" }],
["home", { query: "#home-button" }],
["library", { query: "#appMenu-library-button" }],
[
"logins",
{
query: aDocument => {
return UITour.protonEnabled
? UITour.getNodeFromDocument(aDocument, "#appMenu-passwords-button")
: UITour.getNodeFromDocument(aDocument, "#appMenu-logins-button");
},
},
],
[
"pocket",
{
allowAdd: true,
query: "#save-to-pocket-button",
},
],
[
"privateWindow",
{
query: aDocument => {
return UITour.protonEnabled
? UITour.getNodeFromDocument(
aDocument,
"#appMenu-new-private-window-button2"
)
: UITour.getNodeFromDocument(
aDocument,
"#appMenu-private-window-button"
);
},
},
],
[
"quit",
{
query: aDocument => {
return UITour.protonEnabled
? UITour.getNodeFromDocument(aDocument, "#appMenu-quit-button2")
: UITour.getNodeFromDocument(aDocument, "#appMenu-quit-button");
},
},
],
["readerMode-urlBar", { query: "#reader-mode-button" }],
[
"search",
{
infoPanelOffsetX: 18,
infoPanelPosition: "after_start",
query: "#searchbar",
widgetName: "search-container",
},
],
[
"searchIcon",
{
query: aDocument => {
let searchbar = aDocument.getElementById("searchbar");
return searchbar.querySelector(".searchbar-search-button");
},
widgetName: "search-container",
},
],
[
"selectedTabIcon",
{
query: aDocument => {
let selectedtab = aDocument.defaultView.gBrowser.selectedTab;
let element = selectedtab.iconImage;
if (!element || !UITour.isElementVisible(element)) {
return null;
}
return element;
},
},
],
[
"urlbar",
{
query: "#urlbar",
widgetName: "urlbar-container",
},
],
[
"pageAction-bookmark",
{
query: aDocument => {
// The bookmark's urlbar page action button is pre-defined in the DOM.
// It would be hidden if toggled off from the urlbar.
let node = aDocument.getElementById("star-button-box");
if (node && !node.hidden) {
return node;
}
aDocument.ownerGlobal.BrowserPageActions.placeLazyActionsInPanel();
return aDocument.getElementById("pageAction-panel-bookmark");
},
},
],
]),
nonProtonTargets: [
[
"pageAction-copyURL",
{
query: aDocument => {
aDocument.ownerGlobal.BrowserPageActions.placeLazyActionsInPanel();
return (
aDocument.getElementById("pageAction-urlbar-copyURL") ||
aDocument.getElementById("pageAction-panel-copyURL")
);
},
},
],
[
"pageAction-emailLink",
{
query: aDocument => {
aDocument.ownerGlobal.BrowserPageActions.placeLazyActionsInPanel();
return (
aDocument.getElementById("pageAction-urlbar-emailLink") ||
aDocument.getElementById("pageAction-panel-emailLink")
);
},
},
],
[
"pageAction-sendToDevice",
{
query: aDocument => {
aDocument.ownerGlobal.BrowserPageActions.placeLazyActionsInPanel();
return (
aDocument.getElementById("pageAction-urlbar-sendToDevice") ||
aDocument.getElementById("pageAction-panel-sendToDevice")
);
},
},
],
[
"screenshots",
{
query: aDocument => {
aDocument.ownerGlobal.BrowserPageActions.placeLazyActionsInPanel();
return (
aDocument.getElementById("pageAction-urlbar-screenshots") ||
aDocument.getElementById("pageAction-panel-screenshots_mozilla_org")
);
},
},
],
],
init() {
log.debug("Initializing UITour");
// Lazy getter is initialized here so it can be replicated any time
// in a test.
delete this.url;
XPCOMUtils.defineLazyGetter(this, "url", function() {
return Services.urlFormatter.formatURLPref("browser.uitour.url");
});
XPCOMUtils.defineLazyPreferenceGetter(
this,
"protonEnabled",
"browser.proton.enabled",
false
);
// Add non-proton targets if necessary.
if (!UITour.protonEnabled) {
for (let [id, target] of this.nonProtonTargets) {
this.targets.set(id, target);
}
}
// Clear the availableTargetsCache on widget changes.
let listenerMethods = [
"onWidgetAdded",
"onWidgetMoved",
"onWidgetRemoved",
"onWidgetReset",
"onAreaReset",
];
CustomizableUI.addListener(
listenerMethods.reduce((listener, method) => {
listener[method] = () => this.clearAvailableTargetsCache();
return listener;
}, {})
);
},
getNodeFromDocument(aDocument, aQuery) {
let viewCacheTemplate = aDocument.getElementById("appMenu-viewCache");
return (
aDocument.querySelector(aQuery) ||
viewCacheTemplate.content.querySelector(aQuery)
);
},
onPageEvent(aEvent, aBrowser) {
let browser = aBrowser;
let window = browser.ownerGlobal;
// Does the window have tabs? We need to make sure since windowless browsers do
// not have tabs.
if (!window.gBrowser) {
// When using windowless browsers we don't have a valid |window|. If that's the case,
// use the most recent window as a target for UITour functions (see Bug 1111022).
window = Services.wm.getMostRecentWindow("navigator:browser");
}
log.debug("onPageEvent:", aEvent.detail);
if (typeof aEvent.detail != "object") {
log.warn("Malformed event - detail not an object");
return false;
}
let action = aEvent.detail.action;
if (typeof action != "string" || !action) {
log.warn("Action not defined");
return false;
}
let data = aEvent.detail.data;
if (typeof data != "object") {
log.warn("Malformed event - data not an object");
return false;
}
if (
(aEvent.pageVisibilityState == "hidden" ||
aEvent.pageVisibilityState == "unloaded") &&
!BACKGROUND_PAGE_ACTIONS_ALLOWED.has(action)
) {
log.warn("Ignoring disallowed action from a hidden page:", action);
return false;
}
switch (action) {
case "registerPageID": {
break;
}
case "showHighlight": {
if (!UITour.protonEnabled && data.target.startsWith("pageAction-")) {
// The page action panel is lazily loaded, so we will need to initialize it
// and place actions in the panel before showing the highlight for a panel
// node.
window.BrowserPageActions.initializePanel();
}
let targetPromise = this.getTarget(window, data.target);
targetPromise
.then(target => {
if (!target.node) {
log.error("UITour: Target could not be resolved: " + data.target);
return;
}
let effect = undefined;
if (this.highlightEffects.includes(data.effect)) {
effect = data.effect;
}
this.showHighlight(window, target, effect);
})
.catch(log.error);
break;
}
case "hideHighlight": {
this.hideHighlight(window);
break;
}
case "showInfo": {
let targetPromise = this.getTarget(window, data.target, true);
targetPromise
.then(target => {
if (!target.node) {
log.error("UITour: Target could not be resolved: " + data.target);
return;
}
let iconURL = null;
if (typeof data.icon == "string") {
iconURL = this.resolveURL(browser, data.icon);
}
let buttons = [];
if (Array.isArray(data.buttons) && data.buttons.length) {
for (let buttonData of data.buttons) {
if (
typeof buttonData == "object" &&
typeof buttonData.label == "string" &&
typeof buttonData.callbackID == "string"
) {
let callback = buttonData.callbackID;
let button = {
label: buttonData.label,
callback: event => {
this.sendPageCallback(browser, callback);
},
};
if (typeof buttonData.icon == "string") {
button.iconURL = this.resolveURL(browser, buttonData.icon);
}
if (typeof buttonData.style == "string") {
button.style = buttonData.style;
}
buttons.push(button);
if (buttons.length == MAX_BUTTONS) {
log.warn(
"showInfo: Reached limit of allowed number of buttons"
);
break;
}
}
}
}
let infoOptions = {};
if (typeof data.closeButtonCallbackID == "string") {
infoOptions.closeButtonCallback = () => {
this.sendPageCallback(browser, data.closeButtonCallbackID);
};
}
if (typeof data.targetCallbackID == "string") {
infoOptions.targetCallback = details => {
this.sendPageCallback(browser, data.targetCallbackID, details);
};
}
this.showInfo(
window,
target,
data.title,
data.text,
iconURL,
buttons,
infoOptions
);
})
.catch(log.error);
break;
}
case "hideInfo": {
this.hideInfo(window);
break;
}
case "showMenu": {
this.noautohideMenus.add(data.name);
this.showMenu(window, data.name, () => {
if (typeof data.showCallbackID == "string") {
this.sendPageCallback(browser, data.showCallbackID);
}
});
break;
}
case "hideMenu": {
this.noautohideMenus.delete(data.name);
this.hideMenu(window, data.name);
break;
}
case "showNewTab": {
this.showNewTab(window, browser);
break;
}
case "getConfiguration": {
if (typeof data.configuration != "string") {
log.warn("getConfiguration: No configuration option specified");
return false;
}
this.getConfiguration(
browser,
window,
data.configuration,
data.callbackID
);
break;
}
case "setConfiguration": {
if (typeof data.configuration != "string") {
log.warn("setConfiguration: No configuration option specified");
return false;
}
this.setConfiguration(window, data.configuration, data.value);
break;
}
case "openPreferences": {
if (typeof data.pane != "string" && typeof data.pane != "undefined") {
log.warn("openPreferences: Invalid pane specified");
return false;
}
window.openPreferences(data.pane);
break;
}
case "showFirefoxAccounts": {
Promise.resolve()
.then(() => {
return data.email
? FxAccounts.config.promiseEmailURI(
data.email,
data.entrypoint || "uitour"
)
: FxAccounts.config.promiseConnectAccountURI(
data.entrypoint || "uitour"
);
})
.then(uri => {
const url = new URL(uri);
// Call our helper to validate extraURLParams and populate URLSearchParams
if (!this._populateURLParams(url, data.extraURLParams)) {
log.warn("showFirefoxAccounts: invalid campaign args specified");
return;
}
// We want to replace the current tab.
browser.loadURI(url.href, {
triggeringPrincipal: Services.scriptSecurityManager.createNullPrincipal(
{}
),
});
});
break;
}
case "showConnectAnotherDevice": {
FxAccounts.config
.promiseConnectDeviceURI(data.entrypoint || "uitour")
.then(uri => {
const url = new URL(uri);
// Call our helper to validate extraURLParams and populate URLSearchParams
if (!this._populateURLParams(url, data.extraURLParams)) {
log.warn(
"showConnectAnotherDevice: invalid campaign args specified"
);
return;
}
// We want to replace the current tab.
browser.loadURI(url.href, {
triggeringPrincipal: Services.scriptSecurityManager.createNullPrincipal(
{}
),
});
});
break;
}
case "resetFirefox": {
// Open a reset profile dialog window.
if (ResetProfile.resetSupported()) {
ResetProfile.openConfirmationDialog(window);
}
break;
}
case "addNavBarWidget": {
// Add a widget to the toolbar
let targetPromise = this.getTarget(window, data.name);
targetPromise
.then(target => {
this.addNavBarWidget(target, browser, data.callbackID);
})
.catch(log.error);
break;
}
case "setDefaultSearchEngine": {
let enginePromise = this.selectSearchEngine(data.identifier);
enginePromise.catch(Cu.reportError);
break;
}
case "setTreatmentTag": {
let name = data.name;
let value = data.value;
Services.prefs.setStringPref("browser.uitour.treatment." + name, value);
// The notification is only meant to be used in tests.
UITourHealthReport.recordTreatmentTag(name, value).then(() =>
this.notify("TreatmentTag:TelemetrySent")
);
break;
}
case "getTreatmentTag": {
let name = data.name;
let value;
try {
value = Services.prefs.getStringPref(
"browser.uitour.treatment." + name
);
} catch (ex) {}
this.sendPageCallback(browser, data.callbackID, { value });
break;
}
case "setSearchTerm": {
let targetPromise = this.getTarget(window, "search");
targetPromise.then(target => {
let searchbar = target.node;
searchbar.value = data.term;
searchbar.updateGoButtonVisibility();
});
break;
}
case "openSearchPanel": {
let targetPromise = this.getTarget(window, "search");
targetPromise
.then(target => {
let searchbar = target.node;
if (searchbar.textbox.open) {
this.sendPageCallback(browser, data.callbackID);
} else {
let onPopupShown = () => {
searchbar.textbox.popup.removeEventListener(
"popupshown",
onPopupShown
);
this.sendPageCallback(browser, data.callbackID);
};
searchbar.textbox.popup.addEventListener(
"popupshown",
onPopupShown
);
searchbar.openSuggestionsPanel();
}
})
.catch(Cu.reportError);
break;
}
case "ping": {
if (typeof data.callbackID == "string") {
this.sendPageCallback(browser, data.callbackID);
}
break;
}
case "forceShowReaderIcon": {
AboutReaderParent.forceShowReaderIcon(browser);
break;
}
case "toggleReaderMode": {
let targetPromise = this.getTarget(window, "readerMode-urlBar");
targetPromise.then(target => {
AboutReaderParent.toggleReaderMode({ target: target.node });
});
break;
}
case "closeTab": {
// Find the <tabbrowser> element of the <browser> for which the event
// was generated originally. If the browser where the UI tour is loaded
// is windowless, just ignore the request to close the tab. The request
// is also ignored if this is the only tab in the window.
let tabBrowser = browser.ownerGlobal.gBrowser;
if (tabBrowser && tabBrowser.browsers.length > 1) {
tabBrowser.removeTab(tabBrowser.getTabForBrowser(browser));
}
break;
}
case "showProtectionReport": {
this.showProtectionReport(window, browser);
break;
}
}
// For performance reasons, only call initForBrowser if we did something
// that will require a teardownTourForBrowser call later.
// getConfiguration (called from about:home) doesn't require any future
// uninitialization.
if (action != "getConfiguration") {
this.initForBrowser(browser, window);
}
return true;
},
initForBrowser(aBrowser, window) {
let gBrowser = window.gBrowser;
if (gBrowser) {
gBrowser.tabContainer.addEventListener("TabSelect", this);
}
if (!this.tourBrowsersByWindow.has(window)) {
this.tourBrowsersByWindow.set(window, new Set());
}
this.tourBrowsersByWindow.get(window).add(aBrowser);
Services.obs.addObserver(this, "message-manager-close");
window.addEventListener("SSWindowClosing", this);
},
handleEvent(aEvent) {
log.debug("handleEvent: type =", aEvent.type, "event =", aEvent);
switch (aEvent.type) {
case "TabSelect": {
let window = aEvent.target.ownerGlobal;
// Teardown the browser of the tab we just switched away from.
if (aEvent.detail && aEvent.detail.previousTab) {
let previousTab = aEvent.detail.previousTab;
let openTourWindows = this.tourBrowsersByWindow.get(window);
if (openTourWindows.has(previousTab.linkedBrowser)) {
this.teardownTourForBrowser(
window,
previousTab.linkedBrowser,
false
);
}
}
break;
}
case "SSWindowClosing": {
let window = aEvent.target;
this.teardownTourForWindow(window);
break;
}
}
},
observe(aSubject, aTopic, aData) {
log.debug("observe: aTopic =", aTopic);
switch (aTopic) {
// The browser message manager is disconnected when the <browser> is
// destroyed and we want to teardown at that point.
case "message-manager-close": {
for (let window of Services.wm.getEnumerator("navigator:browser")) {
if (window.closed) {
continue;
}
let tourBrowsers = this.tourBrowsersByWindow.get(window);
if (!tourBrowsers) {
continue;
}
for (let browser of tourBrowsers) {
let messageManager = browser.messageManager;
if (!messageManager || aSubject == messageManager) {
this.teardownTourForBrowser(window, browser, true);
}
}
}
break;
}
}
},
// Given a string that is a JSONified represenation of an object with
// additional "flow_id", "flow_begin_time", "device_id", utm_* URL params
// that should be appended, validate and append them to the passed URL object.
// Returns true if the params were validated and appended, and false if the
// request should be ignored.
_populateURLParams(url, extraURLParams) {
const FLOW_ID_LENGTH = 64;
const FLOW_BEGIN_TIME_LENGTH = 13;
// We are extra paranoid about what params we allow to be appended.
if (typeof extraURLParams == "undefined") {
// no params, so it's all good.
return true;
}
if (typeof extraURLParams != "string") {
log.warn("_populateURLParams: extraURLParams is not a string");
return false;
}
let urlParams;
try {
if (extraURLParams) {
urlParams = JSON.parse(extraURLParams);
if (typeof urlParams != "object") {
log.warn(
"_populateURLParams: extraURLParams is not a stringified object"
);
return false;
}
}
} catch (ex) {
log.warn("_populateURLParams: extraURLParams is not a JSON object");
return false;
}
if (urlParams) {
// Expected to JSON parse the following for FxA flow parameters:
//
// {String} flow_id - Flow Id, such as '5445b28b8b7ba6cf71e345f8fff4bc59b2a514f78f3e2cc99b696449427fd445'
// {Number} flow_begin_time - Flow begin timestamp, such as 1590780440325
// {String} device_id - Device Id, such as '7e450f3337d3479b8582ea1c9bb5ba6c'
if (
(urlParams.flow_begin_time &&
urlParams.flow_begin_time.toString().length !==
FLOW_BEGIN_TIME_LENGTH) ||
(urlParams.flow_id && urlParams.flow_id.length !== FLOW_ID_LENGTH)
) {
log.warn(
"_populateURLParams: flow parameters are not properly structured"
);
return false;
}
// The regex that the name of each param must match - there's no
// character restriction on the value - they will be escaped as necessary.
let reSimpleString = /^[-_a-zA-Z0-9]*$/;
for (let name in urlParams) {
let value = urlParams[name];
const validName =
name.startsWith("utm_") ||
name === "entrypoint_experiment" ||
name === "entrypoint_variation" ||
name === "flow_begin_time" ||
name === "flow_id" ||
name === "device_id";
if (
typeof name != "string" ||
!validName ||
!reSimpleString.test(name)
) {
log.warn("_populateURLParams: invalid campaign param specified");
return false;
}
url.searchParams.append(name, value);
}
}
return true;
},
/**
* Tear down a tour from a tab e.g. upon switching/closing tabs.
*/
async teardownTourForBrowser(aWindow, aBrowser, aTourPageClosing = false) {
log.debug(
"teardownTourForBrowser: aBrowser = ",
aBrowser,
aTourPageClosing
);
let openTourBrowsers = this.tourBrowsersByWindow.get(aWindow);
if (aTourPageClosing && openTourBrowsers) {
openTourBrowsers.delete(aBrowser);
}
this.hideHighlight(aWindow);
this.hideInfo(aWindow);
let panels = [
{
name: "appMenu",
node: aWindow.PanelUI.panel,
events: [
["popuphidden", this.onPanelHidden],
["popuphiding", this.onAppMenuHiding],
["ViewShowing", this.onAppMenuSubviewShowing],
],
},
{
name: "pageActionPanel",
node: aWindow.BrowserPageActions.panelNode,
events: [
["popuphidden", this.onPanelHidden],
["popuphiding", this.onPageActionPanelHiding],
["ViewShowing", this.onPageActionPanelSubviewShowing],
],
},
];
for (let panel of panels) {
// Ensure the menu panel is hidden and clean up panel listeners after calling hideMenu.
if (panel.node.state != "closed") {
await new Promise(resolve => {
panel.node.addEventListener("popuphidden", resolve, { once: true });
this.hideMenu(aWindow, panel.name);
});
}
for (let [name, listener] of panel.events) {
panel.node.removeEventListener(name, listener);
}
}
this.noautohideMenus.clear();
// If there are no more tour tabs left in the window, teardown the tour for the whole window.
if (!openTourBrowsers || openTourBrowsers.size == 0) {
this.teardownTourForWindow(aWindow);
}
},
/**
* Tear down all tours for a ChromeWindow.
*/
teardownTourForWindow(aWindow) {
log.debug("teardownTourForWindow");
aWindow.gBrowser.tabContainer.removeEventListener("TabSelect", this);
aWindow.removeEventListener("SSWindowClosing", this);
this.tourBrowsersByWindow.delete(aWindow);
},
// This function is copied to UITourListener.
isSafeScheme(aURI) {
let allowedSchemes = new Set(["https", "about"]);
if (!Services.prefs.getBoolPref("browser.uitour.requireSecure")) {
allowedSchemes.add("http");
}
if (!allowedSchemes.has(aURI.scheme)) {
log.error("Unsafe scheme:", aURI.scheme);
return false;
}
return true;
},
resolveURL(aBrowser, aURL) {
try {
let uri = Services.io.newURI(aURL, null, aBrowser.currentURI);
if (!this.isSafeScheme(uri)) {
return null;
}
return uri.spec;
} catch (e) {}
return null;
},
sendPageCallback(aBrowser, aCallbackID, aData = {}) {
let detail = { data: aData, callbackID: aCallbackID };
log.debug("sendPageCallback", detail);
let contextToVisit = aBrowser.browsingContext;
let global = contextToVisit.currentWindowGlobal;
let actor = global.getActor("UITour");
actor.sendAsyncMessage("UITour:SendPageCallback", detail);
},
isElementVisible(aElement) {
let targetStyle = aElement.ownerGlobal.getComputedStyle(aElement);
return (
!aElement.ownerDocument.hidden &&
targetStyle.display != "none" &&
targetStyle.visibility == "visible"
);
},
getTarget(aWindow, aTargetName, aSticky = false) {
log.debug("getTarget:", aTargetName);
if (typeof aTargetName != "string" || !aTargetName) {
log.warn("getTarget: Invalid target name specified");
return Promise.reject("Invalid target name specified");
}
let targetObject = this.targets.get(aTargetName);
if (!targetObject) {
log.warn(
"getTarget: The specified target name is not in the allowed set"
);
return Promise.reject(
"The specified target name is not in the allowed set"
);
}
return new Promise(resolve => {
let targetQuery = targetObject.query;
aWindow.PanelUI.ensureReady()
.then(() => {
let node;
if (typeof targetQuery == "function") {
try {
node = targetQuery(aWindow.document);
} catch (ex) {
log.warn("getTarget: Error running target query:", ex);
node = null;
}
} else {
node = this.getNodeFromDocument(aWindow.document, targetQuery);
}
resolve({
addTargetListener: targetObject.addTargetListener,
infoPanelOffsetX: targetObject.infoPanelOffsetX,
infoPanelOffsetY: targetObject.infoPanelOffsetY,
infoPanelPosition: targetObject.infoPanelPosition,
node,
removeTargetListener: targetObject.removeTargetListener,
targetName: aTargetName,
widgetName: targetObject.widgetName,
allowAdd: targetObject.allowAdd,
});
})
.catch(log.error);
});
},
targetIsInAppMenu(aTarget) {
let targetElement = aTarget.node;
// Use the widget for filtering if it exists since the target may be the icon inside.
if (aTarget.widgetName) {
let doc = aTarget.node.ownerGlobal.document;
targetElement =
doc.getElementById(aTarget.widgetName) ||
PanelMultiView.getViewNode(doc, aTarget.widgetName);
}
return targetElement.id.startsWith("appMenu-");
},
targetIsInPageActionPanel(aTarget) {
return aTarget.node.id.startsWith("pageAction-panel-");
},
/**
* Called before opening or after closing a highlight or an info tooltip to see if
* we need to open or close the menu to see the annotation's anchor.
*
* @param {ChromeWindow} aWindow the chrome window
* @param {bool} aShouldOpen true means we should open the menu, otherwise false
* @param {String} aMenuName "appMenu" or "pageActionPanel"
* @param {Object} aOptions Extra config arguments, example `autohide: true`.
*/
_setMenuStateForAnnotation(aWindow, aShouldOpen, aMenuName, aOptions = {}) {
log.debug("_setMenuStateForAnnotation: Menu is ", aMenuName);
log.debug(
"_setMenuStateForAnnotation: Menu is expected to be:",
aShouldOpen ? "open" : "closed"
);
let menu =
aMenuName == "appMenu"
? aWindow.PanelUI.panel
: aWindow.BrowserPageActions.panelNode;
// If the panel is in the desired state, we're done.
let panelIsOpen = menu.state != "closed";
if (aShouldOpen == panelIsOpen) {
log.debug("_setMenuStateForAnnotation: Menu already in expected state");
return Promise.resolve();
}
// Actually show or hide the menu
let promise = null;
if (aShouldOpen) {
log.debug("_setMenuStateForAnnotation: Opening the menu");
promise = new Promise(resolve => {
this.showMenu(aWindow, aMenuName, resolve, aOptions);
});
} else if (!this.noautohideMenus.has(aMenuName)) {
// If the menu was opened explictly by api user through `Mozilla.UITour.showMenu`,
// it should be closed explictly by api user through `Mozilla.UITour.hideMenu`.
// So we shouldn't get to here to close it for the highlight/info annotation.
log.debug("_setMenuStateForAnnotation: Closing the menu");
promise = new Promise(resolve => {
menu.addEventListener("popuphidden", resolve, { once: true });
this.hideMenu(aWindow, aMenuName);
});
}
return promise;
},
/**
* Ensure the target's visibility and the open/close states of menus for the target.
*
* @param {ChromeWindow} aChromeWindow The chrome window
* @param {Object} aTarget The target on which we show highlight or show info.
* @param {Object} options Extra config arguments, example `autohide: true`.
*/
async _ensureTarget(aChromeWindow, aTarget, aOptions = {}) {
let shouldOpenAppMenu = false;
let shouldOpenPageActionPanel = false;
if (this.targetIsInAppMenu(aTarget)) {
shouldOpenAppMenu = true;
} else if (
this.targetIsInPageActionPanel(aTarget) &&
!UITour.protonEnabled
) {
shouldOpenPageActionPanel = true;
// Ensure the panel visibility so as to ensure the visibility of the target
// element inside the panel otherwise we would be rejected in the below
// `isElementVisible` checking.
aChromeWindow.BrowserPageActions.panelNode.hidden = false;
}
// Prevent showing a panel at an undefined position, but when it's tucked
// away inside a panel, we skip this check.
if (
!aTarget.node.closest("panelview") &&
!this.isElementVisible(aTarget.node)
) {
return Promise.reject(
`_ensureTarget: Reject the ${aTarget.name ||
aTarget.targetName} target since it isn't visible.`
);
}
let menuToOpen = null;
let menuClosePromises = [];
if (shouldOpenAppMenu) {
menuToOpen = "appMenu";
menuClosePromises.push(
this._setMenuStateForAnnotation(aChromeWindow, false, "pageActionPanel")
);
} else if (shouldOpenPageActionPanel) {
menuToOpen = "pageActionPanel";
menuClosePromises.push(
this._setMenuStateForAnnotation(aChromeWindow, false, "appMenu")
);
} else {
menuClosePromises.push(
this._setMenuStateForAnnotation(aChromeWindow, false, "appMenu")
);
menuClosePromises.push(
this._setMenuStateForAnnotation(aChromeWindow, false, "pageActionPanel")
);
}
let promise = Promise.all(menuClosePromises);
await promise;
if (menuToOpen) {
promise = this._setMenuStateForAnnotation(
aChromeWindow,
true,
menuToOpen,
aOptions
);
}
return promise;
},
/**
* The node to which a highlight or notification(-popup) is anchored is sometimes
* obscured because it may be inside an overflow menu. This function should figure
* that out and offer the overflow chevron as an alternative.
*
* @param {ChromeWindow} aChromeWindow The chrome window
* @param {Object} aTarget The target object whose node is supposed to be the anchor
* @type {Node}
*/
async _correctAnchor(aChromeWindow, aTarget) {
// PanelMultiView's like the AppMenu might shuffle the DOM, which might result
// in our anchor being invalidated if it was anonymous content (since the XBL
// binding it belonged to got destroyed). We work around this by re-querying for
// the node and stuffing it into the old anchor structure.
let refreshedTarget = await this.getTarget(
aChromeWindow,
aTarget.targetName
);
let node = (aTarget.node = refreshedTarget.node);
// If the target is in the overflow panel, just return the overflow button.
if (node.closest("#widget-overflow-mainView")) {
return CustomizableUI.getWidget(node.id).forWindow(aChromeWindow).anchor;
}
return node;
},
/**
* @param aChromeWindow The chrome window that the highlight is in. Necessary since some targets
* are in a sub-frame so the defaultView is not the same as the chrome
* window.
* @param aTarget The element to highlight.
* @param aEffect (optional) The effect to use from UITour.highlightEffects or "none".
* @param aOptions (optional) Extra config arguments, example `autohide: true`.
* @see UITour.highlightEffects
*/
async showHighlight(aChromeWindow, aTarget, aEffect = "none", aOptions = {}) {
let showHighlightElement = aAnchorEl => {
let highlighter = this.getHighlightAndMaybeCreate(aChromeWindow.document);
let effect = aEffect;
if (effect == "random") {
// Exclude "random" from the randomly selected effects.
let randomEffect =
1 + Math.floor(Math.random() * (this.highlightEffects.length - 1));
if (randomEffect == this.highlightEffects.length) {
randomEffect--;
} // On the order of 1 in 2^62 chance of this happening.
effect = this.highlightEffects[randomEffect];
}
// Toggle the effect attribute to "none" and flush layout before setting it so the effect plays.
highlighter.setAttribute("active", "none");
aChromeWindow.getComputedStyle(highlighter).animationName;
highlighter.setAttribute("active", effect);
highlighter.parentElement.setAttribute("targetName", aTarget.targetName);
highlighter.parentElement.hidden = false;
let highlightAnchor = aAnchorEl;
let targetRect = highlightAnchor.getBoundingClientRect();
let highlightHeight = targetRect.height;
let highlightWidth = targetRect.width;
if (
this.targetIsInAppMenu(aTarget) ||
this.targetIsInPageActionPanel(aTarget)
) {
highlighter.classList.remove("rounded-highlight");
} else {
highlighter.classList.add("rounded-highlight");
}
if (
highlightAnchor.classList.contains("toolbarbutton-1") &&
highlightAnchor.getAttribute("cui-areatype") === "toolbar" &&
highlightAnchor.getAttribute("overflowedItem") !== "true"
) {
// A toolbar button in navbar has its clickable area an
// inner-contained square while the button component itself is a tall
// rectangle. We adjust the highlight area to a square as well.
highlightHeight = highlightWidth;
}
highlighter.style.height = highlightHeight + "px";
highlighter.style.width = highlightWidth + "px";
// Close a previous highlight so we can relocate the panel.
if (
highlighter.parentElement.state == "showing" ||
highlighter.parentElement.state == "open"
) {
log.debug("showHighlight: Closing previous highlight first");
highlighter.parentElement.hidePopup();
}
/* The "overlap" position anchors from the top-left but we want to centre highlights at their
minimum size. */
let highlightWindow = aChromeWindow;
let highlightStyle = highlightWindow.getComputedStyle(highlighter);
let highlightHeightWithMin = Math.max(
highlightHeight,
parseFloat(highlightStyle.minHeight)
);
let highlightWidthWithMin = Math.max(
highlightWidth,
parseFloat(highlightStyle.minWidth)
);
let offsetX = (targetRect.width - highlightWidthWithMin) / 2;
let offsetY = (targetRect.height - highlightHeightWithMin) / 2;
this._addAnnotationPanelMutationObserver(highlighter.parentElement);
highlighter.parentElement.openPopup(
highlightAnchor,
"overlap",
offsetX,
offsetY
);
};
try {
await this._ensureTarget(aChromeWindow, aTarget, aOptions);
let anchorEl = await this._correctAnchor(aChromeWindow, aTarget);
showHighlightElement(anchorEl);
} catch (e) {
log.warn(e);
}
},
_hideHighlightElement(aWindow) {
let highlighter = this.getHighlightAndMaybeCreate(aWindow.document);
this._removeAnnotationPanelMutationObserver(highlighter.parentElement);
highlighter.parentElement.hidePopup();
highlighter.removeAttribute("active");
},
hideHighlight(aWindow) {
this._hideHighlightElement(aWindow);
this._setMenuStateForAnnotation(aWindow, false, "appMenu");
this._setMenuStateForAnnotation(aWindow, false, "pageActionPanel");
},
/**
* Show an info panel.
*
* @param {ChromeWindow} aChromeWindow
* @param {Node} aAnchor
* @param {String} [aTitle=""]
* @param {String} [aDescription=""]
* @param {String} [aIconURL=""]
* @param {Object[]} [aButtons=[]]
* @param {Object} [aOptions={}]
* @param {String} [aOptions.closeButtonCallback]
* @param {String} [aOptions.targetCallback]
*/
async showInfo(
aChromeWindow,
aAnchor,
aTitle = "",
aDescription = "",
aIconURL = "",
aButtons = [],
aOptions = {}
) {
let showInfoElement = aAnchorEl => {
aAnchorEl.focus();
let document = aChromeWindow.document;
let tooltip = this.getTooltipAndMaybeCreate(document);
let tooltipTitle = document.getElementById("UITourTooltipTitle");
let tooltipDesc = document.getElementById("UITourTooltipDescription");
let tooltipIcon = document.getElementById("UITourTooltipIcon");
let tooltipButtons = document.getElementById("UITourTooltipButtons");
if (tooltip.state == "showing" || tooltip.state == "open") {
tooltip.hidePopup();
}
tooltipTitle.textContent = aTitle || "";
tooltipDesc.textContent = aDescription || "";
tooltipIcon.src = aIconURL || "";
tooltipIcon.hidden = !aIconURL;
while (tooltipButtons.firstChild) {
tooltipButtons.firstChild.remove();
}
for (let button of aButtons) {
let isButton = button.style != "text";
let el = document.createXULElement(isButton ? "button" : "label");
el.setAttribute(isButton ? "label" : "value", button.label);
if (isButton) {
if (button.iconURL) {
el.setAttribute("image", button.iconURL);
}
if (button.style == "link") {
el.setAttribute("class", "button-link");
}
if (button.style == "primary") {
el.setAttribute("class", "button-primary");
}
// Don't close the popup or call the callback for style=text as they
// aren't links/buttons.
let callback = button.callback;
el.addEventListener("command", event => {
tooltip.hidePopup();
callback(event);
});
}
tooltipButtons.appendChild(el);
}
tooltipButtons.hidden = !aButtons.length;
let tooltipClose = document.getElementById("UITourTooltipClose");
let closeButtonCallback = event => {
this.hideInfo(document.defaultView);
if (aOptions && aOptions.closeButtonCallback) {
aOptions.closeButtonCallback();
}
};
tooltipClose.addEventListener("command", closeButtonCallback);
let targetCallback = event => {
let details = {
target: aAnchor.targetName,
type: event.type,
};
aOptions.targetCallback(details);
};
if (aOptions.targetCallback && aAnchor.addTargetListener) {
aAnchor.addTargetListener(document, targetCallback);
}
tooltip.addEventListener(
"popuphiding",
function(event) {
tooltipClose.removeEventListener("command", closeButtonCallback);
if (aOptions.targetCallback && aAnchor.removeTargetListener) {
aAnchor.removeTargetListener(document, targetCallback);
}
},
{ once: true }
);
tooltip.setAttribute("targetName", aAnchor.targetName);
let alignment = "bottomcenter topright";
if (aAnchor.infoPanelPosition) {
alignment = aAnchor.infoPanelPosition;
}
let { infoPanelOffsetX: xOffset, infoPanelOffsetY: yOffset } = aAnchor;
this._addAnnotationPanelMutationObserver(tooltip);
tooltip.openPopup(aAnchorEl, alignment, xOffset || 0, yOffset || 0);
if (tooltip.state == "closed") {
document.defaultView.addEventListener(
"endmodalstate",
function() {
tooltip.openPopup(aAnchorEl, alignment);
},
{ once: true }
);
}
};
try {
await this._ensureTarget(aChromeWindow, aAnchor);
let anchorEl = await this._correctAnchor(aChromeWindow, aAnchor);
showInfoElement(anchorEl);
} catch (e) {
log.warn(e);
}
},
getHighlightContainerAndMaybeCreate(document) {
let highlightContainer = document.getElementById(
"UITourHighlightContainer"
);
if (!highlightContainer) {
let wrapper = document.getElementById("UITourHighlightTemplate");
wrapper.replaceWith(wrapper.content);
highlightContainer = document.getElementById("UITourHighlightContainer");
}
return highlightContainer;
},
getTooltipAndMaybeCreate(document) {
let tooltip = document.getElementById("UITourTooltip");
if (!tooltip) {
let wrapper = document.getElementById("UITourTooltipTemplate");
wrapper.replaceWith(wrapper.content);
tooltip = document.getElementById("UITourTooltip");
}
return tooltip;
},
getHighlightAndMaybeCreate(document) {
let highlight = document.getElementById("UITourHighlight");
if (!highlight) {
let wrapper = document.getElementById("UITourHighlightTemplate");
wrapper.replaceWith(wrapper.content);
highlight = document.getElementById("UITourHighlight");
}
return highlight;
},
isInfoOnTarget(aChromeWindow, aTargetName) {
let document = aChromeWindow.document;
let tooltip = this.getTooltipAndMaybeCreate(document);
return (
tooltip.getAttribute("targetName") == aTargetName &&
tooltip.state != "closed"
);
},
_hideInfoElement(aWindow) {
let document = aWindow.document;
let tooltip = this.getTooltipAndMaybeCreate(document);
this._removeAnnotationPanelMutationObserver(tooltip);
tooltip.hidePopup();
let tooltipButtons = document.getElementById("UITourTooltipButtons");
while (tooltipButtons.firstChild) {
tooltipButtons.firstChild.remove();
}
},
hideInfo(aWindow) {
this._hideInfoElement(aWindow);
this._setMenuStateForAnnotation(aWindow, false, "appMenu");
this._setMenuStateForAnnotation(aWindow, false, "pageActionPanel");
},
showMenu(aWindow, aMenuName, aOpenCallback = null, aOptions = {}) {
log.debug("showMenu:", aMenuName);
function openMenuButton(aMenuBtn) {
if (!aMenuBtn || !aMenuBtn.hasMenu() || aMenuBtn.open) {
if (aOpenCallback) {
aOpenCallback();
}
return;
}
if (aOpenCallback) {
aMenuBtn.addEventListener("popupshown", aOpenCallback, { once: true });
}
aMenuBtn.openMenu(true);
}
if (
aMenuName == "appMenu" ||
(aMenuName == "pageActionPanel" && !UITour.protonEnabled)
) {
let menu = {
onPanelHidden: this.onPanelHidden,
};
if (aMenuName == "appMenu") {
menu.node = aWindow.PanelUI.panel;
menu.onPopupHiding = this.onAppMenuHiding;
menu.onViewShowing = this.onAppMenuSubviewShowing;
menu.show = () => aWindow.PanelUI.show();
} else {