- Frontend API
Provides a set of helper functions to integrate the service into Ferdi.
Sets the unread message badge
intdirectMessages
- sets the count of direct messages eg. Slack direct mentions, or a message to @channel
intindirectMessages (optional)
- Set a badge that defines there are new messages but they do not involve me directly to me eg. in a channel (default value: 0)
Ferdi.setBadge(4, 2);
// or
Ferdi.setBadge(3);Sets the active dialog title to the app title
stringtitle
- sets the active dialog title eg. WhatsApp contact name
Ferdi.setDialogTitle('Dialog title');Injects the contents of one or more CSS files into the current webview
stringcssFile
- CSS files that should be injected. This must be an absolute path to the file
const path = require('path');
// inject a single css file
Ferdi.injectCSS(path.join(__dirname, 'style.css'));
// inject multiple css files
const globalStyles = path.join(__dirname, 'global.css');
const focusModeStyles = path.join(__dirname, 'focusmode.css');
Ferdi.injectCSS(globalStyles, focusModeStyles);Injects the contents of one or more JavaScript files into the current webview without context isolation
Ferdi uses context isolation to prevent services from accessing Node.js APIs in the webview.
If you want to expose objects to the service (eg. via the window object) or interact with the Javascript loaded by the service you must do so from a script injected with this method.
Trying to overwrite properties of the window object or other objects or trying to interact with the Javascript loaded by the service from webview.js will fail due to context isolation.
The code is executed as if part of the body of a Javascript function, ie. you should modify the window object explicitly to expose objects in the global scope.
stringjsFile
- JavaScript files that should be injected. This must be an absolute path to the file
const path = require('path');
// inject a single css file
Ferdi.injectJSUnsafe(path.join(__dirname, 'webview-unsafe.js'));
// inject multiple css files
const globalScripts = path.join(__dirname, 'global.js);
const focusModeScripts = path.join(__dirname, 'focusmode.js);
Ferdi.injectCSS(globalScripts, focusModeScripts);Runs an action every X milliseconds (Ferdi default is currently 1s)
functionaction
// slack integration
const path = require('path');
module.exports = Ferdi => {
const getMessages = () => {
const directMessages = $('.unread_highlights, .unread_highlight').not(
'.hidden',
).length;
const indirectMessages = $('.unread').length - directMessages;
Ferdi.setBadge(directMessages, indirectMessages);
};
Ferdi.loop(getMessages);
Ferdi.injectCSS(path.join(__dirname, 'style.css'));
};Runs fn on every notification created by the service before sending them to the host (Useful if you want to update information of the notification before showing it to the user)
functionfn
// messenger integration
module.exports = Ferdi => {
const getMessages = () => {
let count = document.querySelectorAll(
'._5fx8:not(._569x),._1ht3:not(._569x)',
).length;
const messageRequestsElement = document.querySelector('._5nxf');
if (messageRequestsElement) {
count += Ferdi.safeParseInt(messageRequestsElement.textContent);
}
Ferdi.setBadge(count);
};
Ferdi.loop(getMessages);
Ferdi.onNotify(notification => {
if (typeof notification.title !== 'string') {
notification.title =
((notification.title.props || {}).content || [])[0] || 'Messenger';
}
return notification;
});
};You can use a darkmode.css to automatically get the service into a dark theme. If your service already supports its own dark mode (e.g. Reddit and YouTube have built-in dark modes), then you can use a custom dark mode handler instead.
This handler should take the necessary steps to (de-)activate dark mode on the page, e.g. by clicking a button or flipping a switch.
Ferdi won't activate DarkReader or inject darkmode.css if the recipe has defined a custom handler. If you still need to do this, you can use the injectDarkModeStyle or enableDarkMode function provided as the second argument.
functioncallback
booleanisEnabled: Is Dark Mode currently enabled?objecthelpers: Helper functions that you can use in your function:enableDarkMode- Enable DarkReaderdisableDarkMode- Disable DarkReaderinjectDarkModeStyle- Inject darkmode.cssremoveDarkModeStyle- Remove service's darkmode.cssisDarkModeStyleInjected- Function that returns true if darkmode.css is injected into the page
// Handler that works for Reddit
Ferdi.handleDarkMode((isEnabled, helpers) => {
// Open dropdown menu if not already open
const menu = document.querySelector('#USER_DROPDOWN_ID');
if (menu.getAttribute('aria-expanded') === 'false') {
menu.click();
}
setTimeout(() => {
// Check if service is already in right mode
const btn = document.querySelector('[role=menu] button button');
const checked = btn.getAttribute('aria-checked') === 'true';
if ((checked && !isEnabled) || (!checked && isEnabled)) {
// Click the button to switch between modes
btn.click();
}
}, 50);
});
// --- or ---
// Helper that activates DarkReader and injects your darkmode.css at the same time
Ferdi.handleDarkMode((isEnabled, helpers) => {
if (isEnabled) {
helpers.enableDarkMode();
if (!helpers.isDarkModeStyleInjected()) {
helpers.injectDarkModeStyle();
}
} else {
helpers.disableDarkMode();
helpers.removeDarkModeStyle();
}
})While exiting/closing/disabling the service, if you want to clear the local storage, you can use this method to effect the same.
idof the recipe- struct of
storages
Ferdi.clearStorageData(settings.id, {
storages: [
'appcache',
'serviceworkers',
'cachestorage',
'websql',
'indexdb',
],
});While exiting/closing/disabling the service, if you want to release any service workers, you can use this method to effect the same.
A utility method that can be used to safely parse the text content (handles nulls, undefined, etc). Basically a wrapper around parseInt - but handles the safety checks.
stringTextString to be parsed into a number. (Could benullorundefined) Defaults to0
Ferdi.safeParseInt(mySelector.innerText)When you want to set the title of the Ferdi window (while this service is active or in focus), you can use this function
title: The title to be set (for eg: the chat message person/group name in whatsapp)
Ferdi.setDialogTitle(element ? element.textContent : null);