VML Tutorial
VML (Vector Markup Language) is a way of using text to describe graphical shapes. These text descriptions are very short as compared to the size of standard JPG/GIF images, can be embedded within a web page and do not required the download of additional files. The Microsoft Internet Explorer, version 5+, can interpret the VML code and render the described shapes onto the web page with a wide variety of control options. No other browser supports the VML technology at this time. VML is similar to the Scalable Vector Graphics (SVG) technology which all browsers are expected to eventually support and which will provide vector graphics capabilities such as those offered by Macromedia's Flash technology. Because VML is an application of XML, it can be used with HTML and CSS to provide animation and interactivity with users on web pages. If your web site visitors predominately use MSIE, then the use of VML may be a very appropriate, and simpler, way to provide graphics for your site. To sweeten the pie, Microsoft's Office Products (2000+) also support VML.

Before You Start		Pre-Defined Shapes
CSS (style)		ShapeType Element
Overview		Text
Positioning		Groups/Children
Summary Chart		More Examples
Shape Element		Animation/Interactivity

Return to top of document

Before You Start

Before you can use VML within MSIE, there are two lines of code which must be added to your web page. First, the normal <HTML> tag should be replaced with the following:

    <html xmlns:v="urn:schemas-microsoft-com:vml">

Also, the following line must be placed in the <HEAD> section of the web page:

    <style> v\:* { behavior: url(#default#VML); }</style >

These two tags enable MSIE to recognize and render VML tags, such as the simple rectangle VML tags we've seen so far. With these two lines entered, the core HTML code will look like:

    <html xmlns:v="urn:schemas-microsoft-com:vml">
    <head>
    <style> v\:* { behavior: url(#default#VML); }</style >
    </head>
    <body>
    </body>
    </html>

Return to top of document

Overview

Vector graphics are shapes which are rendered from a mathematical description, typically written as plain text. Beginning with version 5, MSIE has included the ability to render vector graphics from text descriptions embedded within the web page. MSIE is the only browser at this time which supports VML.

VML, like standard HTML, uses tag pairs which are read by the browser and used as instructions for displaying content of the web page. In the case of VML, variations of the <v:> and </v:> tag pair are used to contain the VML code - which is a text description of a graphical shape. VML supports eight pre-defined shapes (arc, line, rectangle, oval, curve, polyline, roundrect, and image). Each pre-defined shape has it's own VML tag pair that defines it. VML also supports a shape called 'shape', which can be configured to any custom shape desired.

Here's an example of a pre-defined shape - the rectangle:

The VML code for the rectangle is as follows. It consists of the VML element tag pair <v:rect > and </v:rect>, as well as defining attributes such as fillcolor, strokecolor, and style.

    <v:rect style="width:100;height:100 fillcolor="blue" _
                         strokecolor="red"></v:rect>

In general, VML code describes individual shapes and/or groups of shapes. As we will see, VML offers a variety of ways to define custom shapes, to interact with the user, and to use scripts within web pages to modify shapes and provide animations even after the page is loaded.

The various VML tag pairs are called elements. Some elements define shapes and contain various attributes embedded within the tag which help modify various characteristics of those shapes. For example, fillcolor (from the VML code line above) is an attribute whose value defines the interior color of a shape.

Some VML elements can only be used inside a shape element. Their purpose is to help modify a shape element. These elements tend to be complex enough that embedding them in the shape element tag pair would unnecessarily complicate the VML code, and so are used as stand-alone, embedded elements. This next example shows how the oval shape element uses an embedded fill element to create a shape with a picture embedded within it.

The VML code to create the image-filled shape is as follows:

    <v:oval style="width:100;height:100">
    <v:fill src="garyhead.jpg" type="frame"><v:/fill>
    </v:oval>

The <v:oval> and </v:oval> tag pair defines a VML shape element - the oval. The fill element is placed between the tags of the oval element and has attributes of its own, such as src, which gives the name of the image file to be used to fill the oval shape.

VML shapes consist of outlines and interiors, whose visible characteristics can be controlled by attributes embedded within the VML shape tag pairs or by sub-elements found between the tag pairs (as in the fill element example above). The outline of VML shapes follow a path of straight lines or cubic bezier curves which can be defined using VML code. Features such as color, thickness, and visibility can be defined using the VML code. Likewise, the interior of a VML shape element can be controlled/defined by the VML code. A shape interior can be transparent, filled with a color or color gradient, or filled with an raster (JPG/GIF) image.

Not only can the shapes be pre-loaded into the HTML text of a web page, but their properties can be edited during the life of the web page by using scripts, such as JavaScript. This offers both interactivity as well as animation options to web page programmers.

For example, here is a simple rotating rectangle:

The VML code to create the rectangle is as follows:

    <div style="width:150;height:150">
    <v:rect id="spin" style="width:100;height:100;" fillcolor="yellow" _
                                       strokecolor="blue"></v:rect>
    </div>

The <div> tag was used to create an area in which the rotation would take place. Without it, the changing vertical height of the rotating VML shape would cause the rest of the web page to move up and down to accommodate the changes.

The rotation of the rectangle is achieved by using JavaScript, shown next, to periodically change the angle of rotation.

    <script>
    angle=0;
    function Rotate() {
        angle += 2;
        spin.style.rotation = angle + "deg";
        }
    setInterval("Rotate()", 100);
    </script>

VML additionally supports filling the shapes with gradients, as seen in the following example:

The VML code to create the gradient-filled oval is as follows:

    <v:oval style="width:150;height:100">
    <v:fill color2="#00FF00" type="gradient"></v:fill>
    </v:oval>

In a later section we'll display the code to show all eight pre-defined shapes supported by VML. VML also supports creation of custom shapes and grouping of shapes, which are also discussed later in this tutorial.

Return to top of document

Element & Attribute Summary

-- this section is in revision: 30 May 2004 --

Yes, I know, we haven't discussed everything in this table yet, but I wanted to put it right near the top of this page so you'll see it and can refer to it as you try to put together the various pieces of VML.

Feel free to skip this section and return to it when you feel the need to get a summary view of how the elements and attributes fit together.

First, here's a listing of all the elements supported by VML. The supported attributes of each element are listed in the next table. The core elements define various shapes, either custom or pre-defined. Sub-elements are designed to be used within a core element to modify its characteristics. The Other element category is not so easily described in a single statement. Take a look at the definition of each element in this category to understand its function.

VML Core Elements
group combines multiple shapes into a single unit that can be modified all at once
shape allows definition of a custom shape
shapetype same as shape, except acts as a prototype that can be referenced with a shape element
arc portion of a circle
curve arbitrary line defined by the contents of a path attribute
image
line straight line connecting to xy coordinates
oval oval shape
polyline line consisting of multiple staight line segments
rect rectangle shape
roundrect recetangle shape with user-definable rounded corners
VML Sub-elements
path defines shape outline. used by shape and polyline elements
formulas define formulas that can vary the path of a shape, its inscribed text rectangles, and connection sites. Formula values change as the adj values change on the shape. Formulas can reference other formulas defined earlier in the same formulas element
handles define user interface elements which can vary the adj values on the shape, thereby changing the value of formulas and the rendering of a path based on formulas and adj values.
fill determines a variety of characteristics of a shape (except arc, line, and polyline)
stroke defines visual characteristics of the outline of a shape
shadow creates a shadow for any shape
textbox controls a variety of visual characteristics for words inside a shape
textpath determines where the text in a shape is placed
imagedata identifies the bitmap to be included in a shape and how to apply it
VML Elements (other)
f defines a single value as the result of the evaluation of an expression
h defines which pair of adjust values store the position of the handle and how the handle position can vary as the handle is adjusted
callout -
extrusion -
locks -
skew -
background describes the fill of the background of a page using vector graphics fills

The supported attributes of each VML element are listed in the next table.

Elements and Attributes
Core Elements Sub-elements Other Elements
group
shape
shapetype
arc
curve
image
line
oval
polyline
rect
roundrect path
formulas
handles
fill
stroke
shadow
textbox
textpath
imagedata f
h
callout
extrusion
locks
skew
background
VML Core Attributes
VML Unique Attributes
CSS Attributes (part of Style)

The shape element is the most complex of all elements. The list of attributes given for it in the table above were only some of the most commonly used attributes. The following tables provides the complete list of attributes for a shape element.

Shape Element Attributes
Adj ConnectorType HRPct MSO-Wrap-Distance-Left Rotation UserHidden
AllowInCell CoordOrig HRStd MSO-Wrap-Distance-Right RuleInitiator Visibility
AllowOverlap CoordSize HRWidth MSO-Wrap-Distance-Top RuleProxy Width
Alt DoubleClickNotify ID MSO-Wrap-Edited Spt WrapCoords
BorderBottomColor FillColor Left MSO-Wrap-Mode StrokeColor Z-Index
BorderLeftColor Filled Margin-Bottom OLEIcon Stroked
BorderRightColor Flip Margin-Left OnEd StrokeWeight
BorderTopColor ForceDash Margin-Right OnMouseOver TableLimits
Bullet Height Margin-Top Path TableProperties
Button HR MSO-Position-Horizontal Position Target
BWMode HRAlign MSO-Position-Horizontal-Relative PreferRelative Title
BWNormal HRef MSO-Position-Vertical Print Top
BWPure HRHeight MSO-Position-Vertical-Relative ReGroupID Type
Class HRNoShade MSO-Wrap-Distance-Bottom RelativePosition UserDrawn

A definition of all VML attributes is given in the following table.

Return to top of document

Pre-Defined Shapes

VML supports a total of eight (8) pre-defined shapes. Here's a sample of each, along with the VML tag required to create the shape. Remember that if you want to create an entirely new shape, use the shape element.

Rectangle:    
<v:rect style="width:100;height:100" fillcolor="red" strokecolor="blue"/>

Rectangle (rounded):    
<v:roundrect style="width:100;height:100" arcsize="0.3" fillcolor="blue" _
                                                       strokecolor="red"/>

Line:    
<v:line style="width:100;height:100" from="0,0" to="100,100" _
                         strokecolor="red" strokeweight="4pt"/>

Polyline:    
<v:polyline style="width:100;height:100" points="0,60,50,90,60,10,100,100" _
                                     strokecolor="blue" strokeweight="1pt"/>

Curve:    
<v:curve style="width:100;height:100" from="0,0" control1="30,90" _
 control2="80,10" to="100,0" strokecolor="red" strokeweight="3pt"/>

Arc:    
<v:arc style="width:100;height:100" startangle="0" endangle="120" _
                            strokecolor="blue" strokeweight="2pt"/>

Oval (circle):    
<v:oval style="width:100;height:100" fillcolor="red" strokecolor="blue" _
                                                    strokeweight="1pt"/>

Oval:    
<v:oval style="width:100;height:50" fillcolor="blue" strokecolor="red" _
                                                     strokeweight="3pt"/>

Return to top of document

Text

Return to top of document

Other Examples

To give you a better idea of the range of VML shapes that are possible, here are some examples I've culled from across the web. Use View Source from the browser menu to see the code that generates the shapes.

Note the changing gradient pattern in the above example:

Here are a couple of examples I found elsewhere on the web that you should find very interesting:

Off-site Example #1
Off-site Example #2

Return to top of document

Positioning

Using the style position attribute, VML offers the ability to place shapes anywhere on the web page, to within a pixel's accuracy. There are three position attribute values, static, relative, and absolute. Each determines where a "base point" is defined, from which the top/left stype attributes are used to determine the upper left corner of the shape's bounding box.

Other positioning features include specifying the z-order of shapes on a web page, rotation of a shape, and the option to flip a shape.

The static position attribute value is the default, in which the bottom of the shape is set to the current position in the text flow (top/left stype attributes are ignored). In the example below, the red oval is positioned immediately after the text "Beginning of the shape:". The bounding box takes up space in the text flow.

Beginning of the shape: End. The following code shows how this is done.

    <v:oval style='width:80px;height:90px' fillcolor="red" />

The relative position attribute value lets you place the bounding box with an offset from the current position in the text flow. The top/left style attributes are used. In the example below, the red oval is positioned 50 pixels from the left and 10 pixels from the top relative to the current point in the text flow. The bounding box takes up space in the text flow.

Beginning of the shape: End.

The following code shows how this is done.

    <v:oval style='position:relative;left:20px;top:10px;_
                width:80px;height:90px;' fillcolor="red" />

The absolute position attribute value lets you place the bounding box at an exact distance from the top/left corner of its parent element (the HTML element that contains the shape). This generally means from the top/left corner of the web page. The bounding box does not take up space in the text flow. The following code shows positioning with respect to the top of the page (but is not rendered on this page). As another example, if the shape were placed in a <div> section, the top/left attributes would be with respect to the div area only.

    <v:oval style='position:relative;left:20px;top:10px;_
             width:80px; height:90px;' fillcolor="red" />

The z-index style attribute can be used to determine the order of graphics in a stack, which is allowed by VML positioning. By default, the last shape appearing in the HTML code appears on top, but the z-index style attribute can be used to control the stack order. Its value can be any integer (negative/zero/positive) and the graphic that has a larger z-index value is displayed on top of the graphic that has a smaller z-index value. When both graphics have the same z-index value, the graphic that is listed last in the HTML code appears on top.

In this example, the red oval is displayed on top of the blue rectangle. This is because the z-index value of the red oval is greater than the z-index value of the blue rectangle.

The following code shows how this is done.

    <v:oval style='position:relative;left:10pt;top:10pt;_
  width:100pt; height:40pt;z-index: 1' fillcolor="red" />
    <v:rect style='position:relative;left:10pt;top:15pt;_
 width:100pt; height:40pt; z-index:0' fillcolor="blue" />

If you change the z-index, as shown in the following VML representation, the red oval would move behind the blue rectangle.

The following code shows how this is done.

    <v:oval style='position:relative;left:10pt;top:10pt;_
        width:100pt; height:40pt;z-index:0' fillcolor="red" />
    <v:rect style='position:relative;left:10pt;top:15pt;_
        width:100pt; height:40pt;z-index:1' fillcolor="blue" />

If you supply a negative integer, you can use z-index to position graphics behind the normal text flow, as shown in the following VML representation.

Beginning of the shape: End.

The following code shows how this is done.

    <v:oval style='position:relative;left:20px;top:10px;_
      z-index:-1; width:80px;height:90px;' fillcolor="red" />

The rotation style attribute to specify how many degrees you want a shape to turn on its axis. A positive value indicates a clockwise rotation; a negative value indicates a counter-clockwise rotation. For example, if you specify style='... rotation:90', you can rotate the shape 90 degrees clockwise.

Finally, the flip style attribute to flip a shape on its x or y axis according to the following rules:

Value Description
x Flip the rotated shape about the y axis (invert x ordinates)
y Flip the rotated shape about the x axis (invert y ordinates)

Both x and y may be specified in the flip property. For example, if you type style='... flip:x y', you will flip the shape on both its x and y axis.

Return to top of document

CSS - Style

As discussed above VML elements utilize the CSS2 (Cascading Style Sheets, Level 2) style property to modify VML shapes.

Return to top of document

Shape Element

In addition to the pre-defined shapes offered by VML, programmers can also create custom shapes using the shape element of VML. It may be a bit confusing that VML uses the term 'shape' to describe the element which can be used to make custom shapes. But you'll find the context in which the word shape is used to help make it clear what is meant.

Like the pre-defined shapes, custom shapes are closed paths. In the following example of an isosceles triangle, the three minimum attributes of the shape element are demonstrated - height, width, and path. Note that height and width attributes are CSS properties whereas path is a shape attribute.

In this example, the custom shape is defined as contained in a bounding box of 200x200 pixels. The path attribute describes the outline of the shape as pairs of xy coordinates. The M in the path attribute defines the starting point of the shape outline (M for move to that point) and the coordinates after the L (lines) represent the lines to be drawn to make up the outline of the shape.

In this example, the custom shape starts at (0,200). A line is then drawn to (100,0) and then to (200,200). The line from the last point to the first is automatically drawn by using the X in the path element. The E ends the path.

Using the path is but one of three ways that the properties of a shape can be defined. The three methods are:

By the attributes of the vml:shape element
By the CSS styles of the vml:shape element, which are normally set inside a style attribute on the vml:shape element
By the child elements of the vml:shape element

The following table lists the more frequently used attributes of a shape element. A more complete list was given above in the section on Element & Attribute Summary.

Attribute Value Default
adj A comma-delimited string of up to 8 integers that provides input parameters for vml:formulas child elements None
alt Alternate text shown if the shape can't be drawn for any reason; similar to the ALT \tattribute of HTML's IMG element None
class The class of the shape; used to attach CSS styles to groups of elements in the same class None
coordorigin The local coordinate of the upper- left corner of the shape's box 0, 0
coordsize The width and height of the shape's box in the local coordinate space Same as the width and height of the entire shape
fillcolor The color the shape is filled with; for example, red or #66FF33 White
filled A boolean specifying whether the shape is filled False
href The URL to jump to when the shape is clicked None
id A unique XML name for the element same as any other XML ID type attribute) None
path Commands that define the shape's path None
strokecolor The color used to draw the outline of the shape Black
stroked A boolean specifying whether the path (outline) of the shape should be drawn True
strokeweight The width of the line outlining the shape's path 1px
style The CSS properties applied to this shape None
target The name of the frame or window that a URL loaded when the shape is clicked will be displayed in None
title The name of the shape; displayed when the mouse pointer moves over the shape None
type A reference to the ID of a vml:shapetype element None

The child elements of a shape can also be used to modify a shape.

Element Name Purpose
extrusion A three-dimensional extruded effect
fill Specifies how and with what the shape is filled
formulas Formulas used to calculate the path of the shape
handles Handles by which the shape can be manipulated
imagedata A bitmapped picture from an external source rendered on top of the shape
path Commands specifying how to draw the shape's outline
shadow The shadow effect for the shape
skew An angle by which to skew the shape
stroke The visible outline of the shape
textbox Text inside the shape
textpath A path along which the text is drawn

Return to top of document

ShapeType Elements

For cases where a shape is to be used multiple times on a web page, VML provides the shapetype element. A shapetype is essentially a shape element which is given an id that can then be referenced within another shape element. The shape element which references the shapetype id is drawn per the attributes of the shapetype unless overidden within the shape element itself.

Only the referenced copies of a shapetype element are drawn - the shapetype element itself is never drawn. As shown in the example below, the shape which is to use the shapetype does so by setting its type attribute to reference the shapetype element.

Since the shapetype is not drawn, its declaration does not include width and height. Those attributes are declared by the shape which uses the shapetype. In the following example, a triangle shape type is defined as follows, where each triangle is drawn from a shapetype element, and each triangle defines its own height/width. If the shape element contains attributes found within the shapetype element, then the attributes of the shape element are override those found in the shapetype element.

The code for the shapetype element example above is as follows:

    <v:shapetype id="master" fillcolor="red" _
           path="M 0,0 L 100,100,200,0 X E"></v:shapetype>
    <v:shape type="#master" style="width:50px;  height:50px"/>
    <v:shape type="#master" style="width:100px; height:100px"/>
    <v:shape type="#master" style="width:150px; height:150px"/>

Return to top of document

Groups/Children

VML provides the group element which can allow the web page to treat multiple shape elements as through they were a single element. A group will have its own local coordinate system and any child element coordinates will be in terms of the parent (group) coordinates. A group element can have a limited set of attributes - id, class, style, title, href, target, alt, coordorigin, and coordsize.

For example, to create a oval in a rectangle you can create a group element that contains both an oval and a rectangle.

The VML code that creates this group is as follows:

    <v:group style="width:200px;height:200px" coordorigin="0,0" _
                                              coordsize="400,400">
    <v:rect style="position:absolute;top:0;left:0;width:200;height:200" _
                                          fillcolor="red"></v:rect>
    <v:oval style="position:absolute;top:0;left:0;width:200;height:200" _
                                          fillcolor="blue"></v:oval>
    </v:group>

The group is defined by a 200x200 pixel space on the web page, with abstract dimension of 400x400 and where the 0,0 point is at the top/left of the group container.

Note that elements inside the group use nondimensional numbers for top/left/width/height dimensions. All children of the group are positioned and sized according to the local coordinate system. A group element (shape) whose coordinates extend outside the group boundary will not be truncated at the boundary of the group container.