Posted by Guy Naor
Wed, 18 Oct 2006 15:02:00 GMT
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
jid = JID::new('test@yeush.com/Testing')
password = 'test'
cl = Client::new(jid)
cl.connect
cl.auth(password)
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)
h = REXML::Element::new("html")
h.add_namespace('http://jabber.org/protocol/xhtml-im')
b = REXML::Element::new("body")
b.add_namespace('http://www.w3.org/1999/xhtml')
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/.^/ )
b.add(t)
h.add(b)
m.add_element(h)
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.
Posted in XMPP4R/Jabber, Ruby | no comments | no trackbacks
Posted by Guy Naor
Sat, 14 Oct 2006 15:34:00 GMT
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
Logging in
To start any communication with a Jabber server, we need to first log in to the server:
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...
Posted in XMPP4R/Jabber, Ruby | no comments | no trackbacks
Posted by Guy Naor
Tue, 10 Oct 2006 20:24:00 GMT
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....
Posted in XMPP4R/Jabber, Rails, Ruby | no comments | no trackbacks
