Message Styles

Chat Core uses a message style system based on HTML, JS and CSS that is very similar to the one created for Adium.  If you plan to create a message style for Instantbird or Thunderbird, reading the Adium documentation on the topic may be helpful -- see this tutorial and this reference sheet.

On the other hand, you may prefer to jump right in, using the default message styles as examples: http://mxr.mozilla.org/comm-central/source/im/themes/messages/

The rest of this page includes a variety of information about the specifics for creating a message theme for Instantbird and/or Thunderbird. (Note Thunderbird currently does not provide an UI for users to select the message style, but that doesn't mean they don't work.)

Packaging and file structure

A message style addon needs to be packaged as an xpi file to be installable in Instantbird and Thunderbird.
The typical content of an XPI of a theme will be:

• chrome/ subdirectory (contains the theme files, see below)
• chrome.manifest
• install.rdf

Note: an xpi file is just a zip file with the .xpi extension.

Registration

The files used for the registration of your theme with the theme system are install.rdf, chrome.manifest and Info.plist.

install.rdf

Typical content of install.rdf:

<?xml version="1.0"?>
<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:em="http://www.mozilla.org/2004/em-rdf#">
  <Description about="urn:mozilla:install-manifest">
    <em:id>messagestyle-shortthemename@hostname.domain.tld</em:id>
    <em:name>theme name (human readable)</em:name>
    <em:version>theme version</em:version>
    <em:description>theme description</em:description>
    <em:creator>author name</em:creator>
    <!-- Instantbird -->
    <em:targetApplication>
      <Description>
        <em:id>{33cb9019-c295-46dd-be21-8c4936574bee}</em:id>
        <em:minVersion>1.5</em:minVersion>
        <em:maxVersion>1.6.*</em:maxVersion>
      </Description>
    </em:targetApplication>
  </Description>
</RDF>

chrome.manifest

Typical content of chrome.manifest:

skin    shortthemename    classic/1.0    chrome/

Older message styles store the actual files of the theme in a jar archive, but this is no longer necessary. (A jar file is just a (non-compressed) zip file with the .jar extension.)

All the values in italic in the 2 previous listings should be replaced with appropriate values for your theme.

Important: Please note that for your theme to work, shortthemename in the chrome.manifest and install.rdf files should be identical. The ID of your theme has to start with messagestyle-.

Theme files

The minimal content of chrome/ is:

• Info.plist which contains metadata about the theme
• main.css
• Incoming/Content.html

The other files are optional:

• Style information in CSS files
  • main.css is the stylesheet used for the default variant of the theme, and is also included before the variant-specific stylesheet used for other variants.
  • Variants/<variant name>.css contains the stylesheet for the variant <variant name>.
• Other files used by the stylesheets (e.g. images)
• HTML files: these files are used to build the HTML markup of the conversation.

HTML Template Replacements

These labels will be replaced with message-specific data when used in HTML files bracketed by percentage signs, e.g. %chatName%.

Replacements in header and footer templates

• chatName: Title of the conversation,
• sourceName: The account used for this conversation (the local alias is used if it is set, otherwise the account name is used).
• destinationName: The name of the conversation,
• destinationDisplayName: Title of the conversation,
• incomingIconPath: URL to the buddy icon of the person you are talking to. Will fallback to "incoming_icon.png" if no icon is available,
• outgoingIconPath: Should be the URL to the buddy icon of the account used for this conversation. Currently, this always "outgoing_icon.png",
• timeOpened, timeOpened{format}: The time when the conversation started, takes an optional format argument.

Replacement in both messages and status messages

• message: The text of the message. The actual text will be wrapped in a span node, like this:

<span class="ib-msg-txt">message</span>

• time, time{format}: The time when the message was sent. Takes an optional format parameter (unfortunately, the formats supported are not the same on all the OSes as this internally calls the native strftime function of the OS),
• timestamp: The time when the message was sent, as an integer value (number of seconds since 1970). Useful to compute intervals between messages. Added between 0.2beta2 and 0.2 final,
• datetime: The date and time when the message was sent.
• shortTime: The time when the message was sent,
• messageClasses: CSS classes that apply to the message. This can typically be used in a class attribute of an HTML node. Possible values include:
  • "action": message starting with /me,
  • "message": regular message (not status/system messages),
  • "incoming": incoming message,
  • "outgoing": outgoing message,
  • "autoreply": message sent automatically, for example to reply with an away message,
  • "event": system/status message,
  • "nick": chat message that contains your nick,
  • "error": error message (for example "<user> as cancelled the transfer of <file>"),
  • "delayed": delayed message (Currently this seems to be used only to show the recent message history when joining a Jabber chat room),
  • "notification": notification message (messages requesting the user's attention).

Replacements in messages (incoming or outgoing) only

• userIconPath: URL to the buddy icon of the person you wrote the message. Fallbacks to "Incoming/buddy_icon.png" if the icon is missing. For outgoing messages, it always uses "Outgoing/buddy_icon.png",
• sender: The name of the sender of the message: the alias if one exists, or the username otherwise,
• senderColor: The color associated with the sender of the message. In chatrooms, this will contain a color string valid in a CSS rule. In IM conversations, it will be an empty string.
• senderStatusIcon: URL of an icon associated with the current status (idle, away, offline) of the sender of the message,
• messageDirection: Direction of the message. Always "ltr",
• senderDisplayName: Currently identical to sender. Should be the server-side alias in the future,
• senderScreenName: The username of the sender of the message,
• service: Name of the protocol through which the message transited (e.g AIM, MSN, XMPP, Google Talk, ...),
• textbackgroundcolor: Should be a color string based on the formatting information included in the message. Currently, this is always "transparent".

Replacements in status messages only

• status: Should be a string indicating the nature of the event that caused this message to appear. Currently this isn't implemented, and the result is always an empty string,
• statusIcon: URL of an icon associated with the current status (idle, away, offline) of the other person in the conversation.

Info.plist Keys

The file Info.plist is a property list file containing metadata about the theme.

The following keys are used by Instantbird and Thunderbird:

• DefaultVariant: The name of the default variant. Optional. "default" will be used as the name if this key doesn't exist.
• MessageViewVersion: If the version number provided is >= 3, the main.css file will be used for all variants, otherwise it will be used only for the default variant (this is for compatibility with old Adium themes. In new themes, use the value 4).
• DisplayNameForNoVariant: The display name for the default variant (that is, when no variant is selected). Optional. If this key doesn't exist, a localized version of the string "Default" will be used for display in the theme selection UI.
• DisableCombineConsecutive: This will disable the use of NextContent.html/NextContext.html/NextStatus.html HTML templates. Consécutive messages won't be treated differently from other messages.
• ActionMessageTemplate: This is used to specify how action (/me) messages should be displayed. The value of this key will be used to replace %message% in Content.html, before doing the replacement. Optional. If this key doesn't exist, the default value "* %message% *" will be used.

The following keys work, but only use them if you really feel you absolutely need them, because they make it impossible for the user to select the font in the usual way via Preferences -> Content:

• DefaultFontFamily: the default font family to use for the conversation. Values in CSS stylesheet files can override this.
• DefaultFontSize: the default font size to use for the conversation. Values in CSS stylesheet files can override this.

If your theme needs to work with Adium too, you need more keys, see this page for details.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>ActionMessageTemplate</key>
	<string>&lt;span class="pseudo" style="%senderColor%"&gt;%sender%&lt;/span&gt; %message%</string>
	<key>DefaultVariant</key>
	<string>Normal</string>
	<key>MessageViewVersion</key>
	<integer>4</integer>
</dict>
</plist>

Including JavaScript in message styles

The right file to put JavaScript in a message style is Footer.html. Some Adium themes use a custom Template.html file to include JavaScript in the theme, this is NOT supported in Instantbird / Thunderbird.

The code that you insert in the Footer.html file will be executed as soon as the conversation is loaded. It is a good place to register event listeners.

DOM Mutation events are of particular interest, because they allow you to execute scripts when a new message is added. See the DOM Events documentation.

Example:

This can be placed in the file Footer.html:

<script type="text/javascript">
var body = document.getElementById("ibcontent");
body.addEventListener("DOMNodeInserted", function(aEvent) {
   if (!(aEvent.originalTarget instanceof HTMLElement))
     return;
   var node = aEvent.originalTarget;
   /* the node variable contains the inserted node,
      do something useful with it */
}, false);
</script>

Instantbird/Thunderbird-specific features

Below lists the known differences between message styles in Adium and in Chat Core. Keep in mind that Adium displays conversation using Webkit and that Instantbird / Thunderbird use Gecko, so the rendering may differ slightly.

Files

• NextStatus.html Optional. Used for status messages that quickly follow another status message. If this file doesn't exist, Status.html will be used instead.

Info.plist keys

• ActionMessageTemplate This is used to specify how action (/me) messages should be displayed. The value of this key will be used to replace %message% in Content.html, before doing the replacement. If this key is not provided, the default value "* %message% *" will be used.

CSS Classes

These classes can be used in the CSS files of themes.

• ib-msg-txt This class is present on all texts that are actually a message. The %message% replacement in the HTML templates actually adds a span node with this class around all messages.
• ib-img-smile This class is present on all img tags that were added in messages by the smiley system.
• ib-nick This class is present on participants' nicknames in multi-user chats (MUCs). It carries the "left" attribute when the participant has left the chatroom. You may need an !important if you wish to override the default styling of bold and coloured text. The colour hue of the nick (for use in CSS HSL colour values) is also available stored in the "nickColor" DOM attribute of the DOM element carrying the ib-nick class.
• Mozilla-specific pseudo-classes, for example: *:-moz-any-link

Unread messages ruler

The ruler that appears between read and unread messages (from Instantbird 1.2 and Thunderbird 38) is a hr element with the id #unread-ruler. When styling it, changes which override those in the default style for this element (in conv.css) must be marked !important.

Note: it is possible to style the unread messages themselves by using a CSS sibling selector on the unread ruler.

Element IDs which must not be used by message styles

The following element IDs are used internally by Instantbird and must not be given to any DOM elements by message styles:

• insert-before
• actual-insert
• next-messages-start
• next-messages-end
• unread-ruler
• end-of-split-block

Adium-specific features not implemented in Instantbird / Thunderbird

Files

• Topic.html not supported since Instantbird displays this already in the UI.
• Template.html This file will never be used by Instantbird.
  This file is mostly used by Adium theme authors to change the JavaScript code used by Adium to handle the conversation and more specifically, add new messages to it. The Template.html file included in themes is typically a copy of the Template.html file of Adium, with very few modifications. This code duplication makes it impossible to fix bugs in the original Template.html file because these bugs are copied in several themes. This is NOT the right way to include JavaScript code in a message theme, and Instantbird will not support it. See inserting JavaScript.
• FileTransfer.html, FileTransferRequest.html File transfer isn't handled yet in Instantbird / Thunderbird.

Info.plist keys

• DefaultBackgroundIsTransparent, DisableCustomBackground, DefaultBackgroundColor The handling of user-customized backgrounds for conversations is not yet implemented in Chat Core.
• AllowTextColors This is not handled on a per-theme basis. Text colors in messages can be enabled or disabled by modifying the value of the preference messenger.options.filterMode.
• ImageMask Not implemented.
• ShowsUserIcons Not used.

Keyword substitutions

• %outgoingIconPath% Always returns "outgoing_icon.png" (the default icon included in the theme).
• %messageDirection% Always returns "ltr".
• %textbackgroundcolor{X}% Always returns "transparent"
• %status% Always returns an empty string.

Other

• Image Zooming:
  Adding images directly in messages through AIM direct connect is not yet handled in Instantbird.

• JavaScript enhancements:
  client.debugLog, client.zoomImage, client.handleFileTransfer are not implemented in Instantbird.

• Wekbit CSS extensions:
  Everything prefixed by webkit- in stylesheets won't work with Instantbird. Look for the mozilla equivalent on MDN.

• CSS overflow property:
  Because of bug 42676, we had to disable the overflow CSS property inside conversations by adding this CSS style rule to the default stylesheet:

#Chat * {
  overflow: visible !important;
}

The reason why lots of message styles used overflow: scroll; was that long words that could not wrap broke themes. This is no longer the case with the word-wrap: break-word; property that was recently added and is included in the default stylesheet.

Conversion of Adium message styles

We have a shell script to convert automatically a message style packaged for Adium into a message style installable in Instantbird. Because of the differences between the way Adium and Instantbird handle message styles, we can't guarantee that the resulting message style will actually work in Instantbird / Thunderbird.

It is very easy to use, just download the script makexpi.sh, place the theme you want to convert in the same folder and execute the script!

The script automatically looks for Adium Message Styles in the current folder. It will automatically extact the content of .zip and .tgz archives. It will also attempt to open .dmg disk images (this will fail if you are not executing the script on Mac OS X). If several themes are found, the script will create an .xpi file for each Adium Message Style it found, and finally bundle all the created .xpi files in a single multiple item package xpi file.

Example:

For the following example, we will convert the adium message style Vacation.

Files before the conversion:

$ find .
.
./makexpi.sh
./vacation_5_17162_5829.zip

To launch the conversion, simply execute the script, it will place the resulting .xpi file in a result subfolder and display some details about what it is doing:

$ ./makexpi.sh 
In :
 Extracting vacation_5_17162_5829.zip
 Processing ./Vacation.AdiumMessageStyle:
  Creating vacation.jar
  Creating vacation.xpi
 Moving to vacation_5_17162_5829.xpi
Done!

The result:

$ find .
.
./makexpi.sh
./result
./result/vacation_5_17162_5829.xpi
./vacation_5_17162_5829.zip