HowTo Develop An Equipment Element for Emle

Overview

An Emle Equipment element file defines one or more graphics that are controlled by standard HTML controls likes radio buttons. Once an Emle Equipment file is created it can be used by Emle Lab writers. As an equipment creator you are providing the components to be used by the lab writer. This enables teachers to apply their knowledge of education to create labs without needing to learn the details of XML.

You will combine Emle graphics and common HTML controls like radio buttons to make an equipment element. The JavaScript and XSLT developers have provided you with the elements you need without you having to learn JavaScript and XSLT.

Emle Equipment Element 3 Example

Here is the an example Emle Equpment element file, emle_equipment_3.xml.

emle_equipment_3.xml 
<equipment xmlns="http://emle.sf.net/emle02"
	xmlns:xhtml="http://www.w3.org/1999/xhtml">
         <id>3</id> 
         <title>Solid Rectangle Fraction</title>
         <value>
            <graphic graphicType="EMLE_GT_RECTANGLE" segmentation="EMLE_GST_SOLID" height="101" width="301">
               <value>
                  <pretext>These buttons <xhtml:em>control</xhtml:em> the enclosed unsegmented rectangle graphic.</pretext>
                  <control enable="EMLE_CET_PROPER_FRACTION" order="EMLE_COT_ASCENDING_BY_COMPONENT" >
                     <numerator   min="0" max="4" />
                     <denominator min="0" max="4" />
                  </control>
                  <posttext>Use the buttons to <xhtml:em>change</xhtml:em> the rectangle.</posttext>
               </value>
            </graphic>
            <posttext>This is <xhtml:em>outside</xhtml:em> the graphic but inside the value.</posttext>
         </value>
  </equipment>

This example Emle Equipment element file contains these Emle elements.

This is a bit of XML to write. When you understand the structure it will become easier to deal with. Also, once you look at the XHTML that is generated by the XSL Tranformation the original will seem much easier.

Resulting HTML

emle_lab.js contains JavaScript code that applies the XSL Transfomations in emle_lab.xsl to emle_equipment_3.xml. The results are placed in the web page. Here is what the equipment part of the page looks like.

Resulting HTML 

<div class="emleEquipment">
<h3>
Equipment 3
- Solid Rectangle Fraction
</h3>
<div class="emleValue">
<span class="emleFracNum">
0
</span>
<span class="emleFracDenom">
4
</span>
<div class="emleGraphic">
<span class="emleGType">
EMLE_GT_RECTANGLE
</span>
<span class="emleGSType">
EMLE_GST_SOLID
</span>
<span class="emleOnChange">
emleUpdateGraphic(emleThis);
</span>
<svg width="301" height="101">
<rect class="emleGraphicBlank" height="50" width="50" y="25" x="35">
</rect>
<rect class="emleGraphicBlank" height="50" width="50" y="25" x="85">
</rect>
<rect class="emleGraphicBlank" height="50" width="50" y="25" x="135">
</rect>
<rect class="emleGraphicBlank" height="50" width="50" y="25" x="185">
</rect>
<rect class="emleGraphicOutline" height="50" width="200" y="25" x="35">
</rect>
</svg>
<div class="emleValue">
<div class="emlePreText">
These buttons
<em>
control
</em>
the enclosed unsegmented rectangle graphic.
</div>
<span class="emleFracNum">
0
</span>
<span class="emleFracDenom">
4
</span>
<form onclick='emleHandleInput(this,"EMLE_CET_PROPER_FRACTION");' action="">
<div class="emleEnabled">
<span class="emleOnLoad">
emleHandleInput(emleThis.parentNode.parentNode,"EMLE_CET_PROPER_FRACTION");
</span>
<fieldset>
<legend>
numerator
</legend>
?
<label class="emleEnabled">
  <input checked="checked" value="0" name="numerator" type="radio">
0
</label>
<label class="emleEnabled">
  <input value="1" name="numerator" type="radio">
1
</label>
<label class="emleEnabled">
  <input value="2" name="numerator" type="radio">
2
</label>
<label class="emleEnabled">
  <input value="3" name="numerator" type="radio">
3
</label>
<label class="emleEnabled">
  <input value="4" name="numerator" type="radio">
4
</label>
?
</fieldset>
<fieldset>
<legend>
denominator
</legend>
?
<label class="emleEnabled">
  <input value="1" name="denominator" type="radio">
1
</label>
<label class="emleEnabled">
  <input value="2" name="denominator" type="radio">
2
</label>
<label class="emleEnabled">
  <input value="3" name="denominator" type="radio">
3
</label>
<label class="emleEnabled">
  <input checked="checked" value="4" name="denominator" type="radio">
4
</label>
?
</fieldset>
</div>
</form>
<div class="emlePostText">
Use the buttons to
<em>
change
</em>
the rectangle.
</div>
</div>
</div>
<div class="emlePostText">
This is
<em>
outside
</em>
the graphic but inside the value.
</div>
</div>
</div>

Additonally the JavaScript functions that handle the user input and that changes the graphics are also located in emle_lab.js. Fortunately you do not have to understand or work with these details.

Equipment Element

Every Emle Equipment element contains exactly these three line. Just copy and paste them into your equipment element file each time.

equipment element 
<equipment xmlns="http://emle.sf.net/emle02"
	xmlns:xhtml="http://www.w3.org/1999/xhtml">
  ...
  </equipment>

Each equipment element contains these elements:

The id simply identifies this equipment element by a number. Just pick the next unused value. The title you select which will be used in directories of availble Emle Equipment elements. The value is a container that has no attributes.

emle_equipment_3.xml 
<equipment xmlns="http://emle.sf.net/emle02"
	xmlns:xhtml="http://www.w3.org/1999/xhtml"> 
         <id>3</id>
         <title>Solid Rectangle Fraction</title>
         <value>
            ... 
         </value>
  </equipment>

Graphic Element

So far we have covered a significant part of an Emle Equipment element file with only a copy and paste followed by setting an integer and a title value. The next element is the key part of Emle, the graphic element. It has several attributes all of which are straight forward:

Values for graphicType include EMLE_GT_RECTANGLE and EMLE_GT_CIRCLE. Attribute segmentation can be either EMLE_GST_SOLID or EMLE_GST_SEGMENTED. Both attributes height and width control the size of the graphic in pixels.

emle_equipment_3.xml 
<equipment xmlns="http://emle.sf.net/emle02"
	xmlns:xhtml="http://www.w3.org/1999/xhtml">
         <id>3</id> 
         <title>Solid Rectangle Fraction</title>
         <value>
            <graphic graphicType="EMLE_GT_RECTANGLE" segmentation="EMLE_GST_SOLID" height="101" width="301">
            ...  
            </graphic>
         </value>
  </equipment>

This example will generate an outlined rectangle, 101 by 301 pixels in size for its value 0/4. When its value is set to 1/2 it will have the left half of the outlined rectangle shaded. It will look the same when the value is set to 2/4 because segmentation was set to EMLE_GST_SOLID. If segmentation had been set to EMLE_GST_SEGMENTED instead the 1/2 would look the same in both cases. But for a value of 2/4 there would be a segementation line showing that it was two fourths rather than a single half.

Control Element

emle_equipment_3.xml 
<equipment xmlns="http://emle.sf.net/emle02"
	xmlns:xhtml="http://www.w3.org/1999/xhtml">
         <id>3</id> 
         <title>Solid Rectangle Fraction</title>
         <value>
            <graphic graphicType="EMLE_GT_RECTANGLE" segmentation="EMLE_GST_SOLID" height="101" width="301">
               <value>
                  <pretext>These buttons <xhtml:em>control</xhtml:em> the enclosed unsegmented rectangle graphic.</pretext>
                  <control...>
                  ...
                  </control>
                  <posttext>Use the buttons to <xhtml:em>change</xhtml:em> the rectangle.</posttext>
               </value>
            </graphic>
            <posttext>This is <xhtml:em>outside</xhtml:em> the graphic but inside the value.</posttext>
         </value>
  </equipment>

Note that there is a value element outside the graphic element. The value element is just glue between the levels. This allows the value of the graphic transmit outward to the rest of the page. In the same way there the control element is inside a value element. This valuse element takes the value of the control and passes it out the graphic. So, when the user makes a change in the control elements the result chnages the graphic via the JavaScript functions automagicly.

The control has pretext and posttext elements around it. These are the mechanism for displaying text within an equipment element. The graphic element has a postext but no pretext in this example.

The control element was shown without the details of its attributes. Any control element will be transformed into HTML form controls like radio buttons.

The control element accepts input from the user for a mixed number in the form of a whole number, the fraction numberator and the fraction denominator.

The attributes for the control element are:

The enable attribute tells the JavaScript functions which of the radio buttons are to be enabled or disabled based upon the current state. The value of EMLE_CET_PROPER_FRACTION means that the only buttons that are to be enabled are ones that if selected will result in a value that is a proper fraction. As the user changes a value there will be different buttons becoming enabled and disables. This feature allows the user to not make any "bad" selections.

The order attribute controls oreder the radio buttons are displayed. Currently supported are EMLE_COT_ASCENDING_BY_COMPONENT and EMLE_COT_DESENDING_BY_COMPONENT.

emle_equipment_3.xml 
<equipment xmlns="http://emle.sf.net/emle02"
	xmlns:xhtml="http://www.w3.org/1999/xhtml">
         <id>3</id> 
         <title>Solid Rectangle Fraction</title>
         <value>
            <graphic graphicType="EMLE_GT_RECTANGLE" segmentation="EMLE_GST_SOLID" height="101" width="301">
               <value>
                  <pretext>These buttons <xhtml:em>control</xhtml:em> the enclosed unsegmented rectangle graphic.</pretext>
                  <control enable="EMLE_CET_PROPER_FRACTION" order="EMLE_COT_ASCENDING_BY_COMPONENT" >
                     <numerator   min="0" max="4" />
                     <denominator min="0" max="4" />
                  </control>
                  <posttext>Use the buttons to <xhtml:em>change</xhtml:em> the rectangle.</posttext>
               </value>
            </graphic>
            <posttext>This is <xhtml:em>outside</xhtml:em> the graphic but inside the value.</posttext>
         </value>
  </equipment>

Finally the last two elements are:

These are used to control the range of radio buttons to be dispayed for user input. In this case both the number will have buttons for 0, 1, 2, 3 and 4. Note that the enable attribute on the control element value of EMLE_CET_PROPER_FRACTION will prevent the denominator fomr ever having the 0 enabled. The reason the designed included 0 on the range for the denominator was so that the buttons for the numberator would align with denominators values below them. Alignment may be an attribute in a future release of Emle.