Creating Message Styles

This page is a reference sheet for Adium message style creation. It is not a tutorial for creating one... but an amazing one already exists. A (sort of) Quick Introduction to making your own .AdiumMessageStyle, along with this reference sheet, should give you everything you need to know. Let us know if there are holes, inconsistencies, or the like, and we'll do what we can to correct them.

Info.plist keys

• CFBundleName gives the name of the message style, displayed in Adium and used as a unique identifier for the style.
• DefaultFontFamily and DefaultFontSize should be self explanatory.
• ShowsUserIcons can be set to false, as seen in Simple.AdiumMessageStyle, to grey out and uncheck the Show User Icons preference. This can be done on a per-variant basis (see note below).
• DisableCustomBackground can be set to true to prevent the user from customizing the background image or the background color.
• DefaultBackgroundColor is the hex value of the background color. This does not actually affect your style but DOES display in the preferences window; setting it properly improves the user experience by having the default color they see match the default color of the background color colorwell. This can be done on a per-variant basis (see note below). If you do not specify a background color, the background color is assumed to be white (FFFFFF).
• AllowTextColors can be set to false to disable sent and received colors in messages. This should only be done if normal sending colors (say, black) just plain aren't going to be visible on your default background. This can be done on a per-variant basis.
• ImageMask can be specified with the name of an image file (preferably a PNG image) which will be used as an alpha mask on all user images passed to your message style via the various %userIcon% keywords. This image should be located in your Resources folder and be purely greyscale. Where your image is 100% opaque, the user icon will be displayed as normal. Where your image is 100% transparent, the user icon will be clear and transparent. An example use of this would be to provide a circular opaque image which fades to transparent, making all buddy icons appear in an old-time photograph circular-fade-to-nothing manner.

The only required key is CFBundleName, though the others in Smooth Operator's info.plist are recommended.

Variants

If you wish to create Variants, simply create a Variants subfolder in the Resources folder. Variants will be displayed in Adium's menu using their filename (minus the .CSS extension). Your variant may want to import "../main.css" or a similar file.

If you create one or more Variants, variants are the only css files which will be loaded directly. If you have a main.css you want to use as-is, create a variant which simply imports that file and does nothing else.

Per-variant keys may be created by appending ":VARIANTNAME" to the key. For example, to set a default background color for your variant "Black Version.css", which would display as "Black Version" in the menu, you set the key DefaultBackgroundColor:Black Version to the color (perhaps 000000) as a string. When looking for the settings for a variant, the variant-specific version is tried first. If none is found, the general style setting is tried. If no general setting is found, the default value is used.

Info.plist keys for Variants

• DefaultVariant determines the Variant used by default. Do not include the .css extension.

Available keyword substitutions

The following keywords are for use in header.html and footer.html and are processed only when the chat is first opened:

• %chatName% - A name for the chat. For a one-on-one chat, this will be the display name of the remote user. For a group chat, it is the group chat name or topic, as appropriate.
• %sourceName% - The name of the source account for this chat.
• %destinationName% - The name of the chat's destination.
• %destinationDisplayName% - The serverside (remotely set) name of the chat's destination, such as an MSN display name. (Adium 1.0+)
• %incomingIconPath% - A full path to the image of the remote user. If the remote user does not have an image, or this is a group chat so no image is appropriate, this tag will be replaced by incoming_icon.png, so you should have that file available if this tag is used.
• %outgoingIconPath% - A full path to the image for the local user. If the local user does not have an image this tag will be replaced by outgoing_icon.png, so you should have that file available if this tag is used.
• %timeOpened% - The time at which the chat was opened, in the user's default time format.
• %timeOpened{X}% - The time at which the chat was opened, formatted in the way specified by the NSDateFormatter time format string X.

The following keywords are for use in Content.html, NextContent.html, Context.html, and NextContext.html, processed with each message:

• %userIconPath% - Path to the user icon associated with this message. If the user does not have an icon available, a path to the buddy_icon.png file in the Incoming or Outgoing directory (whichever is appropriate for the message) will be substituted instead, so if your message style uses this tag those files should be supplied as defaults.
• %senderScreenName% - The screen name (UID, ID, member name, etc.) of the sender of this message. See %sender%.
• %sender% - The name of the sender of this message as the user's preferences request it. This is the recommended keyword to use for displaying the sender of a message, as it allows proper user customization within Adium.
• %senderColor% - A color derived from the user's name. If a colon separated list of html colors is at Incoming/SenderColors.txt it will be used instead of the default colors. (Adium 1.0+)
• %senderStatusIcon% - The path to the status icon of the sender (available, away, etc...) (Adium 1.0+)
• %messageDirection% - The text direction of the message (either rtl or ltr) (Adium 1.0+)
• %senderDisplayName% - The serverside (remotely set) name of the sender, such as an MSN display name. (Adium 1.0+)
• %service% - A human readable description for the messaging service associated with this message, such as "AIM" or "MSN".
• %textbackgroundcolor{X}% - documentation forthcoming

The following keywords are for use in Status.html, processed with each status message:

• %status% - A description of the status event. This is neither in the user's local language nor expected to be displayed; it may be useful to use a different div class to present different types of status messages. The following is a list of some of the more important status messages; your message style should be able to handle being shown a status message not in this list, as even at present the list is incomplete and is certain to become out of date in the future:
  • online
  • offline
  • away
  • away_message
  • return_away
  • idle
  • return_idle
  • date_separator
  • contact_joined (group chats)
  • contact_left
  • error
  • timed_out
  • encryption (all OTR messages use this status)
  • fileTransferBegan
  • fileTransferComplete

The following keywords are available in all the status/message HTML files:

• %message% - The message itself of the message/status.
• %time% - The time at which message/status occurred, in the user's default time format.
• %shortTime% - The time at which message/status occurred, in the user's preference of 12 vs. 24 hour time but without AM/PM or seconds designations. Only use this if you must limit the size of the time displayed; prefer using %time%. (Adium 1.2.2+)
• %time{X}% - The time at which message/status occurred, formatted in the way specified by the NSDateFormatter time format string X.
• %messageClasses% - A space separated list of type information for messages, suitable for use as a class attribute. Currently available types are listed below. ("Adium 1.1+")
  • history - the message is from a previous conversation
  • outgoing - the message is being sent from this computer
  • incoming - the message is being sent to this computer
  • message - the message is actually a message, and not something like a status change (note: the exact meaning of this with regard to things like file transfers may change in a future version of Adium)
  • autoreply - the message is an automatic response, generally due to an away status
  • status - the message is a status change
  • event - the message is a notification of something happening (for example, encryption being turned on)

The following keywords are for use in FileTransferRequest.html (which is OPTIONAL, and only used in Adium 1.0+) and are processed with each file transfer request:

• %fileIconPath% - Path to an icon representing the file being sent
• %fileName% - The name of the file being sent
• %saveFileHandler% - A javascript function that triggers the "Save File" dialog for a file transfer. Usage is something like <button onclick="%saveFileHandler%">
• %saveFileAsHandler% - See above, but Save As
• %cancelRequestHandler% - See above, but cancels the transfer

Image Zooming in 1.0

If CSS styles are applied to img.fullSizeImage and img.scaledToFitImage, pictures sent using direct connect will have those styles applied. Clicking on the image will switch between the two classes. This can be used to provide Firefox-style image zooming via a style like img.scaledToFitImage{ width:auto; }

JavaScript enhancements in 1.0

• client.debugLog("string") - Logs "string" to the Console
• client.zoomImage(someImgElement) - Switches inline images from having the class "fullSizeImage" to "scaledToFitImage" and back. This is run automagically when you click on an image.
• client.handleFileTransfer("action", "filename") - The file transfer handler keywords are replaced with calls to this

New File Handling in 1.1

Many of the HTML files are now optional if you don't need them to be different (this should be easier due to %messageClasses%). Specifically:

• If Incoming/NextContent.html isn't found, Incoming/Content.html will be used
• If Outgoing/Content.html isn't found, Incoming/Content.html will be used
• If Outgoing/NextContent.html isn't found, whatever was used for Outgoing/Content.html will be used
• If any of the Context files aren't found, whatever was used for their non-Context equivalent will be used
• If FileTransfer.html isn't found, a modified version of Status.html will be used

This allows smaller message styles, less redundant html, and slightly less Adium memory use.