Babar-Jas-XML How-To:

Overview

This document will describe, step by step, what you need to do to convert your Jas HTML pages to use XML.

To use XML with Jas you need two things for EACH plot that you wish to display on your page. You need

• A valid XML file describing your Histogram
• an <Object> reference within your HTML pointing to that XML file.

For advanced users: If you wish to look at the Document Type Definition (DTD) to which XML files in Jas must conform, please here at the plotML.dtd .

A basic XML file looks like this. As you look at it, note the similarity in syntax to HTML. Note also that while the tag names look unfamiliar, that they define a logical structure to the data, and it isn't difficult to guess what the tags are specifying about the document.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE plotML SYSTEM "plotML.dtd">
<plotML>
  <plot>

    <title>
      <border type="None"/>
      <label text="1D filled plot (square)">
        <font face="SansSerif" points="14" style="BOLD"/>
      </label>
    </title>

    <dataArea>
      <border type="None"/>
	<data1d>

	  <class name="jas.bean.TreeDataSourceProvider"
	         param="Histograms/test/Reference/1D Gaussian (sigma=4)"/>

          <style1d histogramBarsFilled="true" histogramBarColor="Green" 
                   errorBarColor="Black" dataPointColor="Black" 
                   dataPointStyle="cross" dataPointSize="6" 
                   lineColor="Blue" showHistogramBars="true" 
                   showErrorBars="false" showDataPoints="false" 
                   showLinesBetweenPoints="false"/>
	</data1d>
    </dataArea>

    <bounds width="300" height="300"/>

   </plot>
</plotML>

Take a look at overall structure of this file, shown by the nesting of tags within each other. For example, enclosed within the <plot> start tag and the </plot> end tag, are tags for a <title>, <dataArea>, and <bounds>. This makes sense given that a plot is made up of these elements. Looking further, we see that the <title> is made up of a <border> and a <label>, and even further that the <label> has a <font>.

The rest of the details of the XML file will be explained later, I just wanted you to have an idea of what one looks like.

Creating an XML file:

There are currently two ways to create an XML file to specify a histogram in Jas. You can either:

• Use an existing XML file as a template, changing only the relevant tags needed to display your histogram.
• Manipulate a histogram within Jas and use the new 'Save as XML' feature to save the plot to an XML file.

Using an Existing XML file as a template:

Adapting an XML file to suit your own purposes is fairly straightforward. I have provided a number of nicely formatted templates for various sizes and types of histograms in the templates subdirectory where this web page resides. Look for them in /afs/slac.stanford.edu/BFROOT/Computing/Online/EventProc/jas/templates. To view them all, you would need to run a test server and look at them within Jas. Look here for instructions on how to do this.

Just to give you a sample of what kind of templates are available, here are a few screenshots of them being displayed in Jas:

1D_overlay_long.xml	basic1D_square_log.xml
basic1D_long_log.xml	basic2D_square.xml

1D_overlay_large_stats_inside.xml

To demonstrate what you would need to do to adapt one of these templates to your own purposes, we'll start with a simple one and then do a more complex one.

Modifying an XML file for a standard 1D histogram

In this example We're going to change the data source of the plot, the title, the color the plot is drawn in, and type of y axis it uses. We'll use the XML file for the above '1D Logarithmic with Stats (square)' example as out template. The full xml file for this plot is available here.

To change what histogram the plot displays, we need to change the <class> section of the XML file. It currently reads

  
          <class name="jas.bean.TreeDataSourceProvider" 
                 param="Histograms/test/Reference/1D Gaussian (sigma=4)"/>

The 'param' attribute is the path to the histogram in the jas tree. We need to change this to point a different histogram. If you are converting from an HTML file, this path will be the same as the 'value' parameter specified for the histogram in your old HTML file.

Please note: The path parameter is no longer case-sensitive, meaning that the following path parameters

  
                 param="Histograms/test/Reference/1D Gaussian (sigma=4)"
                 param="HISTOGRAMS/TEST/REFERENCE/1D GAUSSIAN (SIGMA=4)"
                 param="HistoGRAMS/test/REFERENCE/1D Gaussian (SIGMA=4)"

We need to work with the <title> section of the XML file. It currently reads

    <title>
       <border type="None"/>
         <label text="1D Logarithmic with stats (square)">
           <font face="SansSerif" points="14" style="BOLD"/>
         </label>
    </title>

We see from this that the 'text' attribute of the title tag must be what we need to change. Change "1D logarithmic ..." to 'Our Changed Histogram'.

To change the plot color:

We need to work with the <style1d> section of the XML file. It currently reads

          <style1d histogramBarsFilled="false" histogramBarColor="Green" 
                   errorBarColor="Black" dataPointColor="Black" 
                   dataPointStyle="box" dataPointSize="6" 
                   lineColor="Red" showHistogramBars="true" 
                   showErrorBars="false" showDataPoints="false" 
                   showLinesBetweenPoints="false"/>

To change the axis type:

We need to work with the <axis> section of the xml file for the y axis. Since we only have one, this is the axis section with location specified to be 'y0'. A second y axis would have it's own axis section of the xml file, with location equal to 'y1'. The y0 axis section currently reads:

      <axis location="y0" type="double" showOverflows="false" 
            logarithmic="true" allowSuppressedZero="true">
        <font face="Dialog" points="12" style="PLAIN"/>
      </axis>

Using the 'Save as XML' feature in JAS

Another way to create an XML file is to manipulate a histogram in Jas, then save it as an XML file. Here's what you need to do:

• Start up jas and connect it to a server.
• Change the 'window style' (under the 'View' menu) to 'internal panes'.
• Navigate through the jas tree at the left until you find the histogram you want to work with. Double click on it. It should appear in an internal frame.
• Manipulate and change the properties of the plot however you like. You should resize the entire internal pane until it is the size you want it to appear in your web page. You can also change the size of the data area, title, location of the legend, and a host of other manipulations possible by right-clicking on the plot and choosing the 'properties' option.
• When you're satisified with the appearance of your histogram, right click on the plot and choose 'Save Plot As'. This will pop up a dialog window asking you where to save the file. You should make sure that you specify a .xml ending and that 'files of type *.xml' is selected. You should also make sure you select 'Save Reference to Live Data', or Jas will save the actual data points in the xml file and you'll have to remove them.
• Now you must edit the XML file you just saved to make it point at your histogram. This will not be necessary in future releases of jas, but right now you must do this. Here's what you need to do:

  Your xml file will contain 1 or 2 (if you're doing an overlay) sections that look like this:

    <class name="???" param="???"/>

You need to replace the ??? in 'name' to 'jas.bean.TreeDataSourceProvider', and the param to be the path to your histogram in the Jas tree. A valid example for my own test server would be:

  
          <class name="jas.bean.TreeDataSourceProvider" 
                 param="Histograms/test/Reference/1D Gaussian (sigma=4)"/>

NOTE: The path parameter is no longer case-sensitive. Please refer to the note above for what exactly this means when using reference histograms.

That's all there is to it! Now we just have to set our HTML file up correctly, and we're done.

Setting up the HTML file

This is the easiest part of the lesson. For each XML plot you have on your page, you must put a corresponding <Object> tag in your HTML. The form of the tag looks like this:

      <object classid="hep.babar.JasExtensions.BabarXMLPlot">
        <PARAM name = "xmlURL" value="relative/path/to/your/xml/file">
      </object>
       

The path to the xml file is relative to the directory from which the HTML page resides in. So, for example, if I wanted to show a plot on my page that needed an xml file in the 'xml' subdirectory of my main HTML directory, my HTML tags would look like this:

      <object classid="hep.babar.JasExtensions.BabarXMLPlot">
        <PARAM name = "xmlURL" value="xml/my_file.xml">
      </object>