Commit 2cc7fa04 authored by Łukasz Starosta's avatar Łukasz Starosta

Widget API contents

parent cf4e44a4
......@@ -39,7 +39,7 @@ export interface Engine {
props,
}: {
parentElement: any;
remount: any;
remount: boolean;
uid: UID;
el: HTMLElement;
component: Component;
......
......@@ -23,6 +23,14 @@ static externalScripts = [
];
```
## dependencies
Specify the dependencies of your widget, which will be visible in the tooltip.
```ts
static dependencies: string[] = [];
```
## static options
> These will override `options` from `defaultProps`
......@@ -68,4 +76,4 @@ interface Options {
## Example - pass a callback through options
See how to use `options` in a different way - to react to a change that happened on the hosting platform. [Example](/widget-api/methods)
See how to use `options` in a different way - to react to a change that happened on the hosting platform. [Example](/widget-api/2-examples)
---
title: "Widget API"
metaTitle: "Widgets - Widget API"
---
# 🚧 Work in progress 🚧
## Introduction
Here you can find the instructions on how to use the `EmbeddableWidget` API.
It is accessible in two ways described below.
## EmbeddableWidget Engine API
This way is usually used while developing the widget, typically in the `index` file of your widget project. There you can define very general settings for the widget.
[EmbeddableWidget Engine API](/widget-api/0-engine-api)
## Window API
Through the global `window` API you can access widget-specific options and methods. This will help you to modify the widget's state or look at runtime.
[Global Window API](/widget-api/1-window-api)
---
title: "Engine API"
metaTitle: "Widgets - Engine API"
---
## Engine API Overview
## refresh
Refresh the widget, specifying the options described below.
```ts
refresh?: ({
parentElement,
remount,
uid: UID,
el,
component,
props
}: {
parentElement: any; // parent element of the widget
remount: boolean; // should the widget be unmounted and mounted again?
uid: UID; // unique identifier of the widget
el: HTMLElement; // the widget element
component: Component; // technology-specific component
props: Partial<Props>; // any props that you pass
}) => void;
```
## createElement
Function used to create the component. Implementation is technology-dependent.
```ts
/**
* e.g. for React use
* `createElement: (props) => { return <Widget {...props}/> }`
*/
createElement: (props: Partial<Props>) => Component;
```
## render
Main function rendering the element to the DOM.
```ts
/**
* e.g. for React use
* `render: (component,el) => ReactDOM.render(component,el)`
*/
render: (component: Component, el: HTMLElement) => void;
```
## unmountComponentAtNode
Function used to unmount the component when should not be in the DOM anymore.
```ts
/**
* e.g. for React use
* `unmountComponentAtNode: (node) => ReactDOM.unmountComponentAtNode(node)`
*/
unmountComponentAtNode: (node: HTMLElement) => void;
```
## resetState
> Optional
Overwrite the resetState function implementation
```ts
resetState?: (uid: UID, state: State) => void;
```
## getState
> Optional
Overwrite the getState function implementation.
Example - omit some fields when sending request with state payload to the server
```ts
getState?: (uid: UID) => State;
```
---
title: "Global API"
metaTitle: "Widgets - Global API"
---
## Introduction
The methods listed here are available through:
```
window[`${widget_name}_Widget`]
```
where `widget_name` is (in this order of importance, 1. overwrites 2.):
1. `WIDGET_TITLE` environmental variable
2. `name` field of the `package.json` file from your project
Real life example:
```
# .env
WIDGET_TITLE=chart
# browser console
window['chart_Widget']
```
---
The options below are then available:
## isSingleton
Is the widget a singleton? (Can only appear once in DOM)
```ts
static isSingleton(): boolean
```
## getState
Get the global Redux state from the component
```ts
static getState(uid: UID): State | void
```
## resetState
Replace the current state with the one given in the second argument
```ts
static resetState(uid = DEFAULT_UID, state?: State, props?: { [key: string]: any }): State
```
## setState
Set the state to the one given in the second argument
```ts
static setState(uid = DEFAULT_UID, state: State)
```
## refresh
Refresh the widget - rerender or remount completely
```ts
static refresh({
remount = false,
parentElement = null,
uid = DEFAULT_UID,
...props
}: {
remount?: boolean;
parentElement?: HTMLElement;
uid?: UID;
[key: string]: any;
} = {})
```
## getOptions
Get the current widget options
```ts
static getOptions(): Partial<Options>
```
## setOptions
Set the widget options
```ts
static setOptions(options: Options, uid: UID = DEFAULT_UID): void
```
## modifyDOMElement
This function is generic to provide the developer with the ability to modify any widget's element in any way. We have implemented basic methods below to [inject style](#injectInlineStyle) or [add/remove class](#injectCSSClass).
> If `querySelector` is not passed, this function will only modify the widget's root element (specified by UID).
> If `querySelector` is passed, this function will modify all elements found by the selector under a particular widget in the DOM (specified by UID).
> Exemplary `modify` implementation: `(element) => element.setAttribute('style', style);`
```ts
static modifyDOMElement({
uid,
querySelector,
modify,
}: {
uid?: string;
querySelector: string;
modify: (element: Element) => void;
}): void
```
## injectInlineStyle
Based on [modifyDOMElement](#modifyDOMElement), injects inline style attribute to an element.
```ts
static injectInlineStyle({
uid,
querySelector,
style,
}: {
uid: string;
querySelector: string;
style: string;
}): void
```
## injectCSSClass
Based on [modifyDOMElement](#modifyDOMElement), injects CSS class to an element.
```ts
static injectCSSClass({
uid,
querySelector,
className,
}: {
uid?: string;
querySelector: string;
className: string;
}): void
```
## removeCSSClass
Based on [modifyDOMElement](#modifyDOMElement), removes CSS class from an element.
```ts
static removeCSSClass({
uid,
querySelector,
className,
}: {
uid?: string;
querySelector: string;
className: string;
}): void
```
## External classes
Used to group elements by particular roles. [Example](/widget-api/2-examples)
```ts
// exemplary roles are: 'background', 'foreground'
export interface ExternalCSSClass {
role: string;
className: string;
}
```
## applyExternalCSSClasses
Based on [modifyDOMElement](#modifyDOMElement), injects CSS classes to an element found by `role`.
```ts
static applyExternalCSSClasses({ uid, classes }: { uid?: UID; classes: ExternalCSSClass[] }): void
```
## removeExternalCSSClasses
Based on [modifyDOMElement](#modifyDOMElement), removes CSS classes from an element found by `role`.
```ts
static removeExternalCSSClasses({ uid, classes }: { uid?: UID; classes: ExternalCSSClass[] }): void
```
## getElement
Get HTML element with `uid`
```ts
static getElement(uid: UID = DEFAULT_UID): HTMLElement | undefined
```
---
title: "Methods"
title: "Examples"
metaTitle: "Widgets - Examples"
---
## Examples
### Applying dark/light theme based on the hosting platform's preferences
## Applying dark/light theme based on the hosting platform's preferences
To accomplish our goal, we need to have the ability to add some classes to our elements at runtime. Let us first outline the usage flow:
......
---
title: "Additional Functionalities"
---
# 🚧 Work in progress 🚧
---
title: "Global API"
---
# 🚧 Work in progress 🚧
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment