previous next

Chapter 1: Embedded Presentations

The easiest way to create an Embedded RealPlayer in a Web page is to include the RealPlayer Netscape plug-in or ActiveX control in your HTML application. An embedded presentation created in this manner typically includes an image window and one or more standard RealPlayer controls, such as the Stop button, the volume slider, and so on.

For More Information: For more information about creating an embedded RealSystem presentation, see the RealSystem Production Guide available at http://service.real.com/help/library/index.html.

Playback of the embedded presentation is controlled using the methods described in Appendix A "Methods"and user interaction with the embedded controls is managed using the callback methods defined in Appendix B "Callback Methods". This chapter describes how to include the Netscape plug-in or ActiveX control in your HTML application and provides the basic syntax for calling methods and callback methods from JavaScript or VBScript.

Choosing the Netscape Plug-in or ActiveX Control

To provide Web page playback, RealPlayer includes a plug-in for browsers that support the Netscape plug-in architecture:

It also has an ActiveX control that provides playback capabilities within these products:

Because they both have the same capabilities, you can use either the plug-in or the ActiveX control depending on which products you need to support.

Using <EMBED> Tags for the Netscape Plug-in

To use RealPlayer's Netscape plug-in, you add <EMBED> tags to your Web page HTML. A typical <EMBED> tag has three necessary parameters (SRC, WIDTH, and HEIGHT), that are used to identify your presentation and the dimensions of the playback area. Many other parameters are available, but they are considered to be optional.

For More Information: For a list of all <EMBED> parameters, see Appendix C "Tag Parameters".

The syntax for a typical <EMBED> tag looks like the following: 

<EMBED SRC="my_content.rpm" WIDTH=300 HEIGHT=134 optional parameter=value>

This example tag creates a playback area 300 pixels wide by 134 pixels high within your Web page, and displays the contents of my_content.rpm within the playback area.

Tip: The SRC parameter may be omitted, when the content mime TYPE parameter is specified similar to:
<EMBED ..., TYPE="audio/x-pn-realaudio-plugin", ...>,
however, doing so may produce unexpected results. Therefore, it is strongly recommended that you always include the SRC parameter and at least supply the name of an empty presentation file.

All parameters typically have the form PARAMETER=value. The parameter names can be any case, although this manual depicts them in uppercase. Except for file names, that must typically be lowercase, parameter values are not case- sensitive. Unless they are URLs, parameter values do not need to be inside quotation marks.

Using <OBJECT> Tags for the ActiveX Control

To use RealPlayer's ActiveX control, you add <OBJECT> tags to your Web page HTML. The tag definition must include the RealPlayer classID value: 

CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA"

and specify the width and height dimensions of the playback area. When you intend to use scripting to reference the control, you must also specify a value for the ID parameter, such as ID=RVOCX.

The syntax for a typical <OBJECT> tag looks like the following: 

<OBJECT ID=RVOCX CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA"
WIDTH=300 HEIGHT=134>
...parameters...
</OBJECT>

This example tag creates a playback area 300 pixels wide by 134 pixels high within your Web page. Between <OBJECT> and </OBJECT> you can define any number of additional parameters using this syntax: 

<PARAM NAME="name" VALUE="value">

PARAM, NAME, and VALUE markers can be any case, although this manual depicts them in uppercase. Except for file names, that must typically be lowercase, parameter values are not case-sensitive. Always enclose parameter values in double quotation marks.

For More Information: For a list of all <OBJECT> parameters, see Appendix A "Methods".

Using Scripting to Access Embedded RealPlayer Controls

Using a scripting language such as JavaScript or VBScript, you can access RealPlayer functions such as the stop, play, and volume controls, without using RealPlayer's standard interface components. For example, you can use your own graphic image for a Stop button, capture user interaction with the image, and stop the clip playback.

For More Information: For detailed descriptions about using scripting languages with the RealPlayer controls, see "Chapter 2: Using Methods and Callbacks".

Using RealPlayer Methods through JavaScript

To extend RealPlayer's Netscape plug-in functionality with JavaScript, you first embed the source file in an HTML page with the <EMBED> tag, for example: 

<EMBED NAME=javademo
    SRC="demo.rpm"
    WIDTH=220 HEIGHT=180
    CONSOLE=one
    CONTROLS=ImageWindow
    BACKGROUNDCOLOR=white
    CENTER=true
    >

In the <EMBED> tag, the NAME parameter provides the name used by the JavaScript functions. For JavaScript to function with RealPlayer, the <EMBED> tag must not contain the parameter NOJAVA=true. That parameter prevents the browser's Java Virtual Machine from starting up in Netscape version 4.x.

Warning! In Netscape version 4.x, when the parameter NOJAVA is set to true, scripting is unavailable. Setting the NOJAVA parameter in Netscape 6.0 has no effect.

You can then use JavaScript to issue RealPlayer commands to control the embedded presentation. The following example shows a simple form that provides a Play, Pause, and Stop button for the embedded presentation. Click here to see this presentation. 

<FORM>
<INPUT TYPE="button" VALUE="Play" onClick="document.javademo.DoPlay()">
<INPUT TYPE="button" VALUE="Pause" onClick="document.javademo.DoPause()">
<INPUT TYPE="button" VALUE="Stop" onClick="document.javademo.DoStop()">
</FORM>

To refer to an embedded instance with JavaScript, you include a NAME parameter in the <EMBED> tag: 

<EMBED NAME=vid SRC="..." WIDTH=300 HEIGHT=134>

You can then refer to the instance through a JavaScript command such as this: 

<Input Type="button" Value="play" onClick="document.vid.DoPlay()">

If you include more than one instance of a single type of embedded control or a variety of different embedded controls in your HTML document, give each instance a unique NAME. This ensures that you can use JavaScript to manage each embedded control individually, if necessary.

For More Information: "Appendix A: Methods" lists the RealPlayer methods.

Using RealPlayer Methods through VBScript

To extend RealPlayer's ActiveX functionality on Internet Explorer, you first embed the source file in an HTML page with the <OBJECT> tag: 

<OBJECT ID=RVOCX CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA" WIDTH=220 HEIGHT=180>
<PARAM NAME="SRC" VALUE="rtsp://realserver.company.com/media/animate.swf">
<PARAM NAME="CONSOLE" VALUE="one">
<PARAM NAME="CONTROLS" VALUE="ImageWindow">
<PARAM NAME="BACKGROUNDCOLOR" VALUE="white">
<PARAM NAME="CENTER" VALUE="true">
</OBJECT>

In the <OBJECT> tag, the ID parameter identifies the embedded clip for reference by VBScript parameters.

You can then use VBScript, or any programming language supported by the browser, to issue RealPlayer commands to control the embedded presentation. The following example shows a simple form that provides a Play, Pause, and Stop button for the embedded presentation. Click here to see this presentation (this presentation requires Internet Explorer). 

<FORM>
<input TYPE="button" VALUE="Play" NAME="doplay">
  <script LANGUAGE="VBScript" FOR="doplay" EVENT="onClick">
  RVOCX.DoPlay
  </script>
<input TYPE="button" VALUE="Pause" NAME="pause">
  <script LANGUAGE="VBScript" FOR="pause" EVENT="onClick">
  RVOCX.DoPause
  </script>
<input TYPE="button" VALUE="Stop" NAME="stop">
  <script LANGUAGE="VBScript" FOR="stop" EVENT="onClick">
  RVOCX.DoStop
  </script>
</FORM>

For More Information: "Appendix A: Methods", lists the RealPlayer methods.

Handling Callback Events From RealPlayer

RealPlayer reports the events that occur within the application to the Netscape plug-in or ActiveX control using a set of predefined API methods known as callbacks. You can use these callback methods on your Web page to intercept and interpret RealPlayer events, including tracking mouse movement, capturing user interactions with the application controls, or monitoring the progress of your presentation.

For More Information: "Appendix B: Callback Methods", lists the RealPlayer callback events.

Receiving Callbacks Through JavaScript

RealPlayer communicates the events that occur in a Netscape plug-in via a set of internal callback routines. However, depending on the platform and version of Netscape you are targeting, the Embedded RealPlayer supports the handling of these events using different mechanisms.

If you are developing a plug-in for Netscape version 6.0 running on Windows, UNIX, or Macintosh, the mechanism consists of including a new <EMBED> tag in your JavaScript and specifying which events to receive. When targeting older versions of Netscape, LiveConnect should continue to be used to receive the callbacks.

The following sections describe the different event handling mechanisms in more detail.

Handling Events in Netscape Version 6.0

Netscape® version 6.0 does not support callback event handling in the same manner as previous versions. For this reason, Embedded RealPlayer build number 6.0.8.1024 and later introduces a new mechanism for event handling involving the use of JavaScript and callback methods in a Netscape plug-in. The procedure is available for development using JavaScript and in the following configurations:

Supported Configurations for the New Event Handling Mechanism
Web Browser Version Windows Macintosh UNIX
Netscape 6.0 or later yes yes no*
Internet Explorer all versions no yes no*

*Will be available in a post-version 8 release of the Unix RealPlayer.

Note: The new event handling mechanism is not available for development in C++ or for use by an ActiveX control.

To use the new mechanism in your JavaScript plug-in, add the SCRIPTCALLBACKS parameter to your <EMBED> tag defintion. Identify the events to handle by providing a comma-separated list of callback methods or by specifying `All' to capture all events. For example: 

        <EMBED SCRIPTCALLBACKS=OnPresentationOpened,
                                                  OnPositionChange,OnPresentationClosed>

- or -

        <EMBED SCRIPTCALLBACKS=All>

You don't need to worry about the backward compatibility of the new tag because all versions of Embedded RealPlayer ignore unrecognized tags. However, you may detect the RealPlayer version and if earlier than build 6.0.8.1024, inform the user that their RealPlayer version does not support the new event handling features.

Handling Events in Netscape Version 4.x

When developing for Netscape versions 4.x, you must use LiveConnect to receive the callbacks sent by the RealPlayer. LiveConnect is described at http://home.netscape.com/eng/mozilla/3.0/handbook/plugins/.

To receive the RealPlayer callbacks, you must first embed a Java <APPLET> tag in your HTML code. This tag should include a reference to the RealPlayer event interface class file, for example (CODE="RMObserver.class"), and have the MAYSCRIPT attribute set. In addition you must also provide a NAME attribute (such as NAME="YourNameHere") that will be used in JavaScript to identify the instance of the applet. The following example shows how to use the <APPLET> tag: 

<APPLET CODE="RMObserver.class" WIDTH=1 HEIGHT=1 NAME="YourNameHere" MAYSCRIPT>
</APPLET>

You can then use the name provided in the <APPLET> tag to receive callbacks. For example, you could use the following line to determine when a clip has closed: 

if(document.YourNameHere.OnClipClosed())

On Linux, the RMObserver.class file is found in the raplayer.zip file in the /RealPlayer9 directory. On Windows, this class file is found in the rpcl3260.zip file in the \Program Files\Netscape\Communicator\Program\Plugins directory.

To provide backward compatibility, the RealPlayer installation includes the following classes for event notification:

Receiving Callbacks Through VBScript

To receive callbacks through VBScript, you use the <OBJECT> tag ID, shown here set to RVOCX: 

<OBJECT ID=RVOCX HEIGHT=256 WIDTH=256>
  CLASSID="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA"
<PARAM NAME="controls" VALUE="all">
<PARAM NAME="SRC" VALUE="http://www.company.com/sample.rpm">
</OBJECT>

You then use a <SCRIPT> tag to receive a VBScript callback. The following example shows a callback for OnShowStatus: 

<P>
Status Text:
<input type="text" name="statusText" size=100><br>
</P>
<SCRIPT language="VBS">
Sub RVOCX_OnShowStatus(byVal text)
  statusText.Value=text
End Sub
</SCRIPT>

Sample Files

Sample applications that show how to use the methods and events described in this guide are provided in the Html\Samples directory. The Javascript samples demonstrate how to program the RealPlayer Plug-in for Netscape Navigator or Internet Explorer. These samples describe most of the methods and events included in this guide and and provide coding examples for JavaScript and HTML. The VBScript samples demonstrate how to implement the RealPlayer ActiveX Control for Internet Explorer. These samples include ActiveX compatible methods and events and provide programming examples for VBScript and HTML.

Warning! The ActiveX Control is not supported on Netscape Navigator.

RealNetworks, Inc. ©2001 RealNetworks, Inc. All rights reserved.
For more information, visit RealNetworks
Click here if the Table of Contents frame is not visible at the left side of your screen.
previous next