ProtoXEP Buttons: A XEP about clicking things

This commit is contained in:
Kim Alvefur 2018-11-29 18:48:46 +01:00
parent 7d9dfeb452
commit 0fbfda95ac
1 changed files with 168 additions and 0 deletions

168
inbox/buttons.xml Normal file
View File

@ -0,0 +1,168 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep><header>
<title>Simple Buttons</title>
<abstract>This specification provides a way to send simple buttons.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
<author>
<firstname>Kim</firstname>
<surname>Alvefur</surname>
<email>zash@zash.se</email>
<jid>zash@zash.se</jid>
</author>
<revision>
<version>0.0.2</version>
<date>2018-09-30</date>
<initials>ka</initials>
<remark>Polishing preparing for submission</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2018-09-02</date>
<initials>ka</initials>
<remark>Initial version</remark>
</revision>
</header>
<section1 anchor="intro" topic="Introduction">
<p>Having actionable buttons in chats is apparently a fashionable thing
now. This specification defines a simple protocol for buttons and
responses.</p>
</section1><section1 anchor="reqs" topic="Requirements">
<ul>
<li>To provide a representation of a simple button or two in a chat.</li>
</ul>
<section2 anchor="todo" topic="TODO">
<ul>
<li>Is "button" too UI-centric?
<ul>
<li>Could base it on the <tt>&lt;action&gt;</tt> element from ad-hoc?</li>
</ul></li>
<li>Styling? Maybe a few fixed styles like normal, warning, danger?</li>
</ul>
</section2></section1><section1 anchor="glossary" topic="Glossary">
<p>OPTIONAL.</p>
<dl>
<di><dt>Button</dt>
<dd>An actionable object that can be invoked.</dd></di>
<di><dt>Click</dt>
<dd>The act of invoking the actionable object.</dd></di>
</dl>
</section1><section1 anchor="usecases" topic="Use Cases">
<p>A chat bot wants to provide fixed choice answers or commands.</p>
</section1><section1 anchor="elements" topic="Elements">
<section2 anchor="button-element" topic="Button element">
<p>A button is represented by a <tt>&lt;button&gt;</tt> element in the
<tt>urn:xmpp:tmp:buttons</tt>.</p>
<example><![CDATA[<button xmlns="urn:xmpp:tmp:buttons" value="button-clicked">
<label xml:lang="en">Click me</label>
</button>]]></example>
<dl>
<di><dt>value</dt>
<dd>Textual payload to be sent in a message <tt>&lt;body&gt;</tt> when the button is
clicked.</dd></di>
<di><dt>&lt;label&gt;</dt>
<dd>Text label for the button. Can be repeated per language.</dd></di>
</dl>
</section2></section1><section1 anchor="protocol" topic="Protocol">
<section2 anchor="sending-a-button" topic="Sending a button">
<p>A message with buttons is sent by including one or more &lt;button&gt;
elements with distinct value attributes. At least one &lt;label&gt; element
MUST be included containing a textual description for the button.</p>
<example><![CDATA[<message from="memberbot@example.com">
<body xml:lang="en">Approve? (yes/no)</body>
<button xmlns="urn:xmpp:tmp:buttons" value="yes">
<label xml:lang="en">Yes</label>
<label xml:lang="sv">Ja</label>
</button>
<button xmlns="urn:xmpp:tmp:buttons" value="no">
<label xml:lang="en">No</label>
<label xml:lang="sv">Nej</label>
</button>
</message>]]></example>
<p>A single message MUST NOT have multiple buttons with the same <tt>@value</tt>.</p>
</section2><section2 anchor="clicking-a-button" topic="Clicking a button">
<p>When the user clicks a button, their client sends a plain text message
body containing the <tt>@value</tt> as &lt;body&gt; text.</p>
<example><![CDATA[<message to="memberbot@example.com">
<body>yes</body>
</message>]]></example>
</section2></section1><section1 anchor="rules" topic="Business Rules">
<p>OPTIONAL. TODO.</p>
</section1><section1 anchor="impl" topic="Implementation Notes">
<p>OPTIONAL. TODO.</p>
</section1><section1 anchor="access" topic="Accessibility Considerations">
<p>Accessibility for whom?</p>
</section1><section1 anchor="i18n" topic="Internationalization Considerations">
<p>Multiple instances of the <tt>&lt;label/&gt;</tt> element MAY be included for the
purpose of providing alternate versions of the same text in different
languages, i.e. with distinct <tt>xml:lang</tt> attributes.</p>
</section1><section1 anchor="security" topic="Security Considerations">
<p>Do not press the big red button marked "Danger: Do Not Push".</p>
</section1><section1 anchor="iana" topic="IANA Considerations">
<p>None.</p>
</section1><section1 anchor="registrar" topic="XMPP Registrar Considerations">
<p>Register the namespace etc.</p>
</section1><section1 anchor="schema" topic="XML Schema">
<p>REQUIRED for protocol specifications.</p>
<code><![CDATA[button
@value : string
label+ : string]]></code>
</section1>
</xep>