Create Your Own XUL Tags - Getting Started Guide

Starting with Luxor Beta 7 you can plug-in your own XUL tags and use them along with all built-in XUL tags. You no longer need to tweak or rebuild the Luxor kernel, instead you can pop a simple XML config file into your app's chrome config folder and start using your very own XUL tags.

Bar Chart XUL Tag Tutorial. To help you get started I show you how to plug-in a <chart> tag to create bar chart diagrams. Example:

 
<chart title="Chart III: Downloads" src="RACHEL_DOWNLOADS" 
  style="color: aqua; font: 25 bold sans-serif; border: outset;" />	     

Comes up as follows:

Using the data series below:

<list id="RACHEL_DOWNLOADS">
  <entry value="23" />
  <entry value="22" />
  <entry value="62" />
  <entry value="68" />
  <entry value="82" />
  <entry value="52" />
  <entry value="98" />
  <entry value="87" />
  <entry value="52" />
</list>

Plug It In, Plug It In. To plug-in your own tags such as <chart> add a config directory to your app's chrome directory tree. Example:

Use <tagdef>s inside the <config> root tag to spice up Luxor with your own tags. <tagdef> requires two attributes: your tag's name such as chart and your tag's XUL tag Java class such as demo.chart.ChartDef.

Example: XUL Tag Plugin Settings

<config>
  <tagdef name="chart" class="demo.chart.ChartDef" />
</config>

Store your tag's settings in the config directory, for example, in moretags.xul. Note, that you can choose whatever name you like because Luxor picks up all files in the config directory to configure itself once you call XulManager.configure().

That's it. Now you can use <chart> like a built-in XUL tag in your app's chrome.

Example: <chart> in Action

<hbox id="CONTENT">
  <groupbox>
    <caption label="Luxor Project Statistics @ Sourceforge" />	 
    <chart title="Chart I: Downloads" src="LUXOR_DOWNLOADS" />
    
    <chart title="Chart II: Page Views" src="LUXOR_PAGEVIEWS" 
       style="color: blue; align: left; border: 20 solid orange;" />
  </groupbox>
      
  <groupbox>
    <caption label="Rachel Project Statistics @ Sourceforge" />	 	 
    <chart title="Chart III: Downloads" src="RACHEL_DOWNLOADS" 
       style="color: aqua; font: 25 bold sans-serif; border: outset;" />	     

    <chart title="Chart IV: Page Views" src="RACHEL_PAGEVIEWS" />
  </groupbox>
</hbox>

Coding Your Own Tags. I use the Chart widget class below to show you how to turn it into a Luxor XUL tag plugin by creating two classes: ChartDef, a class for holding the XUL tag settings, and ChartPeer, a class for setting up and wrapping the Chart widget.

Example: Chart widget class

public class Chart extends JComponent
{
   public void setTitle( String title );
   public void setValues( double values[] );
   public void setTitlePosition( int p ); // e.g. LEFT, CENTER, RIGHT
   public void setTitleFont( Font titleFont );
   public void setChartColor( Color c );
}

The simple Chart widget included in the Luxor plugin distro lets you set the chart's color, title, title font and title position in addition to the chart's data series.

ChartDef a XulTag Class Derivate. First, derive a Java class from luxor.core.XulTag for holding your XUL tag's attributes such as the data source (e.g. src="RACHEL_DOWNLOADS") or CSS style properties (e.g. style="color: aqua; font: 25 bold sans-serif;").

Example: ChartDef.java - Chart XUL Tag Class, Step 1

import org.jdom.*;

import luxor.core.*;


public class ChartDef extends XulTag
{        
    public ChartDef( Element element )
    {
        super( element );
    }
}

Next, add support for the luxor.spi.NComponentFactory interface sporting the createNComponent() method returning a luxor.spi.NComponent reference. NComponent defines the methods Luxor requires for widgets (aka visual components) such as buttons, trees, etc.

Example: ChartDef.java - Chart XUL Tag Class, Step 2

import org.jdom.*;

import luxor.core.*;
import luxor.spi.*;

public class ChartDef extends XulTag implements NComponentFactory
{        
    public ChartDef( Element element )
    {
        super( element );
    }

    public NComponent createNComponent( JComponentResolver resolver )
    {
       return new ChartPeer( this );
    }
}

ChartPeer a NComponent Interface Supporter. Next, you need to create a wrapper class (that is, ChartPeer) for the Chart widget class because it doesn't support the luxor.spi.NComponent interface. Spawn your Chart wrapper class from the luxor.swing.AbstractComponent helper class. luxor.swing.AbstractComponent supports luxor.spi.NComponent and helps you to set up the Chart widget using CSS style properties and more.

Example: ChartPeer.java - Chart Widget Wrapper Class, Step 1

import javax.swing.*;

import luxor.*;
import luxor.spi.*;
import luxor.core.*;
import luxor.swing.*;


public class ChartPeer extends AbstractComponent
{
   private Chart _chart;

   public ChartPeer( ChartDef def )
   {
       super( def );

       _chart = new Chart();              
   }

   public void resolveReferences( NComponentResolver resolver ) {}

   public boolean useMinWidth()  { return false; }
   public boolean useMinHeight() { return false; }

   public JComponent getJComponent() { return _chart; }
}

Finally, use the passed in XUL tag definition (that is, ChartDef) to set up the chart.

The XulTag class offers low-level methods such as String getAttribute( String name ) that returns the value for any attribute and high-level methods such as Color getColor() or Font getFont() that return ready-to-use fonts, colors and so on.

Example: ChartPeer.java - Chart Widget Wrapper Class, Step 2

import java.awt.Component;
import java.awt.Color;
import java.awt.Font;
import javax.swing.*;
import java.util.*;

import luxor.*;
import luxor.spi.*;
import luxor.core.*;
import luxor.swing.*;


public class ChartPeer extends AbstractComponent
{
   private Chart _chart;

   public ChartPeer( ChartDef def )
   {
       super( def );

       _chart = new Chart();              

       String src = def.getAttribute( Xul.Attribute.SRC );

       if( src == null )
          Xul.SyntaxError.REQUIRED_ATTRIBUTE_MISSING( Xul.Attribute.SRC, "chart" );
       else
       {
	     double values[] = XulManager.getXulManager().createDoubleList( src );  
             if( values != null )
		     _chart.setValues( values );
       }
       
       setBorder( _chart );    
       
       String title = def.getAttribute( "title" );
       if( title != null )
	       _chart.setTitle( title );
	       
       Color color = def.getColor();
       if( color != null )
	       _chart.setChartColor( color );
	       
	_chart.setTitlePosition( 
	  def.getAlign( _chart.getTitlePosition() ));        
	       
	Font font = def.getFont();
	if( font != null )
		_chart.setTitleFont( font );

   }

   public void resolveReferences( NComponentResolver resolver ) {}

   public boolean useMinWidth() { return false; }
   public boolean useMinHeight() { return false; }

   public JComponent getJComponent() { return _chart; }
}

More XUL Tag Plugins. For further study you can browse the source for Luxor's built-in tags because your XUL tags do not differ from Luxor's built-in tags.