Skip to content

Commit 24d5e4b

Browse files
kemister85kemister85
committed
DOC-3246: userlookup api docs restructure and organisation update.
1 parent f160ba4 commit 24d5e4b

File tree

3 files changed

+137
-111
lines changed

3 files changed

+137
-111
lines changed

‎modules/ROOT/pages/userlookup.adoc‎

Lines changed: 133 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,117 @@
1-
= Using the User Lookup API
1+
= User Lookup API
2+
:navtitle: User Lookup
23
:description: TinyMCE User Lookup provides an API to identify the current user and retrieve user details via integration-defined methods.
3-
:keywords: userLookup, fetchUsers, userId, avatar, user metadata
4+
:keywords: userLookup, fetchUsers, user_id, user management, collaborative editing
45

56
The {productname} User Lookup API enables integrations to retrieve and cache user details (such as names and avatars) and identify the current user within the editor.
67

7-
This is useful when building features that rely on user context, such as commenting, or displaying a list of elements container user information, and lets you manage user data efficiently with built-in caching.
8+
This is useful when building features that rely on user context, such as commenting, collaborative editing, or displaying user-specific information. The API provides built-in caching for efficient user data management.
89

9-
== Using the User Lookup API
10+
== How it works
1011

11-
Follow the steps below to configure and use the `userLookup` API.
12+
The User Lookup API provides two main functions:
1213

13-
[[step-1-set-the-current-user]]
14-
=== 1. Set the current user_id
14+
[cols="2,4",options="header"]
15+
|===
16+
|Method|Description
1517

16-
The first step is to tell the editor which user is currently active. This is done using the `+user_id+` initialization option.
18+
|`editor.userLookup.userId`|Returns the current user's ID, set via the `user_id` configuration option.
19+
|`editor.userLookup.fetchUsers(userIds)`|Fetches and caches user information. Returns a Promise-based lookup object.
20+
|===
1721

18-
include::partial$configuration/user_id.adoc[leveloffset=+2]
22+
== Basic setup
1923

20-
To access it:
24+
For a basic setup, you only need to configure the `user_id` option:
25+
26+
[source,js]
27+
----
28+
tinymce.init({
29+
selector: '#editor',
30+
user_id: 'current-user-id'
31+
});
32+
----
33+
34+
For more advanced user data fetching, see the <<options,Options>> section below.
35+
36+
== Understanding user lookup
37+
38+
The User Lookup API handles three main scenarios:
39+
40+
1. **Basic identification**: Setting a current user ID for editor context
41+
2. **Dynamic fetching**: Retrieving user details from backend systems
42+
3. **Fallback behavior**: Auto-generating user data when no fetch function is provided
43+
44+
== Data structure
45+
46+
=== User
47+
48+
The user is an `Object` that contains the following fields:
49+
50+
[cols="1,1,1,3",options="header"]
51+
|===
52+
| Field | Type | Required? | Description
53+
| `id` | `string` | required | The unique string ID of the user.
54+
| `name` | `string` | optional | The display name of the user. If not provided, defaults to the `id`.
55+
| `avatar` | `string` | optional | The URL of the user's avatar image or data URI. If not provided, an auto-generated SVG using the user's initials will be used.
56+
| `custom` | `Object` | optional | Additional metadata for the user.
57+
|===
58+
59+
.Example user object:
60+
[source,js]
61+
----
62+
{
63+
id: 'user-1', // Required: User identifier
64+
name: 'Jane Doe', // Optional: Display name (defaults to id)
65+
avatar: 'https://...', // Optional: Avatar URL or data URI
66+
custom: { // Optional: Additional metadata
67+
role: 'admin',
68+
department: 'engineering'
69+
}
70+
}
71+
----
72+
73+
== Options
74+
75+
The following configuration options affect the behavior of the User Lookup API.
76+
77+
include::partial$configuration/user_id.adoc[leveloffset=+1]
78+
79+
include::partial$configuration/fetch_users.adoc[leveloffset=+1]
80+
81+
== Usage Examples
82+
83+
=== Basic Usage
84+
85+
Once the editor is initialized, you can access the current user ID and fetch user information:
2186

2287
[source,js]
2388
----
2489
editor.on('init', () => {
90+
// Get the current user ID
2591
console.log('Current user:', editor.userLookup.userId);
92+
93+
// Fetch user information
94+
const users = editor.userLookup.fetchUsers(['user-1', 'user-2']);
95+
96+
users['user-1'].then((user) => {
97+
console.log('User 1 name:', user.name);
98+
});
99+
100+
// Handle multiple users
101+
Promise.all(Object.values(users)).then((allUsers) => {
102+
allUsers.forEach((user) => {
103+
console.log(`Fetched: ${user.name} (${user.id})`);
104+
});
105+
});
26106
});
27107
----
28108

29-
[[step-2-provide-a-user-fetcher]]
30-
=== 2. Provide a function to fetch user details
109+
NOTE: All lookups are cached. If a user has already been fetched, the same promise will be returned without calling `fetch_users` again.
31110

32-
To simulate a backend lookup, define a local object that maps user IDs to their corresponding data.
111+
[[complete-example]]
112+
=== Complete Example with User Database
33113

34-
include::partial$configuration/fetch_users.adoc[leveloffset=+2]
114+
This example shows how to set up a complete user lookup system with a simulated backend:
35115

36116
.Example
37117
[source,js]
@@ -68,51 +148,18 @@ tinymce.init({
68148
});
69149
----
70150

71-
This example demonstrates how to simulate user lookup in-browser. In a production environment, this function could be swapped out for a network request.
151+
This example demonstrates how to simulate user lookup in-browser. In a production environment, the `fetch_users` function would typically make network requests to your backend API.
72152

73-
The returned array should include objects with:
153+
[[fallback-behavior]]
154+
=== Fallback Behavior
74155

75-
* `id` (string) - Required
76-
* `name` (string) - Optional (defaults to `id`)
77-
* `avatar` (string, URL or data URI) - Optional (auto-generated SVG fallback if missing)
78-
* `custom` (object) - Optional metadata
156+
If no `fetch_users` function is configured, {productname} will return fallback users with auto-generated data:
79157

80-
[[step-3-fetch-user-information]]
81-
=== 3. Fetch user information
158+
* `name` defaults to the user ID
159+
* `avatar` is an auto-generated SVG using the first letter of the name
82160

83-
Once the editor is initialized, use the API to look up multiple users:
161+
This is useful for simpler setups or prototyping:
84162

85-
.Example
86-
[source,js]
87-
----
88-
editor.on('init', () => {
89-
const users = editor.userLookup.fetchUsers(['user-1', 'user-2']);
90-
91-
users['user-1'].then((user) => {
92-
console.log('User 1 name:', user.name);
93-
});
94-
95-
Promise.all(Object.values(users)).then((allUsers) => {
96-
allUsers.forEach((user) => {
97-
console.log(`Fetched: ${user.name} (${user.id})`);
98-
});
99-
});
100-
});
101-
----
102-
103-
NOTE: All lookups are cached. If a user has already been fetched, the same promise will be returned without calling `fetch_users` again.
104-
105-
[[step-4-handle-missing-or-default-users]]
106-
=== 4. Handle default users if `fetch_users` is not provided
107-
108-
If no `fetch_users` function is configured, {productname} will return fallback users:
109-
110-
* `name` will default to the ID
111-
* `avatar` will be a generated SVG using the first letter of the name
112-
113-
This is useful for simpler setups or prototyping.
114-
115-
.Example
116163
[source,js]
117164
----
118165
tinymce.init({
@@ -128,64 +175,46 @@ editor.on('init', () => {
128175
});
129176
----
130177

131-
[[step-5-integrate-user-lookup-in-a-ui]]
132-
=== 5. Integrate User Lookup in a UI Button (Optional)
133-
134-
. Example: Using the API to show the current user's name via a toolbar button.
135-
[source,js]
136-
----
137-
setup: (editor) => {
138-
editor.ui.registry.addButton('show-user', {
139-
text: 'Show User',
140-
onAction: () => {
141-
const currentUser = editor.userLookup.userId;
142-
const users = editor.userLookup.fetchUsers([currentUser]);
143-
144-
users[currentUser].then((user) => {
145-
editor.notificationManager.open({
146-
text: `Logged in as: ${user.name}`,
147-
type: 'info'
148-
});
149-
});
150-
}
151-
});
152-
}
153-
----
178+
== Advanced Usage
154179

155-
Then add this to your toolbar:
180+
[[ui-integration]]
181+
=== UI Integration Example
156182

183+
This example shows how to create a toolbar button that displays the current user's information:
157184
[source,js]
158185
----
159-
toolbar: 'show-user'
186+
tinymce.init({
187+
selector: '#editor',
188+
user_id: 'current-user',
189+
setup: (editor) => {
190+
editor.ui.registry.addButton('show-user', {
191+
text: 'Show User',
192+
onAction: () => {
193+
const currentUser = editor.userLookup.userId;
194+
const users = editor.userLookup.fetchUsers([currentUser]);
195+
196+
users[currentUser].then((user) => {
197+
editor.notificationManager.open({
198+
text: `Logged in as: ${user.name}`,
199+
type: 'info'
200+
});
201+
});
202+
}
203+
});
204+
},
205+
toolbar: 'show-user'
206+
});
160207
----
161208

162-
[[summary]]
163-
== Summary
209+
[[apis]]
210+
== APIs
164211

165-
The `userLookup` API provides two main functions:
212+
The User Lookup API provides the following methods:
166213

167-
[cols="2,4",options="header"]
214+
[cols="3,4,2",options="header"]
168215
|===
169-
|Function|Description
216+
|Method|Description|Return Type
170217

171-
|`editor.userLookup.userId`|Returns the current user’s ID, set via the `user_id` option.
172-
|`editor.userLookup.fetchUsers(userIds)`|Fetches and caches user information from a backend.
218+
|`editor.userLookup.userId`|Gets the current user's ID, set via the `user_id` configuration option.|`string`
219+
|`editor.userLookup.fetchUsers(userIds)`|Fetches and caches user information for the specified user IDs. Returns an object where each key is a user ID and each value is a Promise that resolves to the user object.|`Object<string, Promise<UserObject>>`
173220
|===
174-
175-
== Example User Object
176-
177-
Each returned user object from `fetchUsers()` has the following structure:
178-
179-
.Example
180-
[source,js]
181-
----
182-
{
183-
id: 'user-1',
184-
name: 'Jane Doe',
185-
avatar: 'https://example.com/jane.png',
186-
custom: {
187-
role: 'admin',
188-
department: 'engineering'
189-
}
190-
}
191-
----

‎modules/ROOT/partials/configuration/fetch_users.adoc‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[[fetch_users]]
22
== `fetch_users`
33

4-
A **required callback function** that fetches user data. This function is called with an array of user IDs and should return a `Promise` that resolves to an array of user objects. The callback is used by the xref:userlookup.adoc[`UserLookup`] API. If the returned array does not include all requested user IDs, promises for the missing users will be rejected with a "User {id} not found" error.
4+
A **required callback function** that fetches user data. This function is called with an array of user IDs and should return a `Promise` that resolves to an array of user objects. The callback is used by the xref:userlookup.adoc[`UserLookup`] API. If the returned array does not include all requested user IDs, promises for the missing users will be rejected with a "User \{id} not found" error.
55

66
*Type:* `Function`
77

@@ -11,8 +11,7 @@ A **required callback function** that fetches user data. This function is called
1111
*Returns:*
1212
- `Promise<Array<Object>>`: A promise that resolves to an array of user objects.
1313

14-
=== Example: using `fetch_users` option
15-
14+
.Example: using `fetch_users` option
1615
[source,javascript]
1716
----
1817
tinymce.init({
@@ -27,8 +26,7 @@ tinymce.init({
2726
});
2827
----
2928

30-
=== Example: returning user array with validation
31-
29+
.Example: returning user array with validation
3230
[source,javascript]
3331
----
3432
tinymce.init({

‎modules/ROOT/partials/configuration/user_id.adoc‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,7 @@ This option sets the unique identifier for the current user in the editor. It is
77

88
*Default value:* `'Anonymous'`
99

10-
=== Example: using `user_id` option
11-
10+
.Example: using `user_id` option
1211
[source,javascript]
1312
----
1413
tinymce.init({

0 commit comments

Comments
 (0)