Skin template markup language
As described on the 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. Also allows to define localized texts for various languages and 'register' them under the given name.
Attributes:
- name: The label name
- condition: Boolean condition to be fulfilled
- quoting: How to escape special characters: html,javascript,no; default is html
- noshow: Only register the localized text under the given name but do not print it
<lang-code>
: Defines the text value for the given language code
Examples:
<roundcube:label name="errortitle" quoting="javascript" />
<!-- register label -->
<roundcube:label name="my.label" en_US="My Label" de_DE="Mein Text" noshow="true" />
<!-- print custom label -->
<roundcube:label name="my.label" />
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" />
(since 1.5)
Note: To use dynamic values for object-specific attributes the attribute name can be proceeded by a colon (:).
Examples:
<roundcube:object name="messages" :optionsmenuicon="!in_array('list_cols', (array)config:dont_override)" />
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) > 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.
version
Prints the current version of the Roundcube installation.
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.
logo
Creates a <img>
tag to display the logo. If set, the src
attribute is replaced by the config option skin_logo
.
Attributes
- src: Path to logo in skin folder
- alt: Alt text for image; defaults to object productname
mailboxlist
The list of subscribed mailboxes/folders of the current IMAP account either as <ul>
or <select>
.
See message.html for examples.
messages
Container for the table of messages. Supports many attributes for styling. See mail.html for an example.
messagecountdisplay
Inserts a placeholder for displaying the number of messages and the currently displayed range.
quotadisplay
Block element to display the mailbox quota provided by the IMAP server.
mailboxname
Container to display the currently selected mailbox/folder name.
messageheaders
Creates a table with headers of the currently displayed message. See message.html for an example.
messagebody
This is where the message content will be inserted. Usable in message.html and messagepreview.html
messagecontentframe
Inserts an <iframe>
- the preview pane - to load the message preview.
See mail.html for an example.
messagepartframe
Creates an <iframe>
to load the selected attachment.
Only used in messagepart.html.
messagepartcontrols
Filename, size and download link of the selected attachment. Used in messagepart.html.
searchfilter
Creates a drop-down menu to select quick-search filters. See mail.html for an example.
searchform
A search input field surrounded with a <form>
used for searching messages or contacts.
See mail.html for an example.
messageattachments
The list of attachments of the currently displayed message. Usable in message.html and messagepreview.html
blockedobjects
Message box displayed when a HTML message contains blocked objects such as remote images and stylesheets.
composeheaders
composesubject
composebody
composeattachmentlist
composeattachmentform
composeattachment
priorityselector
editorselector
receiptcheckbox
storetarget
See compose.html for examples of the above objects.
filedroparea
This container will be activated to receive files dragged & dropped into the browser window in order to be uploaded. Used in compose.html and contactedit.html
directorylist
Similar to the mailboxlist this inserts the list of available address directories. Used in addressbook.html.
addresslist
addressframe
recordscountdisplay
See addressbook.html for an example.
contacthead
contactphoto
contactdetails
Used in contact.html.
contacteditform
contactedithead
photouploadform
Used in contactedit.html.
importstep
importnav
See importcontacts.html for examples.
prefsframe
sectionslist
userprefs
sectionname
See settings.html for examples.
identitieslist
Used in identities.html.
identityform
Used in identityedit.html.
foldersubscription
folderframe
See folders.html for examples.
folderdetails
Used in folderedit.html.
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:
session:
This selector gives access to session variables. For example:
session:username
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 Explorermz
True if Mozilla Firefox or other Mozilla derivatens
True if Netscape browseropera
True for Opera browserskhtml
True for KHTML-based browserssafari
Alias for KHTMLchrome
True for Google Chrome browserver
The version number according to the browser typelang
The user agent language (2 chars)win
True for Windows operating systemmac
True for Mac OSlinux
True for any Linux OSunix
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
Table of Contents
- Skin template markup language
- Tags
- roundcube:include
- roundcube:var
- roundcube:exp
- roundcube:label
- roundcube:button
- roundcube:container
- roundcube:object
- roundcube:if/elseif/else/endif
- Content objects
- version
- loginform
- message
- username
- productname
- logo
- mailboxlist
- messages
- messagecountdisplay
- quotadisplay
- mailboxname
- messageheaders
- messagebody
- messagecontentframe
- messagepartframe
- messagepartcontrols
- searchfilter
- searchform
- messageattachments
- blockedobjects
- composeheaders
- composesubject
- composebody
- composeattachmentlist
- composeattachmentform
- composeattachment
- priorityselector
- editorselector
- receiptcheckbox
- storetarget
- filedroparea
- directorylist
- addresslist
- addressframe
- recordscountdisplay
- contacthead
- contactphoto
- contactdetails
- contacteditform
- contactedithead
- photouploadform
- importstep
- importnav
- prefsframe
- sectionslist
- userprefs
- sectionname
- identitieslist
- identityform
- foldersubscription
- folderframe
- folderdetails
- Environment variables
- Conditional expressions