		{
		"name": "@chili-publish/publisher-interface",
		"version": "0.3.0",
		"version": "0.3.1",
		"author": "chili-publish",
		@@ -50,2 +50,4 @@ "description": "PublisherInterface is a class object that allows you to interact with the CHILI Publisher editorObject via postMessage without the complexity of postMessage.",
		"@parcel/transformer-typescript-types": "2.5.0",
		"@playwright/test": "^1.27.1",
		"@types/node": "^18.11.2",
		"@typescript-eslint/eslint-plugin": "^5.27.0",
		@@ -55,2 +57,3 @@ "@typescript-eslint/parser": "^5.27.0",
		"parcel": "2.5.0",
		"playwright": "^1.27.1",
		"typedoc": "^0.22.17",
		@@ -64,4 +67,5 @@ "typescript": "^4.7.2"
		"build": "parcel build",
		"build-docs": "typedoc ./src/PublisherInterface.ts"
		"build-docs": "typedoc ./src/PublisherInterface.ts",
		"test": "node ./test/run_tests.js"
		}
		}

195

README.md

		# Publisher Interface
		The Publisher Interface was designed to make integrating into CHILI publish Online easy.

		PublisherInterface is a class object that allows you to interact with the CHILI Editor editorObject via [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) without
		the complexity of postMessage.
		As a happy side effect, the setter for `document.domain`, which many integrations rely on, will become immutable at the beginning of January 2023. This means that the Publisher Interface will be the only supported way to communicate with Publisher via an `<iframe>`.

		Why choose this over interacting with the editorObject directly?
		All the magic happens with `PublisherInterface` PublisherInterface is a class object that allows you to interact with the CHILI Editor editorObject via postMessage without the complexity of postMessage.

		* The first and most obvious reason is CORS - by using PublisherInterface you do not have to worry about reverse proxy tricks, which are are not officially supported.
		* The documentation of each function of PublisherInterface (really the editorObject) is the most complete documentation in existence.
		* Works with CHILI publisher Online.
		* Promise based and modern.
		This project is officially supported by [CHILI publish](https://chili-publish.com).

		<br/>
		Notes:
		* The Publisher JavaScript API has been stable for years, and there is no plans to add to it. So this project may not get many updates. That is a good thing, it means there is no bugs.
		* Originally this project was called Publisher Connector. The name was changed to avoid confusion with the future connectors plugin system. Please update your projects if you were using the old naming convention and library.

		#### Note:
		As of version 0.3, the project name was changed from PublisherConnector to PublisherInterface to avoid confusion with future connector plugins.
		## Documentation
		You can find complete documentation on the [wiki](https://github.com/chili-publish/publisher-interface/wiki/Converting-To-Publisher-Interface)

		<br/>
		* [Installation](#installation) - Easy npm install.
		* [Getting Started](#getting-started) - A very quick tutorial to get you started.
		* [Why I Cannot Use editorObject](https://github.com/chili-publish/publisher-interface/wiki/Why-I-Cannot-Use-editorObject) - A description of why `editorObject` can no longer be used when communicating with an `<iframe>`.
		* [Differences With editorObject](https://github.com/chili-publish/publisher-interface/wiki/Differences-With-editorObject) - All the differences between `PublisherInterface` and `editorObject`.
		* [Integrating Publisher](https://github.com/chili-publish/publisher-interface/wiki/Integrating-Publisher) - A much longer tutorial for those starting a new project with Publisher.
		* [Moving to Publisher Interface](https://github.com/chili-publish/publisher-interface/wiki/Moving-to-Publisher-Interface) - A guide for those who already have a project with Publisher and are now converting their current integration from `editorObject` to Publisher Interface.
		* [Big List of JavaScript Use Cases](https://github.com/chili-publish/publisher-interface/wiki/Big-List-of-JavaScript-Use-Cases) - A very long list of JavaScript use cases. [WIP]
		* [API Documentation](https://github.com/chili-publish/publisher-interface/wiki/API-Docs) - auto-generated documentation of the `PublisherInterface` class and associated types. Even though it is auto-generated, the comments therein were written with insight.

		## Installation

		You can install PublisherInterface via npm

		`npm i @chili-publish/publisher-interface`
		```
		npm i @chili-publish/publisher-interface
		```

		<br/>

		or through yarn
		```
		yarn add @chili-publish/publisher-interface
		```

		`yarn add @chili-publish/publisher-interface`
		<br/>

		## Usage

		1. Import PublisherInterface.

		If you downloaded the library:
		You can also use it directly in the browser via unpkg.
		```javascript
		import {PublisherInterface} from "@chili-publish/publisher-interface";
		import {PublisherInterface} from "https://unpkg.com/@chili-publish/publisher-interface@latest/dist/PublisherInterface.min.js";
		```

		or using in the web via unpkg URL:
		## Dependencies
		The Publisher Interface has 1 dependency which is the [Penpal](https://github.com/Aaronius/penpal) library.

		All other dependencies are only for the developer tools such as auto generating docs, testing, and packaging.

		This means that their is very little security concerns, and the limitations are the same as those found in [Penpal](https://github.com/Aaronius/penpal)

		### Browser Support

		Publisher Interface runs successfully on the most recent versions of Chrome, Firefox, Safari, and Edge. Internet Explorer is
		not supported.

		## Getting Started
		The easiest way to get started is to pull the package from unpkg.

		```javascript
		@@ -46,14 +67,15 @@ import {PublisherInterface} from "https://unpkg.com/@chili-publish/publisher-interface@latest/dist/PublisherInterface.min.js";
		<br/>
		2. Get the HTMLIFrameElement which contains the CHILI Editor.

		If you downloaded via NPM you can import it with
		```javascript
		const iframe = document.getElementById("editor-iframe");
		import {PublisherInterface} from "@chili-publish/publisher-interface";
		```

		<br/>
		3. Create an instance of PublisherInterface by using the `build` method and passing the HTMLIFrameElement (created above)
		as a parameter. The `build` method returns a promise, which when resolved has the instance of the PublisherInterface.

		Then in your JavaScript code, get the iframe which is loading the Publisher editor, and pass that iframe element into the `build()` function of `PublisherInterface`.

		```javascript
		PublisherInterface.build(iframe).then(
		const iframe = document.getElementById("editor-iframe");
		const interface = PublisherInterface.build(iframe).then(
		PublisherInterface => PublisherInterface.alert("Hi!")
		@@ -63,15 +85,7 @@ );

		🚨 Important - make sure that you call `build()` before the iframe `onload` event is fired. In practice this means that you should never call `build()` when that event is fired.

		<br/>

		### 🚨️ IMPORTANT 🛑

		The PublisherInterface `build` method must be called before the IFrame loads the Editor. This is due to
		how [Penpal](https://github.com/Aaronius/penpal), the library the PublisherInterface is built on, functions.

		If you set the `src` attribute of the IFrame in your HTML and have a script tag that runs the build method, then
		everything will be fine. The issue is only if you were to wait until IFrame was loaded before calling the `build`
		method.

		For example the below code will work because the `build` method is called before the IFrame is loaded.

		Here is a complete example:
		```html
		@@ -87,4 +101,4 @@ <body>
		(async () => {
		const PublisherInterface = await PublisherInterface.build(iframe);
		const documentName = await PublisherInterface.getObject("document.name");
		const interface = await PublisherInterface.build(iframe);
		const documentName = await interface.getObject("document.name");
		console.log(documentName);
		@@ -96,105 +110,4 @@ })();

		## API Reference

		- [PublisherInterface](/docs/index.html)

		## Differences with `editorObject`

		The PublisherInterface class and editorObject object share many similarities. This is not odd as the PublisherInterface is an
		interface for interacting with the editorObject via postMessage. Below will mark any key differences.

		### Naming

		A small, but important difference is that the methods from the PublisherInterface uses common JavaScript naming - camel
		case. This differs from the Pascal case used by the editorObject.

		So `editorObject.GetObject` becomes `PublisherInterface.getObject`.

		So `editorObject.SetProperty` becomes `PublisherInterface.setProperty`.
		<br/>
		<br/>

		### Promise Return

		While the editorObject methods return without delay, the PublisherInterface uses postMessage. This means that the message
		must be serialized, sent, deserialized across from one window to another.

		To make this easy, the PublisherInterface methods return a Promise.

		So instead of:

		```javascript
		const documentId = editorObject.GetObject("document.id");
		console.log(documentId);
		```

		You would do:

		```javascript
		PublisherInterface.getObject("document.id").then(
		documentId => console.log(documentId)
		);
		```

		or use `await`, in a function marked `async`:

		```javascript
		const documentId = await PublisherInterface.getObject("document.id");
		console.log(documentId);
		```

		Just like editorObject methods, if something goes wrong, an error will be thrown.
		<br/>
		<br/>

		### Events

		The PublisherInterface does events completely different from what is documented for the editorObject.

		To use events with the editorObject, it involved called the `editorObject.AddListener` method and then defining a
		function on `window.OnEditorEvent` that took a string for events. The OnEditorEvent function would typically have a
		switch case or a series of if/else to determine which event was called.

		PublisherInterface makes things much simpler. If you want to listen to an event and then do something, then name it and add
		a callback function.

		```javascript
		await PublisherInterface.addListener(
		"FrameMoveFinished",
		target => console.log("Frame moved with id " + target)
		);
		```

		Removing an event is pretty much the same.

		```javascript
		await PublisherInterface.removeListener("FrameMoveFinished");
		```

		<br/>

		### Getting PublisherInterface

		When not using postMessage, there were two common methods to get the editorObject.

		* Editor page would allow you to set a callback using GetEditor on the IFrame contentWindow to get the editorObject
		* DocumentFullyLoaded event was called by default, so you could wait until that event was fired and sent to
		window.OnEventEvent to get the editorObject directly from the IFrame contentWindow

		Neither of these methods are possible now, and you will need to use the `build` method on PublisherInterface. See Usage
		above.
		<br/>

		## Limitations

		PublisherInterface is built on [Penpal](https://github.com/Aaronius/penpal), which means that it inherits all same
		limitations.

		### Browser Support

		PublisherInterface runs successfully on the most recent versions of Chrome, Firefox, Safari, and Edge. Internet Explorer is
		not supported.

		### Errors

		See [Penpal Errors](https://github.com/Aaronius/penpal#errors)
		To read more, check out our [documentation](#documentation).

dist/chiliInternalWrapper.js

dist/chiliInternalWrapper.js.map

dist/PublisherConnector.d.ts

dist/PublisherConnector.js

@chili-publish/publisher-interface - npm Package Compare versions

New alerts

Improved metrics

Worsened metrics