Abstract Abstract addAdd this layout to an element
+Abstract destroyAbstract hideAbstract hideAbstract setSet content (or add iframe)
+Abstract showAbstract showGenerated using TypeDoc
+
+
+
Container for widgets
+Container constructor
+Container's DOM element
+Optional reduceViewportChange: DebounceFunction to throttle viewport change events
+Returns a Promise that resolves when the container enters the viewport from the top
+Generated using TypeDoc
+
+
+
Abstract Content element
+Generated using TypeDoc
+
+
+
Embedded layout
+destroy Destroy layout
+Creating a new layout
+Layout configuration
+Add current object to container
+Container to which the current element is added
+Set content in the layout
+Layout content
+Generated using TypeDoc
+
+
+
Consumer inside an iframe
+Constructor
+Configuration
+Additional properties
+Factory that exports a facade available to the widget
+Widget initialization function, should render the application
+Generated using TypeDoc
+
+
+
Wrapper over an iframe
+viewportChange Event when the viewport of the element changes + destroy Termination of the provider
+Creating a new provider instance
+Get the visible area of the iframe
+Subscription to changes in the visible area of the iframe
+Callback function
+Generated using TypeDoc
+
+
+
Mediator - a widget factory
+Creating a new instance of the mediator
+Widget configuration
+Additional properties/methods for the mediator +You can specify an object with any properties, except for reserved ones (and properties starting with _):
+Mediator identifier
+Prefix used for data-attributes
+Widget instances
+Widgets
+Create a widget and place it on the page
+Widget name
+Element/selector where the widget will be inserted
+Optional params: Record<string, any>Widget initialization parameters
+Create a widget and place it on the page
+Widget name
+Optional params: Record<string, any>Widget initialization parameters
+Define a widget
+Widget configuration
+Additional widget properties, this object is copied to the widget as is and supplements it with these properties
+Factory that exports a facade available to the widget
+Create a widget and place it on the page
+Widget name
+Element/selector where the widget will be inserted
+Optional params: Record<string, any>Widget initialization parameters
+Create a widget and place it on the page
+Widget name
+Optional params: Record<string, any>Widget initialization parameters
+Initialization of DOM elements
+Factory that exports a facade available inside an iframe
+Create a widget and place it on the page
+Widget name
+Element/selector where the widget will be inserted
+Optional params: Record<string, any>Widget initialization parameters
+Create a widget and place it on the page
+Widget name
+Optional params: Record<string, any>Widget initialization parameters
+Initialization of DOM elements
+Generated using TypeDoc
+
+
+
Layout for modal window
+destroy Destroy layout
+Create a new layout
+Layout configuration
+Set content in layout
+Layout content
+Generated using TypeDoc
+
+
+
Widget
+destroy Widget deletion event
+Creating a new widget instance
+Mediator
+Widget identifier
+Widget configuration
+Widget properties, this object is copied as is into the widget and supplements it with these properties
+Some external parameters for the widget. +You can specify an object with any properties, except for reserved ones (and properties starting with _):
+Widget identifier
+Widget name
+Set a container for the widget
+Create an iframe
+The URL where the iframe is located
+A factory that exports the facade available in the iframe
+Destroy the widget and stop listening events
+Create a widget and place it on the page
+Widget name
+Element/selector where the widget will be inserted
+Optional params: Record<string, any>Widget initialization parameters
+Create a widget and place it on the page
+Widget name
+Optional params: Record<string, any>Widget initialization parameters
+Initialization of DOM elements
+Scroll to a specific part of the iframe
+The coordinate relative to the top-left corner of the iframe to scroll to
+Scroll animation time, default is 200
+Callback for iframe viewport change (whether the iframe is visible or not)
+Wait when the container enters the viewport from the top
+Generated using TypeDoc
+
+
+
Creating a mediator
+Configuration
+Optional properties: Record<string, any>Additional properties
+Generated using TypeDoc
+
+
+
Creates a manager that monitors changes to the viewport of an element
+Generated using TypeDoc
+
+
+
Iframe registration
+Configuration
+Additional properties
+Generated using TypeDoc
+
+
+
Generated using TypeDoc
+
+
+
Generated using TypeDoc
+
+
+
Library helps you to create widgets, including widgets that work via an iframe.
+postMessage directly.npm install widgetly
+or
+yarn add widgetly
+The Mediator is an instance of the widget factory. After creating an instance, you can declare widgets. If you are using iframe widgets, place this code in the parent window.
+// ./mediator.ts
import {createMediator} from 'widgetly'
export const mediator = createMediator({
// Prefix for data attributes when inserting widgets via HTML code
prefix: 'rc'
}, {
myMethod() {
return 1
},
someProp: {
someMethod() {
return 2
}
}
})
+After creating the mediator, you can start declaring widgets via the factory.
+mediator.defineWidget(config, properties)
+// ./widget.ts
import {EmbedLayout} from 'widgetly'
import {mediator} from './mediator'
mediator.defineWidget({
// Widget name
name: 'EmbedComments',
// Widget initialization function
// - should return a Promise
// - should render the widget
async initialize() {
// Wait until the widget enters the viewport
await this.whenContainerInViewport({lazy: true})
// Create an iframe tied to the current widget
this.iframe = this.createIframe(iframeUrl)
// Create an embedded layout
this.layout = new EmbedLayout({
spinner: '<div class="Spinner" />'
})
this.layout.showLoading()
this.layout.addToDOM(this.container)
this.layout.setContent(this.iframe)
// Wait until the widget renders in iframe
await this.iframe.initialize()
this.layout.hideLoading()
}
}, {
// All methods declared here will enrich widget
hide() {
this.layout.hide()
},
show() {
this.layout.show()
}
})
+// ./widget.ts
import {OverlayLayout} from 'widgetly'
import {mediator} from './mediator'
mediator.defineWidget({
// Widget name
name: 'LoginModal',
// Widget initialization function
// - should return a Promise
// - should render the widget
async initialize() {
// Create an iframe tied to the current widget
this.iframe = this.createIframe(iframeUrl)
// Create an overlay layout
this.layout = new OverlayLayout({hidden: true})
this.layout.setContainer(this.container)
this.layout.setContent(this.iframe)
// Wait until the widget renders in iframe
await this.iframe.initialize()
this.layout.show()
}
})
+Layout is an element into which an iframe and loader are inserted.
+There are following types of layouts:
+Inside the iframe, you need to wrap the initialization of your widget.
+registerIFrame(config, properties)
+// ./app.tsx
import React, {useEffect} from 'react'
export const App = ({transport, onReady}) => {
useEffect(() => {
onReady()
}, [onReady])
return (
<TransportContext.Provider value={transport}>
<main>
...
</main>
</TransportContext.Provider>
)
}
+// ./iframe.tsx
import React from 'react'
import {createRoot} from 'react-dom/client'
import {registerIFrame} from 'widgetly'
import {App} from './app'
const rootElement = document.getElementById('my_app')
const root = createRoot(rootElement)
registerIFrame({
async initialize() {
await new Promise(resolve => {
root.render(
<App
transport={this}
onReady={resolve}
/>
)
})
}
})
+The mediator can automatically create widgets in containers with the corresponding data attributes when it appears in the DOM.
+// ./app.ts
import React from 'react'
import './mediator'
export const App = () => {
return (
<div
data-rc-widget="EmbedComments"
data-rc-app-id={APP_ID}
data-rc-page-url={window.location.pathname}
/>
)
}
+Or create widget through the factory to gain full control over the widget.
+mediator.buildWidget(name, containerElement, params)
+// ./app.ts
import mediator from './mediator'
const container = document.getElementById('my_comments');
mediator.buildWidget('EmbedComments', container, {
appId: APP_ID,
pageUrl: window.location.pathname
}).then(widget => {
// At this moment, you can use the widget external methods
});
+Currently we only have the API which you can check here.
+After you clone the repo you just need to run yarn's default command to install and build the packages
yarn
+We have a test suite consisting of a bunch of unit tests to verify utils keep working as expected. Test suit is run in CI on every commit.
+To run the tests
+yarn test
+To run the tests in watch mode
+yarn test:watch
+To run linting the codebase
+yarn lint
+To check typings
+yarn typecheck
+To check bundle size
+yarn sizecheck
+Please open an issue if you have any questions or concerns.
+MIT
+Generated using TypeDoc
+
+
+
Generated using TypeDoc
+
+
+
Container element
+Generated using TypeDoc
+
+
+
Generated using TypeDoc
+
+
+
Generated using TypeDoc
+
+
+
Generated using TypeDoc
+
+
+
Widget facade available to the user
+Generated using TypeDoc
+
+
+
Configuration of the consumer inside an iframe
+Optional externalizeOptional externalizeGenerated using TypeDoc
+
+
+
Mediator configuration
+Prefix for data-attributes
+Optional externalizeFactory that exports a facade available in an iframe
+Generated using TypeDoc
+
+
+
Overlay layout configuration for modal window
+Optional animationDuration of opacity animation in ms, default 200
+Optional classCSS class added to element
+Optional hiddenAdd hidden layout to DOM
+Optional spinnerHTML template for spinner
+Generated using TypeDoc
+
+
+
Base viewport manager
+Generated using TypeDoc
+
+
+
Visible area
+Visible height of the element
+Coordinates relative to the top left corner of the element from which it is visible
+Coordinates relative to the top left corner of the element from which it is visible
+Visible width of the element
+Generated using TypeDoc
+
+
+
Widget configuration
+Unique widget name
+Optional reduceFunction to slow down the processing of Viewport changes, if it is absent, the standard debounce is used
+Optional destroyWidget deletion function, this function should be called by the user when deleting the widget
+Optional externalizeA factory that exports the facade available to the user.
+By default, exports properties passed to the widget and properties that the iframe exports
Optional externalizeA factory that exports the facade available in the iframe
+Widget initialization function, should render the widget
+Generated using TypeDoc
+
+
+
Generated using TypeDoc
+
+
+
Const Monitor scroll window
+Generated using TypeDoc
+
+
+
Const Create a MutationObserver
+Generated using TypeDoc
+
+
+
Basic layout
+destroy Destroy layout
+