Create a theme editing project

1. Navigate to a location of your choice and create the directory for your new theme editing project - e.g. new-xuse-themes
2. cd into your new project directory.
3. Run the command:

   xuse new-theme-project new-theme-name                
                   

   where new-theme-name should be replaced by a theme name of your choice.
4. Xuse will create the approporiate directory structure, create the new theme files (cloned from the xuse-standard theme), extract the example project and generate the HTML based on your new theme.

Creating more themes

If you are really enthustiastic you can additional themes within your theme editing project.

1. Navigate to your theme editing project directory.
2. Run the command:

   xuse new-theme another-theme                
                   

   where another-theme should be replaced by a theme name of your choice.
3. Xuse will create the new theme files (cloned from the xuse-standard theme).
4. To generate the HTML files to preview your new theme you need to edit the xuse.properties file to have the following values:

   xuse.output.html.theme=another-theme
   xuse.theme.creation=yes
   xuse.output.dir=src/theme-tests/another-theme    
   

5. Then regenerate the HTML from the example project.

Installing your theme

Once you have created your theme you need to install it in Xuse so that it can be used for any Xuse project on your computer.

1. Navigate to your theme editing project directory.
2. Run the command:

   xuse install-theme new-theme-name                
                   

   where new-theme-name should be replaced by your theme name that you want to install.
3. Xuse will install the new theme files.
4. Navigate to your standard projects and edit the xuse.properties file to use your new theme:

   xuse.output.html.theme=new-theme-name    
   

5. Then regenerate the HTML to reference your new theme.

Distributing your theme

If you want to share your theme with others you can zip the theme directory so that you have a zip file called new-theme-name.zip. Xuse has a built in command to achieve this:

1. Navigate to your theme editing project directory.
2. Run the command:

   xuse create-theme-distro new-theme-name                
                   

   where new-theme-name should be replaced by your theme name that you want to create the distribution from.
3. Xuse will create the file new-theme-name.zip.

You can distribute this to friends and colleagues as you wish. They should install the theme by placing the zip file in a directory of their choice and then following the instructions from step 2 above.

Creating custom styles

If you want to customise css attrbutes for generated Xuse documentation you will need to edit the theme.css (note the filename has to be theme.css so that it is referenced by the HTML correctly).

Depending on how you have created the theme.css file you may already have some css declarations that you can go and edit as you see fit. If you have cloned one of the xuse built in themes you will be able to see all the css ids and classes that have been styled.

Please note that even the built in themes may not reference all the generated ids and classes so it is best to do a view source on the generated HTML to see what options there are for customising the styles.

Creating custom icons and images

All the images in the images directory can be customised but there are constraints. In a Xuse theme images are used in a couple of ways:

1. Direct: Some images are directly referenced by the generated HTML and cannot be deleted. To enable custom styling images can be replaced but the replaced images must have the same name and be the same dimensions as the original.
2. CSS: Other images that you might see in the built-in themes are typically referenced by the css for background images. As these are only referenced by the css you can add, replace or delete these images as you see fit.

Example of directly referenced images used by the built in xuse-standard and xuse-soft themes.

std.	sft.	filename	description
		R-plus.png	Red coloured icon for expanding the section (e.g. requirement detail).
		R-minus.png	Red coloured icon for collapsing the section (e.g. requirement detail).
		A-plus.png	Amber coloured icon for expanding the section (e.g. requirement detail).
		A-minus.png	Amber coloured icon for collapsing the section (e.g. requirement detail).
		G-plus.png	Green coloured icon for expanding the section (e.g. requirement detail).
		G-minus.png	Green coloured icon for collapsing the section (e.g. requirement detail).
		elbow.png	Used to create the folder navigation - represents an image that is logically an elbow.
		elbow-plus.png	Used to create the folder navigation - represents an image that is logically an elbow which can be expanded to show sub-level contents.
		elbow-minus.png	Used to create the folder navigation - represents an image that is logically an elbow which can be collapsed to hide sub-level contents.
		tee.png	Used to create the folder navigation - represents an image that is logically an tee.
		tee-plus.png	Used to create the folder navigation - represents an image that is logically an tee which can be expanded to show sub-level contents.
		tee-minus.png	Used to create the folder navigation - represents an image that is logically an tee which can be collapsed to hide sub-level contents.
		vertical.png	Used to create the folder navigation - represents a vertical space created by sibling items.
		actor-icon.png	An icon for the actor model element.
		package-icon.png	An icon for model packages.
		req-icon.png	An icon for a requirement model element.
		stakeholder-icon.png	An icon for a stakeholder model element.
		use-case-icon.png	An icon for a use-case model element.
		note-icon.png	An icon to indicate the presence of comments/annotations.
		spacer.gif	A generic spacer img used to alter layouts in some places.

Adding Javascript event handlers

Xuse makes some use of Javascript functions to improve the usability of the generated HTML. For instance javascript is used to manage the navigation and to expand and collapse the detailed requirements sections.

Whilst it is not at all necessary to change the default javascript behaviour for your new theme, Xuse provides the facility to override the default functions or add new functions.

• To override functions simply declare a function with the same signature in theme.js.
• To add new functions and attach them to objects you can create your new functions in theme.js, create the appropriate initPage() function to attach the behaviour using the built-in attachEvent() function that is available from core.js.
• If you want to store and retieve some global variables that will be available on every page you can add variables and functions to header.js that is loaded by the header.html page (and is thus only refreshed if the frameset is refreshed).

Putting it all into action

This all sounds complicated so lets have a look at an example. Suppose I want to add a mouseover event to the first requirement (RQ0) in the requirements table to display a value retrieved from header.js then first I would create the appropriate accessors in header.js:

var myVar = 'Initial value';

function setMyVar( varValue ) {
    myVar = varValue;
}

function getMyVar( varValue ) {
    return myVar;
}

Then add the following to theme.js

/*
 * Example functions showing how you can read/write
 * to persistent global variables in header.js
 */

//Set a variable 
function setMyVarInHeader( varValue ) {
    top.frames["header"].setMyVar( varValue );
}

//Get a variable value 
function getMyVarFromHeader() {
    return top.frames["header"].getMyVar();
}

//Display the header value 
function showHeaderVarValue() {
    alert('Value stored in header is: ' + getMyVarFromHeader());   
}

/*
 * Example of init method attaching an event
 * To the first requirements row in the requirements
 * table in the example project
 *
 * Un-comment the lines to get it working
 */  
function initRequirements() {
    /*
     * Set a global variable in header.js
     */     
    setMyVarInHeader('Test variable value set from theme.js');
    /*
     * Attach a mouseover event to the object with id = 'RQ0'
     * When the event is fired the function
     * showHeaderVarValue() will be executed
     */   
    attachEvent(document.getElementById('RQ0'), 
                    'mouseover', showHeaderVarValue);
}

Now when you roll your mouse over the first requirement in the example project you should see the following

Arrgh - why are you using frames?

The Xuse HTML site was inspired by JavaDoc layout where the navigation frame is seperate from the content pane - I know frames are a pain from a CSS styling perspective but they keep the navigation simple.

If you think there is a better way of achieving the same effect without frames please feel free to email me at odlingsmee@users.sourceforge.net.

Can I change the HTML?

No the HTML is generated from XML files via XSLT - changing the generated HTML requires a change in XSLT. If you have some visual requirements that can only be met by changing the generated HTML we are willing to take suggestions.

Are the PDFs themable?

No not yet - this is an area we are working on.