Context Navigation

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.
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 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.
%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.
%senderStatusIcon% - The path to the status icon of the sender (available, away, etc...)
%messageDirection% - The text direction of the message (either rtl or ltr)
%senderDisplayName% - The serverside (remotely set) name of the sender, such as an MSN display name.
%textbackgroundcolor{X}% - This keyword is used to represent the highlight background color. "X" is the opacity of the background, ranges from 0 to 1 and can be any decimal between.

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)
- purple (all IRC topic and join/part messages use this status)
- fileTransferStarted
- fileTransferCompleted

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%.
%time{X}% - The time at which message/status occurred, formatted in the way specified by the NSDateFormatter time format string X.
%service% - A human readable description for the messaging service associated with this message, such as "AIM" or "MSN".
%variant% - The name of the active message style variant, with all spaces replaced with an underscore. A variant named "Alternating Messages - Blue Red" will become "Alternating_Messages_-_Blue_Red".
%userIcons% - Will be replaced with "showIcons" if the "Show user icons" checkbox is selected, and will be replaced with "hideIcons" if the checkbox is deselected.
%messageClasses% - A space separated list of type information for messages, suitable for use as a class attribute. Currently available types are listed below.
- history - the message is from a previous conversation
- consecutive - the message is a "consecutive" message, which means it was displayed within five minutes of the immediately preceding message and is from the same sender
- 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
- mention - the incoming message (in groupchat) matches your username or one of the mention keywords specified in Adium's advanced prefs.
- focus - the message was received while focus was lost
- firstFocus - the first message received while focus was lost
- status - the message is a status change
- event - the message is a notification of something happening (for example, encryption being turned on)
- %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)
  - purple (all IRC topic and join/part messages use this status)
  - fileTransferBegan
  - fileTransferComplete

The following keywords are for use in Resources/FileTransferRequest.html (which is OPTIONAL) 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

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 mathuaerknedam, 3 months ago

Download in other formats:

Plain Text