CODEX

Implementing a TinyMCE URL Dialog

URL dialogs are TinyMCE UI components used to display external web pages. These dialogs are used in scenarios where standard TinyMCE plugins and dialogs do not suffice. The external page displayed in the URL dialog may be hosted on a completely different domain than the TinyMCE parent.

Figure 1: web page with TinyMCE editor and URL dialog

Communication

Messaging between the TinyMCE editor and the external page is done with JavaScript through the window.postMessage() method which allows cross-origin communication between the window objects.

Figure 2: messaging between TinyMCE and external page

To follow along with the rest of this article you may wish to open the demo application and download the source code from GitHub.

Cloning demo application from GitHub

$ git clone https://github.com/jeffholst/tinymce-url-dialog
$ cd tinymce-url-dialog

The tinymce-url-dialog folder should now contain the following files:

• README.md
• main.js
• index.html
• dialog.html

Demo Walkthrough

1. open the index.html file in a web browser
2. click the Open URL Dialog button in the TinyMCE toolbar to open a new dialog window
3. in the URL Dialog click the Get TinyMCE Content button to retrieve the “Hello, World!” content of the parent TinyMCE editor
4. in the URL Dialog update the TextArea to say “Hello, Galaxy!” instead of “Hello, World!”
5. in the URL Dialog click the Set TinyMCE Content button to update the parent TinyMCE with the new message
6. close the URL Dialog by clicking the X in the top right corner
7. The TinyMCE content should now say “Hello, Galaxy!”

Figure 3: Demo Walkthrough

Overview

main.js

To simplify this demo all JavaScript used by both index.html and dialog.html is contained in the main.js file.

index.html

This is the starting page for the project and contains the TinyMCE editor. Once the page is loaded in the browser the main.js/initializeParent() function is called.

Figure 4: index.html

The main.js/initializeParent() function initializes the TinyMCE with these key features:

• an Open URL Dialog button is added to the TinyMCE toolbar
• clicking the Open URL Dialog button fires the onAction() function and opens the external dialog.html file in a modal window
• the onMessage() function is added to listen for messages from the external page
• the sendMessage() API call is used to send messages from the TinyMCE to the external page.

Figure 5: main.js initialization of TinyMCE

dialog.html

When the Open URL Dialog button is clicked in the TinyMCE editor the external dialog.html is displayed as the URL dialog. Once the page is loaded in the browser the main.js/initializeDialog() JavaScript function is called.

Figure 6: dialog.html

The key feature of the main.js/initializeDialog() function is to add a window.addEventListener() function to the page to listen for messages from the TinyMCE parent window.

Figure 7: main.js adding window.addEventListener() to page

The window.addEventListener() function is responsible for checking the received event.origin to verify it should be accepted and then needs to examine the event.data to determine what to do.

The external dialog.html page sends messages to the parent TinyMCE with the window.parent.postMessage call in the main.js/sendMessage() function.

Figure 8: main.js — sendMessage()

Syntax: window.parent.postMessage(message, targetOrigin)
message: data sent to parent window
targetOrigin: specifies what the origin of the parent window must be to dispatch the event.  Wildcard(*) indicates no preference otherwise the scheme, hostname, and port of the specified origin must match for the event to be dispatched

Communicate Flow

Figure 9: Communication flow

Conclusion

For additional examples and to see all the configuration options for a TinyMCE URL dialog, be sure to check out the official documentation.

References

• Demo Link
• GitHub Repository
• Getting Started with TinyMCE
• TinyMCE Docs | URL dialog