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.
<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"})
.
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');
})
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
.
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).
<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.
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
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
.
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)=>{
})
}
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:
- Add the following script tag in your HTML:
<script src="https://lib.imjoy.io/imjoy-loader.js"></script>
- Optionally, add div tags for the displaying the ImJoy menu and windows. For example:
<div id="window-container"></div>
<div id="menu-container"></div>
- 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);
});
For the loader functions (loadImJoyRPC
, loadImJoyCore
, loadImJoyBasicApp
), you can optinally pass a config
object contains the following options:
version
: specify theimjoy-core
orimjoy-rpc
library versionapi_version
: forimjoy-rpc
only, to contrain the api version of the RPCdebug
: load the fullimjoy-core
version instead of a minified version, useful for debuggingbase_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 processedshow_window_title
: Boolean, whether the window title should be shownshow_progress_bar
: Boolean, whether the progress bar should be shownshow_empty_window
: Boolean, whether the empty window should be shownhide_about_imjoy
: Boolean, whether the about ImJoy menu item should be hiddenmenu_style
: Object, the menu stylewindow_style
: Object, the window stylemain_container
: String, the id of the main containermenu_container
: String, the id of the menu containerwindow_manager_container
: String, the id of the window containerimjoy_api
: Object, override the implementation of some ImJoy API functions
To get started, please take a look at:
A more complete example is the ImJoy Application (live demo).