Webkit Chat Themes

Internals

Terms

• Helper scripts

  Communication with loaded WebKit themes occurs through bridge Qt object JavaScript scripts in theme. There are few of such scripts in Psi. Some of them are loaded globally. Others loaded with certain theme or theme adapter.

• Theme adapter

  Currently Psi supports two types of themes:

  1. Its own themes / Psi themes

     These replicates classic Pi behaviour. They may look complicated since all initialization is done in JavaScript and present in each theme but this makes them more flexible.

  2. Adium themes

     Just popular themes for any messenger originally born for Adium.

  Each type of theme has helper script - adapter.js. This script is responsible for theme loading, and initialization of new chats with certain theme.

• Bridge object

  On C++ side we have standard QObjects. These QObjects can be embedded to WebView and look like JavaScript objects. Psi has two of such objects.

  1. Theme bridge - It's general purpose bridge
  2. Session bridge - Chat window specific bridge create for each instance of WebView

  Both of them have some API useful for themes code.

• Theme

  A set of files, scripts and styles located under <adapter name>/<theme name> directory. The rules to find theme are the same as for iconsets.

Theme loading

Root directory for chat themes and related files is themes/chatview. This directory contains adapters' directories which finally keep themes.

Example

/usr/share/psi-plus/themes/chatview/util.js
/usr/share/psi-plus/themes/chatview/psi
/usr/share/psi-plus/themes/chatview/adium
/usr/share/psi-plus/themes/chatview/adium/adapter.js
...
/usr/share/psi-plus/themes/chatview/adium/Pushpin.AdiumMessageStyle

To use themes few initializations steps are required.

First we start in ChatViewThemeProvider::load

1. Find util.js

This script is responsible for very common things like getting some chat UI settings. Sending logs back to C++ code and others.

2. Find adapter.js

It's real theme loader and theme support script.

3. Find theme path

Adapter and its themes may reside in different directories. So theme path is computed each time Psi loads a new theme.

4. Create internal WebView

It's just for theme initialization. This step is handled by ChatViewTheme class

5. Embed theme bridge and helper scripts

So theme bridge QObject, util.js and adapter.js will be loaded into internal WebView right before init of JavaScript part.

6. Call JavaScript init

So at this moment we have the QObject bridge. From JS side it's seen as chatServer (name may change in the future) in global namespace and it's embedded first. Then util.js and adapter.js are evaluated into WebView. The last step here is to call window[chatServer.jsNamespace()].adapter.loadTheme()

7. loadTheme adapter's method

Main responsibilities:

1. Caching main template / html page (html contents is sent to chatServer)
2. Caching any subtemplates and other files if required.
3. Call theme specific init code if any
4. Tell real theme name to chatServer
5. Rename chatServer in global namespace and tell C++ part the new name. This is done to avoid possible conflicts and may be some security.
6. Setting default avatars for theme with avatars.

No the theme is considered to be loaded and loadTheme must return "ok" string.

If Psi was unable to load theme it will try to load some fallback, in other words classic theme and if it fails too then no way.