Widget API contents

lib/src/types.ts

@@ -39,7 +39,7 @@ export interface Engine {
     props,
   }: {
     parentElement: any;
-    remount: any;
+    remount: boolean;
     uid: UID;
     el: HTMLElement;
     component: Component;

pages/content/getting-started/3-configuration.md

@@ -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)

pages/content/widget-api.md

 ---
 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)

pages/content/widget-api/0-engine-api.md

+---
+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;
+```

pages/content/widget-api/1-window-api.md

+---
+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
+```

pages/content/widget-api/methods.md → pages/content/widget-api/2-examples.md

 ---
-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:
 

pages/content/widget-api/additional-functionalities.md

----
-title: "Additional Functionalities"
----
-
-# 🚧 Work in progress 🚧

pages/content/widget-api/global-api.md

----
-title: "Global API"
----
-
-# 🚧 Work in progress 🚧