Creating a skin user interface

Most jAlbum skins allow users to set skin specific settings on a custom skin tab in the jAlbum settings window. To enable this for your skin too, please follow this guide.

The screenshot below illustrates a simple custom user interface:

As the skin developer you have the full power of Java/Groovy at your hands to create any imaginable user interface and the code behind to make it tick. Here is how you do it: Put a "onload.groovy" script file in the skin directory. jAlbum will read this file every time that skin is selected/loaded, use the script to construct the user interface and finally install it inside jAlbum. Here is a simple example.

/** 
 * This script is being run when a skin is selected
 * The script produces a simple custom user interface.
 * Author David Ekholm
 */
 
import se.datadosen.component.*;

// Controls that are to be imported into jAlbum as variables
ControlPanel ui = new ControlPanel() {

   JTextField copyright = new JTextField("");
   JCheckBox showLabels = new JCheckBox("Show labels");
   JCheckBox showDates = new JCheckBox("Show dates", true);
   JCheckBox showImageNum = new JCheckBox("Show image numbers", true);
   {
   // Layout controls easily similar to how text is added in a word processor
   ui.add("p", new JLabel("This is a small example of a custom user interface."));
   ui.add("p", new JLabel("Copyright"));
   ui.add("tab hfill", ui.copyright);
   ui.add("p", ui.showLabels);
   ui.add("br", ui.showDates);
   ui.add("br", ui.showImageNum);
   }
};
// Finally install components into jAlbum
window.setSkinUI(ui);

Note, for complex skins you can explicitly set the size of the GUI created, but the preferred method is to add at the end of onload.bsh:

window.pack();

This will ensure that all of the components are visible within the user interface.

jAlbum will create skin variables out of the values of the controls you put inside a ControlPanel class (actually any class implementing the JComponentHolder marker interface). The controls need to be of "Swing" type so use "JButtons" and "JLabels" not "Button" or "Label" classes! If you for instance have a JComboBox control called backgroundColor, you can then refer to its current value as ${backgroundColor} in skin template files like .htt files and .css files.

Controls to variables mapping

The mapping of user interface controls to the corresponding skin variables is performed as follows:

The skin specific settings are persisted with jAlbum's project files. They are prefixed with "skin." to avoid collision with jAlbum variables.

Managing state

Those writing user interfaces know it can be a drag to manage component state, for instance to synchronize the enabled/disabled state of a group of components with the selected state of a checkbox. To simplify this task, jAlbum provides some convenience classes called StateMonitor and ComponentUtilities.

Layout of controls

The example above uses the RiverLayout layout engine of the ControlPanel to lay out controls. RiverLayout works similar to how text is being added to a word processor. Just adding controls will have them flow from left to right (no line wrapping), but adding certain "constraint strings" like "br", "p" and "tab" will affect the layout.

Here is the full set of constraint strings:

Setting default values

To ensure your GUI elements have defined default values use a SkinModel.java file in your skin. With it, you're guaranteed against void and null, see example below, variables. Any variable declared there and having a default value is guaranteed to never be void or null. As a bonus, you get properly typed variables and a skin that works in console mode too.

A SkinModel is a SkinModel.java class file filled with variable references and then compiled to a class file. Put it inside your skin's "plugins" folder or within a jar file within your skin's "lib" folder.

Example:

public class SkinModel {
		
	// Site tab
	public int blogStyleDepth = 1;
	public boolean useBreadcrumbPath = false;
	public boolean showTopNavigation = true;
	public boolean topNavigationPagesOnly = true;
	public String logoName;  //Note, defining a variable without a value is valid but logoName will initially be null
	public boolean showBottomNavigation = false;
	
	public boolean useSearch = true;
	public String searchFields = "title,comment,name,creator,keywords";
}

There is an external tool that will make this file for you You don't need to compile these SkinModel.java files as jAlbum uses BeanShell to dynamically do so, but it is recommend practice.