Skip to content

Commit 265d78a

Browse files
edhelasedhelas
committed
XEP-0317: Hats, Update and complete the protocol
As a client developper the current Hats XEP is far from be usable and feature complete. The goal of those changes is to: - Allow clients to develop a nice UI to manage and assign hats, for example like Discord is doing (see https://support.discord.com/hc/en-us/articles/214836687-Discord-Roles-and-Permissions) - Reconciliate existing implementations and their specificities, see https://docs.ejabberd.im/tutorials/muc-hats/ - Those changes were meant to be backward compatible with the current 0.2.0 version This PR make the following changes: - Specify a urn:xmpp:hats:commands:dcreate command to add a hat to the available list - Specify a urn:xmpp:hats:commands:ddestroy command to destroy a hat from the list - Clarify how the service should broadcast the hat changes when it is edited, assigned, removed or destroyed - Specify a way for an entity to get the complete list of hats using the chatroom presence - Add a hue optional parameter allowing entities to assign a color to the hat that can be displayed properly in any conditions on the client (as explained in XEP-0392: Consistent Color Generation) - Fix some typos
1 parent a84e713 commit 265d78a

File tree

1 file changed

+182
-12
lines changed

1 file changed

+182
-12
lines changed

‎xep-0317.xml

Lines changed: 182 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,34 @@
5555
</section1>
5656

5757
<section1 topic='Discovery' anchor='disco'>
58-
<p>A MUC service that supports hats MUST advertise a &xep0030; feature of "urn:xmpp:hats:0".</p>
58+
<p>A MUC service that supports hats MUST advertise a &xep0030; feature of "urn:xmpp:hats:0" and the actions available to the requesting JID.</p>
59+
60+
<example caption='User’s client discovers the hat features of a MUC service'><![CDATA[
61+
<iq type='get'
62+
id='p87Ne'
63+
from='[email protected]/garden'
64+
to='[email protected]'>
65+
<query xmlns='http://jabber.org/protocol/disco#info'/>
66+
</iq>]]></example>
67+
<example caption='Room advertises hats support'><![CDATA[
68+
<iq type='result'
69+
id='p87Ne'
70+
to='[email protected]/garden'
71+
from='[email protected]'>
72+
<query xmlns='http://jabber.org/protocol/disco#info'>
73+
<identity
74+
category='conference'
75+
type='text'
76+
name='Shakespearean Chat Service'/>
77+
<feature var='urn:xmpp:hats:0'/>
78+
<feature var='urn:xmpp:hats:commands:dcreate'/>
79+
<feature var='urn:xmpp:hats:commands:ddestroy'/>
80+
<feature var='urn:xmpp:hats:commands:don'/>
81+
<feature var='urn:xmpp:hats:commands:doff'/>
82+
...
83+
</query>
84+
</iq>]]></example>
85+
5986
</section1>
6087

6188
<section1 topic='Protocol' anchor='protocol'>
@@ -74,7 +101,7 @@
74101
</hats>
75102
</presence>
76103
]]></example>
77-
<p>Every hat is uniquely identified by its URI. Hats also carry a human-readable title for display purposes. Within XMPP, a hat is contained within a &lt;hat/> element in the 'urn:xmpp:hats:0' namespace. This element MUST possess a 'uri' attribute (containing the hat's URI), a 'title' attribute containing the name of the hat for display purposes, and MAY contain an 'xml:lang' attribute that identifies the language used in the 'title' attribute. The &lt;hat/> element MAY contain additional custom payloads defined by other XEPs, or payloads specific to an implementation or deployment.</p>
104+
<p>Every hat is uniquely identified by its URI. Hats also carry a human-readable title for display purposes. Within XMPP, a hat is contained within a &lt;hat/> element in the 'urn:xmpp:hats:0' namespace. This element MUST possess a 'uri' attribute (containing the hat's URI), a 'title' attribute containing the name of the hat for display purposes, MAY contain an 'xml:lang' attribute that identifies the language used in the 'title' attribute and MAY contain a Hue Angle color that define the hat color to apply. The &lt;hat/> element MAY contain additional custom payloads defined by other XEPs, or payloads specific to an implementation or deployment.</p>
78105
<p>Entities may have multiple hats. The &lt;hats/> element is defined as a container of zero or more &lt;hat/> elements.</p>
79106

80107
<p>As noted, a participant can wear many hats. The following example shows a participant who is a MUC room owner and both a "host" and a "presenter" in an online meeting system. This system also demonstrates how hats can be annotated with custom information (here, the example &lt;badge/> element).</p>
@@ -87,20 +114,162 @@
87114
<item affiliation='owner' role='moderator'/>
88115
</x>
89116
<hats xmlns='urn:xmpp:hats:0'>
90-
<hat title='Host' uri='http://schemas.example.com/hats#host' xml:lang='en-us'>
91-
<badge xmlns="urn:example:badges" fgcolor="#000000" bgcolor="#58C5BA"/>
117+
<hat title='Host' uri='http://schemas.example.com/hats#host' hue='327.255249' xml:lang='en-us'>
118+
<badge xmlns="urn:example:badges" level="3"/>
92119
</hat>
93-
<hat title='Presenter' uri='http://schemas.example.com/hats#presenter' xml:lang='en-us'>
94-
<badge xmlns="urn:example:badges" fgcolor="#000000" bgcolor="#EC0524"/>
120+
<hat title='Presenter' uri='http://schemas.example.com/hats#presenter' hue='171.430664' xml:lang='en-us'>
121+
<badge xmlns="urn:example:badges" level="5"/>
95122
</hat>
96123
</hats>
97124
</presence>
98125
]]></example>
99126
</section2>
100-
<section2 topic='Adding a Hat' anchor='add'>
101-
<p>Hats are added and removed using &xep0050;.</p>
102-
<p>The following flow shows how to add a hat.</p>
103-
<example caption='Admin Requests to Add a Hat'><![CDATA[
127+
<section2 topic='Discovering existing Hats'>
128+
<p>An entity might be interested to get all the existing hats available in a chatroom.</p>
129+
<p>A chatroom MAY then publish the complete list of existing hats in its own presence.</p>
130+
<example caption='The chatroom publish the list of available hats'><![CDATA[
131+
<presence
132+
from='[email protected]'
133+
id='gt54a256'
134+
to='[email protected]/foo'>
135+
...
136+
<hats xmlns='urn:xmpp:hats:0'>
137+
<hat title='Host' uri='http://schemas.example.com/hats#host' hue='327.255249' xml:lang='en-us'/>
138+
<hat title='Presenter' uri='http://schemas.example.com/hats#presenter' hue='171.430664' xml:lang='en-us'/>
139+
...
140+
</hats>
141+
</presence>
142+
]]></example>
143+
</section2>
144+
<section2 topic='Create and update a Hat' anchor='create'>
145+
<p>Hats are reated and destroyed using &xep0050;.</p>
146+
<p>The following flow shows how to create a hat.</p>
147+
<p>Updating a hat follows the same flow but set an existing "hat_uri". If a hat is updated the service SHOULD rebroadcast the related JID presences with the refreshed hat list.</p>
148+
<example caption='Admin Requests to Create a Hat'><![CDATA[
149+
<iq from='[email protected]/office'
150+
id='gd53a2b6'
151+
to='[email protected]'
152+
type='set'
153+
xml:lang='en'>
154+
<command xmlns='http://jabber.org/protocol/commands'
155+
action='execute'
156+
node='urn:xmpp:hats:commands:dcreate'/>
157+
</iq>
158+
]]></example>
159+
160+
<example caption='Service Returns Form to Admin'><![CDATA[
161+
<iq from='[email protected]'
162+
id='gd53a2b6'
163+
to='[email protected]/office'
164+
type='result'
165+
xml:lang='en'>
166+
<command xmlns='http://jabber.org/protocol/commands'
167+
node='urn:xmpp:hats:commands:dcreate'
168+
sessionid='A971D19A-2226-4DAD-B261-9D0886B9A026'
169+
status='executing'>
170+
<x xmlns='jabber:x:data' type='form'>
171+
<title>Creating a Hat</title>
172+
<instructions>Fill out this form to create a hat.</instructions>
173+
<field type='hidden' var='FORM_TYPE'>
174+
<value>urn:xmpp:hats:commands</value>
175+
</field>
176+
<field var='hat_title'
177+
type='text-single'
178+
label='Hat title'>
179+
<required/>
180+
</field>
181+
<field var='hat_uri'
182+
type='text-single'
183+
label='Hat URI'>
184+
<required/>
185+
</field>
186+
<field var='hat_hue'
187+
type='text-single'
188+
label='Hat Hue'/>
189+
</x>
190+
</command>
191+
</iq>
192+
]]></example>
193+
<example caption='Admin Submits Form'><![CDATA[
194+
<iq from='[email protected]/office'
195+
id='9fets723'
196+
to='[email protected]'
197+
type='set'
198+
xml:lang='en'>
199+
<command xmlns='http://jabber.org/protocol/commands'
200+
node='urn:xmpp:hats:commands:dcreate'
201+
sessionid='A971D19A-2226-4DAD-B261-9D0886B9A026'>
202+
<x xmlns='jabber:x:data' type='submit'>
203+
<field type='hidden' var='FORM_TYPE'>
204+
<value>urn:xmpp:hats:commands</value>
205+
</field>
206+
<field var='hat_title'>
207+
<value>Assistant</value>
208+
</field>
209+
<field var='hat_uri'>
210+
<value>http://tech.example.edu/hats#TeacherAssistant</value>
211+
</field>
212+
<field var='hat_hue'>
213+
<value>327.255249</value>
214+
</field>
215+
</x>
216+
</command>
217+
</iq>
218+
]]></example>
219+
<example caption='Service Informs Admin of Completion'><![CDATA[
220+
<iq from='[email protected]'
221+
id='9fets723'
222+
to='[email protected]/office'
223+
type='result'
224+
xml:lang='en'>
225+
<command xmlns='http://jabber.org/protocol/commands'
226+
node='urn:xmpp:hats:commands:don'
227+
sessionid='A971D19A-2226-4DAD-B261-9D0886B9A026'
228+
status='completed'/>
229+
</iq>
230+
]]></example>
231+
</section2>
232+
<section2 topic='Destroy a Hat' anchor='destroy'>
233+
<p>The following flow shows how to remove a hat.</p>
234+
<p>When a hat is destroyed, it is automatically removed from all the JIDs where it was assigned.</p>
235+
<p>The service SHOULD rebroadcast the related JID presences with the refreshed hats list.</p>
236+
<example caption='Admin Requests to Destroy a Hat'><![CDATA[
237+
<iq from='[email protected]/office'
238+
id='rei4n2b0'
239+
to='[email protected]'
240+
type='set'
241+
xml:lang='en'>
242+
<command xmlns='http://jabber.org/protocol/commands'
243+
action='execute'
244+
node='urn:xmpp:hats:commands:ddestroy'>
245+
<x xmlns='jabber:x:data' type='submit'>
246+
<field type='hidden' var='FORM_TYPE'>
247+
<value>urn:xmpp:hats:commands</value>
248+
</field>
249+
<field var='hat'>
250+
<value>http://tech.example.edu/hats#TeacherAssistant</value>
251+
</field>
252+
</x>
253+
</command>
254+
</iq>
255+
]]></example>
256+
<example caption='Service Informs Admin of Completion'><![CDATA[
257+
<iq from='[email protected]'
258+
id='rei4n2b0'
259+
to='[email protected]/office'
260+
type='result'
261+
xml:lang='en'>
262+
<command xmlns='http://jabber.org/protocol/commands'
263+
node='urn:xmpp:hats:commands:ddestroy'
264+
sessionid='A971D19A-2226-4DAD-B261-7D0886B9A123'
265+
status='completed'/>
266+
</iq>
267+
]]></example>
268+
</section2>
269+
<section2 topic='Assiging a Hat' anchor='add'>
270+
<p>Hats are assigned and removed using &xep0050;.</p>
271+
<p>The following flow shows how to assign a hat.</p>
272+
<example caption='Admin Requests to Assign a Hat'><![CDATA[
104273
<iq from='[email protected]/office'
105274
id='fdi3n2b6'
106275
to='[email protected]'
@@ -183,6 +352,7 @@
183352
</section2>
184353
<section2 topic='Removing a Hat' anchor='remove'>
185354
<p>The following flow shows how to remove a hat.</p>
355+
<p>When the hat is removed service SHOULD rebroadcast the related JID presence with the refreshed hat list.</p>
186356
<example caption='Admin Requests to Remove a Hat'><![CDATA[
187357
<iq from='[email protected]/office'
188358
id='fdi3n2b6'
@@ -200,15 +370,15 @@
200370
<value>[email protected]</value>
201371
</field>
202372
<field var='hat'>
203-
<option label='Teacher&apos;s Assistant'><value>http://tech.example.edu/hats#TeacherAssistant</value></option>
373+
<value>http://tech.example.edu/hats#TeacherAssistant</value>
204374
</field>
205375
</x>
206376
</command>
207377
</iq>
208378
]]></example>
209379
<example caption='Service Informs Admin of Completion'><![CDATA[
210380
<iq from='[email protected]'
211-
id='9fens61z'
381+
id='fdi3n2b6'
212382
to='[email protected]/office'
213383
type='result'
214384
xml:lang='en'>

0 commit comments

Comments
 (0)