This is part of a series of blog posts, and this one covers “How to create a Chrome Extension for a custom Editor”.
You can navigate through the series by clicking on the following topics:
- How to create a custom Editor in a React application;
- How to create a Chrome Extension for a custom Editor;
- How to create a VS Code Extension for a custom Editor;
- How to create a custom View;
- How to create a VS Code Extension for a custom View;
- How to create a more complex custom View;
- How to integrate a custom Editor, an existing Editors, and custom Views on a Web App;
Before we start, to develop a Chrome Extension, it’s important to notice their full capabilities, so take a look at the Google documentation (link here).
Starting
We’re going to render our Base64Png Editor created in the last section on top of base64png files uploaded on GitHub, so instead of seeing the text content, the Editor will show up. Here’s a quick look at how it’ll show up.
This Extension is using the final version of the Base64Png Editor, which is available on this example repository.
This is the same file, but without the rendered Editor!
Code
To have a Chrome Extension, it’s necessary to create some files:
- manifest.json
- src/envelope/index.ts
- static/envelope/index.html
- src/contentscript.ts
manifest.json
The manifest.json tells the Chrome Browser to find specific files or which permissions the Extension needs to fulfill some operations. We’re not going through the specifics of this file, just some essential properties.
Because this Chrome Extension will run on a GitHub page, it’s necessary to specify that on the manifest, and we do it on the content_scripts and the permissions property.
| { | |
| "name": "Kogito Base64 PNG Editor", | |
| "version": "0.6.0", | |
| "manifest_version": 2, | |
| "description": "Kogito Base64 PNG Editor", | |
| "icons": { | |
| "128": "resources/icon_128.png" | |
| }, | |
| "content_scripts": [ | |
| { | |
| "run_at": "document_idle", | |
| "js": ["contentscript.js"], | |
| "matches": ["https://github.com/*"], | |
| "all_frames": true | |
| } | |
| ], | |
| "permissions": [ | |
| "https://*.github.com/*", | |
| "http://*.github.com/*" | |
| ] | |
| } |
src/contentscript.ts
This file is responsible for the initialization of the Chrome Extension. It’ll run only on GitHub pages as the manifest.json and content_script property is set up. To start the Chrome Extension, we need to pass along some information. Here we give the icon’s path that will be shown on the chrome://extensions page, the name of the cookie that handles the GitHub token (useful in case you want to use the Extension on private repository), and the Envelope locator. The Envelope locator maps a file extension to a specific Envelope, located on our dist folder after we build the project.
| import { startExtension } from "@kogito-tooling/chrome-extension"; | |
| // String replaced by Webpack using the 'string-replace-loader' | |
| const resourcesPathPrefix = "$_{WEBPACK_REPLACE__targetOrigin}"; | |
| startExtension({ | |
| name: "Kogito Base64 PNG React Editor", | |
| extensionIconUrl: chrome.extension.getURL("/resources/kie-icon.png"), | |
| githubAuthTokenCookieName: "github-oauth-token-base64-editors", | |
| editorEnvelopeLocator: { | |
| targetOrigin: window.location.origin, | |
| mapping: new Map([ | |
| [ | |
| "base64png", | |
| { | |
| resourcesPathPrefix: `${resourcesPathPrefix}/dist/`, | |
| envelopePath: `${resourcesPathPrefix}/dist/envelope/index.html`, | |
| }, | |
| ], | |
| ]), | |
| }, | |
| }); |
src/envelope/index.ts
This file is responsible for the initialization of the Envelope. Here we use the Base64EditorFactory to create a Base64Png Editor, and then we specify the context. It’s essential to generate an output from this file using Webpack or any other module bundler of your choice.
Our Envelope will start on the “envelope-app” container (an HTML div) in the static/envelopendex.html. The bus method is used by the Envelope to communicate with the Channel.
| import { init } from "@kogito-tooling/editor/dist/envelope"; | |
| import { EnvelopeBusMessage } from "@kogito-tooling/envelope-bus/dist/api"; | |
| import { ChannelType, getOperatingSystem } from "@kogito-tooling/channel-common-api"; | |
| import { Base64PngEditorFactory } from "base64png-editor"; | |
| init({ | |
| container: document.getElementById("envelope-app")!, | |
| bus: { | |
| postMessage<D, T>(message: EnvelopeBusMessage<D, T>, targetOrigin?: string, _?: any) { | |
| window.parent.postMessage(message, targetOrigin!, _); | |
| }, | |
| }, | |
| editorFactory: new Base64PngEditorFactory(), | |
| editorContext: { channel: ChannelType.GITHUB, operatingSystem: getOperatingSystem() }, | |
| }); |
static/envelope/index.html
This file is the Envelope HTML, and the envelope/index.ts will use it to start the Editor on it. Your module bundler should copy this file to the same folder of the envelope/index.ts.
| <!DOCTYPE html> | |
| <html lang="en"> | |
| <head> | |
| <style> | |
| html, | |
| body, | |
| div#envelope-app { | |
| margin: 0; | |
| border: 0; | |
| padding: 0; | |
| overflow: hidden; | |
| height: 100%; | |
| } | |
| </style> | |
| <title></title> | |
| <meta charset="UTF-8" /> | |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> | |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> | |
| </head> | |
| <body> | |
| <div id="loading-screen" style="z-index:100;position:relative"></div> | |
| <div id="envelope-app"></div> | |
| <script src="index.js"></script> | |
| </body> | |
| </html> |
Running
To run this Extension locally, we need an https server exposing the Envelope to our localhost, for that we’re using the Webpack devserver. Still, you can utilize any other way to expose it.
| devServer: { | |
| compress: true, | |
| watchContentBase: true, | |
| https: true, | |
| port: 9000 | |
| } |
Important: After the server is running, you need to permit your browser to load the content of localhost without an https certificate, and for that, you can access chrome://flags/#allow-insecure-localhost or alternatively access https://localhost:9000 and add an exception to it.
Obs: Further on the Web App example, we’re going to see a way to access the Envelope without a local server after deploying it to a GitHub page!
With the server running, we’re going to the chrome://extensions page on your Chrome Browser, click on the Load unpacked button, and select the generate dist folder generated from the compile process.
Wrapping up
Now you’re good to go, you can access your GitHub repository with a base64png file on it, and the Editor will show up!
This finishes this section. The next one is about how to Embed the Base64Png Editor on the VS Code!
Thanks for reading, and see you in the next section.
