How to configure Dialogs with TinyMCE

Easy to use interfaces are essential. You don’t want your readers to get stuck in some visual swamp when they're trying to get a goal finished in your application. One way to streamline user experience is to make your Dialog’s easy to understand, and easy to use.

We’ve drawn on an example Dialog (the box or window that opens when users click on certain plugins), and the following article highlights the different components of a Dialog – to help illustrate how they’re configured in TinyMCE.

What are rich text editor Dialogs?

A Dialog is a specific set of components that help you create and build – by introducing some specific JavaScript objects into your rich text editor HTML. A Dialog is made up of three components: the title, the body, and the footer. When you open up the Advanced Source Code plugin, the window that opens contains a header (“Source Code”), a body (The text editor content in HTML), and the footer (The “Cancel” and “Save” buttons). 

Depending on your user’s needs, you can build your own Dialog by thinking of what microcopy and functions you need in each of the three components.

The body component

The first step to understanding the Dialog configuration needed for building a custom Dialog is to understand what’s possible with the body component. This component holds the most information. It’s where end users look and spend the most time dwelling on when they think about what step to take next.

Here are some of the Dialog body options: 

1. Panel or TabPanel – These two components hold onto Dialog body components. They are an array of items, where the items in the array are the body components.
2. Bar – Creates a single row of items in the Dialog body.
3. Collection – This shows the user a series of buttons to select, like a grid of emoji.
4. Input – Provides a text input field for the user, with a label next to the text entry field (to help the user complete their goal).

The following paragraphs contain an example of a custom Dialog that uses a Panel component containing an Input component.

How to configure a custom Dialog

For this example, we’ll use a TabPanel, with the user’s goal being to select something from a group of different options.

1. Set up a variable in your rich text editor HTML for the new Dialog
2. Use the title, body, and button functions to form the core of the Dialog
3. Add in the specific body elements

Implementing a web based API is required for the Dialog to work correctly and help users complete their goals. For the example, we’ve used the initalData Dialog option, which connects to the getData() API.

When the user completes their goal, and confirms they are finished by clicking the button in the Dialog footer, the information typed into the Dialog travels through the API call, and then TinyMCE publishes the content into the text editor with the tinymce.activeEditor.execCommand function. 

  initialData: {
    catdata: 'initial Cat',
    isdog: false
  },
onSubmit: function (api) {
    var data = api.getData();
    var pet = data.isdog ? 'dog' : 'cat';

    tinymce.activeEditor.execCommand('mceInsertContent', false, '<p>My ' + pet +'\'s name is: <strong>' + data.catdata + '</strong></p>');
    api.close();
  }
};

There are several other API actions you can include, and our documentation describes them in detail.

Configure the Title and Dialog body

var dialogConfig =  {
  title: 'Pet Name Machine',
  body: {
    type: 'panel',
    items: [
      {
        type: 'input',
        name: 'catdata',
        label: 'enter the name of a cat'
      },
      {
        type: 'checkbox',
        name: 'isdog',
        label: 'tick if cat is actually a dog'
      }
    ]
  },

Configure the Dialog footer

  buttons: [
    {
      type: 'cancel',
      name: 'closeButton',
      text: 'Cancel'
    },
    {
      type: 'submit',
      name: 'submitButton',
      text: 'Do Cat Thing',
      primary: true
    }
  ],

The example Dialog also Includes the tinymce.init JavaScript:

tinymce.init({
  selector: "textarea.petMachine",
  toolbar: "dialog-example-btn",
  setup: function (editor) {
    editor.ui.registry.addButton("dialog-example-btn", {
      icon: "code-sample",
      onAction: function () {
        editor.windowManager.open(dialogConfig);
      },
    });
  },
  content_style:
    "body { font-family:Helvetica,Arial,sans-serif; font-size:14px }",
});

Since customized Dialog configurations can become lengthy, especially when using the TabPanel component, configuring a separate JavaScript file can help organize your web application development. The Pet Name Dialog example resides inside a separate JavaScript file, which connects to the rich text editor HTML index file. 

What’s next?

You can find a complete version of the Pet Name Dialog in our TinyMCE documentation. Once you’ve tested a Dialog, you can try creating some other custom design elements such as images, to ensure that users working with your rich text editor achieve their goals.