Appendix B. Kopete Chat Window Style Guide

Kopete Chat Window Style reference.

Beginning with Kopete 0.12, we are now using Adium format for our Chat Window style. The theme format is based on HTML templates and CSS. They are easier to make and develop, only a knowledge of HTML and CSS is needed. Also, styles can have variants (defined as CSS file) which add more customization value :).

Reference guide.

Adium format consist of a directory structure, HTML templates, CSS files and keywords that are replaced each time the template is processed. The final conversation is a XHTML page where messages are added with DOM operations. The central element is a div element named Chat. Before and after this div element goes the Header and Footer template. Messages are children of the Chat div element.

Directory Structure

A style must respect this directory structure. Code in Kopete are thinking around this directory structure. When archiving the style, archive the styleName directory. The directory structure is a structure of a Mac OS X bundle for those familiar with that operating system. Also you must respect the case displayed here, because a UNIX system is case-sensitive.

styleName\ (can have .adiumMessageStyle as suffix, because in Mac OS X it is a bundle)
        Contents\
                Info.plist
                Resources\
                        main.css
                        Header.html
                        Footer.html
                        Status.html
                        Incoming\ (and Outgoing\)
                                Content.html
                                NextContent.html (for consecutive messages)
                                Context.html (for message history)
                                NextContext.html
                                Action.html
                        Variants\
                                *.css

About <div id="insert"></div>

This is a special div element used internally. It is a placeholder to indicate where to insert the next message. If it is a new message, it is removed and the new message take place. But if it is a consecutive message, the div element is replaced with the content of new message. This special div element is required in Content,Context,NextContent,NextContext templates. Though it not harm to put it also in Action and Status template.

HTML templates.

Template description.

Header.html (Required)

Use the Header template to display a nice header to the conversation. This template is inserted before Chat div element. If you don't use it, just put an empty file.

Footer.html (Required)

This is mostly the same as Header but it is for the footer of a conversation. This template is inserted after Chat div element. If you don't use it, just put an empty file.

Status.html (Required)

This template is used to display an internal message. Internal messages such as status change, message from Kopete (e.g. Incoming File Transfer). When the style do not supply an Action template, it is used to display Action message.

Incoming/Content.html, Outgoing/Content.html (Required)

The content template is the message core. Think it as a block that will hold messages. Make sure it is ready to receive consecutive messages, don't design it to only display one message. Consecutive messages will be inserted at the div insert element.

Incoming/NextContent.html, Outgoing/NextContent.html (Required)

The NextContent template is a message fragment for consecutive messages. It will be inserted into the main message block. The HTML template should contain the bare minimum to display a message.

Incoming/Action.html, Outgoing/Action.html (Optional) (Kopete Extension)

This template is a Kopete extension to the Adium format. It is available for Incoming and Outgoing direction. Action messages are special message to tell we are doing an action. Example: "/me is installing Kopete" would be displayed as "DarkShock is installing Kopete".

Incoming/Context.html, Incoming/NextContext.html, Outgoing/Context.html, Outgoing/NextContext.html (Optional)

These templates are not used in Kopete. In Adium, they are used to display history. It is mostly the same thing as Content and NextContent but with some differences to distinguish from normal messages.

About CSS styles and Variants

HTML template are used to describe how the structure is made. But all the style is described in CSS files. main.css is the main style, where variants are just alterations of the main style. Examples of variants are different colors, no display of user photo. Both main.css and variants and imported in final XHTML page.

-main.css

This is the main CSS file which is common for all variants. This file should contain all the main description of the style.

-Variants

Variants are CSS files located in Variants/ directory. Each variant is a single CSS file that include the main.css and do alteration to the main style.

Debugging styles

Here is two tips for testing a style while creating it.

-Save a sample conversation.

In Chat Window, you can save a conversation. This is a copy of the internal XHTML page displayed. Use it in Konqueror to test your CSS files.

-Disable style cache.

A little configuration switch exist to disable the style cache. When enabled, it reload the HTML templates each time the style is asked. Add the following lines to your kopeterc. Very useful when testing a style in Kopete

[KopeteStyleDebug]
disableStyleCache=true

Keywords reference

Keywords are likes holes to fill with details. On each new message, they are replaced with the correct value corresponding to their context. To fully support all features of Kopete, we added some keywords extensions to the Adium. Also some keywords are only available in certain context.

Keywords list for Header and Footer templates.

There keywords are processed at the beginning of the chat.

%chatName%

This is the name of the current chat session. For a typical session, it display the name of the contact and his status. For IRC, it display the topic of a channel.

%sourceName%, %destinationName%

These are the name of the contacts for a chatsession. %sourceName% is your name. %destinationName% is the name of the contact you are chatting with. Prefer %chatName% over those, because they could be confusing for groupchat and IRC.

%incomingIconPath%, %outgoingIconPath%

These are the image/photo/avatar of the contacts for a chatsession. Incoming represent the contact photo and Outgoing represent your own photo. If they are no photo available, it use buddy_icon.png image which is located in Incoming or Outgoing directory.

%timeOpened%, %timeOpened{X}%

It is the time when the chat session begin. %timeOpened% use the default time format for the current locale. If you want to use a specific time format, use %timeOpened{X}% where X is a string containing the time format. The time parameters are the same as the glibc function strftime. Do man strftime to get the list of available parameters.

Keywords list for Content, NextContent, Context, NextContext, Action template

There keywords are processed for each message.

%userIconPath%

This is the image/photo/avatar of the contact associated with the message. If they are no photo available, it use buddy_icon.png image which is located in Incoming and Outgoing directory depending of the message direction.

%senderScreenName%

This is the contact ID of the contact associated with the message. Examples: me@hotmail.com, 45566576, JohnSmith.

%sender%

This is the name of the contact associated with the message. It use MetaContact display name as a source.

%service%

Display the name of the service associated with the message. Examples: Jabber, Yahoo, MSN.

%textbackgroundcolor{X}%

In Kopete, this keyword is used to represent the highlight background color. Ignore parameter in the braces and only use it as %textbackgroundcolor{}.

%senderStatusIcon% (Kopete extension)

Display the status icon of the contact associated with the message. It's a file path.

%senderColor%, %senderColor{N}% (Kopete extension)

Generate a color from the sender contact id. Can be used to display a different color for contact nickname.

%senderColor{N}% where N is a positive number. If N is greater than 100, it represent a lighter color than the contact's color. If N equal 150 it is a color which is 50% brighter. If N is less than 100 then it is a darker color. Useful for having a background colored differently for each contact.

If you want to use theses colors in a variant, but not in the main style, you have to workaround.


<div style="color:%senderColor%;border:none;border-color:%senderColor{40}%;"><p class="message">...</p></div>

you can apply color to the p.message element in your main.css file, and in your variant put something like

	p.message { color:inherit; border-color:inherit; }

Keyword list common for messages and Status.html

%message%

The message itself. This is a HTML fragment.

%time%, %time{X}%

The time when the message was received. %time% use the default time format for the current locale. If you want to use a specific time format, use %time{X}% where X is a string containing the time format. The time parameters are the same as the glibc function strftime. Do man strftime to get the list of available parameters.

%messageDirection% (Kopete Extension)

Represent the message direction, if the message must be displayed right-to-left or left-to-right. The values are either "rtl" or "ltr". Read Message Direction guideline to see how to use this keyword properly.