Plugin:TabSRMM/Templates

From Miranda NG
< Plugin:TabSRMM
Revision as of 02:09, 28 October 2022 by Dart Raiden (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
Other languages:

This article describes how to use and customize the look of the message history by using the templates. Templates are strings which determine how each message will be formatted in the message history of TabSRMM. Templates give you some control over the look of your message log, however, their capabilities are basic and if you need more customization options, you should consider using IEView.

Note
These templates will work for the standard message log only. If you use IEView or History++, then the standard message log is disabled and you must configure the layout of your message history in these plugins instead of TabSRMM. See this article for more information on how to configure the message history.

While templates are quite feature-rich, their functionality is limited by the possibilities of the Windows Rich Text control which is used to display the message history in TabSRMM.

Templates can be exported and imported as a part of a theme

General information about templates

A template is a string with a length up to 150 characters. It mainly contains variables which tell TabSRMM how to format a single message within the message history. A template set is a collection of 8 templates, each with its own purpose and there are 2 template sets – one for left to right and one for right to left printed messages.

TabSRMM comes with two default template sets (one for LTR and one for RTL) which are hardcoded into the plugin. It also contains a template set editor which allows you to change the templates in a relatively comfortable way. When you change your templates, they are saved in Mirandas database and any changed template will overwrite the default hardcoded one. You don't need to edit or change all 8 templates of a set, it is perfectly ok to change only a few and leave the others alone.

You can export and import templates by using the theme export/import feature which will save your complete theme, including all fonts, colors and your currently active templates to a INI style text file. You can later re-import this theme and get your custom templates back (e.g. after installing a fresh copy of Miranda or after creating a new profile).

The template editor can also reset your templates to the default (hardcoded) variants. This can be helpful when you have completely screwed up a template and prefer to start over from scratch rather than repairing it. The Revert to default button can be used to reset a single template, while the Reset all templates button can be used to reset the entire template set to the default hardcoded templates.

The 8 templates of a template set

  • Message In – an incoming message when message grouping is not active.
  • Message Out – an outgoing message when message grouping is not active.
  • Group In (start) – the first message of a group of incoming messages when the message log formatting is set to grouped mode.
  • Group Out (start) – the first message of a group of outgoing messages when the message log formatting is set to grouped mode.
  • Group In (inner) – subsequent messages of a group of incoming messages.
  • Group Out (inner) – subsequent messages of a group of outgoing messages.
  • Status change – a status change event
  • Error message – an error message printed to the message log (e.g. the message which appears when a message delivery has failed).
Note
Templates are simple strings with embedded variables – variables must begin with a % character and are case sensitive.

Supported variables

Note
Items like grid lines and selective background colors cannot work in automatic bidirectional mode. This is a limitation of the rich edit control.
Variable Description
%! dummy – everything followed by this variable will be printed "as is" with the current font and color. This variable can be used to skip certain elements depending on the template mode (see modifiers below)
%N nickname
%S message symbol (from the Webdings font) – displays only if "Show symbols" is checked in the message log settings menu
%I icon – again, only shown when the setting is checked
%M the message string itself
%n a "hard" line break (cr/lf – will break indent)
%l a soft linefeed, will preserve indent
%h hour (24 hour format, 0–23)
%a hour (12 hour format)
%m minute
%s second
%o month
%d day of month
%y year (4 digits)
%w day of week (Sunday, Monday... translatable)
%p AM/PM symbol
%U UIN (contextual, own UIN for sent, buddy's UIN for received messages)
%E date, localized, depending on your regional settings. Short format (05/03/2005..)
%D date, localized, depending on your regional settings. Long format (May, 05, 2005...)
%R date, localized, using Today and Yesterday, older dates in long format
%r date, localized, using Today and yesterday, older dates in short format
%O name of month, translatable
%T localized timestamp (depending on your regional settings)
%e error message (only use it in the error message template)

Formatting (simple)

Variable Description
%* bold (works as toggle, first occurrence turns bold on, next turns it off)
%/ italic, same
%_ underline, again, same way
%~ font break – switches to the "default" font for the event (depending on incoming/outgoing and history status)
%-x insert a horizontal grid line with the color X (x is one of the predefined colors). If x is omitted, use the grid line color
%Hx highlight with color x (set the background color)
%fX switch to one of the predefined fonts, where X is a one character code and can have the following values (case sensitive as always):
  • d: – font for date/timestamp
  • n: – font for nickname
  • m: – font for message text
  • M: – font for "misc" events (file, URL, etc.)

The variable will take the current message context into account, that is, it will switch to the font which matches the state of the message (received, sent, old or new). Text following this variable will be printed using the given font. The next variable will, however, change the font again, depending on its context

%cX use one of the predefined colors for the following text output (X is a number from 0 to 4, referring to the color index). Only useful together with the & modifier (see below) and maybe the %fX variable. The X can also be one of the following characters: m, d or n where m selects the color for message text, d the color for timestamps and n the color for nick names. These modifiers respect the message context (incoming, outgoing, old or new)

About modifiers

Currently, there are 5 different modifiers which can be used to `alter` the behavior of most variables. Modifiers have to follow the % character immediately, however, their order is not important. Multiple modifiers are possible, but please note that some combinations don't make much sense.

The # character means that the variable does only apply to old events, that is, events which are loaded from the history when you open a message window. Contrary, the $ character does the opposite – the variable will only show up in new events. You can use these modifiers to get different message formatting for old and new events.

The & modifier means "skip font". If used, the variable will be printed without setting the font for the variables context. Effectively, the font which is currently selected remains valid.

The ? modifier means that this variable will be skipped when the template is set to simple mode while the \ modifier allows to skip a variable when the template is in normal mode. Switching between normal and simple mode is a message log setting available from the message log menu which you can find in the menu bar or by clicking on the message log toolbar button.

These 2 variables allow you to have 2 different layouts available and quickly switch between layouts.

Some examples

Variable Description
%&N prints the nickname, but does not use the font which is configured for nicknames
&N prints the nickname, using the font for timestamps (selected by %fd)
c3%&N prints the nickname, using the font for timestamp, but with the text color set to color #4