How can I change the graphics for my application

I know there is a method in Application-class called setTheme which receives one string parameter called “theme”. What is that parameter, what values can I use? At least two themes I have found, base and corporte. Can I create my own?

just make a backup of the whole corporate theme folder, and then place your own graphics in the corporate/img folder. you can also edit the stylesheet in corporate/css.

That’s perfectly alright to do so (it requires you to unpack the jar-file), but there is a more serious alternative you could use.

Toolkit supports theme inheritance in all of it’s aspects (js/css/images). That means you don’t have to create everything from scratch yourself. You can only change the parts you need (or implement some new functionality if you wish).



Creating your own theme (the short version)


1.
The first thing you do, is create a new folder in the themes folder (WebContent/WEB-INF/lib/themes). The name of the folder is the name of your theme.
Note: the name must be in lowercase and start with a letter and it can only contain alphanumeric characters.
Let’s create a folder named “mytheme”.


2.
Next, you can copy the description.xml file from the corporate theme folder (WebContent/WEB-INF/lib/themes/corporate/description.xml) to your new theme folder. This file describes your theme contents. Let’s go through the contents of this file:

<?xml version="1.0" encoding="ISO-8859-1"?>

<theme name="corporate">

	<author name="IT Mill Ltd" email="info@itmill.com" />

	<description>
		IT Mill Toolkit Corporate theme.
	</description>

	<extends theme="base" />  

	<!--  Corporate theme only supports UIDL mode -->
	<modes>
		<mode name="ajax"/>
		<mode name="html"/>
	</modes>

	<fileset>

		<!-- UIDL Mode support files -->
		<fileset mode="ajax">

			<!--  CSS stylesheets to load in html head -->
			<file name="css/corporate-ajax.css" />

			<!-- JavaScripts to load in html head -->
			<file name="script/corporate-ajax-components.js" />
		</fileset>
	</fileset>
	
</theme>

The first thing you notice is that it’s plain-old XML. It should be pretty straightforward to understand the basic structure of the file.

The nodes you should pay more close attention are the “extends”, “modes” and “fileset” nodes.

The
extends
is optional, but you should always use it unless you plan to write all the client side scripts yourself (which I do not suggest). The “theme”-attribute defines what theme your theme will extend upon.

The
modes
define what rendering modes your theme should support. At least one should be specified. At the time of writing this, only two modes are supported: “html” and “ajax”. The html mode uses XSLT to render the pages and ajax mode uses only Javascript. The choise is yours, but I personally prefer the ajax mode, where you gain the power of asynchronous http-calls.

The
fileset
defines all the files your theme uses. If you’re extending a theme, you only have to specify any additional files (like some new components), and all the rest are inherited automatically from the extended theme. Normally you declare all your CSS and Javascript files here, you don’t need to declare any images or icons. To change only the looks of a theme, you only need to specify a new CSS file.
Note:
you specify the filesets specifically for the different modes that you have declared.

We can define our new theme as follows (replace my name and e-mail with yours :)):

<?xml version="1.0" encoding="ISO-8859-1"?>
<theme name="mytheme">
	<author name="Jouni Koivuviita" email="jouni.koivuviita@itmill.com" />
	<description>My first new theme!</description>
	<extends theme="corporate" />  
	<modes>
		<mode name="ajax"/>
	</modes>
	<fileset>
		<fileset mode="ajax">
			<file name="css/own-styles.css" />
		</fileset>
	</fileset>
</theme>


There’s much more to the description file markup (see base theme description.xml for example), but not enough room to explain it all here. A more detailed documentation is coming soon enough.


3.
Now you should create the folder structure for your theme. This usually consists of the following folders: “css”, “icon”, “img”, “layout” and “script”. None of these are required by default. But if you’re planning to use CustomLayouts you have to create the “layout”-folder and place all the HTML-files there. Otherwise you free to create your own structure, as long as it follows the fileset-declarations in your description.xml-file.

In our case this means we create a folder named “css”. If we plan to use new images to make our new theme, we should create the “img” folder as well (which we won’t do in this example). Go ahead and create a new stylesheet file as well (called “own-styles.css” like in the description.xml).

Our file structure now looks like this ([+]
notes a folder):

[+]
mytheme
  [+]
css
     own-styles.css
  description.xml


4.
The next thing to do now, is to write the new CSS rules for your theme. The HTML-structure Toolkit generates is not currently documented, so you’ll have to get familiar with it on your own.
Firebug
greatly eases this task. A proper documentation of the HTML structure is also in development.

Do note though, that the structure is probably going to change soon (we are going to refactor and simplify the structure to some extent), so don’t use too much time creating a new theme, cause it probably won’t work correctly with the coming versions of Toolkit. This is unfortunate at the moment, but we assure that the change is for the better :slight_smile:

In the CSS rules you can now override any previous theme images (use relative paths), colors, fonts, spacings etc. If you don’t write any rules in your own theme, the theme will look exactly like the one you extend from.

Hopefully this guide provides at least the minimal knowledge to implement your own theme. A proper guide/documentation is in the works, and will ship within the next four months.