Writing WYMeditor Plugins

Plugin-Writing Mini Guide

1. Create an example in examples/

Make sure and provide a description on the example page and ideally, initialize the editor with content that makes playing with your plugin easy.

Note

Please avoid adding a file in test other than for unit tests. The .html files in test rot quickly (other than unit tests) because users don’t see them.

Serving Examples

You can load your example via:

$ grunt server
$ google-chrome http://localhost:9000/examples/

Serving Examples from dist/

To make sure your examples also works from the built distribution, we can tell grunt to build first:

$ grunt server:dist
$ google-chrome http://localhost:9000/examples/

2. Create your plugin folder

  • Your folder will live at src/wymeditor/plugins/<pluginName>.
  • Your main javascript file should be jquery.wymeditor.<pluginName>.js.
  • Any images or CSS should live in that folder.

3. Build your awesome thing

Now get cracking!

See the Example Contribution Process guide for general contribution advice.

If you get stuck, join us in the #wymeditor IRC channel on freenode.

4. Document your awesome plugin

Create a docs/wymeditor_plugins/included_plugins/<your_plugin>.rst file and tell your future users:

  1. What your plugin does.
  2. How to enable it (a link to the example is good).
  3. How to customize it, if you have customization options.
  4. Anything else they need to know about browser compatibility, etc.

Plugin Do’s and Don’ts

Don’t enable your plugin on file load

Your plugin should not activate itself just by loading your plugin’s javascript. To use your plugin, the user must add some kind of initialization in the wymeditor postInit. For example:

jQuery('.wymeditor').wymeditor({
    postInit: function(wym) {
        wym.yourPlugin = new YourPlugin({optionFoo: 'bar'}, wym);
    }
});

Note

The embed plugin currently violates this, which is a bug.

Mark your dialog-opening buttons

If your plugin includes buttons that open dialog windows, mark the list item with the class wym_opens_dialog. This will prevent your dialog window from opening in the background.

Handle focus

When UI interactions steal focus from the document, consider using editor.focusOnDocument.

For example, right before a dialog window closes.