Context Navigation

Introduction

With KMess it is possible to completely change the appearance of the chat messages. This page describes how to create a chat style.

KMess' chat styles use a combination of XHTML, CSS 2.1 and XSL. Right-to-left languages, layout and translated text are all supported. Knowlegde of XSL is optional, however (X)HTML and CSS 2.1 knowledge is required. The basics of XSL are explained to get started.

Contents of a chat style

The chat styles are stored in <kdedir>/share/apps/kmess/styles. The <kdedir> can either be your local ~/.kde folder, or the value of

kde-config --prefix

Each subdirectory becomes a chat style, the directory name itself is the name of the style. The chat style subdirectory contains two files:

A xsl file. It can be edited to tune the HTML output.
A css file. It styles the HTML output of the xsl file. This file is optional.

The xsl and css files have the same name as the chat style. So, if the folder is called "Example", it contains the "Example.xsl" and "Example.css" files. This avoids overwriting files when moving them to a different folder.

The following diagram displays the relation between the XSL and CSS files:

Each chat message is formatted as an XML message. KMess uses the XSL file to transform this XML into XHTML. The XHTML is displayed in the chat window. If a CSS file is available, it can be used to style the resulting XHTML page.

The XHTML and CSS code can use any XHTML and CSS 2.1 supported by Konqueror. KMess uses KDE's KHTMLPart internally, to show the chat messages.

Creating a new style

To create your own chat style, create a new folder first, e.g. Test1. Then copy an existing xsl file from a different folder, name it Test1.xsl.

Open the file to update the description and credits. If you keep the GPL license note, we could choose to include your style in the next KMess release by default! It also gives style creators the permission to use each other's code (not ideas!) as well.

The themes Dim, Efficient, Colourful, Fresh and Pure, have almost identical xsl files. Those themes rely on CSS to handle the layout. Use one of those themes as base if you're skilled with CSS.

The Classic theme uses a minimal amount of CSS, and includes all HTML markup in the xsl file. This can serve as first example or base, if your CSS knowledge is limited.

The XML chat message

When KMess receives a chat message, it generates an XML message which looks like this:

  <message type='incoming' date='2007-12-20' time='22:26:52'>
    <from>
      <contact contactId='alice@kmess.org'>
        <displayPicture url='' />
        <displayName text='Alice' dir='ltr' />
      </contact>
    </from>

    <body color='#0033cc'
          fontFamily='Sans Serif'
          fontBold='0'
          fontItalic='0'
          fontUnderline='0'
          fontBefore='&lt;font face="Sans Serif" color="#0033cc"&gt;'
          fontAfter='&lt;/font&gt;'
          dir='ltr'>
    Aren't you going to open your gift?
    &lt;img src="/opt/kde3/share/apps/kmess/emoticons/regular.png"
            height="29" width="29" alt=":)" title=""
            valign="top" class="standardEmoticon"&gt;</body>
  </message>

This is the message which the XSL file transforms into HTML. As you can see, it contains all relevant contact information, message details and the body itself. The emoticons are already replaced, so no worries here. The body content can be copied literally to the HTML output.

To ease the creation of chat styles, the message fonts are prepared already in the fontBefore and fontAfter attributes. The other font attributes can be ignored, or can be used to tune the HTML output even more. The dir attribute specifies the direction of the text. Like the body, fontBefore and fontAfter attributes, it can be used 1-on-1 in the HTML output.

The file <kdedir>/share/apps/kmess/styles/examplemessage.xml contains the possible XML messages KMess generates (view it online here). It can be used to develop the chat styles, and test it later as well (e.g. for right-to-left support).

The message type attribute can have the following values:

outgoing: it's an outgoing message from the user.
incoming: it's an incoming message from another contact.
incomingOffine: it's an Offline-IM message from an other contact.
application: it's an application message, e.g. an invitation to transfer a file. This message is typically displayed with a blue font.
notification: it's a passive notification message from an application, e.g. "connecting to port", "file received". Typically displayed in purple.
system: it's an error message, e.g. "contact is offline", "unsupported invitation". Typically displayed in red.

Some attributes may be omitted:

The date and time attributes are omitted if the user disabled "Show time in chat messages".
The url attribute from the displayPicture tag can be left empty if the user has no display picture.

This can be used in the XSL code to change the layout based on the user settings. It also enforces the settings of the user. It's not possible for a chat style to display a timestamp if the user wants to hide it.

The entire chat conversation is wrapped in a <messageRoot> element. This element can be used to generate the HTML header and footer.

The XSL file

In most cases, an existing XSL file could be used as base for your theme. The XSL file gives you complete control over the position of HTML elements. For developers, it also gives abilities to add if-statements and for-loops to process the messages.

A short introduction to XSL

In an XSL file, there are two different kind of elements. Elements with an xsl: prefix are used as processing instructions. Elements without such prefix become normal XHTML tags.

The following processing instructions are commonly used:

xsl:if: this tests for an element, or element value
xsl:choose: use to create "if ... else if ... else" statements.
xsl:for-each: use to loop through all child elements, used for grouped messages.
xsl:apply-templates: process the selected child elements with a different template.

The <xsl:if> and <xsl:choose> elements can be used to show or hide HTML from the output. The test attribute can be something like test=" body/@dir = 'ltr' ". This checks if the body element looks like <body dir="ltr">. Code such as test="@time" simply checks whether an attribute exists. The test attribute uses XPath syntax.

More information can be found at the XSLT tutorial of W3Schools.

Converting the message

The XSL file of every chat style starts with the following header:

  <?xml version='1.0'?>
  <xsl:stylesheet version="1.0"
                  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                  xmlns:kmess="http://www.kmess.org/xmlns/ChatStyles/v1/" >
    <xsl:output method="html"
                encoding="utf-8"
                indent="no"
                omit-xml-declaration="yes" />

    <xsl:param name="basepath" select="'.'" />
    <xsl:param name="csspath"  select="'Name-of-chat-style.css'" />

The first step is the <messageRoot> element which wraps all <message> elements. If this step is omitted, KMess generates a default header and footer. It is however, a nice introduction to XSL too:

  <xsl:template match="messageRoot">
    <html id="ChatMessageView">
      <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <base href="{$basepath}" />
        <style type="text/css">
          /* standard colors for compatibility with dark color schemes */
          body      { font-size: 10pt; margin: 0; padding: 5px; background-color: #fff; co
          a:link    { color: blue; }
          a:visited { color: purple; }
          a:hover   { color: red; }
          a:active  { color: red; }
        </style>
        <style type="text/css">
          /* import additional style */
          @import "<xsl:value-of select="$csspath" />";
        </style>
      </head>
      <body>
        <div id="messageRoot">
          <!-- chat messages are appended here by KMess -->
          <xsl:apply-templates />
        </div>
      </body>
    </html>
  </xsl:template>

To convert the <message> element, we need to define a second XSL template. It's the root element for all HTML output.

  <xsl:template match="message"> ...  </xsl:template>

This template can be filled with the different message types. This can be done with an <xsl:choose> element.

  <xsl:template match="message">

    <xsl:choose>
      <xsl:when test="@type='incoming' or @type='outgoing' or @type='offlineIncoming'">
        ...
      </xsl:when>

      <xsl:when test="@type='application'">
        ..
      </xsl:when>

      <xsl:when test="@type='notification'">
        ..
      </xsl:when>

      <xsl:when test="@type='system'">
        ..
      </xsl:when>

    </xsl:choose>
  </xsl:template>

The CSS file

Chat styles are free to generate any HTML output, including different CSS selectors. As reference, the XSL files from the Pure and Fresh styles define the following standard selectors:

html#ChatMessageView: the root element, to override default font definitions with a #Chat Message View body selector.
div.incoming: container for an incoming message.
div.incomingOffline: container for an incoming offline-IM message.
div.outgoing: container for an outgoing message.
div.application: container for an application message (e.g. invite for file transfer).
div.notification: container for a notification message (e.g. file received).
div.system: container for a system message (error messages, e.g. contact is offline, unsupported invitations).
div.outgoing: container for an outgoing message.
dt: the message caption line.
span.time: the contact name in the caption.
span.time: the message time in the caption.
dd: the message body.
div.messagegroup: container for grouped messages.
dd.first-child: the first message in a message group.
dd.middle-child: the messages in the middle of a message group.
dd.last-child: the last message in a message group.
.ltr: placed around elements when the user typed a message in a left-to-right language.
.rtl: placed around elements when the user typed a message in a right-to-left language.

KMess processes winks, links and emoticons before the message is forwarded to the chat style. The following CSS selectors can be used to style the preprocessed output:

img.standardEmoticon: a standard emoticon.
img.customEmoticon: a custom emoticon from a contact.
img.customEmoticonPlaceholder: a placeholder used while a custom emoticon is being downloaded.
span.filename: the filename in application and notification messages.
span.failedFilename: the filename in failure notices.
div.winkContainer: the container which contains displayed winks (which are Adobe Flash™ objects).

Attachments

conversion-diagram.png (11.3 kB) - added by amroth 7 months ago.

Download in other formats:

Plain Text