#summary Message logged in Facebook users in Django
#labels django

*This is Work in Progress documentation for a feature in SVN.*

= Introduction =

In an application it is often important to send simple status messages quickly.  `facebook.djangofb.models.Message` is provided as a simple way to queue messages to Facebook users in your Django applications.  It should seem familiar to existing users of [http://www.djangoproject.com/documentation/authentication/#messages Django Messages] from `django.contrib.auth`, as it is meant as a near-replacement for it.


= Installation =

To make use of the Message Model you need to install it in your Django settings file.  Under `INSTALLED_APPS` you'll need to add `facebook.djangofb`.  Then run `python manage.py syncdb` to install the model.

The other settings change you will want to make is to add the Message context processor.  This will automatically add the currently logged-in Facebooks users messages into your template context.  Under `TEMPLATE_CONTEXT_PROCESSORS` add `facebook.djangofb.context_processors.message`.


= Usage =

To create a message, import the Message model and you can simply create one, as you would any Django model:

{{{
Message(uid=request.facebook.uid, # current user
    status=2, 
    message="Your item was saved!",
).save()
}}}

== Facebook Status Codes ==

Facebook, and hence the Message model, supports three different forms of status messages.  Here's the status codes:

{{{
Explanation = 0
Error = 1
Success = 2
}}}

You are not restricted to just these codes, but the Message model gives you a hand with these Facebook codes.  You can use `message.get_status_display()` to get the friendly name of the status code for the current status of a message.  Additionally the model provides a `as_fbml()` method to get the FBML representation of the message.

== Canvas Templates ==

In your canvas templates, assuming you have the context processor installed all you need to add is (assuming an FBML template, for an iframe template you'll need to format it a bit more than just as_fbml):

{{{
{% for message in messages %}
{{ message.as_fbml }}
{% endfor %}
}}}

Then any messages you send to a user will appear there the next time they visit a canvas page.