Overview - postMessage API
Iframe messaging
The edmDesignerApi.openProject function will return an iframe. It is possible to communicate with this iframe with the window.postMessage native method.
Special elements and features
There are some speciel elements and functionalities what can be used with iframe messaging. You can configure most of this features in our dashboard. The basic concept behind this feature is that this configurable elements and buttons will post a message (with window.postMessage native method which was mentioned above) to the parent window (it should be your site). You should handle the message on your side, it does not matter how, and send back the content with the corresponding action name (see below). For example: a popup window where the user can take some action, set what kind of content he wants to use, and you should send back this content wiht the right action name.
Wysiwyg texteditor buttons
You can insert custom strings to the cursor position in the wysiwyg editor. With this feature you can configure texteditor buttons, which will appear in the wysiwyg editor’s toolbar. There can be as many different texteditor buttons as you want. Each button can have its own label. If a user clicks one of this buttons, it posts a message to the parent window with window.postMessage native method. This messages can be configured too in our dashboard.
The basic usecase of a texteditor button: The user edits one of his text or title, and wants to insert some custom string so he clicks to one of the texteditor buttons. It posts the configured message to the parent window (which should be your site) where you should provide an interface where he can choose which custom string he wants to use. The selected string should be posted back with the right action name to our iframe.
Please note that if you want the content to be unchanged/untouched in the generated html code then you should generate that code with the “generate without sanitizing” route (instead of the normal generate route. That way the generated code won’t be safe enough, so after you replaced your placeholders YOU SHOULD SANITIZE the code (with google caja)
Texteditor button message format
When a user clicks a texteditor button, we post you (parent window) a message. This message is a stringified json with two parameters: - action {String} The action name you configured for this type of code elements - content {String} The selected text in the editor (if there is any. It will be null if there is no selected text). Plesae note that the selected text will always be overriden with the content you send in the repsonse. If you want to keep the selected text then you should send it back in/with your content.
example: “{\"action\”: \“the action you configured for this texteditor button\”, \“content\”: \“the selected text or null if there is no selected text\”}“
Texteditor button’s structure
A texteditor button configuration has the following parameters: - id : The id/type of the texteditor button. This is what distinguish one button from another. - action : The message our iframe will send to you when a user clicks the texteditor button belonging to this configuration. (You can find how you have to respond to this message here) - label : The name of the button. This will appear as the label of the button. It is localizable and works quite similar like the header/footer localization. Please note that the "en” value is the default value, so it should always be set.
You can configure your texteditor buttons for: * every instance * every user belonging to one instance * a group of user * some selected user
A user inherits a texteditor button settings just like it is explained in the feature configuration part of the documentation
Possbile messages to send
List of the events you can send to the iframe (as a message).
Save Project
It is possible to manualy ask the iframe to save the actual (opened) project. As a response the iframe will post a save result message.
The message you need to send: saveProject
Force selected element to be deselected
It is possible to force the editor to deselect the actual selected element. There won’t be any kind of response (from the api iframe) to this message. The message you need to send: loseSelected
Insert to cursor in wysiwyg editor
The response for the incoming messages from texteditor buttons. You need to post a stringified json as the message string. It should have two properties: - action {String} The name of the action: InsertToCursor - content {String} The content (placeholders) the user wants to insert to the cursor
The message you need to send: {“action”: “InsertToCursor”, “content”: “your content goes here”}
Possible response messages
List of the events the iframe can send to your application (as a message).
Save result
It is the answer for the save project request. It can have to different statuses:
In case of success the answer message will be the following: Save result: success
In case of failure the answer message will be the following: Save result: failed
Project Loading Started
The iframe will send you a message at the begining of the project loading. The message will be the following: ProjectLoadingStarted
Project Loading Finished
The iframe will send you a message when the project loading is done. It can have different statuses: In case the project loading was succesful, the message will be the following: ProjectLoadingSuccess In case the project loading failed, the message will be the following: ProjectLoadingFailed
Tutorials
| Tutorial | Description |
|---|---|
| The Basics | In this tutorial you will learn about our dashboard, the access token generation and the very basic functionalities, like creating and opening projects. |
| Admin Functionalities | The biggest take away of this tutorial that you will see how to create new users in our system, so you will be able to associate one user for each of users in your system. |
| Old Built-in Gallery Configuration | In this tutorial you will learn about how to set up the gallery properly, how to implement the hooks on your side and you will also learn about the security of these hooks. |
Other documentations
| Document | Description |
|---|---|
| Basics | This documentation covers the very basics of the integration, like:
|
| Advanced | This documentation covers more advanced topics. Probably you will only need some of these functionalities.
|
| postMessage API | By reading this documentation you can learn about how to manipulate the editor itself from the client side. Basically this client side API is based on the postMessage function with which you can send messages between frames from different domains.
|
| Element descriptors | A detailed description of our element types used in projects and favorite elements. We generate all of our outputs based on these JSON descriptors. |
| Old built-in gallery | Don’t use it. Use the new postMessage based solution. |
| Migrating to the CDN based editor | In this article you will learn about how to migrate from the good old version of the editor to the superfast and robust CDN based version. |
Example implementations
Our PHP examples are very well maintained, but the others are probably not up-to-date. Still, they can be a good starting point, but you might want to take a look at the PHP examples as well in the meanwhile.
- PHP example
- PHP admin example
- Node.js example
- Cold Fusion example - Thank you Tom Chiverton from Extravision! :)
- Django example - Thank you Ferenc Vehmann from ZenHeads! :)
If you have another example implementation, please let us know, we will fork it and will put a link here.