wiki:Development/Styles

TracNav(Development)? This is part of the Development Documentation Project, please help document Colloquy if you know anything that would be relevant here for other users to know about.

Creating new Colloquy Styles

A new major feature of Colloquy 2 are the extensible conversation styles. Styles are simple OS X bundles wraped around a CSS file file (at minimum) or a CSS file and a XSL file. Knowing this, the fact that Colloquy uses XML (see the Transcript file format) to store chat messages that come in over the network is no surprise to some. Pairing these three technologies gives us great flexibility when processing and displaying a message on screen.

One way to create a new style is to copy the folder of an existing style, rename the copy to the name of your new style, and edit the info.plist to reflect the new name. Then, in Colloquy, do a /reload styles to have it show up in the app. Note that if you want to use an XSL file and the style you started with didn't include one, you can grab that from inside the app bundle. (You can look inside bundles by right-clicking on them and selecting "show bundle content".)

The process of formatting a message follows these steps, start to finish. First, wrap the message in a simple XML envelope, encoding any special characters and representing IRC styling as XHTML. This XML envelope gets transformed with the curent style's XSL file (or a built-in default XSL file). The resulting transformation from the XSL on the XML should be XHTML that can then be rendered with help from the style's CSS file. Rendering is done via Apple's Safari (WebKit) engine—so the possibilities are endless (evidenced by the built-in iChat-like Bubbles style).

The anatomy of a complex style is as follows, with optional elements italicized:

ATTENTION: The supplement.html is no longer supported! We now look for genericTemplate.html, chatRoomTemplate.html, directChatTemplate.html, smartTranscriptTemplate.html or transcriptTemplate.html depending on the type of panel; the generic template will be used if the others don't exist. If your template has a <div id="contents"></div>, Colloquy will append the messages inside that div, otherwise we just append to the body.

When you would like to perform a Javascript action every time a new envelope (message) is inserted you can use this line inside a html file:

document.getElementById('contents').addEventListener( 'DOMNodeInserted', hideSameTimestamps );

hideSameTimestamps is just an example Javascript function. You can use whatever you like there. Please make sure that your HTML file has a <head> section, and that your body has an element with an id="contents".

The Variants folder inside the Resources is a great way to provide subtle variations upon the main CSS that gives the end user more choice. These variants show up as a sub-menu of the style, named exactly as they are in the variants folder (or keyed upon that name to a translation in the users localization Variants.strings). Any images you wish to use should also be bundles in the Resources folder and referenced relatively through the HTML or CSS.

For examples of various styles, look inside Colloquy's application bundle (normally "/Applications/Colloquy?.app") in the "Contents/Resources/Styles?" folder. You will find the Standard and Bland styles use the built-in "default.xsl" file (in the "Contents/Resources?" folder), while the Bubbles and Novel style use custom XSL files. If you want to create your own XSLT file, take a look at the default.xsl file or the XSLT files of the other stylesheets.

Colloquy also uses the standard Info.plist keys defined by Apple, namely CFBundleName and CFBundleIdentifier.


Install Style Bundles in the following location: ~/Library/Application Support/Colloquy/Styles/

If you created a new style that you want to make public, please mail it to us so we can add it to the Official Style repository.

Last modified 8 years ago Last modified on Nov 27, 2006 1:10:16 PM