The Jancy Object

The Jancy object is going to be the primary interface through which your plug-in will add to/modify Jancy. It contains a number of useful methods and is the home for all of the core interfaces.

The global Jancy object is always available at global.jancy.

Methods

jancy.addURLHandler(func)

• func (function)

Register a function that will be called any time a tab navigates.

func will be called with the following arguments:

• jancy (Jancy object) the global Jancy object
• tab (Tab object) a Tab object
• url (string) the URL being navigated to

func should return true if no further evaluation of the URL needs to happen otherwise it should return false.

To unregister your function use the jancy.removeURLHandler method.

function myHandler(jancy, tab, url) {
  if (url.startsWith('josh://')) {
    // Do something special here.
    return true
  }
  return false
}
jancy.addURLHandler(myHandler)

jancy.addWebReadyFunction(name, func, state)

• name (string)
• func (function)
• state (any) optional passed as an argument to func. If func resolves with a value, that value will be used as state on the call to func.

Register a function to be called when the webcontents of a tab has been established but before the first navigation event.

func will be called with the following arguments:

• jancy (Jancy object) the global jancy object
• tab (Tab object) a Tab object
• wc (WebContents) the Electron WebContents object associated with the tab
• state (any) see state above.

func must return a promise that resolves with a new state value.

To unregister your function use the jancy.removeWebReadyFunction method.

async function myWebReady(jancy, tab, wc, state) {
  if (state === undefined) {
    state = 1
  }
  console.log(`I've been called ${ state } times`)
  return state + 1
}
jancy.addWebReadyFunction("my webready function", func)

jancy.getAppDataPath(file)

• file (string) optional

Returns a string with the app data path or optionally a file/folder in the app data path if file is defined.

• On Windows the plug-in folder is located at %appdata%\Jancy\plugins
• On MacOS the plug-in folder is locatd at ~/Library/Application Support/Jancy/plugins

jancy.getBundlePath(file)

• file (string) optional

Returns a string with the bundle path or optionally a file/folder in the bundle if file is defined.

jancy.getHomePage()

Returns a string with the currently configured home page.

This is a convience method that does some error checking on the homePage preference and returns a default home page if the user hasn’t set the homePage preference.

jancy.getInterface(key)

• key (string)

Returns the object associated with key previously regisitered with jancy.registerInterface().

jancy.getPlatform()

Returns a string describing the platform (OS) Jancy is currently running on.

• For Windows the return value will be win32
• For MacOS the return value will be darwin

jancy.getShortUUID()

Returns a string containing the last 12 characters of UUID generated from the uudiv4 package.

const uuid = jancy.getUUID()
console.log(uuid) // "a7006c25a39f"

jancy.getUUID()

Returns a string containing a UUID generated from the uudiv4 package.

const uuid = jancy.getUUID()
console.log(uuid) // "75442486-0878-440c-9db1-a7006c25a39f"

jancy.registerInterface(key, obj)

• key (string)
• obj (object)

Associates obj with key. obj can be retrieved later via jancy.getInterface().

Interfaces are a simple way to extend Jancy functionality. The intended use-case was for plug-ins to add specialized interfaces (simple objects with custom methods). Other plug-ins could then query for a handle to the interface object and do something with it.

const myObj = {
  doSomething() {
    // some special thing that only myObj can do...
  }
}
jancy.registerInterface('myInterface', myObj)
// Later on...
const myObj = jancy.getInterface('myInterface')
myObj.doSomething()

jancy.removeURLHandler(func)

• func (function)

Unregister a function previously registered via jancy.addURLHandler().

function myHandler(jancy, tab, url) {
  if (url.startsWith('josh://')) {
    // Do something special here.
    return true
  }
  return false
}
jancy.addURLHandler(myHandler)
// later on...
jancy.removeURLHandler(myHandler)

jancy.removeWebContextMenuHandler(func)

• func (function)

Unregister a function previously registered via jancy.addWebContextMenuHandler().

function myHandler(jancy, tabbedWindow, tab, wc, params) {
  if (params.mediaType === "image") {
    return {
      id: 'log-image-url',
      label: 'Log image URL',
      click: () => {
        jancy.console.log(`clicked image at ${ params.srcURL }`)
      }
    }
  }
}

jancy.addWebContextMenuHandler(myHandler)
// later on...
jancy.removeWebContextMenuHandler(myHandler)

jancy.removeWebReadyFunction(name)

• name (string)

Unregister a function previously registered via jancy.addWebReadyFunction().

async function myWebReady(jancy, tab, wc, state) {
  if (state === undefined) {
    state = 1
  }
  console.log(`I've been called ${ state } times`)
  return state + 1
}
jancy.addWebReadyFunction("my webready function", func)
// later on...
jancy.removeWebReadyFunction("my webready function")

jancy.require(path, invalidateCache=false)

• path (string)
• invalidateCache (boolean)

Returns the module exported from the file at path optionally invalidating any previously cached versions of the module.

Interfaces

A list of all the core Jancy interfaces can be found here.