Skin template markup language

As described on the Doc_Skins page, skin templates are regular XHTML files with special tags which are then replaced by the content according to their meaning.

Tags

The template engine of Roundcube supports the following tags. All tags are written in common HTML syntax and require certain attributes. Regular HTML attributes are also accepted and will be added to the final HTML output of the according tag.

roundcube:include

Includes (and processes) the referenced file. Similar to PHPs include() the content of the included file will be parsed by the template engine and then placed where this tag is placed.

Attributes:

• file: Path to the file to be included starting with /
• condition: Boolean condition to be fulfilled

Example:

<roundcube:include file="/includes/head.html" />

roundcube:var

Returns the content of the specified environment variable. See Environment variables for possible values.

Attributes:

• name: The variable name

Example:

<roundcube:var name="env:task" />

roundcube:exp

Evaluates the given expression and returns the resulting content. The syntax of the expressions is actually PHP code but can contain variables as described in Environment variables.

Attributes:

• expression: The expression to evaluate

Examples:

<roundcube:exp expression="!empty(cookie:mailviewsplitter) ? cookie:mailviewsplitter-5 : 245" />
<roundcube:exp expression="browser:ie ? 'width:400px' : '380px'" />

roundcube:label

Gets a localized text with the given name.

Attributes:

• name: The label name
• condition: Boolean condition to be fulfilled

Example:

<roundcube:label name="mailboxlist" />

roundcube:button

Creates a button for a specific command of the Roundcube client. A button is also registered in the UI manager and is automatically enabled and disabled according to the current state of the application.

Attributes:

• type: The type of the button. Possible values are link|input|image
• command: The application command this button triggers
• prop: Additional argument of the triggered command
• label: Localized text content of "link" buttons
• title: The common HTML title attribute. Use the name of a localized label
• content: The actual content of the generated HTML element
• class: CSS class(es) for the disabled state of the button
• classAct: CSS class(es) for the enabled state
• classSel: CSS class(es) applied when the button is pressed
• imagePas: Image file for the disabled state
• imageAct: Image file for the enabled state
• imageSel: Image displayed when the button is pressed
• condition: Boolean condition to be fulfilled

Types:

• link: Creates a regular <a></a> tag
• input: Creates a form button
• image: Creates a button using the given image

Examples:

<roundcube:button command="mark" prop="read" label="markread" class="rlink" classAct="rlink active" />
<roundcube:button command="save" type="input" class="button mainaction" label="save" />
<roundcube:button command="add" imageAct="/images/btn_add_act.png" imagePas="/images/btn_add_pas.png" width="32" height="32" title="newcontact" />

roundcube:container

This tag defines a container where plugins can add their stuff. HTML content will be added at this tags position by the template engine and it also specifies the ID of a DOM element where more content can be added client side.

Attributes:

• name: The name of the container
• id: ID of the HTML element which actually represents this container

Example:

<div id="thetaskbar">
...
<roundcube:container name="taskbar" id="thetaskbar" />
</div>

roundcube:object

Dynamic content which is created by the application is put into the template with this tag. An object is identified by the name attribute and can require further attributes according to the object type as well as regular HTML attributes which are just passed through. The section Content objects describes all available objects and their attributes.

Please note that most objects are only available in certain steps/tempaltes. An object tag will be ignored and replaced by an empty string if it's not available.

Attributes:

• name: The object to put here
• condition: Boolean condition to be fulfilled
• object-specific attributes

Examples:

<roundcube:object name="messageContentFrame" id="messagecontframe" width="100%" height="100%" src="/watermark.html" />
<roundcube:object name="messageCountDisplay" style="padding:0.5em; float:right" />

roundcube:if/elseif/else/endif

These tags allow you the include or exclude certain parts of the template if a given Conditional expressions evaluates to true.

Attributes:

• condition: Boolean condition to be fulfilled

Example:

<roundcube:if condition="count(env:address_sources) &gt; 1" />
  ...
<roundcube:else />
  ...
<roundcube:endif />

Content objects

These dynamic objects are created by the core application and will be placed wherever a roundcube:object tag is found. Objects are selected by the name attribute of the tag. The following objects are available and require/support the listed attributes.

loginform

The first thing you'll see is generated by this object.

Attributes

• form: The name of the <form> tag surrounding it. If empty the form tag will be generated
• autocomplete: Is added to the input fields to enable/disable the browser's form completion

message

Gets the container for messages displayed to the user.

username

Displays the current user name.

productname

Inserts the product name set by config.

mailboxlist

messages

messagecountdisplay

quotadisplay

mailboxname

messageheaders

messagebody

messagecontentframe

messagepartframe

messagepartcontrols

searchfilter

searchform

messageattachments

mailboxname

blockedobjects

composeheaders

composesubject

composebody

composeattachmentlist

composeattachmentform

composeattachment

priorityselector

editorselector

receiptcheckbox

storetarget

directorylist

addresslist

addressframe

recordscountdisplay

importstep

importnav

prefsframe

sectionslist

identitieslist

userprefs

sectionname

foldersubscription

createfolder

renamefolder

TBC.

Environment variables

Certain variables from the running PHP script are available to the templates too. They're mainly used to build conditional expressions or to be written to the final output using the roundcube:expression tag. There are several "sources" or environments where values can be retrieved from. A variable selector consists of the environment name followed by a colon and the field name:

env:action

The following environments are available:

config:

All configuration values as set in config/main.inc.php can be accessed using this selector. It is also possible to set a default value which is used in case the config parameter is not set. This is done by adding another colon followed by the default value:

config:sent_mbox:Sent

env:

This selector gives access to state variables which define the current action and all its state. The most important ones are:

env:task
env:action
env:quota
env:address_sources

Env variables are very specific to tasks and actions. See the source code for more vars.

cookie:

This selectors provides access to the cookies submitted by the client. This includes cookies which were set server-side as well as cookies set by the skin itself using javascript.

request:

Similar to the cookie: selector this one provides access to values of the current request submitted either by POST or GET.

browser:

The Roundcube backend provides a browser detection class which analyzes the user agent string submitted by the client and extracts certain values and boolean properties. The browser selector contains the following properties:

ie	True if Internet Explorer
mz	True if Mozilla Firefox or other Mozilla derivate
ns	True if Netscape browser
ns4	True if Netscape 4
opera	True for Opera browsers
khtml	True for KHTML-based browsers
safari	Alias for KHTML
chrome	True for Google Chrome browser
ver	The version number according to the browser type
lang	The user agent language (2 chars)
win	True for Windows operating system
mac	True for Mac OS
linux	True for any Linux OS
unix	True for other Unix systems

Conditional expressions

If a tag has the condition attribute it will only create output if the conditional expression within this attribute evaluates to true. These expressions consist of environment variables, boolean operators and also PHP functions. They should either evaluate to true or false, numeric values > 0 are considered as true.

Examples:

env:task == 'mail && !empty(cookie:mailviewsplitter)
count(env:address_sources) <= 1
config:identities_level:0 < 2
browser:safari || browser.opera