Mercury-IM/Smack
Mercury-IM/Smack
1
0
Fork 0
mirror of https://codeberg.org/Mercury-IM/Smack synced 2024-11-22 22:32:06 +01:00
Code Issues Releases Wiki Activity
Smack/documentation/extensions/xhtml.md

204 lines
6.8 KiB
Markdown
Raw Normal View History

Convert html documentation to markdown
2014-08-16 00:09:55 +02:00
XHTML Messages
==============
Provides the ability to send and receive formatted messages using XHTML.
Follow these links to learn how to compose, send, receive and discover support
for XHTML messages:
* Compose an XHTML Message
* Send an XHTML Message
* Receive an XHTML Message
* Discover support for XHTML Messages
**XEP related:** [XEP-71](http://www.xmpp.org/extensions/xep-0071.html)
Compose an XHTML Message
------------------------
**Description**
The first step in order to send an XHTML message is to compose it. Smack
provides a special class that helps to build valid XHTML messages hiding any
low level complexity. For special situations, advanced users may decide not to
use the helper class and generate the XHTML by themselves. Even for these
situations Smack provides a well defined entry point in order to add the
generated XHTML content to a given message.
Note: not all clients are able to view XHTML formatted messages. Therefore,
it's recommended that you include a normal body in that message that is either
an unformatted version of the text or a note that XHTML support is required to
view the message contents.
**Usage**
Create an instance of _**XHTMLText**_ specifying the style and language of the
body. You can add several XHTML bodies to the message but each body should be
for a different language. Once you have an XHTMLText you can start to append
tags and text to it. In order to append tags there are several messages that
you can use. For each XHTML defined tag there is a message that you can send.
In order to add text you can send the message **#append(String
textToAppend)**.
After you have configured the XHTML text, the last step you have to do is to
add the XHTML text to the message you want to send. If you decided to create
the XHTML text by yourself, you will have to follow this last step too. In
order to add the XHTML text to the message send the message **#addBody(Message
message, String body)** to the _**XHTMLManager**_ class where _message_ is the
message that will receive the XHTML body and _body_ is the string to add as an
XHTML body to the message.**
**Example**
In this example we can see how to compose the following XHTML message:
```
<body>
<p style='font-size:large'>Hey John, this is my new
<span style='color:green'>green</span>
<em>!!!!</em>
</p>
</body>
```
```
// Create a message to send
Message msg = chat.createMessage();
msg.setSubject("Any subject you want");
msg.setBody("Hey John, this is my new green!!!!");
// Create an XHTMLText to send with the message
XHTMLText xhtmlText = new XHTMLText(null, null);
xhtmlText.appendOpenParagraphTag("font-size:large");
xhtmlText.append("Hey John, this is my new ");
xhtmlText.appendOpenSpanTag("color:green");
xhtmlText.append("green");
xhtmlText.appendCloseSpanTag();
xhtmlText.appendOpenEmTag();
xhtmlText.append("!!!!");
xhtmlText.appendCloseEmTag();
xhtmlText.appendCloseParagraphTag();
Don't append closing body in XHTMLText.toString() Also add XHTMLExtension.from(Message) and change XHTMLManager.addBody() signature so that it expects a XHTMLText (Modifications to the original patch by Florian Schmaus).
2015-01-05 05:11:06 +01:00
xhtmlText.appendCloseBodyTag();
Convert html documentation to markdown
2014-08-16 00:09:55 +02:00
// Add the XHTML text to the message
Don't append closing body in XHTMLText.toString() Also add XHTMLExtension.from(Message) and change XHTMLManager.addBody() signature so that it expects a XHTMLText (Modifications to the original patch by Florian Schmaus).
2015-01-05 05:11:06 +01:00
XHTMLManager.addBody(msg, xhtmlText);
Convert html documentation to markdown
2014-08-16 00:09:55 +02:00
```
Send an XHTML Message
---------------------
**Description**
After you have composed an XHTML message you will want to send it. Once you
have added the XHTML content to the message you want to send you are almost
done. The last step is to send the message as you do with any other message.
**Usage**
An XHTML message is like any regular message, therefore to send the message
you can follow the usual steps you do in order to send a message. For example,
Deprecate Chat API, introduce new Chat API Also add (From|To)TypeFilter and update/fix the documentation in a few places.
2017-01-11 19:35:55 +01:00
to send a message as part of a chat just use the message **#sendMessage(Message)** of
_**Chat**_ or you can use the message **#sendStanza(Stanza)** of
Convert html documentation to markdown
2014-08-16 00:09:55 +02:00
_**XMPPConnection**_.
**Example**
In this example we can see how to send a message with XHTML content as part of
a chat.
```
// Create a message to send
Message msg = chat.createMessage();
// Obtain the XHTML text to send from somewhere
Don't append closing body in XHTMLText.toString() Also add XHTMLExtension.from(Message) and change XHTMLManager.addBody() signature so that it expects a XHTMLText (Modifications to the original patch by Florian Schmaus).
2015-01-05 05:11:06 +01:00
XHTMLText xhtmlBody = getXHTMLTextToSend();
Convert html documentation to markdown
2014-08-16 00:09:55 +02:00
// Add the XHTML text to the message
XHTMLManager.addBody(msg, xhtmlBody);
// Send the message that contains the XHTML
chat.sendMessage(msg);
```
Receive an XHTML Message
------------------------
**Description**
It is also possible to obtain the XHTML content from a received message.
Remember that the specification defines that a message may contain several
XHTML bodies where each body should be for a different language.
**Usage**
To get the XHTML bodies of a given message just send the message
**#getBodies(Message)** to the class _**XHTMLManager**_. The answer of this
Don't append closing body in XHTMLText.toString() Also add XHTMLExtension.from(Message) and change XHTMLManager.addBody() signature so that it expects a XHTMLText (Modifications to the original patch by Florian Schmaus).
2015-01-05 05:11:06 +01:00
message will be an _**List**_ with the different XHTML bodies of the
Convert html documentation to markdown
2014-08-16 00:09:55 +02:00
message or null if none.
**Example**
In this example we can see how to create a PacketListener that obtains the
XHTML bodies of any received message.
```
// Create a listener for the chat and display any XHTML content
Deprecate Chat API, introduce new Chat API Also add (From|To)TypeFilter and update/fix the documentation in a few places.
2017-01-11 19:35:55 +01:00
IncomingChatMessageListener listener = new IncomingChatMessageListener() {
public void newIncomingMessage(EntityBareJid from, Message message, Chat chat) {
Don't append closing body in XHTMLText.toString() Also add XHTMLExtension.from(Message) and change XHTMLManager.addBody() signature so that it expects a XHTMLText (Modifications to the original patch by Florian Schmaus).
2015-01-05 05:11:06 +01:00
// Obtain the XHTML bodies of the message
List<CharSequence> bodies = XHTMLManager.getBodies(message);
Deprecate Chat API, introduce new Chat API Also add (From|To)TypeFilter and update/fix the documentation in a few places.
2017-01-11 19:35:55 +01:00
if (bodies == null) {
return;
// Display the bodies on the console
for (CharSequence body : bodies) {
System.out.println(body);
Don't append closing body in XHTMLText.toString() Also add XHTMLExtension.from(Message) and change XHTMLManager.addBody() signature so that it expects a XHTMLText (Modifications to the original patch by Florian Schmaus).
2015-01-05 05:11:06 +01:00
}
Deprecate Chat API, introduce new Chat API Also add (From|To)TypeFilter and update/fix the documentation in a few places.
2017-01-11 19:35:55 +01:00
}
Convert html documentation to markdown
2014-08-16 00:09:55 +02:00
};
Deprecate Chat API, introduce new Chat API Also add (From|To)TypeFilter and update/fix the documentation in a few places.
2017-01-11 19:35:55 +01:00
chatManager.addListener(listener);
Convert html documentation to markdown
2014-08-16 00:09:55 +02:00
```
Discover support for XHTML Messages
-----------------------------------
**Description**
Before you start to send XHTML messages to a user you should discover if the
user supports XHTML messages. There are two ways to achieve the discovery,
explicitly and implicitly. Explicit is when you first try to discover if the
user supports XHTML before sending any XHTML message. Implicit is when you
send XHTML messages without first discovering if the conversation partner's
client supports XHTML and depenging on the answer (normal message or XHTML
message) you find out if the user supports XHTML messages or not. This section
explains how to explicitly discover for XHTML support.
**Usage**
In order to discover if a remote user supports XHTML messages send
**#isServiceEnabled(XMPPConnection connection, String userID)** to the class
_**XHTMLManager**_ where connection is the connection to use to perform the
service discovery and userID is the user to check (A fully qualified xmpp ID,
e.g. jdoe@example.com). This message will return true if the specified user
handles XHTML messages.
**Example**
In this example we can see how to discover if a remote user supports XHTML
Messages.
```
Message msg = chat.createMessage();
// Include a normal body in the message
msg.setBody(getTextToSend());
// Check if the other user supports XHTML messages
if (XHTMLManager.isServiceEnabled(connection, chat.getParticipant())) {
// Obtain the XHTML text to send from somewhere
String xhtmlBody = getXHTMLTextToSend();
// Include an XHTML body in the message
qHTMLManager.addBody(msg, xhtmlBody);
}
// Send the message
chat.sendMessage(msg);
```
Reference in a new issue Copy permalink