Chapter 14: Hyperlinks

A SMIL file can define links to other media. A video might link to a second video, for example. When the viewer clicks the link, the second video replaces the first. Or the video could link to an HTML page that opens in the viewer's browser. You can even define areas as hot spots with links that vary over time. The bottom corner of a video can link to a different URL every ten seconds, for instance.

Understanding Hyperlinks

SMIL provides two hyperlink tags, both found in HTML. So if you are familiar with HTML linking, you'll pick up SMIL linking quickly. The SMIL <a> tag is the simpler means of creating hypertext links, but the <area/> tag is more powerful. The <area/> tag includes all features of <a>, and provides additional ones, such as the ability to create hot spots (image maps) and timed links. Using the <area/> tag for all hyperlinks is recommended, but the <a> tag is also available to provide basic linking functions.

For More Information: The two sections "Creating a Simple Link", and "Using the <area/> Tag", provide the basic instructions for using the two link tags.

Links to HTML Pages

Your SMIL file can link to HTML pages that open in the RealONE Player environment (Windows only), or the viewer's default browser. The RealONE Player environment offers three types of browsing windows in addition to the viewer's default browser, as illustrated in the following figure.

Media and Browsing Windows in the RealONE Player

media window

The media window plays clips and SMIL presentations only. It does not display HTML page content.

context window

The context window can display HTML pages that supplement media clips with title and copyright information, for example. This window appears only if you explicitly open an HTML page in it through a specially configured URL.

main browsing window

The main browsing window can attach to, or detach from, the media and context windows. When attached, it appears below the media and context windows. Detached, it functions as a stand-alone window. You can display any HTML page associated with your presentation here.

secondary browsing window

RealONE Player can display any number of stand-alone, secondary browsing windows. You can display any HTML pages associated with your presentation in secondary browsing windows instead of the main browsing window.

Tip: Because all of the browsing windows within the RealONE Player environment use the viewer's Internet Explorer browser (version 4.0 or higher), they can display HTML, Javascript, and ActiveX content.

For More Information: The section "Selecting a Browsing Window" explains the attributes that target the RealONE Player browser windows.

Links to Streaming Media

A hyperlink can also open in the RealONE Player media window, targeting an existing SMIL region, replacing the current presentation, or popping up a new media window. Note, though, that SMIL offers features that you can use in place of hyperlinking. For example, you can pop up a new window during the course of a presentation by using SMIL layout tags. With advanced timing, you can start or end a clip when the viewer clicks another clip. Neither of these features requires hyperlinks. So before you define hyperlinks, be sure that you understand the possibilities offered by SMIL.

For More Information: The section "Linking to Streaming Media" lists the attributes and values specific to streaming media links.

Linked Pop-Up Windows vs. Secondary Pop-Up Windows

A hyperlink can pop up a new RealONE Player media window when clicked, You can also pop-up a window with a <topLayout> tag as described in "Secondary Media Windows". Defining secondary media windows is appropriate when you want the new window to pop up at a predefined point in your presentation. Creating a hyperlink to a new RealONE Player media window is preferable when you want the new window to pop up based on viewer interaction, and the media you display in the window is not part of your main SMIL presentation.

Hyperlinks vs. Exclusive Groups

If you plan to create an interactive application, you need to consider carefully whether to provide interactivity through hyperlinks, <excl> groups, or both. Suppose that you plan to create a presentation that offers three different video clips that the viewer can select by clicking three buttons. You can author your SMIL presentation in different ways:

Link the video clips to the buttons with hyperlinks.

Using hyperlinks, you can link each button to a separate video. In this case, your main SMIL file does not contain <video/> tags that refer to the video clips. Instead, each button uses a hyperlink to play the clip when the button is clicked. This method works well when you want to launch each video in a separate window.

Place the video clips in an <excl> group, and use advanced timing commands to play each video when the viewer clicks a button.

Within an <excl> group, you include a <video/> tag for each video clip. You then use advanced SMIL timing attributes to play each video clip when the viewer clicks one of the buttons. This method is preferable if you want to display all buttons and clips in a single media window, or you want to include SMIL timing and layout attributes in each <video/> clip source tag.

For More Information: For more on the <excl> tag, see "Creating an Exclusive Group". Chapter 13 explains advanced timing features.

Methods of Activating a Link

The screen pointer turns into a hand icon when the viewer moves the pointer over an active link in the RealONE Player media window. Typically, the viewer opens the link by clicking it. SMIL lets you define other ways to open a link, too. You might specify a keyboard key that the viewer can press to open the link, for instance. Links can also open automatically, letting you display different Web pages as a presentation plays, for example.

For More Information: See "Defining Basic Hyperlink Properties" for more information about these features.

General Tips for Creating Hypertext Tags

Hyperlink tags work only with clip source tags. You cannot make an entire group into a hyperlink, or turn a SMIL region into an image map.

Hyperlink tags cannot be nested. You can associate any number of hot spots or timed links defined through <area/> tags with a single clip source tag, however.

Some clips can also define hyperlinks. A RealText clip, for example, can define hyperlinks for portions of text. When a viewer clicks an area where a clip link and a SMIL link overlap, the SMIL link is used.

When turning a clip into a hypertext link, include the longdesc attribute in a clip source tag, using it to describe the hyperlink destination. See "Using a Long Description" for more information.

Creating a Simple Link

The simplest type of link connects an entire source clip to another clip. As in HTML, you define the link with <a> and </a> tags. But whereas you enclose text between <a> and </a> in HTML, you enclose a clip source tag between <a> and </a> in SMIL:

<a href="rtsp://realserver.example.com/video2.rm"> 
  <video src="video.rm" region="videoregion"/>
</a>

The preceding example links the source clip video.rm to the target clip video2.rm. When the viewer clicks video.rm as it plays, video2.rm replaces it. In an <a> tag, the href attribute is required. The URL begins with rtsp:// if the linked clip streams to RealONE Player from RealServer, or http:// if the file downloads from a Web server.

For More Information: For information on link attributes, see "Defining Basic Hyperlink Properties". See either "Linking to HTML Pages" or "Linking to Streaming Media" depending on your intended link target.

Using the <area/> Tag

The <area/> tag differs from the <a> tag in that you place it within the clip source tag rather than around it. This means that you must turn unary clip source tags such as <video/> into binary tags such as <video>...</video>. The <area/> tag typically ends with a closing slash, but in some cases you need to use an <area>...</area> tag pair. The following is a basic <area/> tag that links one video clip to a second video clip:

<video src="video.rm" region="videoregion">
  <area href="rtsp://realserver.example.com/video2.rm"/>
</video>

For More Information: For more on tag pairs, see "Binary and Unary Tags". For an example of when you must use <area> and </area>, see "Setting the Context Window Size".

If the <area/> tag includes no spatial coordinates, the entire clip becomes a link, making the <area/> tag function just like the <a> tag. A clip source tag can include any number of <area/> tags. When you define multiple <area/> links for a single clip, however, you need to do one or both of the following:

Specify temporal coordinates so that each <area/> link is active at a different time.

Define spatial coordinates in each <area/> tag to turn each link into a hot spot that does not overlap the other hot spots.

Creating a Timed Link

An <area/> tag can include temporal attributes that specify when the link is active, relative to the start of clip playback. If you do not include temporal attributes, the link stays active as long as the source clip appears onscreen. To add timing attributes, use the SMIL begin and end values. You cannot use dur, clipBegin, or clipEnd, however.

The following example creates two temporal links for the clip video.rm. The first link is active for the first 30 seconds of playback. The second link is active for the next 30 seconds. Because no spatial coordinates are given, the entire video is a link:

<video src="video.rm" region="videoregion">
  <area href="http://www.real.com" begin="0s" end="30s".../>
  <area href="http://www.realnetworks.com" begin="30s" end="60s".../>
</video>

Tip: An active link is one that the viewer can open, whether by clicking it or pressing the link's access key. The link does not open automatically, however, unless you use actuate="onLoad". For more information, see "Opening a URL Automatically".

For More Information: See "Setting Begin and End Times". The begin and end attributes use the SMIL timing values described in "Specifying Time Values".

View it now! (requirements for viewing this sample)
This sample plays a clip linked to different HTML pages at different times.

Defining Hot Spots

To create a hot spot with an <area/> tag, you use the shape attribute to define the hot spot's shape, and a coords attribute to define the hot spot's size and placement. You define the shape and coords attributes in SMIL just as you do in HTML 4.0. The following example shows two hot spots created for a clip:

<video src="video.rm" region="videoregion">
  <area href="..." shape="rect" coords="20,40,80,120" .../>
  <area href="..." shape="circle" coords="200,60,30" .../>
</video>

How you specify the coordinate values depends on what shape (rectangle, circle, or polygon) you want, as explained in the following sections. Note that in all hot spots, the coordinates are measured from the media clip's upper-left corner regardless of where you place the clip in a region.

Choosing Percentages or Pixels for Hot Spots

You can use either pixel measurements or percentages to define any hot spot. The preceding example uses pixels, whereas the following example uses percentages to place a rectangular hot spot in the center of the source clip:

<video src="video.rm" region="videoregion">
  <area href="..." shape="rect" coords="25%,25%,75%,75%"/>
</video>

When a clip is a different size than its playback region, a fit="fill", fit="meet", or fit="slice" attribute in the <region/> tag automatically resizes the clip. In these cases, a hot spot defined with percentages scales along with the clip, whereas one defined with pixels does not. Therefore, it's often better to use percentages if the region's fit attribute uses the meet, slice, or fill value. It's OK to use pixel measurements if the clip is the same size as the region, or the region's fit attribute uses the hidden or scroll value.

For More Information: For more on the fit attribute values, see "Defining How Clips Fit Regions".

Tip: A viewer may also resize a presentation manually by, for example, clicking and dragging a RealONE Player corner. In these cases, hot spots scale with clips whether you define the hot spots with pixels or percentages. You can prevent a clip from resizing, though, as explained in "Changing Resize Behavior".

Creating a Rectangular Hot Spot

Use shape="rect" to create a rectangular hot spot. You then specify four coords values in pixels or percentages to set the hot spot's size and placement, measured from the upper-left corner of the source clip in the following order:

distance of the hot spot rectangle's left edge from the clip's left edge
(left-x)

distance of the hot spot rectangle's top edge from the clip's top edge
(top-y)

distance of the hot spot rectangle's right edge from the clip's left edge
(right-x)

distance of the hot spot rectangle's bottom edge from the clip's top edge
(bottom-y)

Coordinate values are separated by commas, as shown in the following example:

<video src="video.rm" region="videoregion">
  <area href="..." shape="rect" coords="20,40,80,120"/>
</video>

The preceding example uses pixel values to define a hot spot 60 pixels wide (80 pixels minus 20 pixels) and 80 pixels high (120 pixels minus 40 pixels). It creates a hot spot like that shown in the following illustration.

Rectangular Hot Spot

Tip: Think of the first pair of values as defining the x and y coordinates of the hot spot's upper-left corner, and the second pair of values as defining the x and y coordinates of the hot spot's lower-right corner.

Defining a Circular Hot Spot

You can use shape="circle" to create a circular hot spot. Three coords values then specify in pixels or percentages the circle's center placement and radius in the following order:

distance of the hot spot circle's center from clip's left edge (center-x)

distance of the hot spot circle's center from the clip's top edge (center-y)

the hot spot circle's radius

The coordinate values are separated by commas, as shown in the following example:

<video src="video.rm" region="videoregion">
  <area href="..." shape="circle" coords="100,120,50"/>
</video>

The preceding example uses pixel values to place the circular hot spot's center 100 pixels in from the clip's left edge, and 120 pixels down from the clip's top edge. The hot spot has a radius of 50 pixels. The following figure illustrates this example.

Circular Hot Spot

Tip: The last value, which sets the circle's radius, should not be more than the smaller of the other two values. If the first two values are 40 and 20, for example, the third value should not be more than 20. Otherwise, part of the circle extends beyond the clip boundaries and is cut off.

Making a Polygonal Hot Spot

Use shape="poly" to make a polygonal hot spot with any number of sides. You might create a triangle or an octagon, for example. For every n sides of the polygon you want to create, you must specify 2n values in the coords attribute. To create a triangle, for example, you need to specify six coords values. Each pair of coordinate values indicates the placement of a corner of the polygon in this order:

distance of the polygon corner from the clip's left edge (corner-x)

distance of the polygon corner from the clip's top edge (corner-y)

The following example defines a triangular hot spot:

<video src="video.rm" region="videoregion">
  <area href="..." shape="poly" coords="40,150,120,30,200,150"/>
</video>

The following figure illustrates the preceding example. The first value pair for the coords attribute defines the triangle's lower-left corner. The coords value pairs then proceed clockwise, defining the top corner, followed by the lower- right corner.

Polygonal Hot Spot

Tip: When defining a polygon, you can start with any corner, specifying the placement of additional corners by going around the polygon either clockwise or counter-clockwise.

Tips for Defining Hot Spots

You can use whole and decimal values for percentages with the coords attribute. For example, the values "4%" and "4.5%" are both valid.

You can mix pixels and percentages in the coords attribute. For example, the attribute coords="50,50,100%,100%" places a rectangular hot spot's left and top boundaries in and down 50 pixels from the source clip's upper-left corner, respectively. But the hot spot's right and bottom boundaries extend to the source clip's right and bottom edges, respectively, no matter the source clip's size.

Values such as coords="30,30,10,10" for a rectangular hot spot are ignored, and the hot spot will not function. Here, the hot spot's left side is defined as being farther to the right than its right side. As well, the top is defined to be below the bottom.

A hot spot defined to extend beyond the source clip is cropped at the clip's edge. For example, if a rectangular hot spot uses coords="50,50,300,300" but the source clip is 200 by 200 pixels, the hot spot's effective coordinates are "50,50,200,200". For this reason, no percentage value can effectively be more than 100%.

If multiple hot spots overlap on a clip, the link for the hot spot defined first in the SMIL file is used when the viewer clicks the overlapping area.

Many programs, including shareware and freeware, can generate HTML image maps. You can use one of these programs to define the coordinates for a hot spot. Simply create an HTML image map over an image that is the same size as your clip, view the HTML source, and copy the image map coordinates into your <area/> tag.

The following table lists sample percentage coordinates that define rectangular hot spots for a source clip. Each hot spot is a quarter the size of the source clip.

Sample Percentage Coordinates for a Rectangular Hot Spot
Hot Spot Rectangle Position	Attributes
upper-left quadrant	`shape="rect" coords="0,0,50%,50%"`
upper-right quadrant	`shape="rect" coords="50%,0,100%,50%"`
lower-left quadrant	`shape="rect" coords="0,50%,50%,100%"`
lower-right quadrant	`shape="rect" coords="50%,50%,100%,100%"`
center	`shape="rect" coords="25%,25%,75%,75%"`

View it now! (requirements for viewing this sample)
Play this sample to view separate hyperlinks defined for each quadrant of the screen.

Defining Basic Hyperlink Properties

The hyperlink attributes summarized in the following table affect link properties in <a> and <area/> tags whether the link opens an HTML page or a media presentation.

Basic Hyperlink Attributes
Attribute	Value	Function	Reference
`accesskey`	`key_name`	Defines a key stroke that opens the link.	click here
`actuate`	`onLoad\|onRequest`	Opens the link automatically or on request.	click here
`alt`	`text`	Supplies alternate text.	click here
`href`	`URL`	Provides the link URL.	click here
`nohref`	(none)	Indicates no URL (`<area/>` tag only).	click here
`tabindex`	`integer`	Sets a tabbing order for links.	click here

Tip: The accesskey, alt, and tabindex attributes are defined the same in SMIL 2.0 as they are in HTML 4.0.

Specifying the Link URL

As with an HTML hyperlink, the SMIL href attribute specifies the URL to open. This should be an HTTP URL for items opened in a browser window, whether those items reside on a Web server or RealServer. SMIL files or clips opened in RealONE Player should generally have an RTSP URL if they reside on RealServer. They must have an HTTP URL if they reside on a Web server, however. See the following sections for more information:

For information on URL formats, see "Writing Clip Source URLs". Although this section discusses URLs for clip source tags such as <video/>, the basic URL format is the same for hyperlinks.

To display a link target in a Web browser, follow the instructions in "Linking to HTML Pages".

When opening a streaming media clip or SMIL file, use the additional attributes described in "Linking to Streaming Media".

Leaving Out a URL Reference for Hot Spots

The nohref attribute, which can be used only in <area/> tags, indicates that the hot spot has no URL associated with it. You can use nohref with interactive timing commands to start another clip when the hot spot is clicked, for example. The nohref attribute does not take a value.

Opening a Link on a Keystroke

The accesskey attribute defines a keyboard key that the viewer can press to open the link. The viewer presses just the defined key, and does not need to press a helper key such as Alt to open the link. You can define any number of access keys for a link. In the following example, the viewer could press the keyboard letter m to open the link:

<area href="http://www.example.com" accesskey="m" .../>

View it now! (requirements for viewing this sample)
This sample demonstrates access key hyperlinks.

Tips for Defining Access Keys

The access key value is case-sensitive, so the viewer cannot press m (lowercase "m") to open the link if you specify an uppercase "M" with accesskey="M", for example. You can specify both the lowercase and uppercase versions of the same key, though, to ensure that letter case does not matter.

Access keys can be letters or numbers, but not function keys or command keys such as Alt, Esc, or F5.

As long as the clip associated with the link is visible, the viewer can click the link as well as open it with the access key. You cannot define a link that is accessible only through an access key. However, you can create the hyperlink as a very small hot spot, such as a one-pixel rectangle.

When you make an entire source clip a link, mention the access key in a longdesc attribute in the clip source tag. See "Using a Long Description" for more information.

Your presentation should indicate which access keys the viewer can use. You can do this with RealText, which is described in Chapter 6. You can also display this information in the context window, as described in "Opening HTML Pages in the Context Window".

If the same access key is encoded into a clip to perform some function, the SMIL access key overrides the encoded key's functionality.

It is best not to use the same access key when defining multiple links that are active at the same time. If multiple, active links use the same access key, the following criteria determine which link opens when the viewer presses the access key:

Links for clips not assigned to regions (such as audio clips) override links for clips assigned to regions.

When a clip displays on top of other clips because its region has a higher z-index value, its links override the links associated with the lower clips. However, if the upper clip uses a value of 1 to 50 for rn:mediaOpacity, its associated links do not register clicks, and the links for lower clips will open.

For More Information: For more on rn:mediaOpacity, see "Adding Transparency to All Opaque Colors".

If the z-index stacking order does not determine the link precedence, the link that becomes active first overrides the other links.

If links become active at the same time, the link listed first in the SMIL file overrides the other links.

You can also define access keys to start or stop elements as described in "Defining a Keyboard Event". To avoid conflicts, do not define the same key for an event and a hyperlink.

Opening a URL Automatically

The actuate attribute has a default value of onRequest, which means the link opens when the viewer clicks the link or presses the link's access key. If you set actuate="onLoad", however, the link opens as soon as the link tag becomes active in the SMIL presentation timeline, without requiring any user input. For example, the following link opens when the video clip begins to play:

<video src="video.rm" region="videoregion">
  <area href="http://www.example.com" actuate="onLoad".../>
</video>

Tip: As described in "Creating a Timed Link", you can use a begin attribute in the <area/> tag to cause the link to become active at any point after its associated clip starts to play.

For More Information: See "Displaying a Web Page when a Presentation Ends" for an example of using actuate to open a Web page when a presentation concludes.

Displaying Alternate Link Text

A hyperlink can include an alt attribute that uses short, descriptive text as its value. It is good practice always to include an alt attribute in hyperlinks. When the viewer moves the screen pointer over the link, the alt text displays in the status line above the RealONE Player media window, indicating what the link will display. In the following example, the text "Introductory Video" is used for the alt value:

<area href="..." alt="Introductory Video" .../>

If the clip that includes the link also has an alt value, the link's alt value displays instead of the clip's. If the link has no alt value, its URL displays in place of the clip's alt value. In short, a link always overrides the clip's alt value.

For More Information: The section "Including an Alternate Clip Description" covers the alt attribute in clip source tags. See "Coded Characters" for information on including special characters in alt text.

Setting a Tab Index for Multiple Links

When multiple links appear onscreen, the viewer can press Tab to cycle between the links, then press Enter to open a link. Using the tabindex attribute, you can specify the tabbing order. This attribute, which has a default value of 0, takes a positive integer as a value. RealONE Player highlights the clip with the lowest tabindex value first. It highlights the clip with the next higher tabindex value each time the viewer presses Tab. The following is an example of two clips playing in parallel, each of which has a hyperlink:

<par>
  <img src="..." region="ad_region"...>
    <area href="..." tabindex="2" .../>
  </img>
  <video src="..." region="video_region"... >
    <area href="..." tabindex="1" .../>
  </video>
</par>

In the preceding example, the link for the video clip has the lower tabindex value, so RealONE Player highlights it first when the viewer presses Tab. RealONE Player highlights the image clip next when the viewer presses Tab again.

Note: If two or more <area/> tags have the same tabindex value, the tabbing order follows the order in which the clip source tags appear in the SMIL file. This also occurs if you leave tabindex out of all <area/> tags.

Linking to HTML Pages

The attributes summarized in the following table allow you to open HTML pages from your SMIL presentation. You can use these attributes to open a Web page while a presentation plays, for example. On Windows operating systems, Web page links open by default in browsing windows within the RealONE Player environment, though you can also open them in the viewer's default browser. On other operating systems, all HTML URLs open in the viewer's default browser.

Attributes for Opening a Link in a Web Browser
Attribute	Value	Default	Function	Reference
`external`	`true\|false`	`false`	Opens link in a browser when `true`.	click here
`height`	`pixels`	media height	Sets context window height in `<param>` tag.	click here
`rn:sendTo`	`_osdefaultbrowser\| _rpbrowser\| _rpcontextwin`	(none)	Specifies window that opens the HTML page.	click here click here
`sourceLevel`	`percentage`	`100%`	Sets audio level.	click here
`sourcePlaystate`	`pause\|play\|stop`	`pause`	Changes source state.	click here
`target`	`name`	current window	Targets window or frame.	click here
`width`	`pixels`	`330`	Sets context window width in `<param>` tag.	click here

Selecting a Browsing Window

For a SMIL hyperlink to open in a Web browser, the external attribute must be set to true. (The external attribute's default value is false, however, which opens the link in the RealONE Player media window.) The link must also use an HTTP URL that the browser can request. Minimally, a SMIL link for content played in a Web browser looks like the following example:

<area href="http://www.example.com" external="true"/>

Using external="true" is the only requirement for opening an HTML page in a Web browser. As described in "Links to HTML Pages", however, RealONE Player on Windows operating systems offers several browsing windows within the RealONE Player environment. The following table lists the attributes required to open an HTML URL in one of these windows.

Attributes for Opening an HTML Link in the RealONE Player on Windows
Attributes	Target	Reference
`external="true"`	A secondary browsing window that does not attach to the media and context windows.	click here
`external="true" rn:sendTo="_rpbrowser"`	The main RealONE browsing window, which can attach to, or detach from, the media and context windows.	click here
`external="true" rn:sendTo="_osdefaultbrowser"`	The viewer's default Web browser.	click here
`external="true" rn:sendTo="_rpcontextwin"`	The context window, which appears to the right of the media window.	click here

View it now! (requirements for viewing this sample)
This sample provides an overview of RealONE Player linking, demonstrating how to use SMIL to open HTML pages in the RealONE Player context and browsing windows.

Note the following important points about using the rn:sendTo attribute:

The rn:sendTo attribute works only in SMIL <area/> tags. It does not function with <a> tags.

The rn:sendTo attribute works only with RealONE Player on Windows operating systems. On Macintosh and Unix computers, the rn:sendTo attribute is ignored and the links open the viewer's default browser. This also occurs in any other SMIL-based media player.

Using the rn:sendTo attribute requires that you declare the following namespace in the <smil> tag:

xmlns:rn="http://features.real.com/2001/SMIL20/Extensions"

For More Information: For background on customized attributes and namespaces, see "Using Customized SMIL Attributes".

Targeting the Main Browsing Window

The RealONE Player's main browsing window can attach to, or detach from, the media and context windows. This is the recommended window for displaying Web pages along with your presentation. To target this window, declare the customized namespace in your <smil> tag as described above, and use a hyperlink that looks like the following:

<area href="http://www.example.com" external="true" rn:sendTo="_rpbrowser" .../>

Tip: To target this window from an HTML page displaying in the context window or a secondary browsing window within the RealONE Player environment, use <a href="URL" target="_rpbrowser">.

Using the Viewer's Default Browser

On Windows, Web page links open in a RealONE Player browsing window by default. Although this is preferred means for displaying these pages, you can also open these links in the viewer's default Web browser. To do this, declare the customized namespace in your <smil> tag as described above, and create a link that looks like the following:

<area href="http://www.example.com" external="true" rn:sendTo="_osdefaultbrowser" .../>

Opening HTML Pages in the Context Window

Appearing to the right of the media window in the RealONE Player on Windows operating systems, the context window can display HTML pages that supplement your SMIL presentation. It might display title and copyright information about clips as they play, for example. Using advanced SMIL timing features described in Chapter 13, as well as the hyperlinking features described in this chapter, you can open a URL in the context window at any time during the presentation.

To open an HTML page in the RealONE Player context window, add rn:sendTo="_rpcontextwin" to the <area/> link tag:

<area href="http://www.example.com/context.html" external="true" rn:sendTo="_rpcontextwin" sourcePlaystate="play"/>

Using this attribute requires that you declare the following namespace in the <smil> tag:

xmlns:rn="http://features.real.com/2001/SMIL20/Extensions"

Setting the Context Window Size

Through <param/> tags, you can extend an <area/> tag link to include sizing information for the RealONE Player context window. This requires that you turn your <area/> tag into a binary tag as described in "Binary and Unary Tags". You can then add <param/> tags to the link, as shown in the following example, to specify the context window width and height in pixels:

<area href="..." external="true" rn:sendTo="_rpcontextwin" ...>
  <rn:param name="width" value="320"/>
  <rn:param name="height" value="240"/>
</area>

View it now! (requirements for viewing this sample)
This sample automatically opens a series of HTML pages in the RealONE Player context window.

Tips for Using the Context Window

The context window is designed for small HTML pages that supplement a media presentation. To display large Web pages, open URLs in a browsing window. See "Selecting a Browsing Window".

The context window's size is fixed for the presentation's duration. The first URL that targets the context window therefore sets the window size. Sizing information in subsequent links is ignored. The "presentation duration" includes the length of time required to play the original SMIL file, as well as any subsequent, linked clips or SMIL files.

If a context window link does not specify a window size, a default width of 330 pixels is used. The default height is the SMIL presentation's height, which is typically set by the height attribute in the <root-layout/> tag.

You cannot set a context window height that is smaller than the height of your presentation. If your <root-layout/> tag creates a presentation height of 300 pixels, for example, your context window will be 300 pixels high even if you specify a shorter height, such as 200 pixels. However, you can create a context window that is taller than your presentation, such as 400 pixels. In this case, the media window is centered vertically next to the context window.

For best results, keep the context window approximately the same size as the media window (specified with the <root-layout/> tag's height and width attributes). Be careful that the combined widths of the media window and context window do not make the presentation too large to display on small computer screens.

The media window and the context window appear next to each other with no divider. If these windows are the same height, you can create a uniform background by setting the same background color values in each window. For the media window, you set this color with the backgroundColor attribute of your SMIL presentation's <root-layout/> tag.

For More Information: For more on SMIL background colors, see "Adding Background Colors".

If your context window HTML page is too large to display fully in the defined window space, the RealONE Player adds scroll bars to the context window.

Because of the generally small size of the context window, using frames in this window is not recommended.

The RealONE Player caches the contents of the context window URL (the HTML page, images, and so on) for the duration of the presentation. The cached contents are removed when a new presentation begins to play in the media window, however.

To keep the presentation playing as links open in the context window, use sourcePlaystate="play" and actuate="onLoad" in the <area/> tag in your SMIL file.

A standard hypertext link in a browsing window cannot open a URL in the context window because the context window requires sizing information.

Targeting a Frame or Named Window

When you use SMIL to open an HTML page, the SMIL target attribute works much the same as the HTML target attribute. When a hyperlink targets a RealONE Player secondary browsing window (using just external="true") or the default browser (using rn:sendTo="_osdefaultbrowser"), the target attribute can do one of the following:

open a new, named browsing window

target an existing, named window

select a named frame within an existing window

When a link specifies the main browsing window (with rn:sendTo="_rpbrowser") or the context window (using rn:sendTo="_rpcontextwin"), the target attribute can select an existing frame. The following example shows how to open a link in the frame named rightpane within the main browsing window:

<area href="http://www.example.com" external="true" 
rn:sendTo="_rpbrowser" target="rightpane".../>

Tip: The HTML values _new and _top are not supported in the RealONE Player environment. Use actual window names instead.

Controlling the Media Playback State

By default, the RealONE Player presentation pauses while the browser opens the link. The viewer can resume the presentation by clicking the RealONE Player Play button. RealONE Player typically needs to rebuffer the presentation briefly before continuing playback. You can also make RealONE Player stop the presentation completely, or continue playing when the link opens, with a stop or play value, respectively, for the sourcePlaystate attribute:

<area href="http://www.example.com" external="true" sourcePlaystate="play".../>

The preceding link keeps the presentation playing as the browser opens the Web page. In this case, RealONE Player may need to rebuffer the presentation if browser operation uses too much bandwidth. To help prevent this, your streaming presentation should use less bandwidth than that listed in the table "Maximum Streaming Rates".

Tips for Opening HTML Page Links

RealONE Player passes the entire URL to the browser, which requests the resource. You can therefore include in the SMIL href attribute any additional parameters you want the browser to receive. A common use of this is linking to an anchor in an HTML page:

<area href="http://www.example.com/story.html#part2" external="true".../>

If the RealONE Player media window is operating in full-screen mode, it resumes normal-size operation when a link opens in a browsing window. For more on full-screen mode, see "Setting a Presentation's Starting Mode".

If you use sourcePlaystate="play" to keep the SMIL presentation playing while the viewer's default Web browser opens the link, you cannot prevent the browser from obscuring RealONE Player. Whether RealONE Player remains on top of other applications as it plays is entirely under the viewer's control.

When targeting modem users and using sourcePlaystate="play", leave a few Kbps of bandwidth available to download HTML pages, depending on the size of the HTML pages that will display. To minimize bandwidth required by the browser, link to Web pages that do not contain large graphics.

See "Adjusting Audio Volumes in Linked Presentations" for information on using the sourceLevel attribute to change the RealONE Player volume when the Web page opens.

Linking to Streaming Media

When you link to another streaming media presentation, whether a SMIL file or a single clip, you can open the link URL in the existing RealONE Player media window, or pop up a new media window. The following table summarizes the attributes that you use to link to a streaming media presentation that opens in a RealONE Player media window.

Attributes for Opening a Link in the RealONE Player Media Window
Attribute	Value	Default	Function	Reference
`href="command: openwindow()"`	`(name,` `URL)`	(none)	Opens a media window from Flash or RealText.	click here
`destinationLevel`	`percentage`	`100%`	Sets audio level of target.	click here
`destinationPlaystate`	`pause\|play`	`play`	Sets play state of target.	click here
`show`	`new\|replace`	`replace`	Opens link in a new or the current window.	click here
`sourceLevel`	`percentage`	`100%`	Sets audio level of source.	click here
`sourcePlaystate`	`pause\|play\|stop`	`pause\|play`	Sets play state of source depending on `show.`	click here
`target`	`ID`	(none)	Links to a specific window or region.	click here

Replacing the Source Presentation

A link that does not include the external="true" attribute (which opens the link in a Web browser) replaces the current presentation in the RealONE Player media window. The source presentation is only paused, however, so the viewer can return to it by clicking RealONE Player's Play>Previous Clip command. Hence, an RTSP link like the following:

<area href="rtsp://realserver.example.com/video2.rm"/>

is equivalent to the following link, in which the show, destinationPlaystate, and sourcePlaystate attributes are explicitly set to their default values:

<area href="rtsp://realserver.example.com/video2.rm" show="replace" 
destinationPlaystate="play" sourcePlaystate="pause"/>

In some cases, you may want to set destinationPlaystate="pause" to keep the new presentation from playing until the viewer clicks the RealONE Player Play button. It's not necessary ever to include the sourcePlaystate attribute when replacing a presentation in RealONE Player. Its value of pause is always used with show="replace", so specifying play or stop for sourcePlaystate has no effect.

The following table summarizes the possible hyperlink attribute values for replacing a presentation in the existing RealONE Player window. The first option listed in the table is the default.

Hyperlink Attributes for Replacing a Presentation in RealONE Player
Source	Destination	Attributes
pause	play	`show="replace" sourcePlaystate="pause" destinationPlaystate="play"`
pause	pause	`show="replace" sourcePlaystate="pause" destinationPlaystate="pause"`
stop	play or pause	Not allowed. The source state is always `pause`.

View it now! (requirements for viewing this sample)
In this sample, click the playing clip to replace it with a new clip in the same media window.

Opening a New Media Window with SMIL

You can use either the show or the target attribute to open a new media window. The basic means for doing this is to set show="new" in the link tag. You can open any number of new windows this way. Using show="new" does not create a named window that you can target with another hyperlink, however:

<area href="rtsp://realserver.example.com/video2.rm" show="new".../>

By default, the current window containing the link and the new window with the target media are both set to play. Therefore, the preceding example is equivalent to the following example:

<area href="rtsp://realserver.example.com/video2.rm" show="new" 
sourcePlaystate="play" destinationPlaystate="play".../>

Depending on how you want linking to operate, you can change the setting for sourcePlaystate to pause or stop. You can also set destinationPlaystate to pause. A common scenario is to pause the source presentation when the viewer opens the new window. The viewer can restart the source presentation by clicking the RealONE Player Play button. The following example illustrates this markup:

<area href="rtsp://realserver.example.com/video2.rm" show="new" 
sourcePlaystate="pause" destinationPlaystate="play"/>

View it now! (requirements for viewing this sample)
In these samples, you can click the playing clip to open a new clip in a new window and pause the first clip, or keep the first clip playing.

Targeting a Specific Window or Region

Whereas show="new" opens a link in a new, unnamed media window, target="name" creates a named window that you can select through subsequent hyperlinks. It also lets you open linked media in a specific SMIL region of an existing window, rather than in a new window. The show="new" attribute does not include these two capabilities.

The target attribute takes a user-defined name as its value. As with show="new", you can set sourcePlaystate to play, pause, or stop. You can also set destinationPlaystate to play or pause. The following example defines a link that opens in a SMIL region or a new window named play3:

<area href="rtsp://realserver.example.com/video2.rm" target="play3" 
sourcePlaystate="pause" destinationPlaystate="play".../>

When RealONE Player opens the link in preceding example, it displays the linked media in the following way:

RealONE Player displays the linked media in the existing SMIL region named play3. That is, it looks for a SMIL region in any open window that has the play3 ID:

<region id="play3" .../>

If no SMIL region named play3 exists, RealONE Player displays the linked media in the window named play3. That is, it looks for a window created through a previous hyperlink that used a target="play3" attribute.

If no window named play3 exists, RealONE Player creates a new window with the play3 name, displaying the linked media in that window.

View it now! (requirements for viewing this sample)
These two samples each display two images linked to two separate videos. The first sample uses the target attribute to open each video in the same media window. The second sample uses the target attribute to open each video in a different media window.

Tips for Opening Streaming Media in New Windows

If you use both target and show in a link, the show attribute is ignored.

You can use target exclusively to define your streaming media hyperlinks:

To replace the current presentation, include neither target nor show. Replacing the presentation is the default action, so you do not need to include these attributes.

Use target="name" to open a link in a SMIL region, or in a new or existing window.

The following table summarizes the attribute values for opening streaming media in a new RealONE Player window, using either show="new" or target="name".

Hyperlink Attributes for Opening a Presentation in a New Window
Source	Destination	Attributes
play	play	`show="new"\|target="name" sourcePlaystate="play" destinationPlaystate="play"`
play	pause	`show="new"\|target="name" sourcePlaystate="play" destinationPlaystate="pause"`
pause	play	`show="new"\|target="name" sourcePlaystate="pause" destinationPlaystate="play"`
pause	pause	`show="new"\|target="name" sourcePlaystate="pause" destinationPlaystate="pause"`
stop	play	`show="new"\|target="name" sourcePlaystate="stop" destinationPlaystate="play"`
stop	pause	`show="new"\|target="name" sourcePlaystate="stop" destinationPlaystate="pause"`

To avoid possible conflicts, use unique names for all SMIL regions and all windows that you open with target="name".

Use short, single-word names with target="name".

Do not use target="_new".

When you open linked media in a new or existing window, the window resizes to the media's defined size.

When you open linked media in an existing SMIL region, the window does not resize, and the region's fit attribute determines how the linked media appears if the region and media are different sizes. See "Defining How Clips Fit Regions" for more on fit.

Linking to a SMIL Fragment

A SMIL file hyperlink can target a specific place in another SMIL file, or another part of itself. To create a link of this type, you simply include the appropriate SMIL ID in the href attribute after the URL and a pound sign (#), just as if linking to an HTML fragment:

<area href="rtsp://realserver.example.com/movie2.smil#text_and_video" .../>

The preceding link would open the designated SMIL file, and start playback at the clip or group that included the text_and_video ID:

<par id="text_and_video">
  <video src="video2.rm" region="newsregion"/>
  <textstream src="text.rt" region="textregion"/>
</par>

Note that the target SMIL file defines two regions, newsregion and textregion. When RealONE Player receives the new SMIL file, it creates those regions as specified in the new SMIL file's header.

Linking to a Clip with a Timeline Offset

You can use the <area> tag's time coordinates to create a timeline offset in a linked clip. Suppose that you want to link a video to another video at 30 seconds into the second video's timeline. In the source SMIL file, you define a link from the first video to a SMIL file that contains the second video. In the second SMIL file, the video's <area> tag defines the timeline offset using SMIL timing parameters.

Here is a sample of the link in the first SMIL file:

<video src="video.rm" region="videoregion">
  <area href="rtsp://realserver.example.com/newmedia.smil#vid2"/> 
</video>

The following is the linked video clip in the second SMIL file, newmedia.smil:

<video src="video2.rm" region="newsregion">
  <area id="vid2" begin="30s"/>
</video>

For More Information: "Specifying Time Values" describes the SMIL timing values.

Tips for Linking to SMIL Fragments

To link to a fragment within the same SMIL file, use only href="#ID".

You can link to any clip, <par>, <seq>, <excl>, or <switch> group by defining an id attribute for the clip or group. Do not link to an element in a SMIL file header, however, or to an element within a <switch> group.

You cannot link to a clip in a <par> group and exclude the other clips in that group. All clips in the group will play in their designated regions.

If additional clips follow the target clip in the SMIL file, those clips play as well. If you want to link to a single clip but the SMIL file that contains the clip includes other clips as well, link to the desired clip directly. Or create a new SMIL file that lists only the single target clip.

Adjusting Audio Volumes in Linked Presentations

Two attributes in a hyperlink tag, sourceLevel and destinationLevel, can change the volume of the source clip and the destination clip when a link opens. If the source clip does not stop or pause when the link opens, for example, you can use sourceLevel to turn down the source clip's volume and boost the destination clip's volume:

<a href="..." sourceLevel="35%" destinationLevel="125%" ...>...</a>

The audio level attributes always use a percentage value. The default value of 100% plays the audio at its recorded volume. A value of 50%, for example, plays the audio at half its normal volume, whereas a value of 200% plays the audio at twice its normal volume.

Note that the sourceLevel and destinationLevel attributes control only the relative volume of the audio stream sent to the speakers. They do not change the general sound level setting on the viewer's computer, which remains entirely under the viewer's control. All sound level adjustments are subject to limitations in the computer hardware.

Tip: When displaying a Web page, as described in "Linking to HTML Pages", you can use sourceLevel to turn down or boost RealONE Player's volume as appropriate. The destinationLevel attribute will not affect any audio elements, such as an embedded WAV file played by the browser, though.

Opening a New Media Window Through RealText or Flash

A RealText or a Flash clip, playing alone or as part of a SMIL presentation, can define a hyperlink that opens another clip in a new media window. This link uses a proprietary parameter, command:openwindow(name,URL), as the value of the href attribute. This is not a SMIL feature, and you write this parameter directly into the RealText markup, or encode it in the Flash Player file with the Get URL command.

The hypertext reference for this type of link has the following structure:

href="command:openwindow(name, URL, [zoomlevel=double|full|normal])"

The command:openwindow parameter requires two arguments, name and URL. The zoomlevel argument is optional. You can separate arguments with a comma, but this is not required. A space may precede or follow a comma. If an argument contains characters such as commas or parentheses, enclose it in single quotation marks.

View it now! (requirements for viewing this sample)
Display this scrolling RealText clip to view several hyperlinking possibilities, including opening new media windows in normal, double-size, and full-screen modes.

Window Names

The required name argument, which supplies a predefined or user-defined name for the new media window, is the first parameter listed for command:openwindow. The following table describes the parameter values.

name Parameter
Value	Action
`_new` or `_blank`	Opens a new media window each time the viewer clicks the link. Each subsequent link named `_new` or `_blank` opens a new window as well.
`_self` or `_current`	Opens the URL in the current media window.
`name`	Creates a new media window with the user-defined name. A subsequent `openwindow` command using the same name opens the given URL in the same window.

Target URL

Following the name argument, the required URL argument gives the fully qualified URL to the clip or SMIL presentation to play in the new window. You must include the protocol (rtsp://, http://, chttp://, or file://) in the URL. Relative URLs do not work.

Zoom Level

The optional zoomlevel=double|full|normal argument sets the new media window to open in double-size or full-screen mode respectively. The normal value is the default. If the operating system does not support full-screen mode, normal mode is used instead.

Tip: You can also open the initial presentation in double or full-screen mode by using a Ram file. For details on doing this, as well as guidelines for using double and full-screen modes, see "Setting a Presentation's Starting Mode".

Note: Earlier versions of RealPlayer support additional parameters, such as autosize and ontopwhileplaying, that RealONE Player ignores. RealONE Player is therefore backwards-compatible with presentations developed for earlier versions of RealPlayer. These additional parameters are obsolete, however.

Examples

The following examples show how to target various windows with the command:openwindow hyperlink syntax inRealText and Flash clips.

Targeting the Same Window with Multiple Links

The following RealText link opens a URL in a new media window named feature:

<a href="command:openwindow(feature, rtsp://realserver.example.com/comedy.rm">Comedy Hour</a>

In Flash, the Get URL command looks like this:

command:openwindow(feature, rtsp://realserver.example.com/comedy.rm)

When first clicked, this link creates a media window named feature. If another link also targets the feature window, clicking that link starts the new URL in the feature window. Clicking the link in the following example starts an animal program in the window running the comedy program:

<a href="command:openwindow(feature, rtsp://realserver.example.com/animals.rm)">Sharks!</a>

The Flash Get URL version looks like this:

command:openwindow(feature, rtsp://realserver.example.com/animals.rm)

Opening Separate Windows

Each link opens a separate window if the window names are different, or you use the predefined name _new or _blank. The following RealText links open separate windows:

<a href="command:openwindow(_new, rtsp://realserver.example.com/comedy.rm)">Comedy Hour</a>

<a href="command:openwindow(_blank, rtsp://realserver.example.com/animals.rm,)">Sharks!</a>

In Flash, the Get URL commands look like these:

command:openwindow(_new, rtsp://realserver.example.com/comedy.rm)

command:openwindow(_blank, rtsp://realserver.example.com/animals.rm)

Launching Clips in the Current Window

Use either _current or _self to open the URL in the current window. The following example is for RealText:

<a href="command:openwindow(_self,  rtsp://realserver.example.com/comedy.rm)">Comedy Hour</a>

The next RealText link plays the clip at double its encoded size:

<a href="command:openwindow(_current,  rtsp://realserver.example.com/animals.rm, zoomlevel=double)">Sharks!</a>

The following are the same commands issued through Get URL in Flash:

command:openwindow(_self, rtsp://realserver.example.com/comedy.rm)

command:openwindow(_current, rtsp://realserver.example.com/animals.rm, zoomlevel=double)

Tips for Opening Media Windows with RealText or Flash

Unlike HTML, RealSystem markup tags are case-sensitive. Be sure to use lowercase for command:openwindow and its parameters.

When the viewer clicks a command:openwindow link, the new clip automatically plays, and the presentation that contains the link stops. You cannot change this playback state to pause the original presentation, for example.

RealText and Flash clips can also open links in a Web browser. For basic information on hypertext links in RealText, see "Creating Links and Issuing Commands".

Because command:openwindow is not a SMIL command, it does not offer all the SMIL linking features, such as activating automatically or on a keystroke.

If a SMIL hyperlink overlaps a command:openwindow link, the SMIL link takes precedence.

Hyperlink Examples

The following examples show different applications of hyperlinking. Choose Sample Files from the pull-down menu to view all the playable sample files included in this chapter.

Displaying a Web Page when a Presentation Ends

Using the <area/> tag, you can easily display Web pages as a clip plays. The following example uses advanced SMIL timing commands to open a Web page when the video clip ends:

<video src="video1.rm" id="main" fill="freeze">
  <area href="http://www.example.com" external="true" rn:sendTo="_rpbrowser" 
actuate="onLoad" begin="main.end"/> 
</video>

In this example, the hyperlink uses actuate="onLoad" to open the URL automatically when the link becomes active. The begin="main.end" attribute opens the link when the clip with id="main" ends. This advanced timing feature is described in "Defining an Element Start or Stop Event".

The rn:sendTo attribute sends the URL to the RealONE Player main browsing window, as described in "Targeting the Main Browsing Window". You can leave this attribute out of the <area/> tag to open the URL in a secondary browsing window. Including the rn:sendTo attribute requires that you declare the following namespace in the <smil> tag:

xmlns:rn="http://features.real.com/2001/SMIL20/Extensions"

View it now! (requirements for viewing this sample)
In this sample, an HTML page automatically opens when a clip finishes playing.

Opening Web Pages During a Presentation

The following markup uses a series of <area/> tags with different begin times to open four Web pages at different points as an audio clip plays. The actuate="onLoad" attribute causes each link to open its Web page as soon as the link becomes active. Because the links do not use rn:sendTo="_rpbrowser" as in the preceding example, the pages open in secondary browsing windows. The attribute sourcePlaystate="play" keeps the clip playing as each page opens:

<audio src="audio1.rm">
  <area href="http://www.example.com/page1.htm" begin="30s" external="true" 
    actuate="onLoad" sourcePlaystate="play"/>
  <area href="http://www.example.com/page2.htm" begin="1min" external="true" 
    actuate="onLoad" sourcePlaystate="play"/>
  <area href="http://www.example.com/page3.htm" begin="2min" external="true" 
    actuate="onLoad" sourcePlaystate="play"/>
  <area href="http://www.example.com/page4.htm" begin="3min" external="true" 
    actuate="onLoad" sourcePlaystate="play"/>
</audio>

View it now! (requirements for viewing this sample)
Play this sample to watch HTML pages open automatically as a clip plays.

Tip: Opening a Web page requires bandwidth. If your streaming media uses all of the viewer's available bandwidth, opening a Web page may cause the presentation to stall. When opening Web pages during a presentation, be sure that your streaming media uses less bandwidth than the maximum listed in the table "Maximum Streaming Rates".