Charles Bubble Plugin Documentation
Install the Chrome extension source code and set up your app → Get started
- Charles Bubble Plugin Documentation
- Feature overview. Please read ⚠️
- Define opening action
- Get tab infos
- Get user selected text
- Get element text
- Get element HTML
- Open URL in sidebar modal
- Open URL in full-screen modal
- Copy text to clipboard
- Populate an input filed
- Simulate mouse click on element
- Capture screenshot
- Show native alert
- Open URL in new tab
- Set an extension badge color and text
- Change extension icon
- Close extension
- Save to Chrome storage
- Injecting custom JavaScript
- FAQ
- Can I record audio form my extension?
- Can I use Google/FB OAuth to log in ('Log in with Google')?
Feature overview. Please read ⚠️
⚠️ Some features only work in the extension popup or only in the sidebar:
Feature | Popup | Sidebar / Modal |
Get tab infos | ✅ | ✅ |
Get user selected text | ✅ | ✅ |
Get element text | ✅ | ✅ |
Get element HTML | ✅ | ✅ |
Open URL in sidebar modal | ✅ | ❌ |
Open URL in full-screen modal | ✅ | ❌ |
Copy text to clipboard | ✅ | ✅ |
Populate an input filed | ✅ | ✅ |
Simulate mouse click on element | ✅ | ✅ |
Capture screenshot | ✅ | ❌ |
Show native alert | ✅ | ✅ |
Open URL in new tab | ✅ | ✅ |
Set an extension badge color and text | ✅ | ❌ |
Change extension icon | ✅ | ❌ |
Close extension | ✅ | (✅) |
Save to Chrome storage | ✅ | ✅ |
Injecting custom JavaScript | ✅ | ❌ |
Record audio from Bubble app (using 3rd party Bubble plugins) | ❌ | ✅ |
Define opening action
By default, a click on the extension icon opens the extension popup. You can, however, change this so that by default the extension opens as a side bar or full-screen modal.
🎉 Since Charles is awesome, most plugin actions will also work in the side bar or full-screen modals
To do so:
- open
background.js
in any text editor, and uncomment either lines 5-8 (i.e. remove the // in front of the lines) or lines 11-14. - Adjust the URL in line 5 or 10 to point to your Bubble app. Start the URL with
https:://…
- Open
manifest.json
in any text editor and delete the full line '"default_popup": "popup.html",' in manifest.json and make sure there is no empty line left
or
Get tab infos
- Place the
Charles: Tab inf
o element on the page - Access the elements states Tab title and Tab URL
Get user selected text
- Place the
Charles: Selected text
element on the page - Access the elements state Selected Text
Get element text
- Place the
Charles: Element text
element on the page - Give it a value for the selector that matches the element you want to select, eg.
h1
for the h1 title element: - https://www.w3schools.com/jsref/met_document_queryselector.asp
- https://www.w3schools.com/css/css_selectors.asp
- https://www.w3schools.com/cssref/css_selectors.php
Please note that Charles will automatically select the first element that matches the selector.
Learn more about CSS selectors:
Get element HTML
- Place the
Charles: Element HTML
element on the page - Give it a value for the selector that matches the element you want to select, eg.
html
to select the whole html document: - https://www.w3schools.com/jsref/met_document_queryselector.asp
- https://www.w3schools.com/css/css_selectors.asp
- https://www.w3schools.com/cssref/css_selectors.php
Please note that Charles will automatically select the first element that matches the selector.
Learn more about CSS selectors:
Open URL in sidebar modal
Use the action Charles: Open iFrame in sidebar
workflow action and give it a URL to open and width in px or %: Start the URL with https:://…
Open URL in full-screen modal
Use the action Charles: Open iFrame in modal
workflow action and give it a URL to open. Start the URL with https:://…
:
Copy text to clipboard
Use the action Charles: Copy to clipboard
workflow action and give it a text to copy:
Populate an input filed
Use the action Charles: Populate input field
workflow action and give it:
- A text value to populate the input with
- A CSS selector to select the input you want to populate
- Please note that Charles will automatically select the first element that matches the selector.
Learn more about CSS selectors:
- https://www.w3schools.com/jsref/met_document_queryselector.asp
- https://www.w3schools.com/css/css_selectors.asp
- https://www.w3schools.com/cssref/css_selectors.php
Simulate mouse click on element
Use the action Charles: Simulate mouse click on element
workflow action and give it:
- A CSS selector to select the element you want to simulate the click on
- Please note that Charles will automatically select the first element that matches the selector.
Learn more about CSS selectors:
- https://www.w3schools.com/jsref/met_document_queryselector.asp
- https://www.w3schools.com/css/css_selectors.asp
- https://www.w3schools.com/cssref/css_selectors.php
Capture screenshot
Take a screenshot of the active tab’s viewport (i.e. the part that is currently visible on the screen):
- Add the element
Charles: Screenshot
to the page. - Use the action
Charles: Capture Screenshot
to initiate a screenshot - Once the screenshot is taken, the event
screenshotCaptured
is triggered. You can use theCharles: Screenshot
's states Screenshot URL
to access an image uploaded to the Bubble CDN. Please use:saved to S3
to make sure the image is permanently stored. This should be the main way of storing images.-
Base64 encoded image
to save a base64 encoded image directly to Bubble’s databse. This can be useful if you need to use any 3rd party APIs that expect a base64 encoded image. Please note that the string contains a prefix:data:image/png;base64,iVBORw0KGgoAAA…
.
Show native alert
Use the action Charles: Show alert
workflow action and give it an alert text:
Open URL in new tab
Use the action Charles: Open new tab
workflow action and give it a URL to open. Start with https:://…
:
Set an extension badge color and text
Use the action Charles: Set badge text and color
workflow action and give it a short number or text (max 4 characters) and a color (using a hex code):
To remove the badge text and color: run the workflow with empty number / text. Please leave a value for the color, otherwise there might be an error.
Change extension icon
- Create a new set of extension icons in the dimensions 16px, 32px, 48px, 128px and place them in the
images
folder in the extension source code folder. You can also create a subfolder to keep things cleaner. - Use the action
Charles: Change icon
workflow action fill in the paths to the new images starting withimages/…
:
To reset the the icon, run the same workflow, but point it back to the original images:
Close extension
To close the extension popup:
Use the action Charles: Close extension popup
workflow action:
To close the extension sidebar:
There is no direct workflow action to do so, but you can use the Simulate mouse click on element
workflow action to simulate a click on the sidebar closing button, using the selector #chrls-sidebar-close-button
:
To close the extension full-screen modal:
Same as above, but use #chrls-full-close-button
as selector:
Save to Chrome storage
With Charles you can save text to Window.localStorage. ⚠️ Please make sure you use the Charles Chrome Extension v1.6 or later.
- Add the Charles: Chrome storage element to your Bubble app
- Use the workflow actions:
- Charles: Write to local storage
- Charles: readFromLocalStorage
- Charles: deleteFromLocalStorage
- Charles: clearLocalStorage
- Extension context: Isolated context of the extension. Can be accessed from any tab.
- Active tab context: Read and write in the local storage of the currently active tab.
- After using ‘Charles: readFromLocalStorage’, an event ‘Charles:Chromestorage A Local variable is read’ will be triggered. You can access the results in the ‘Charles: Chrome storage’ - Element’s states ‘Variable name’ and ‘Variable value’, e.g.
⚠️ The extension can read / write either in the context of the extension itself or in the context of the active tab (currently active website in Chrome)
Injecting custom JavaScript
With Charles you can inject custom JavaScript files into a page. ⚠️ Please make sure you use the Charles Chrome Extension v1.6 or later.
Unfortunately, in Chrome Manifest v3 it is no longer possible to inject remote JavaScript into a page. However, we have built in 3 empty files into Charles (in the folder CustomJavaScript), where you can add your own JavaScript. If you like, you can also add more .js files into the folder.
There are two ways to inject a file into a page.
- Most common: Inject a file every time a certain page is loaded. E.g. every time the user visits bubblehacks.io. The extension does not have to be open (i.e. the user does not have to click the extension icon.). A common use case for this is to inject a button to a page. This can be configured in manifest.json → content_scripts
For this to work, you need to adjust the following code:
- matches: match pattern on which pages the script should be injected. See https://developer.chrome.com/docs/extensions/mv3/content_scripts/#matchAndGlob for more information
- exclude_matches: match pattern on which pages the script should NOT be injected. See https://developer.chrome.com/docs/extensions/mv3/content_scripts/#matchAndGlob for more information
- js: Script file(s) to be injected. Make sure the File Name corresponds to a file in the CustomJavaScript folder of the extension. Also make sure to add the folder name in front of the file name, e.g.
"CustomJavaScript/customScript1.js”
. You can include multiple files, adding them using comma-separation - The example above will inject the custom script
customScript1.js
in https://bubblehacks.io/ and all it’s subpages, except https://bubblehacks.io/charles.
- Less common: Using the Bubble Plugin to inject a file when the extension popup is visible and an action is triggered in your Bubble file. Make sure the File Name corresponds to a file in the CustomJavaScript folder of the extension.
FAQ
Can I record audio form my extension?
Yes and no. Chrome has certain limitations on microphone access, which affects audio recording capabilities. However, there are alternative options available depending on the type of extension you are using.
If you are using the extension's sidebar, you can utilize an audio recording plugin within your Bubble app to capture audio. When initiating the recording process, the user will be prompted to grant permission for microphone access.
Unfortunately, recording audio directly from the extension's popup is currently not supported.
Can I use Google/FB OAuth to log in ('Log in with Google')?
Yes, you can, but not directly within the extension window due to Google's iFrame restrictions. To work around this:
- Open a new tab linked to your Bubble app.
- Complete the login process there.
- Once authenticated on the site, you'll be automatically logged into the extension as well.