Adium

Creating Message Styles

This page is a reference sheet for Adium message style creation, it is not a tutorial for creating one. Here is our tutorial that, 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 fix them.

Message Style Structure

A message style is a hierarchy of files and directories structured like this:

<stylename>.AdiumMessageStyle [directory]
	Contents [directory]
		Info.plist
		Resources [directory]
			Main.css [optional]
			Content.html [optional]
			FileTransferRequest.html [optional]
			Footer.html [optional]
			Header.html [optional]
			Status.html [optional]
			Incoming [directory, optional]
				Content.html [optional]
				NextContent.html [optional]
				Context.html [optional]
				NextContext.html [optional]
				Buddy_icon.png [optional]
				SenderColors.txt [optional]
			Outgoing [directory, optional]
				Content.html [optional]
				NextContent.html [optional]
				Context.html [optional]
				NextContext.html [optional]
				Buddy_icon.png [optional]
			Variants [directory, optional]
				<PrimaryVariant>.css [optional]
				<SecondaryVariant>.css [optional]

The hierarchy above is somewhat less than useful because, while some files are required, they may be able to appear in multiple valid locations. For example, there MUST be at least one Content.html, but it can be located either in Resources/ or in Resources/Incoming/. Similarly, Resources/Main.css is required if you have no variants, but is not required if you have Resources/Variants/<PrimaryVariant>.css.

Files Within the Message Style

  • Info.plist is a required file that provides a variety of meta-data to Adium and Mac OS X.
  • Main.css is a (usually) required file likely to contain all or most of your message style styling.
  • Footer.html is an optional HTML template that is loaded after all other HTML templates. It is always loaded, and is a good place to include custom javascript (until the awaited better place is finished).
  • Header.html is an optional HTML template that is loaded only when the "Show Header" checkbox has been selected in Adium's Messages prefpane. It is loaded before all other HTML templates.
  • Topic.html is an optional HTML template that is loaded for topic content. In group chats, this replaces the Header.
  • Status.html is an optional HTML template for status and event messages.
  • Content.html is a required HTML template for the display of chat messages.
  • NextContent.html is an optional HTML template for providing alternative HTML for consecutive chat messages.
  • Context.html is an optional HTML template for providing alternative HTML for chat messages in the message history.
  • NextContext.html is an optional HTML template for providing alternative HTML for consecutive chat messages in the message history.
  • Buddy_icon.png is the buddy icon that will (by default) be displayed when the "Show User Icons" checkbox is deselected in Adium's messages prefpane.
  • SenderColors.txt is a file containing a colon-separated list of colors that will be used for %senderColor%. Any color which is valid in CSS can be used.
  • <PrimaryVariant>.css is an optional file for providing message style variants. Your variants will be displayed by the filename, excluding the .css extension.

HTML template fallback

In most cases the use of %messageClasses% means that most of the optional files are not necessary. This allows smaller message styles, less redundant HTML, and slightly less Adium memory use.

  • If Resources/Incoming/NextContent.html isn't found, Resources/Incoming/Content.html will be used
  • If Resources/Outgoing/Content.html isn't found, Resources/Incoming/Content.html will be used
  • If Resources/Outgoing/NextContent.html isn't found, whatever was used for Resources/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 Resources/FileTransferRequest.html isn't found, a modified version of Resources/Status.html will be used
  • If Resources/Incoming/Content.html isn't found, Resources/Content.html will be used
  • If Resources/Status.html isn't found, Resources/Content.html will be used

id="insert"

Status.html and every Content.html must contain an id="insert" element so that Adium knows where to put a consecutive message. The insert can be any type of element, but is most often a <div> and looks like this: <div id="insert"></div>.

Use the HTML template fallback rules to determine what HTML template replaces the insert element.

Info.plist keys

  • MessageViewVersion indicates what version of Adium's internal messageview rendering the message style is intended to work with. Valid values are 0, 1, 2, 3, or 4. If you are creating a new message style you probably want to use the highest version number available. Here's the documentation, such as it is.
  • CFBundleVersion gives the version of the message style as displayed in Adium's Xtras Manager (Version 1.6 and newer).
  • CFBundleName gives the name of the message style as displayed in Adium and is used as a unique identifier for the style. It should be less than 16 characters long. Adium will only load a single instance of any CFBundleName, so it must be unique.
  • CFBundleIdentifier gives the name of the message style as a UTI string of the form <source>.<messagestylename>.<type>. im.adium.<messagestylename>.style is used for official bundled message styles, but you may want to use <username>.<messagestylename>.style where <username> is your username on adiumxtras.com and <messagestylename> is the value you used for CFBundleName. Adium will only load a single instance of any CFBundleIdentifier, so it must be unique.
  • CFBundleGetInfoString is the version info that is displayed in the finder when "get info" is executed on the messagestyle. It should probably be the Version Number of your message style.
  • DefaultFontFamily and DefaultFontSize should be mostly self explanatory. However, it is worth noting that you cannot specify specific fonts. For example, you can specify "Lucida Grande", but not "Lucida Grande Bold".
  • ShowsUserIcons can be set to false to grey out and uncheck the Show User Icons preference. This can be done on a per-variant basis (see note below).
  • DisableCombineConsecutive can be set to true to prevent Adium from treating as "consecutive" messages that are received from the same sender within the last five minutes.
  • DefaultBackgroundIsTransparent can be set to true if the chat windows should be transparent wherever a background is not explicitly set.
  • 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; properly setting it 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 include DefaultBackgroundColor then the background color is assumed to be white (FFFFFF).
  • AllowTextColors can be set to false to disable the display of 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 keys are MessageViewVersion, CFBundleName, and CFBundleIdentifier.

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.
  • DisplayNameForNoVariant determines the name of "variant" when no variant exists, but is only valid when used in conjunction with MessageViewVersion 1 or 2. Do not include the .css extension.

Available keyword substitutions

The HTML templates can contain special words with a "%" at each end. Those are "keywords", and Adium will replace them when the HTML is rendered. They can be used anywhere in the HTML file, supplying content (%sender%), CSS classes (%messageClasses%), etc. details are on the Message Style Keywords Reference Sheet.

Miscellaneous details

Image Zooming

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

  • 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

Groupchat Styling

The class 'groupchat' is added to the #Chat element to allow groupchat-specific styling.

Group chats feature a <div id="topic">…</div> in place of the header. In group chats which support it, the contents of Topic.html are inserted into this <div> for topic changes. The substitutions in Topic.html are the same as Content.html, with one change: %topic% is replaced with <span contentEditable id="topicEdit">[message contents]</span>. This allows the user to edit the topic presented. %message% contains the topic text without the span wrapping.

Page last modified by Robby, 3 years ago