[SidePanel API] Adds four examples (#890)

* Add global side panel * Add multiple panes sample * Add dictionary side panel sample * Add google.com and action click extension * Switch to lowercase * Fix name * Fix links * Add screenshots and links * Tweak google sp * Remove logs * Add install reason * Add default title to action * Change extension names Update readme's * Tweak comments Add aside * increase picture size * Add screenshots * Add spaces * Update screenshots * Update img size * Refactor multiple panels * rename action folder to site-specific * Switch to Side Panel API * Apply suggestions from Tech review p2 Thanks Oliver! Co-authored-by: Oliver Dunk <oliverdunk@google.com> * Add space Change variable --------- Co-authored-by: Oliver Dunk <oliverdunk@google.com>
GoogleChrome · May 3, 2023 · 064dde6 · 064dde6
1 parent dc5d34f
commit 064dde6
Show file tree

Hide file tree

Showing 29 changed files with 274 additions and 0 deletions.
diff --git a/functional-samples/cookbook.sidepanel-global/README.md b/functional-samples/cookbook.sidepanel-global/README.md
@@ -0,0 +1,15 @@
+# Global Side panel example
+
+This example demonstrates how to display the same side panel on every site using the [Side Panel API](https://developer.chrome.com/docs/extensions/reference/sidePanel/).
+
+## Running this extension
+
+1. Clone this repository.
+2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked).
+3. Open the side panel UI
+
+   <img src="https://wd.imgix.net/image/BhuKGJaIeLNPW9ehns59NfwqKxF2/2uFG8qxM7cqyMuXWlD9R.png?auto=format&w=400" alt="Global side panel">
+
+4. Choose the "Global side panel".
+
+   <img src="https://wd.imgix.net/image/BhuKGJaIeLNPW9ehns59NfwqKxF2/iidZp01nIEHRUjrpt6Hn.png?auto=format&w=700" alt="Global side panel">
diff --git a/functional-samples/cookbook.sidepanel-global/images/icon-128.png b/functional-samples/cookbook.sidepanel-global/images/icon-128.png
diff --git a/functional-samples/cookbook.sidepanel-global/images/icon-16.png b/functional-samples/cookbook.sidepanel-global/images/icon-16.png
diff --git a/functional-samples/cookbook.sidepanel-global/images/icon-48.png b/functional-samples/cookbook.sidepanel-global/images/icon-48.png
diff --git a/functional-samples/cookbook.sidepanel-global/manifest.json b/functional-samples/cookbook.sidepanel-global/manifest.json
@@ -0,0 +1,15 @@
+{
+  "manifest_version": 3,
+  "name": "Global side panel",
+  "version": "1.0",
+  "description": "Sidepanel declared only in the manifest visible to all sites",
+  "icons": {
+    "16": "images/icon-16.png",
+    "48": "images/icon-48.png",
+    "128": "images/icon-128.png"
+  },
+  "side_panel": {
+    "default_path": "sidepanel.html"
+  },
+  "permissions": ["sidePanel"]
+}
diff --git a/functional-samples/cookbook.sidepanel-global/sidepanel.html b/functional-samples/cookbook.sidepanel-global/sidepanel.html
@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>My Sidepanel</title>
+  </head>
+  <body>
+    <h1>All sites sidepanel extension</h1>
+    <p>This side panel is enabled on all sites</p>
+    <script src="sidepanel.js"></script>
+  </body>
+</html>
diff --git a/functional-samples/cookbook.sidepanel-global/sidepanel.js b/functional-samples/cookbook.sidepanel-global/sidepanel.js
@@ -0,0 +1 @@
+console.log('sidepanel.js');
diff --git a/functional-samples/cookbook.sidepanel-multiple/README.md b/functional-samples/cookbook.sidepanel-multiple/README.md
@@ -0,0 +1,16 @@
+# Multiple side panels example
+
+You can use [`sidepanel.getOptions()`](https://developer.chrome.com/docs/extensions/reference/sidePanel/#method-getOptions) to retrieve the current side panel and switch between side panels. This example sets a welcome side panel when the extension is first installed, then when the user navigates to a different tab, it replaces it with the main side panel.
+
+## Running this extension
+
+1. Clone this repository.
+2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked).
+3. Open the side panel UI
+4. Choose "Multiple side panels" to see the welcome page.
+
+<img src="https://wd.imgix.net/image/BhuKGJaIeLNPW9ehns59NfwqKxF2/dhSqpr4hqDX0EFy8NlzE.png?auto=format&w=600" alt="Welcome side panel">
+
+5. Navigate to https://developer.chrome.com to see the main side panel.
+
+<img src="https://wd.imgix.net/image/BhuKGJaIeLNPW9ehns59NfwqKxF2/vtTL1BW8HLukz7jlrqZb.png?auto=format&w=600" alt="Main side panel">
diff --git a/functional-samples/cookbook.sidepanel-multiple/images/icon-128.png b/functional-samples/cookbook.sidepanel-multiple/images/icon-128.png
diff --git a/functional-samples/cookbook.sidepanel-multiple/images/icon-16.png b/functional-samples/cookbook.sidepanel-multiple/images/icon-16.png
diff --git a/functional-samples/cookbook.sidepanel-multiple/images/icon-48.png b/functional-samples/cookbook.sidepanel-multiple/images/icon-48.png
diff --git a/functional-samples/cookbook.sidepanel-multiple/manifest.json b/functional-samples/cookbook.sidepanel-multiple/manifest.json
@@ -0,0 +1,16 @@
+{
+  "manifest_version": 3,
+  "name": "Multiple side panels",
+  "version": "1.0",
+  "description": "Displays welcome side panel on installation, then shows the main panel",
+  "background": {
+    "service_worker": "service-worker.js"
+  },
+  "icons": {
+    "16": "images/icon-16.png",
+    "48": "images/icon-48.png",
+    "128": "images/icon-128.png"
+  },
+  "permissions": ["sidePanel"]
+}
+
diff --git a/functional-samples/cookbook.sidepanel-multiple/service-worker.js b/functional-samples/cookbook.sidepanel-multiple/service-worker.js
@@ -0,0 +1,13 @@
+const welcomePage = 'sidepanels/welcome-sp.html';
+const mainPage = 'sidepanels/main-sp.html';
+
+chrome.runtime.onInstalled.addListener(() => {
+  chrome.sidePanel.setOptions({ path: welcomePage });
+});
+
+chrome.tabs.onActivated.addListener(async ({ tabId }) => {
+  const { path } = await chrome.sidePanel.getOptions({ tabId });
+  if (path === welcomePage) {
+    chrome.sidePanel.setOptions({ path: mainPage });
+  }
+});
diff --git a/functional-samples/cookbook.sidepanel-multiple/sidepanels/main-sp.html b/functional-samples/cookbook.sidepanel-multiple/sidepanels/main-sp.html
@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>My Sidepanel extension</title>
+  </head>
+  <body>
+    <h1>This is the main side panel</h1>
+    <p>Use this extension to make your dreams come true!</p>
+  </body>
+</html>
diff --git a/functional-samples/cookbook.sidepanel-multiple/sidepanels/welcome-sp.html b/functional-samples/cookbook.sidepanel-multiple/sidepanels/welcome-sp.html
@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Welcome to this side panel</title>
+  </head>
+  <body>
+    <h1>Welcome!</h1>
+    <p>Thank you for installing this side panel extension</p>
+  </body>
+</html>
diff --git a/functional-samples/cookbook.sidepanel-site-specific/README.md b/functional-samples/cookbook.sidepanel-site-specific/README.md
@@ -0,0 +1,15 @@
+# Site-specific side panel example
+
+This example demonstrates how to display the side panel only on google.com using the [Side Panel API](https://developer.chrome.com/docs/extensions/reference/sidePanel/). It also allows users to open the side panel by clicking on the [action icon](https://developer.chrome.com/docs/extensions/reference/action/) or a keyboard shortcut.
+
+## Running this extension
+
+1. Clone this repository.
+2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked).
+3. [Pin](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#pin) the extension.
+4. Go to https://www.google.com.
+5. Click on the action icon to open the side panel.
+
+💡 You can also open the side panel by pressing `Ctrl+B` (Windows) or `Cmd+B` (macOS).
+
+<img src="https://wd.imgix.net/image/BhuKGJaIeLNPW9ehns59NfwqKxF2/3vhkSp1cBQOydpYZoRbD.png?auto=format&w=700" alt="Google.com side panel">
diff --git a/functional-samples/cookbook.sidepanel-site-specific/images/icon-128.png b/functional-samples/cookbook.sidepanel-site-specific/images/icon-128.png
diff --git a/functional-samples/cookbook.sidepanel-site-specific/images/icon-16.png b/functional-samples/cookbook.sidepanel-site-specific/images/icon-16.png
diff --git a/functional-samples/cookbook.sidepanel-site-specific/images/icon-48.png b/functional-samples/cookbook.sidepanel-site-specific/images/icon-48.png
diff --git a/functional-samples/cookbook.sidepanel-site-specific/manifest.json b/functional-samples/cookbook.sidepanel-site-specific/manifest.json
@@ -0,0 +1,26 @@
+{
+  "manifest_version": 3,
+  "name": "Site-specific side panel",
+  "version": "1.0",
+  "description": "Use the action icon or keyboard shortcut to open the side panel on google.com",
+  "background": {
+    "service_worker": "service-worker.js"
+  },
+  "action": {
+    "default_title": "Click to open panel"
+  },
+  "permissions": ["sidePanel", "tabs"],
+  "commands": {
+    "_execute_action": {
+      "suggested_key": {
+        "default": "Ctrl+B",
+        "mac": "Command+B"
+      }
+    }
+  },
+  "icons": {
+    "16": "images/icon-16.png",
+    "48": "images/icon-48.png",
+    "128": "images/icon-128.png"
+  }
+}
diff --git a/functional-samples/cookbook.sidepanel-site-specific/service-worker.js b/functional-samples/cookbook.sidepanel-site-specific/service-worker.js
@@ -0,0 +1,23 @@
+const GOOGLE_ORIGIN = 'https://www.google.com';
+
+// Allows users to open the side panel by clicking on the action toolbar icon
+chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
+
+chrome.tabs.onUpdated.addListener((tabId, info, tab) => {
+  if (!tab.url) return;
+  const url = new URL(tab.url);
+  // Enables the side panel on google.com
+  if (url.origin === GOOGLE_ORIGIN) {
+    chrome.sidePanel.setOptions({
+      tabId,
+      path: 'sidepanel.html',
+      enabled: true
+    });
+  } else {
+    // Disables the side panel on all other sites
+    chrome.sidePanel.setOptions({
+      tabId,
+      enabled: false
+    });
+  }
+});
diff --git a/functional-samples/cookbook.sidepanel-site-specific/sidepanel.html b/functional-samples/cookbook.sidepanel-site-specific/sidepanel.html
@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>My Google side panel extension</title>
+  </head>
+  <body>
+    <h1>My google.com sidepanel</h1>
+    <p>This side panel will display only on www.google.com</p>
+  </body>
+</html>
diff --git a/functional-samples/sample.sidepanel-dictionary/README.md b/functional-samples/sample.sidepanel-dictionary/README.md
@@ -0,0 +1,22 @@
+# Dictionary Side panel example
+
+This example allows users to right-click on a word and see the definition on the side panel using the [Side Panel API](https://developer.chrome.com/docs/extensions/reference/sidePanel/).
+
+NOTE: This example only defines the word extensions and popup.
+
+## Running this extension
+
+1. Clone this repository.
+2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked).
+3. Open the side panel UI
+4. Choose the "Dictionary side panel".
+
+<img src="https://wd.imgix.net/image/BhuKGJaIeLNPW9ehns59NfwqKxF2/9QJK3CNx71t67M3MlIUY.png?auto=format&w=385" alt="Dictionary side panel">
+
+5. Go to https://developer.chrome.com/docs/extensions/
+6. Right-click on the "Extensions" word.
+7. Choose the "Define" context menu
+
+You should see the definition on the side panel
+
+<img src="https://wd.imgix.net/image/BhuKGJaIeLNPW9ehns59NfwqKxF2/aC3zkJDPliNLXdvfugeU.png" alt="Dictionary extension context menu">
diff --git a/functional-samples/sample.sidepanel-dictionary/images/icon-128.png b/functional-samples/sample.sidepanel-dictionary/images/icon-128.png
diff --git a/functional-samples/sample.sidepanel-dictionary/images/icon-16.png b/functional-samples/sample.sidepanel-dictionary/images/icon-16.png
diff --git a/functional-samples/sample.sidepanel-dictionary/manifest.json b/functional-samples/sample.sidepanel-dictionary/manifest.json
@@ -0,0 +1,20 @@
+{
+  "name": "Dictionary side panel",
+  "version": "0.1",
+  "manifest_version": 3,
+  "description": "Provides definitions in the side panel.",
+  "background": {
+    "service_worker": "service-worker.js"
+  },
+  "icons": {
+    "128": "images/icon-128.png",
+    "16": "images/icon-16.png"
+  },
+  "side_panel": {
+    "default_path": "sidepanel.html"
+  },
+  "permissions": [
+    "sidePanel",
+    "contextMenus"
+  ]
+}
diff --git a/functional-samples/sample.sidepanel-dictionary/service-worker.js b/functional-samples/sample.sidepanel-dictionary/service-worker.js
@@ -0,0 +1,18 @@
+function setupContextMenu() {
+  chrome.contextMenus.create({
+    id: 'define-word',
+    title: 'Define',
+    contexts: ['selection']
+  });
+}
+
+chrome.runtime.onInstalled.addListener(() => {
+  setupContextMenu();
+});
+
+chrome.contextMenus.onClicked.addListener((data) => {
+  chrome.runtime.sendMessage({
+    name: 'define-word',
+    data: { value: data.selectionText }
+  });
+});
diff --git a/functional-samples/sample.sidepanel-dictionary/sidepanel.html b/functional-samples/sample.sidepanel-dictionary/sidepanel.html
@@ -0,0 +1,15 @@
+<html>
+  <head>
+    <title>Dictionary Side Panel</title>
+  </head>
+  <body>
+    <h1>Dictionary</h1>
+    <hr />
+    <p id="select-a-word">Select a word to see the definition.</p>
+    <div>
+      <h2 id="definition-word"></h2>
+      <p id="definition-text"></p>
+    </div>
+    <script src="sidepanel.js"></script>
+  </body>
+</html>
diff --git a/functional-samples/sample.sidepanel-dictionary/sidepanel.js b/functional-samples/sample.sidepanel-dictionary/sidepanel.js
@@ -0,0 +1,18 @@
+const words = {
+  extensions:
+    'Extensions are software programs, built on web technologies (such as HTML, CSS, and JavaScript) that enable users to customize the Chrome browsing experience.',
+  popup:
+    "A UI surface which appears when an extension's action icon is clicked."
+};
+
+chrome.runtime.onMessage.addListener(({ name, data }) => {
+  if (name === 'define-word') {
+    // Hide instructions.
+    document.body.querySelector('#select-a-word').style.display = 'none';
+
+    // Show word and definition.
+    document.body.querySelector('#definition-word').innerText = data.value;
+    document.body.querySelector('#definition-text').innerText =
+      words[data.value.toLowerCase()];
+  }
+});