|Version 4 (modified by thomasb, 3 years ago) (diff)|
Skins - Styling the Roundcube Frontend
- How do skins work
- Components of a skin
- The template engine
- Templates and their usage
Skins - Styling the Roundcube Frontend
One nice feature of Roundcube certainly is it's strict separation of functionality and appearance. This allows you to create your individual skin with as much or as little features you'd like. The following explains how skins work and what commands and objects are available from the template engine.
How do skins work
A skin is a set of HTML-based templates with CSS stylsheets and all the rest that is necessary to make Roundcube look nice. All files belonging to a skin are stored in a subfolder of the skins/ directory which also denotes the name of the skin.
As the last step of processing a request from the client the template engine of Roundcube reads a template file from the active skin and replaces certain placeholders with real content. There's a neat schema in the Documentation page that explains the process.
Components of a skin
Within the skin subfolder all templates are read from the subfolder templates/ and their file names are hard-coded. All other files are individual and are referenced from the templates and therefore can be named individually. Roundcube is shipped with a default skin (skins/default/ which is worth a look in order to see what a complete skin is made of.
This is the least structure a skin should provide:
skins/<skinname>/ preview.png templates/ addcontact.html addressbook.html compose.html editcontact.html editidentity.html error.html identities.html importcontacts.html login.html mail.html managefolders.html message.html messagepart.html messagepreview.html printmessage.html plugin.html settings.html settingsedit.html showcontact.html
The template engine
All templates are pure XHTML files and contain special tags of the form <roundcube: .../> which are parsed and replaced with the according content. Using these special tags you can also include other template files and make conditional blocks. The syntax and a detailed list of available tags is described on the Skin Markup Language page.
If enabled by configuration ($rcmail_config['skin_include_php']) also PHP code within templates is executed. All references like images, stylesheets and included files must be defined a absolute paths (starting with /) where / is the root of the skin subfolder.
Templates and their usage
No need to explain that this template is used to display the login page.
The default view of the mail section of Roundcube. This template should contain the folders and messages list and maybe the preview pane to display a message inline. The preview pane actually is an iframe which displays a mail message rendered with the messagepreview.html.
Used to display the selected message including all headers and attachments. The message display is opened in the full browser window and also requires navigational parts to get back to the main view.
Similar message.html but used for the inline display of a message within the preview pane. No navigational elements are required here.
This template is used to render the frame to display a message attachment. It mainly contains an object where the actual attachment is loaded into.
When opening a mail message for printing this template is loaded. It should include some stylesheets optimized for printing and not navigation elements. It will be opened in a new window and might provide a link to close it.
This template gathers all the form elements that are necessary to compose a mail message. Copy it from the default skin because it might become quite complicated :-)
The main view of the address book section is controlled by this template. Similar to the mail view it displays the list of contacts, address sources and groups and it loads the contact details in an iframe.
Used to display all details of the selected contact record.
The edit form for a contact record is rendered using this template. It is also loaded in the iframe defined by the main address book view.
Very similar to the editcontact.html template but it probably shows different titles and buttons that match the task of creating a new contact record.
The entire import process is styled by this template. The main content is hard-coded but this template provides the environment like title and navigation for these steps.
The section for all user settings is defined by this template. It consists of the list of settings groups and also shows the navigation to other settings parts like identities and folder management.
This template renders the form to change a certain group of user settings. It is loaded into an iframe which is defined by the main settings.html template.
The list of sender identities is managed using this template. It has a similar structure as the addressbook.html template showing a list of stored identities and an iframe to load the edit form.
Contains the edit form to create or modify a sender identity record and is loaded in an iframe and thus don't requires any navigation elements.
The template that holds all elements needed to manage the imap folders of the current mailbox. It is part of the settings section and should contain links to other parts of this section.
This is a generic template which is used to render the contents of a plugin. Most plugins bring their own templates but in case one doesn't this template is loaded.
Last but not least this template is used to display notifications about fatal errors which prevent the system from working correctly.