Skip to content

Commit 4a826c5

Browse files
author
Sorita Heng
committed
Update UID options partials
1 parent ef516e7 commit 4a826c5

File tree

5 files changed

+160
-22
lines changed

5 files changed

+160
-22
lines changed

‎modules/ROOT/pages/apis/tinymce.userlookup.adoc‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
= tinymce.UserLookup
2+
:navtitle: tinymce.UserLookup
3+
:description: This is the user lookup api.
4+
:keywords: user lookup, fetchUsers()
5+
:moxie-type: api
6+
7+
This is the user lookup API.
8+
9+
== Summary
10+
11+
Provides user lookup capabilities for TinyMCE. Used to retrieve and cache user information via API, typically passed as `fetch_users` in the config.
12+
13+
== Properties
14+
15+
[cols="1,1,3", options="header"]
16+
|===
17+
| Name | Type | Summary
18+
19+
| userId
20+
| String
21+
| Current user's ID for the TinyMCE editor instance
22+
23+
|===
24+
25+
== Methods
26+
27+
[cols="1,3", options="header"]
28+
|===
29+
| Name | Summary
30+
31+
| fetchUsers()
32+
| Retrieves and caches user information for specified user IDs, returning an array of promises
33+
34+
|===
35+
36+
=== fetchUsers(userIds: Array): Promise
37+
38+
Retrieves and caches user information for the specified user IDs, returning an array of promises.
39+
40+
.Parameters
41+
[cols="1,3", options="header"]
42+
|===
43+
| Parameter | Description
44+
45+
| userIds (Array)
46+
| An array of user IDs to fetch information for.
47+
48+
|===
49+
50+
== Using the UserLookup API
51+
52+
=== 1. Configuring `fetch_users`
53+
54+
`fetch_users` must be provided when initializing TinyMCE. It receives an array of IDs and must return a Promise resolving to an array of user objects.
55+
56+
.Example:
57+
[source,js]
58+
----
59+
tinymce.init({
60+
selector: 'textarea',
61+
user_id: 'current-user-id',
62+
/**
63+
* @param {string[]} ids
64+
* @returns {Promise<Array<{ id: string, name?: string, avatar?: string }>>}
65+
*/
66+
fetch_users: (ids) => fetch(`/api/users?ids=${ids.join(',')}`)
67+
.then((r) => r.json())
68+
});
69+
----
70+
71+
=== 2. Accessing the Current User ID
72+
73+
[source,js]
74+
----
75+
const editor = tinymce.activeEditor;
76+
console.log('Logged in as', editor.userLookup.userId);
77+
----
78+
79+
=== 3. Retrieving User Information
80+
81+
[source,js]
82+
----
83+
const [ meP, colleagueP ] = editor.userLookup.fetchUsers([
84+
editor.userLookup.userId,
85+
'user-42'
86+
]);
87+
88+
Promise.all([ meP, colleagueP ])
89+
.then(([ me, colleague ]) => {
90+
console.log(`${me.name} is chatting with ${colleague.name}`);
91+
})
92+
.catch(console.error);
93+
----
94+
95+
=== 4. Caching & Concurrency
96+
97+
- First request triggers `fetch_users` to query the external source.
98+
- Subsequent requests for the same user ID reuse the cached Promise.
99+
100+
=== 5. Error Handling
101+
102+
- If `fetch_users` omits an ID, the corresponding Promise rejects with:
103+
`"User <id> not found"`
104+
- Network or validation failures are propagated as rejected Promises.
105+
- If `fetch_users` is not configured, `fetchUsers()` throws synchronously.
106+
107+
=== 6. Custom Properties
108+
109+
Custom user fields (e.g., roles, preferences, `createdAt`) can be included in the resolved object. These will be returned unchanged.
110+
111+
== User Object Structure
112+
113+
[cols="1,1,1,3", options="header"]
114+
|===
115+
| Field | Type | Required | Description
116+
117+
| id
118+
| string
119+
| Yes
120+
| Unique user identifier
121+
122+
| name
123+
| string
124+
| No
125+
| Display name
126+
127+
| avatar
128+
| string
129+
| No
130+
| URL of the avatar image
131+
132+
| description
133+
| string
134+
| No
135+
| Short bio or description
136+
137+
| custom
138+
| object
139+
| No
140+
| Arbitrary metadata (roles, preferences, createdAt, etc.)
141+
142+
|===

modules/ROOT/partials/configuration/suggestededits_fetch_users.adoc renamed to modules/ROOT/partials/configuration/fetch_users.adoc

Lines changed: 1 addition & 3 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 for the Suggested Edits view. 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:#userlookupapi[`UserLookup API`].
4+
A callback function that retrieves user data for the plugin. It receives an array of user IDs and returns a `Promise` resolving to an array of user objects. The callback uses the xref:#userlookupapi[`UserLookup API`].
55

66
*Type:* `Function`
77

@@ -16,8 +16,6 @@ A **required callback function** that fetches user data for the Suggested Edits
1616
----
1717
tinymce.init({
1818
selector: 'textarea', // Change this value according to your HTML
19-
plugins: 'suggestededits',
20-
toolbar: 'suggestededits',
2119
user_id: 'unique-identifier', // Replace this with a unique string to identify the user
2220
fetch_users: (ids) => fetch(`/api/users?ids=${ids.join(',')}`)
2321
.then((r) => r.json())

‎modules/ROOT/partials/configuration/suggestededits-options.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
include::partial$configuration/suggestededits_user_id.adoc[]
2-
include::partial$configuration/suggestededits_fetch_users.adoc[]
1+
include::partial$configuration/user_id.adoc[]
2+
include::partial$configuration/fetch_users.adoc[]
33
include::partial$configuration/suggestededits_model.adoc[]
44
include::partial$configuration/suggestededits_content.adoc[]
55
include::partial$configuration/suggestededits_access.adoc[]

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

Lines changed: 0 additions & 17 deletions
This file was deleted.

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
[[user_id]]
2+
== `user_id`
3+
4+
This option specifies a unique identifier for the current user, enabling the plugin to distinguish between different users in the editor. The option uses the xref:#userlookupapi[`UserLookup API`].
5+
6+
*Type:* `+String+`
7+
8+
.Example
9+
[source,javascript]
10+
----
11+
tinymce.init({
12+
selector: 'textarea', // Change this value according to your HTML
13+
user_id: 'unique-identifier' // replace this with a unique string to identify the user
14+
});
15+
----

0 commit comments

Comments
 (0)