Skip to content

Latest commit

 

History

History
273 lines (214 loc) · 9.67 KB

integration.md

File metadata and controls

273 lines (214 loc) · 9.67 KB
Raw

Integration with ImJoy-Core

You can load the ImJoy core into your website or web application, such that you can call another ImJoy plugins.

Or, you can inject the ImJoy runtime into your web application, such that it can be loaded as an ImJoy window plugin.

Load ImJoy Core to your website or web application

Option 1: Load the ImJoy Core into your HTML file

<script src="https://lib.imjoy.io/imjoy-loader.js"></script>

<script>
loadImJoyCore().then((imjoyCore)=>{
    const imjoy = new imjoyCore.ImJoy({
        imjoy_api: {},
        //imjoy config
    })
    imjoy.start({workspace: 'default'}).then(()=>{
        alert('ImJoy Core started successfully!')
    })
})
</script>

A full example html file can be found here.

Note: To improve reproducibility in production, you should specify the version for the core by calling for example loadImJoyCore({version: "0.13.16"}).

Option 2: Use the npm module

You can install imjoy-core via npm:

npm install imjoy-core

To load and start the ImJoy core in your application:

import * as imjoyCore from 'imjoy-core'

const imjoy = new imjoyCore.ImJoy({
    imjoy_api: {},
    //imjoy config
});

imjoy.start({workspace: 'default'}).then(async ()=>{
    console.log('ImJoy started');
})

Display window plugins

To support the display of window plugins, you will need to listen to the add_window event and then create div with a generated window id, for example:

imjoy.event_bus.on("add_window", w => {
      const container = document.createElement('div');
      container.id = w.window_id; // <--- this is important
      container.style.backgroundColor = '#ececec';
      container.style.height = "300px";
      container.style.width = "100%";
      // Here we simply add to the body
      // but in reality, you can embed it into your UI
      document.body.appendChild(container)
})

Now, if you call imjoy.api.createWindow (or within another plugin call api.createWindow), ImJoy will first emit add_window event, and then it will try to render an iframe under the container defined by id=w.window_id.

Use your web application inside ImJoy

If you want to support loading your web app as an ImJoy window plugin, and that will allow users use your web app from within ImJoy and being able to make a workflow out of it. For example, if you have a web app for visualizing data which made to be used as a standalone app, it is easy make it work as an ImJoy window plugin.

You can easily support by loading the ImJoy Remote Procedure Call(RPC) runtime, which will load and give you an api object from the ImJoy core. Later on you can use the api functions to register your own api functions (e.g. a imshow function for a image viewer app).

Option 1: Load the ImJoy RPC library in your HTML file

<script src="https://lib.imjoy.io/imjoy-loader.js"></script>

<script>
loadImJoyRPC().then(async (imjoyRPC)=>{
    const api = await imjoyRPC.setupRPC({name: 'My Awesome App'});
    function setup(){
        api.alert('ImJoy RPC initialized.')
    }
    // define your api which can be called by other plugins in ImJoy
    function my_api_func(){

    }
    // Importantly, you need to call `api.export(...)` in order to expose the api for your web application
    api.export({'setup': setup, 'my_api_func': my_api_func});
})
</script>

Note: To improve reproducibility in production, you should specify the api_version (or pin to a specific version) by calling for example loadImJoyRPC({api_version: "0.2.3"}).

Alternatively, you can load the imjoy-rpc library via cdn https://cdn.jsdelivr.net/npm/imjoy-rpc@latest/dist/imjoy-rpc.min.js (or replace @latest to a version number). Using the the imjoy-loader will be more flexible since it only load when you call the load function.

A full example html file can be found here.

Option 2: Import the ImJoy RPC library from the npm module

Install the imjoy-rpc library via npm:

npm install imjoy-rpc

Then you can load the ImJoy RPC runtime and setup the RPC, an api object can then be used to interact with the ImJoy core.

import { imjoyRPC } from 'imjoy-rpc';

imjoyRPC.setupRPC({name: 'My Awesome App'}).then((api)=>{
 // call api.export to expose your plugin api
})

Note: This will only work if your app is started from within ImJoy as a window plugin (iframe).

You can then serve your web application on any hosting service, e.g. on Github pages. Assuming the url is https://my-awesome-app.com/ (add query string if necessary).

In any other ImJoy plugin, you can then use your web app by:

// as a new window
const win = await api.createWindow({
    type: 'My Awesome App',
    src: 'https://my-awesome-app.com/',
    data: { }
})

// or, as a dialog
const win = await api.showDialog({
    type: 'My Awesome App',
    src: 'https://my-awesome-app.com/',
    data: { }
})

// further interaction can be performed via `win` object

Using with RequireJS (and jQuery)

You can also use the libraries with RequireJS, this is typically used with, for example jQuery.

The following example illustrate the use of imjoyLoader with RequireJS.

<script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"></script>
<script>
require.config({
    paths: {
        'imjoyLoader': 'https://lib.imjoy.io/imjoy-loader.js',
    }
});

require(["imjoyLoader"], function (imjoyLoder) {
    imjoyLoder.loadImJoyRPC().then(async (imjoyRPC) => {

    }
    imjoyLoder.loadImJoyCore().then(async (imjoyCore) => {
        
    }
}
</script>

Similarily, you can also use RequireJS to load imjoy-rpc and imjoy-core.

Automatically switching between plugin and core mode

For web applications which support loading as a plugin and use the imjoy core, we provide a function to enable automatic swithching between the two modes by detecting whether the current webpage is loaded inside an iframe:

// check if it's inside an iframe
if(window.self !== window.top){
    loadImJoyRPC().then((imjoyRPC)=>{
        
    })
}
else {
    loadImJoyCore().then((imjoyCore)=>{

    })
}

Load ImJoy basic app

If you want to setup a basic ImJoy app, you can use the loadImJoyBasicApp function.

For example, if you want to build a basic ImJoy app or use it within your project websie, you will need to:

  1. Add the following script tag in your HTML:
<script src="https://lib.imjoy.io/imjoy-loader.js"></script>
  1. Optionally, add div tags for the displaying the ImJoy menu and windows. For example:
    <div id="window-container"></div>
    <div id="menu-container"></div>
  1. To initialize the app, add the following javascript code to a script block or your script file:
loadImJoyBasicApp({
    process_url_query: true,
    show_window_title: false,
    show_progress_bar: true,
    show_empty_window: true,
    menu_style: { position: "absolute", right: 0, top: "2px" },
    window_style: {width: '100%', height: '100%'},
    main_container: null,
    menu_container: "menu-container",
    window_manager_container: "window-container",
    imjoy_api: { } // override some imjoy API functions here
}).then(async app => {
    // get the api object from the root plugin
    const api = app.imjoy.api;
    // if you want to let users to load new plugins, add a menu item
    app.addMenuItem({
        label: "➕ Load Plugin",
        callback() {
        const uri = prompt(
            `Please type a ImJoy plugin URL`,
            "https://github.com/imjoy-team/imjoy-plugins/blob/master/repository/ImageAnnotator.imjoy.html"
        );
        if (uri) app.loadPlugin(uri);
        },
    });

    // if you want a windows displayed in a draggable rezisable grid layout
    const grid = await api.createWindow({
        src: "https://grid.imjoy.io/#/app",
        name: "Grid",
    });
    // you can show windows in the grid
    const viewer = await grid.createWindow({ src: "https://kaibu.org" });

    // or display a message
    await api.showMessage("This is a message");
    // or progress
    await api.showProgress(50);
});

API options

For the loader functions (loadImJoyRPC, loadImJoyCore, loadImJoyBasicApp), you can optinally pass a config object contains the following options:

  • version: specify the imjoy-core or imjoy-rpc library version
  • api_version: for imjoy-rpc only, to contrain the api version of the RPC
  • debug: load the full imjoy-core version instead of a minified version, useful for debugging
  • base_url: a custom url for loading the libraries

For loadImJoyBasicApp, there are several additional options:

  • process_url_query: Boolean, whether the url query should be processed
  • show_window_title: Boolean, whether the window title should be shown
  • show_progress_bar: Boolean, whether the progress bar should be shown
  • show_empty_window: Boolean, whether the empty window should be shown
  • hide_about_imjoy: Boolean, whether the about ImJoy menu item should be hidden
  • menu_style: Object, the menu style
  • window_style: Object, the window style
  • main_container: String, the id of the main container
  • menu_container: String, the id of the menu container
  • window_manager_container: String, the id of the window container
  • imjoy_api: Object, override the implementation of some ImJoy API functions

Examples for using the ImJoy Core

To get started, please take a look at:

A more complete example is the ImJoy Application (live demo).