Skin Maps

Table of Contents

• Description
• Usage
• Examples
• Available tags
• See also
  • • • Development:

Skin-defined lookup tables for infolabel values

---

Description

Skin maps let a skin replace the raw value of an infolabel with a string of its own choosing. A map is a list of key/value pairs; at runtime an infolabel is resolved to its current value, that value is looked up as a key, and the mapped string is displayed instead. Keys that the map does not define are displayed unchanged, so a map only has to list the values it wants to rewrite.

Typical uses are turning short technical values into presentable text, such as an audio codec eac3 into Dolby Digital+, or a two letter country code into a full country name, without needing a python script or a chain of String.IsEqual conditions.

Maps are defined with <map> tags in Includes.xml or descendants pulled in with <include file="..."/>, alongside the other definitions that file carries:

<!-- Includes.xml -->
<includes>
    <constant name="...">...</constant>
    <variable name="...">...</variable>
    <map name="AudioCodecs">
        <entry key="...">...</entry>
    </map>
</includes>

Or keep them in their own file and pull that in:

<!-- Includes.xml -->
<includes>
    <include file="Includes_Maps.xml"/>
</includes>
 
<!-- Includes_Maps.xml -->
<includes>
    <map name="AudioCodecs">
        <entry key="...">...</entry>
    </map>
    <map name="HdrTypes">
        <entry key="...">...</entry>
    </map>
</includes>

They are read with the $MAP[] label format. See the list of available tags for the definition rules.

v22 Skinning engine changes

Added skin maps

---

Usage

A map is read with $MAP[mapname, infolabel]. Both are required and both are trimmed of surrounding whitespace:

<label>$MAP[AudioCodecs, ListItem.AudioCodec]</label>

Being a label format, it is not limited to <label>. It works wherever $INFO[] and $VAR[] do, including inside a <variable> value:

<variable name="AudioCodecLabel">
    <value>$MAP[AudioCodecs, ListItem.AudioCodec]</value>
</variable>

Like $INFO[] and $VAR[], two further optional arguments set a prefix and a postfix. They are added only when the infolabel resolves to a value, so a separator never appears on its own:

<label>$MAP[HdrTypes, ListItem.Property(stream.hdrtype), | ]</label>

$ESCMAP[] behaves identically but escapes the result, in the same way $ESCINFO[] and $ESCVAR[] relate to $INFO[] and $VAR[]. Use it where the mapped value is passed on to something that parses it again, such as a builtin function argument.

Note

$MAP[] is a label format. It is not valid inside a boolean condition.

---

Examples

The simplest map rewrites a handful of values:

<map name="AudioCodecs">
    <entry key="ac3">Dolby Digital</entry>
    <entry key="eac3">Dolby Digital+</entry>
    <entry key="dtshd_ma">DTS-HD MA</entry>
</map>

With the map above, a file whose audio codec is ac3 displays Dolby Digital, while a file whose codec is flac displays flac, because the map does not define that key.

A map may alias another with the ref attribute rather than repeating its entries. Entries listed in the aliasing map are searched first, so it can add keys the referenced map does not define, or override ones it does:

<map name="AudioCodecsVerbose" ref="AudioCodecs">
    <entry key="eac3_ddp_atmos">Dolby Digital Plus with Atmos</entry>
</map>

Here $MAP[AudioCodecsVerbose, ListItem.AudioCodec] gives Dolby Digital Plus with Atmos for eac3_ddp_atmos, and Dolby Digital for ac3, the latter coming from the referenced map.

---

Available tags

Skin maps have the following available tags:

Tag	Description
map	A single lookup table. Requires a name attribute; a map without one is ignored. Accepts an optional ref attribute naming another map to fall back to.
entry	One key/value pair, written as <entry key="rawvalue">Display value</entry>. Requires a non-empty key attribute and non-empty text; an entry missing either is ignored. (can be repeated)

Note

A map defining the same key twice keeps the first entry and logs a warning.

Two maps sharing a name are not merged: the last definition replaces the earlier one and a warning is logged.

A map with no usable entries and no ref is skipped entirely.

A ref naming a map that is never defined is reported at load time, and lookups through it return the raw value.

A ref chain that loops back on itself is detected, aborted, and the raw value returned.

---

See also

Development:

• Skinning