Skip to content

Latest commit

 

History

History
337 lines (234 loc) · 9.1 KB

frontend_api.md

File metadata and controls

337 lines (234 loc) · 9.1 KB
Raw

Frontend API

Provides a set of helper functions to integrate the service into Ferdium.

Ferdium Class Methods

setBadge(directMessages, [indirectMessages])

Sets the unread message badge

Arguments

  1. int directMessages
  • sets the count of direct messages eg. Slack direct mentions, or a message to @channel
  1. int indirectMessages (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)

Usage

Ferdium.setBadge(4, 2);

// or

Ferdium.setBadge(3);

setDialogTitle(title)

Sets the active dialog title to the app title

Arguments

  1. string title
  • sets the active dialog title eg. WhatsApp contact name

Usage

Ferdium.setDialogTitle('Dialog title');

injectCSS(pathToCssFile)

Injects the contents of one or more CSS files into the current webview

Arguments

  1. string cssFile
  • CSS files that should be injected. This must be an absolute path to the file

Usage

const path = require('path');

// inject a single css file
Ferdium.injectCSS(path.join(__dirname, 'style.css'));

// inject multiple css files
const globalStyles = path.join(__dirname, 'global.css');
const focusModeStyles = path.join(__dirname, 'focusmode.css');

Ferdium.injectCSS(globalStyles, focusModeStyles);

injectJSUnsafe(pathToJsFile)

Injects the contents of one or more JavaScript files into the current webview without context isolation

Ferdium 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.

Arguments

  1. string jsFile
  • JavaScript files that should be injected. This must be an absolute path to the file

Usage

const path = require('path');

// inject a single css file
Ferdium.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);

Ferdium.injectCSS(globalScripts, focusModeScripts);

loop(action)

Runs an action every X milliseconds (Ferdium default is currently 1s)

Arguments

  1. function action

Usage

// slack integration
const path = require('path');

module.exports = Ferdium => {
  const getMessages = () => {
    const directMessages = $('.unread_highlights, .unread_highlight').not(
      '.hidden',
    ).length;
    const indirectMessages = $('.unread').length - directMessages;

    Ferdium.setBadge(directMessages, indirectMessages);
  };

  Ferdium.loop(getMessages);

  Ferdium.injectCSS(path.join(__dirname, 'style.css'));
};

onNotify(fn)

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)

Arguments

  1. function fn

Usage

// messenger integration
module.exports = Ferdium => {
  const getMessages = () => {
    let count = document.querySelectorAll(
      '._5fx8:not(._569x),._1ht3:not(._569x)',
    ).length;
    const messageRequestsElement = document.querySelector('._5nxf');
    if (messageRequestsElement) {
      count += Ferdium.safeParseInt(messageRequestsElement.textContent);
    }

    Ferdium.setBadge(count);
  };

  Ferdium.loop(getMessages);

  Ferdium.onNotify(notification => {
    if (typeof notification.title !== 'string') {
      notification.title =
        ((notification.title.props || {}).content || [])[0] || 'Messenger';
    }

    return notification;
  });
};

handleDarkMode(callback)

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.

Ferdium 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.

Arguments

  1. function callback

Callback function arguments

  1. boolean isEnabled: Is Dark Mode currently enabled?
  2. object helpers: Helper functions that you can use in your function: enableDarkMode - Enable DarkReader disableDarkMode - Disable DarkReader injectDarkModeStyle - Inject darkmode.css removeDarkModeStyle - Remove service's darkmode.css isDarkModeStyleInjected - Function that returns true if darkmode.css is injected into the page

Usage

// Handler that works for Reddit
Ferdium.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
Ferdium.handleDarkMode((isEnabled, helpers) => {
  if (isEnabled) {
    helpers.enableDarkMode();
    if (!helpers.isDarkModeStyleInjected()) {
      helpers.injectDarkModeStyle();
    }
  } else {
    helpers.disableDarkMode();
    helpers.removeDarkModeStyle();
  }
})

clearStorageData

While exiting/closing/disabling the service, if you want to clear the local storage, you can use this method to effect the same.

Arguments

  1. id of the recipe
  2. struct of storages

Usage

  Ferdium.clearStorageData(settings.id, {
      storages: [
        'appcache',
        'serviceworkers',
        'cachestorage',
        'websql',
        'indexdb',
      ],
    });

releaseServiceWorkers

While exiting/closing/disabling the service, if you want to release any service workers, you can use this method to effect the same.

safeParseInt(stringText)

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.

Arguments

  1. stringText String to be parsed into a number. (Could be null or undefined) Defaults to 0

Usage

Ferdium.safeParseInt(mySelector.innerText)

isImage(link)

A utility method that can be used to verify if a link is an image. Returns true if is image and false if it is not an image.

Arguments

  1. url Url to be parsed.

Usage

Ferdium.isImage(link)

setDialogTitle(title)

When you want to set the title of the Ferdium window (while this service is active or in focus), you can use this function

Arguments

  1. title: The title to be set (for eg: the chat message person/group name in whatsapp)

Usage

Ferdium.setDialogTitle(element ? element.textContent : null);