Chamaileon SDK

Appearance

Next Steps with the Chamaileon SDK ​

After completing the Getting Started guide, use this page to unlock advanced features and best practices.

Concept ​

"Initialize Once, Update on the Fly"

The core philosophy of SDK v2 is to provide blazing-fast performance and a consistent developer experience. To achieve this, we've built the SDK around a central concept: you initialize a plugin instance once, and then update its data and settings on the fly. This avoids the overhead of repeatedly destroying and re-creating plugins.

You can also decide to use each plugin in fullscreen or inline mode with the same settings and data.

This is made possible through two primary interaction patterns:

Hooks ​

Functions you provide to the plugin. The plugin calls these functions to notify your application of events (e.g., onSave, onClose) or to request data from you (e.g., onEditImage).

Methods ​

Functions returned by the plugin instance. Your application calls these methods to command the plugin (e.g., updateData, getDocument, show, hide).

SDK parameters ​

PropertyTypeDescription
accessTokenstringused to authenticate inside the SDK
getAccessTokenfunctionreturns a newly generated access token
localestringThe used language pack
urlsobject#see detailed explanation
colorsobject#see detailed explanation
fontobject#see detailed explanation

Detailed parameter explanation ​

PropertyTypeDescription
urls.splashScreenstringAn url of a html file which will be displayed in an iframe until the plugins load. You can find examples here.
urls.createLogoJSstringAn url of a hosted javascript file with a function named createLogo() in it. It is up to you how you customize this. You can do any kind of fancy transitions with JS. You can find examples here.
colorsobjectYour own theme colors. The colors property represents the Vuetify Theme Configuration object. In most cases it's enough if you set up the primary color.
font.urlstringAn url of the font file you want to use in our plugins.
font.familystringThe font family you want to use in our plugins.

Plugin initialization ​

You can navigate to each plugin's documentation by using the links on the left-hand-side.

We also have a migration guide that you can follow to migrate from v1 to v2. You can find it in the left-hand-side menu as well.

After the successful initialization the chamaileonSDK will return an object with two create functions and a destroy function. You can initialize our plugins included in the SDK by invoking those functions. With the createFullscreenPlugin function you can create a fullscreen plugin and with the createInlinePlugin you can create an inline plugin.

js
const fullScreenPluginInstance = await chamaileonPlugins.createFullscreenPlugin({
	plugin: "plugin-name",
	data: {},
	settings: {},
	hooks: {},
});

const inlinePluginInstance = await chamaileonPlugins.createInlinePlugin(
	{
		plugin: "plugin-name",
		data: {},
		settings: {},
		hooks: {},
	},
	{
		container: HTMLElement,
		dimensions: {
			width: "100%"
			height: "100%",
			scale: 1,
		}
	}
);

The destroy function destroys every plugin instance and removes them from the DOM including their the wrapper element. After this it also destroys the SDK instance as well.

js
chamaileonPlugins.destroy();

Plugin usage ​

updateHooks ​

Updates the hooks inside the plugin instance on the fly.

js
await pluginInstance.methods.updateHooks({ hooks, resetHooks });

The updateHooks object parameter has the following parameters:

PropertyTypeDescription
hooksobjectThe same object format should be used as at the initialization stage.
resetHooksbooleanChooses if you want to reset the already configured hooks or just want to add to them. Default: false

Starting context

js
const onSave = () => {};
const onDelete = () => {};
const onFail = () => {};

const activeHooks = [];

const pluginInterface = await createFullscreenPlugin(...);
// For this example let's say that we sent
// the "onFail" hook with the init function

pluginInterface.methods.updateHooks = (hooks) => {
	activeHooks = hooks;
}

Update the hooks while keeping the already defined ones

js
await pluginInterface.methods.updateHooks({ hooks: { onSave } });
// after the method call the activeHooks should be equal with ["onSave", "onFail", "error"];

If a hook is passed with it's value set to null instead of it being a function then it will be removed from the list of available hooks inside the plugin.

Update the hooks and only keep the new ones

js
await pluginInterface.methods.updateHooks({ hooks: { onDelete }, resetHooks: true });
// after the method call the activeHooks should be equal with ["onDelete", "error"];

Fullscreen plugins ​

The fullscreen plugin instance will return some default functions that can be used to show/hide the plugin itself or to show/hide the splash screen inside the plugin instance.

Show ​

This function will show the selected plugin instance. The plugin's animation start position, opacity, scale and the animation's duration can be set. This function will return a Promise that will be resolved when the animation is finished.

For a smooth animation you should update the plugin before or after the show function call and not during the transition process.

js
const config: {
	x: "-100vw", // position on the X axis where the show animation starts
	y: "0px", // position on the Y axis where the show animation starts
	opacity: 0.5, // opacity at the start of the show animation
	scale: 1, // scale at the start of the show animation
	time: 450 // full duration of the show animation in milliseconds
}

pluginInstance.show(config);

Hide ​

This function will hide the selected plugin instance. It will start the same animation process as the show function but backwards.

js
pluginInstance.hide();

Show splash screen ​

You can show a splash screen inside the plugin instance by calling this function. You should this when the plugin is loading new data or settings and the plugin is already visible on the screen.

js
pluginInstance.showSplashScreen();

Hide splash screen ​

You can show a splash screen inside the plugin instance by calling this function. You should call this when every new data and setting has already finished loading into the plugin.

js
pluginInstance.hideSplashScreen();

Example Documents ​

You might need some example documents (JSONs) during development: