1
0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-23 08:08:53 -05:00
xeps/inbox/buttons.xml
2020-04-21 00:07:45 +02:00

169 lines
4.7 KiB
XML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?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>