The Dev Blog: Category XMPP4R/Jabber

Ruby and XMPP/Jabber Part 3: Adding html to the messages

guy.naor@famundo.com (Guy Naor) — Wed, 18 Oct 2006 11:02:00 -0400

If you used a Jabber client like GAIM or Trillian you know that it supports rich text messages. Those can be really nice to send some nicely formatted messages.

But I couldn't find much documentation on how to do it, outside the XEP/JEPs. To save you the pain of reading RFCs and XEPs/JEPs, I'll show you here how to send those nice rich messages.

The rich text is sent as an additional element of the message. The body still remains the same plain text body, and will be displayed by clients that do not support rich-text.

The type of markup that can be used is pretty limited - a small subset of regulat xhtml markup. The full details of the markup and how to use it are given in XEP-0071. But I'll go here over the important details.

To send the message we add a new element of type html with the namespace http://jabber.org/protocol/xhtml-im, and in it we put the html. The html should be the body part only. The following tags are supported: a, br, img, ul, li, ol, p, span. (Technically there are more tags that could match the namespace, but are not recommended.) The markup is styled with CSS using the style attribute of the tag. Supported styles are: background-color, color, font-family, font-size, font-style, font-weight, margin-left, margin-right, text-align, text-decoration.

Lets give it a try in irb (using the same login details from the previous post:

require 'xmpp4r/client'
include Jabber

# Login
jid = JID::new('test@yeush.com/Testing')
password = 'test'
cl = Client::new(jid)
cl.connect
cl.auth(password)

# Create a message
to = "test_with_me@yeush.com"
subject = "XMPP4R Rich-Text Test"
body = "Wow, I can do HTML now. But if you see this, your client doesn't support it"
m = Message::new(to, body).set_type(:normal).set_id('1').set_subject(subject)

# Create the html part
h = REXML::Element::new("html")
h.add_namespace('http://jabber.org/protocol/xhtml-im')

# The body part with the correct namespace
b = REXML::Element::new("body")
b.add_namespace('http://www.w3.org/1999/xhtml')

# The html itself
t = REXML::Text.new( "This is so <strong><span style='background: #003EFF; '><span style='font-size: large; '>COOL!!!</span></span></strong>. I can really do <strong>HTML</strong> now.", false, nil, true, nil, %r/.^/ )

# Add the html text to the body, and the body to the html element
b.add(t)
h.add(b)

# Add the html element to the message
m.add_element(h)

# Send it
cl.send m

It's pretty simple once you understand how to add the element to the message. Nothing fancy going on. And you can use other ways to build the markup. I'm using REXML as it's what XMPP4R considers the native elements. But assigning pre-formatted elements will also work.

Well, go send some nice messages, and come back for the next post about queries and callbacks. This will get us a bit deeper into the protocol, and get us ready for more interesting things.

UPDATE: A short explanation of the last parameter on the REXML::Text.new parameter is in order. As we are passing a pre-formatted text that include characters that are XHTML markup characters, we need to tell REXML to ignore those. We do that by passing a regular expression that will never match anything as the illegal parameter.

Ruby and XMPP/Jabber Part 2: Logging in and sending simple messages

guy.naor@famundo.com (Guy Naor) — Sat, 14 Oct 2006 11:34:00 -0400

Time to get down to some sample code!

In this part I will show how to log in to a Jabber server and send a simple message. This is the basis of everything else, and will give you something nice to start with. After all, sending messages is the most common use for Jabber.

Installation

Get the code from here, unpack it and then run ./setup.rb from the directory you open the archive to. YOu can also get the gem and install it locally. As it's pure ruby, there aren't any complications with it.

What we will need?

To start, get irb going as we'll do it interactively so we can get immediate results. You will also need a Jabber account you can login to, and another account to send messages to. You could send to the same account, actually, but it's nicer with a second one.

For this session, I will be using my account at DreamHost - they provide Jabber as one of the features of the account, which is pretty cool. YOu can also setup one of your own, but it's beyons the scope of this post.

Server: yeush.com

User: test

Password: test (don't worry, I'm not this crazy, this is a fake password...)

And we'll interact with another accounts (that has the test account as a buddy that can connect to): test_with_me@yeush.com.

Now in irb, make sure we have xmpp4r included:

irb
require 'xmpp4r/client'
include Jabber # Makes using it a bit easier as we don't need to prepend Jabber:: to everything

Logging in

To start any communication with a Jabber server, we need to first log in to the server:

# Jabber::debug = true # Uncomment this if you want to see what's being sent and received!
jid = JID::new('test@yeush.com/Testing')
password = 'test'
cl = Client::new(jid)
cl.connect
cl.auth(password)

That's all it takes to login, really! Now for some explanations. The jabber system is made of a collection of servers that can be either stand alone, or connected to each other (called open federation). Each entity connecting to the network must have a unique ID, called a JID (Jabber ID). The id is made up of the user name, server the user is on and an optional resource. The resource is the part after the /, in this case /Testing. The resources can be arbitrarily named, and allow the same person/entity to be connected and talking from many places at once, while still knowing where to send replies back to.

Now that we are connected, let's do something with it...

Sending a simple message

Most of what we want to do in a Jabber session is send messages. So let's get one going:

to = "test_with_me@yeush.com"
subject = "XMPP4R test"
body = "Hi, this is my first try from XMPP4R!!!"
m = Message::new(to, body).set_type(:normal).set_id('1').set_subject(subject)
cl.send m

What did we have here? We assigned a few parameters, created a new message object, and had the client send it. subject is mostly ignored by clients. Very few will show it. body is the plain text message you want to send. *to* is well, the to.

A message is simple an REXML document, and the calls to setid('1') and settype(:normal), set those values in the message element. :normal is the message type. Look in the documentation for all possible types. We will be using :normal and :chat. id is used to identify the message, and can be anything. Usually it's an advancing counter, and it can also include letters and underscore.

After we have the message constructed, we let the client send it. Like I explained in the first part, the whole XMPP protocol is based on XML documents being sent and received. You can type m.to_s in irb to get the document representation. Here is how the message looks in XML:

<message type='normal' id='1' to='test_with_me@yeush.com'>
  <body>Hi, this is my first try from XMPP4R!!!</body>
  <subject>XMPP4R test</subject>
</message>

Go and play with that a bit, and on the next installment we'll see how to add rich-text to the messages (hint: adding it to the body won't work - you need a special html element for that).

See you next time...

Ruby and XMPP/Jabber - a Multi Posts Series, Part 1

guy.naor@famundo.com (Guy Naor) — Tue, 10 Oct 2006 16:24:00 -0400

Instant Messages is one of the most common apps running on people's desktops. And they have the nice feature of popping up when a new message comes in. Exploiting this programmatically can open up a huge array of options.

In Famundo we added the ability to send alarms notifications to IM addresses. The initial implementation was easy and pretty trivial, given all the samples I found. When I wanted to go further, it became complicated, and there were no more examples to look at. Things like sending rich text messages, or talking to other IM services through XMPP gateways. I promise to show how to just that (and other things) in this series of posts.

I started with Jabber4R, but then realized it's not supported anymore, and all development is now done in XMPP4R. So I switched to it. It is a much more advanced library, and is pretty big. One of the prolems with it is the complexity. Part of it is the inherent complexity of the XMPP protocol. (Though I read somewhere it's simple, don't believe everything you read...)

My goal in this series of posts is to guide you into using XMPP4R to send messages, subscribe to services, send queries, etc... I might get also into receiving messages, though I see it as less important for rails applications. We'll see how much time I have on my hands. If there's something specific you would like me to discuss - let me know.

So lets get starting!

XMPP is a messaging protocol based on XML messages passed between clients and servers. Better known as THE open source for instant messaging protocol/server, is also the protocol used by GoogleTalk. there are also public servers you can subscribe to and use freely. With the right gateways it will let you send messages to all the other major IM networks (AIM, ICQ, MSN and YM). You can read all about it here. The protocol is described in a large collection of RFCs/JEPs and as those usually are, it's a bit of work to decipher them. But I do recommend reading atleast some of them. Depending on what you are trying to achieve.

Another good option are the Jabber/XMPP related books. But be warned they are not that complete, and are not Ruby based. The two I have are Java based:

Programming Jabber

Instant Messaging in Java

The following installments will be:

Part 2: Logging in and sending simple messages to a Jabber/XMPP server

Part 3: Adding html to the messages

Part 4: Queries + Callbacks

Part 5: Presence, or here I am!

Part 6: Sending messages to proprietary networks (AIM, ICQ, MSN, YM)

Tune in for more....