Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
= Action Messenger -- Instant Messaging made simple Action Messenger is a framework for designing and testing application components which both send and receive instant messages. It was heavily based on Action Mailer which does the same thing for email. == Installation Installation is as usual: either install from the gem or drop into the 'vendor' directory of your Rails application. Somewhere (probably in 'config/environment.rb') you will want to add the following: require 'action_messenger' == Configuring the messenger Configuration of messengers works in a similar fashion to configuration of databases in Active Record. The default location of the configuration file is 'config/messenger.yml'. The simplest configuration is to use a single messenger. default: type: xmpp4r jid: firstname.lastname@example.org/resource password: secret Multiple messengers can be defined in this fashion, however most applications should only need one, and by default the messenger named 'default' is the one which is used. The configuration file can contain ERB fragments too, in case more complicated decisions need to be made when configuring the messenger. == Sending messages The following is the simplest example of a class able to send a message: class AlarmClock < ActionMessenger::Base def wake_up(user) recipients user body 'Wake up!' end end As with Action Mailer, sending or creating a message does not involve calling your method directly: AlarmClock.create_wake_up("email@example.com") # => Message object for unit tests AlarmClock.send_wake_up("firstname.lastname@example.org") # sends the message == Receiving messages To receive messages, implement a public instance method called receive that takes an ActionMessenger::Message object as its single parameter. They also need to register to receive messages by calling receives_messages on the class. A simple example: class MessageLogger < ActionMessenger::Base receives_messages def receive(message) MessageLogEntry.create(:sender => message.from :body => message.body) end end This will work as you expect if you are using FastCGI, Mongrel or some other method of running the server that doesn't run Ruby once per invocation (notably, CGI will not work.) If you use a cluster of FastCGI or Mongrel instances, you may need to make the resources unique for each one. If this becomes a problem it can be simplified in a future version. == Dependencies At present, the only dependency is XMPP4R, and this dependency is currently included in this bundle. XMPP4R is licenced under the Ruby licence; a copy of this licence can be found in vendor/xmpp4r/LICENSE. == License Action Messenger is released under the MIT license. A copy of this licence can be found in the file named COPYING. == Support The homepage is currently at: http://trypticon.org/software/actionmessenger/ Contact details can be found at the homepage. Action Messenger is currently extremely experimental software, and there is no guarantee that it will be stable in the near future. However, if people do find bugs I will endeavour to fix them, and I am accepting feature requests that aren't already listed on the homepage.