ThemingTutorial

This tutorial will guide you through the process of creating a custom theme for PHPL.

Concepts

PHPL themes are applied on a per-item basis. The theme is matched against the item being rendered, and the appropriate rules are applied before the item is finally formatted using the properties defined in the theme.

You can match items based on their type, their class, and their status, with the rules composed in that specific order.

Understanding rules

To match all items, use the rule *. This should go at the top of your theme, as the rules are processed in the order they exist in the theme file. Thus, putting it at the bottom of the theme will override anything assigned by previous matches.

* {
    background:blue; 
    color:bright-white;
}

To match against the type, just use the type as is. You can add the class (after a dot) or the status (after a colon) to the rule as well. This doesn't make sense for all rules tho, as not all modules return status, and the type+class matching mostly makes sense if you add multiples of the same type, f.ex. multiple text items that should have different appearance.

path { background:black; color:green; }

status { background:white; }
status:good { color:bright-green; }
status:bad { color:bright-red; }

text.blue { color:blue; }
text.purple { color:purple; }

Classes are also used by different modules of the same type, for example all modules that show version control (VCS) status such as the git module should use the class vcs. That way, you can style all the VCS items the same way without having to style each of the possible modules one at a time.

.vcs { background:cyan; color:bright-white; }

In a similar way, you can style all similar statuses in one go:

:bad { color:red; style:bold italic; }

Applying properties

The properties implemented lets you control the padding, colors and style. Padding is configured using pad-before and pad-after, with the value being either an integer (indicating how many whitespaces to add) or a string (which is used verbatim). The following lines will surround the panel text with brackets, but remove all padding from the path item:

* { pad-before:"["; pad-after:"]"; }
path { pad-before:0; pad-after:0; }

Colors are usually specified using color names, as in the examples above. The basic 16-color palette uses the following names that can be used with color and background:

    black               red                 green               yellow              
    blue                magenta             cyan                white               
    gray                bright-red          bright-green        bright-yellow       
    bright-blue         bright-magenta      bright-cyan         bright-white        

Using none will reset the default foreground or background color.

The available text styles are bold, italic and underline. These can be combined by separating them with spaces

path {
    style: bold italic;
}

Using variables

You can use variables to share property values between multiple rules. You cold for example define a variable to hold the standard background color or a specific accent color. To set a variable, you use the $set() directive:

$set(bg0,black);
$set(bg1,blue);

To reference it, prefix the variable name with a percent sign:

.someclass { background:%bg1; }

Including other styles

• $source(<file>): Include the file if it can be found. Will not report errors if missing.
• $include(<file>): Include the specified file, error out if it can not be found.

You can use these two directives to create a theme that uses shared components and allow the user to modify aspects of it by creating the appropriate file:

// This is mytheme-white.theme
$include(mytheme.common)
$source(mytheme.custom)
* { background: white; }

The file mytheme.custom will only be included if it is found alongside mytheme-white.theme while the file mytheme.common will always be included.

Overriding icons

You can override icons with the $icon(name,icon) directive. The following will use the letter "Y" as the branch icon for the git module. Unicode is allowed. Do not quote the icon string as it is not parsed by the tokenizer but in a preprocessing step. This also means that you can not use the character ) as an icon right now.

$icon(git.branch,Y)