User Management

The User Management feature provides a centralized and extensible mechanism for managing user information in SpreadJS-based applications.

It defines how user data—such as names, IDs, and avatars—is created, accessed, and updated across components like Threaded Comments or Collaboration tools.

Core Concepts

User

A User is a plain JavaScript object that implements the IUser interface.

It represents an individual user and contains key identity properties such as:

• id – Unique user identifier.

• name – Display name of the user.

• email (optional) – Contact or reference information.

• avatar (optional) – Visual representation that can be defined by various image source formats.

• color (optional) – Custom color used for user labeling or visual distinction.

A sample user object might look like this:

{
  id: "user1",
  name: "Alice",
  email: "alice@example.com",
  color: "#5B8FF9"
}

UserManager

The UserManager object, available under the GC.Spread.Common namespace, provides global functions to access and control user information within the spreadsheet environment.

• It is a global singleton—no instantiation is required.

• It controls how user data is stored, fetched, and updated throughout the entire application.

• It manages all registered users and their associated metadata.

• It supports configuration for user look‑up, searching, and event binding.

• You can use it to set or get the current user context at runtime.

• It provides an async function get for get user info.

The UserManager serves as a shared service for user‑related operations across the entire SpreadJS platform.

Setup and Configuration

To enable user management, you need to define your application’s user data and configure how the UserManager retrieves user information.

The configuration step tells SpreadJS how to:

• Get user details by ID.

• Perform user searches.

• Optionally, specify color schemes for consistent visual identity.

Define Users

A user is represented by a JavaScript object following the IUser interface.

Each user requires at least an id and name, and can optionally include other properties such as email, avatar, or color.

// Example
var users = [
  { id: "user1", name: "Alice", email: "alice@example.com" },
  { id: "user2", name: "Bob",   email: "bob@example.com" }
];

Configure the UserManager

The UserManager must be configured once—typically during application initialization—using the configure() method.

This method accepts a configuration object that defines how user data is fetched and searched.

• get(userId) – Returns a Promise<IUser> resolving to a user object for a given ID. The get method will invoke the get method configured in IUserManagerOptions.

• search(query) – (Optional) Returns matching users when implementing a user selection UI.

• colorScheme – (Optional) Defines custom colors used when avatars or display colors are auto‑generated.

// Example
const options = {
  get: async (userId) => {
        if (userId === undefined) {
            return;
        }
        return new Promise((resolve) => {
            const user = users.find(u => u.id === userId);
            resolve(user);
        });
    },
    search: async (query) => {
        return new Promise((resolve) => {
            resolve(users.filter(u => 
                        u.name.toLowerCase().includes(query.toLowerCase()) || 
                        u.email.toLowerCase().includes(query.toLowerCase())
                    ));
        });
    }
}

GC.Spread.Common.UserManager.configure(options);

Once configured, the UserManager functions as a global singleton, allowing other SpreadJS features—such as Threaded Comments—to automatically reference user data by ID.

Using the UserManager

Once the UserManager is configured, you can use it to manage and respond to the current user context within your application.

This includes setting or retrieving the current active user, and handling user‑related events.

Setting the Current User

The current() method is used to get or set the ID of the current user.

Examples:

// Set current user
GC.Spread.Common.UserManager.current("user1");

// Get current user
var currentUserId = GC.Spread.Common.UserManager.current();

When automatically created, the Guest user will have:

• A random UUID as id

• A culture‑specific display name (for example, “Guest” in English culture)

Handling User Events

UserManager supports event subscription and management through the following methods:

• bind(event, handler): Subscribe a function to an event. The handler will be invoked when the event occurs.

• unbind(event, handler?): Unsubscribe a function. If no handler is given, all handlers for that event are removed.

Supported Events:

• CurrentUserChanged — This event is triggered asynchronously whenever the current user is successfully changed.

You can subscribe to this event to react to user context changes in your application logic, such as updating the UI or refreshing user‑specific data.

Examples:

function onUserChanged(event, args) {
  console.log(`User changed: ${args.oldCurrentUser?.id} → ${args.newCurrentUser?.id}`);
}

// Subscribe to event
GC.Spread.Common.UserManager.bind(GC.Spread.Common.UserManager.Events.CurrentUserChanged, onUserChanged);

// Unsubscribe from event
GC.Spread.Common.UserManager.unbind(GC.Spread.Common.UserManager.Events.CurrentUserChanged, onUserChanged);

Avatar Handling Rules

If no avatar image is provided:

• The uppercase first letter of user.name will be used as avatar text.

• The avatar background color is derived from user.color if defined.

• If user.color is not specified, a deterministic color is chosen from a pre-set color scheme based on the user’s ID.

Default Color Scheme

SpreadJS uses the following default palette of 20 colors when no custom colorScheme is specified:

#3B82F6  #10B981  #8B5CF6  #F59E0B  #EF4444
#06B6D4  #EC4899  #84CC16  #6366F1  #14B8A6
#F97316  #A855F7  #22C55E  #EAB308  #F43F5E
#0EA5E9  #D946EF  #65A30D  #DC2626  #7C3AED

Developers can override the default scheme by specifying a colorScheme array when configuring the UserManager.

// Example
GC.Spread.Common.UserManager.configure({
  get: async (userId) => {
        if (userId === undefined) {
            return;
        }
        return new Promise((resolve) => {
            const user = users.find(u => u.id === userId);
            resolve(user);
        });
    },
    search: async (query) => {
        return new Promise((resolve) => {
            resolve(users.filter(u => 
                        u.name.toLowerCase().includes(query.toLowerCase()) || 
                        u.email.toLowerCase().includes(query.toLowerCase())
                    ));
        });
    }
  colorScheme: ["#5B8FF9", "#61DDAA", "#F6BD16"] // custom colors
});