Simplifying User Identity Management Across TinyMCE with User Lookup API

If you’ve used TinyMCE’s Comments or Revision History add-ons, you’ve probably run into the hassle of managing user identities separately for each one. With the 8.0 release, TinyMCE not only introduced the new Suggested Edits plugin but also the User Lookup API.

The User Lookup API aims to streamline user identity management through API methods that retain data across plugins, eliminating duplication and making it easier for developers to consistently handle and distribute user information.

Understanding the User Lookup API

The User Lookup API consists of two main components:

Configuration options

• user_id: Sets the current user's identifier, telling TinyMCE who is currently using the editor.
• fetch_users: A callback function that retrieves user details such as avatar, name, and role. Used for various plugins that use these attributes.

Runtime API methods

Once the editor is initialized, you can access:

• editor.userLookup.userId: Returns the current user's ID (as set by user_id).
• editor.userLookup.fetchUsers(userIds): Programmatically fetches user details and returns an object with user IDs as keys and Promises as values.

Understanding the User object

The User Lookup API recognizes four standard fields in each user object:

Here’s an example showing a user object with all four options. 

{
  id: 'user-123',
  name: 'Jane Smith',
  avatar: 'https://...',
  custom: {                
    role: 'viewer',         
    department: 'content',
  }
}

Note: Any additional fields must be placed inside the custom object. Fields outside these four properties will be ignored.

Getting started: User Lookup API basic setup

The simplest way to start using the User Lookup API is by setting the current user's ID:

tinymce.init({
  selector: "textarea",
  user_id: "john.doe@example.com", // Set the current user
  plugins: "image link lists media searchreplace table wordcount",
});

With just this configuration, TinyMCE will:

• Identify the current user as "john.doe@example.com"
• Provide fallback user data with auto-generated avatars
• Make the user ID available through editor.userLookup.userId

Building a complete collaborative editing implementation

For a production-ready setup, you'll want to integrate the User Lookup API with your backend user system. If you aren’t using TinyMCE yet, you can sign up for a 14-day free trial and experience the editor and the premium plugins, like those used in the following implementation.

Here's an example that demonstrates how to set up user lookups with the new Suggested Edits plugin alongside Comments and Revision History:

const userDirectory = {
  usa: {
    id: "usa",
    name: "America",
    avatar:
      "https://t4.ftcdn.net/jpg/00/65/12/49/360_F_65124908_UpNHzTdQn2HNAIT8yYqybMQeGfsRmVc7.jpg",
  },
};
tinymce.init({
  selector: "textarea",

  // Plugins - including the new Suggested Edits!
  plugins: "revisionhistory tinycomments suggestededits",

  // Toolbar buttons
  toolbar: "suggestededits | revisionhistory | addcomment showcomments",

  // User Lookup API configuration
  user_id: "usa",
  fetch_users: (userIds) => {
    return Promise.all(
      userIds.map(
        (userId) =>
          new Promise(
            (resolve) => resolve(userDirectory[userId] || { id: userId }) // Return user data or a fallback object if not found
          )
      )
    );
  },

  // Revision History configuration
  revisionhistory_fetch: () => Promise.resolve([]), // Replace with API call
  revisionhistory_display_author: true,

  // Comments plugin configuration
  tinycomments_mode: "embedded",
});

How TinyMCE collaboration features work with the User LookUp API

1. Set user_id: 'usa' to identify the current user.
2. When TinyMCE needs to display who made a comment or edit, it calls fetch_users(['usa']) to get that user's details (name, avatar, etc.).
3. If there are multiple users (like in Revision History), it may call fetch_users(['usa', 'uk', 'france']) to get details for all of them at once.

Migrating existing implementations

Note: The User Lookup API is only available in TinyMCE 8.0 and later. Make sure you've upgraded to version 8 before implementing these changes. 

If you're already using TinyMCE with plugins that require user information, migrating to the User Lookup API significantly simplifies your codebase.

Instead of configuring separate author fields and user fetchers for each plugin, you set a single user_id and provide one fetch_users function that is shared by all features. This consolidates logic, removes duplicated code and settings, and keeps user details consistent across comments, revisions, and suggested edits.

Before (Multiple user systems):

// Old approach - redundant user lookups and configurations
tinymce.init({
  selector: "textarea",
  plugins: "tinycomments revisionhistory",

  // Comments plugin configuration
  tinycomments_mode: "embedded",
  tinycomments_author: "current-user",
  tinycomments_author_name: "Current User",
  tinycomments_fetch_user: (userId) => {
    return fetch(`/api/users/${userId}`).then((r) => r.json());
  },

  // Revision History configuration
  revisionhistory_fetch: () => Promise.resolve([]), // Fetch saved revisions
  revisionhistory_display_author: true,
  revisionhistory_author: {
    id: "current-user",
    name: "Current User",
    avatar: "https://example.com/avatar.png",
  },
});

After (Unified User Lookup API):

// New approach - single user system
tinymce.init({
  selector: "textarea",
  plugins: "tinycomments revisionhistory",

  // Single user configuration
  user_id: "current-user",

  // Single fetch function for all plugins
  fetch_users: (userIds) => {
    return Promise.all(
      userIds.map(
        (userId) =>
          new Promise(
            (resolve) => resolve(userDirectory[userId] || { id: userId }) // Return user data or a fallback object if not found
          )
      )
    );
  },

  // Still need these base configurations
  tinycomments_mode: "embedded",
  revisionhistory_fetch: () => Promise.resolve([]),
  revisionhistory_display_author: true,

  // But no more plugin-specific user configurations needed!
  // The User Lookup API handles all user identity management
});

Conclusion

The User Lookup API makes it easier than ever to handle user management in TinyMCE. It offers a unified, cached, and promise-based system that removes the hassle of juggling multiple lookup implementations while boosting both speed and reliability.

Whether you’re running a simple blog with comments or building a large collaborative platform, the User Lookup API gives you a solid foundation for consistent and efficient user identity management across all TinyMCE collaborative features.

Next Steps

1. Update Your Implementation: If you're using user-dependent plugins, migrate to the User Lookup API.
2. Enhance User Experience: Try using the API to create custom user-awareness features.

Ready to get started? Check out the User Lookup API documentation and start building better collaborative experiences today!