home | about us | contact | site map  

sofTV.net Trigger Descriptions

Overview
Trigger Sources
Referencing Regions
Trigger Commands

sofTV_ChangeSrc sofTV_ChangeTxt sofTV_Hide sofTV_Show sofTV_Move sofTV_Resize sofTV_Restore sofTV_Play sofTV_Stop sofTV_Seek sofTV_Rewind sofTV_Forward

sofTV_PageFlip sofTV_SchStart sofTV_SchStop sofTV_SchGoto sofTV_ChangeSlide sofTV_NextSlide sofTV_PrevSlide sofTV_SetSlideThumbnail sofTV_SetSlide sofTV_Script

Custom Triggers

Every web page built with sofTV.Author can handle sofTV.net trigger commands. Trigger Commands greatly enhance the dynamic nature of the web page.

For example, triggers can be used to:

• Show or Hide a sofTV region
• Change the content in a video, text, or graphic region on screen
• Seek to a specified time in a video clip
• Seek to a specified anchor tag, or piece of text in a text region
• Open a new browser window
• Cause a sofTV Region to move around on screen, or resize
• Run a user-provided JavaScript function

Some real-life examples of what you can accomplish are:

• Show a player's statistics, and picture on the web page whenever he scores,
• Show product information in sync with the video content. Allow users to purchase the clothing actors are wearing in the video,
• Create buttons on screen that allow you to jump to specific stories within an HTML file with many news stories,
• Allow users to enter search text in a box on screen, then search for the text in an HTML file,
• Pop up an advertisement in a banner ad in sync with an ad in the video stream,
• Show PowerPoint slides in sync with the video of the CEO doing an annual report,
• Allow a user to select from a number of video clips on a web page,
• Open a browser with a purchase form when a user elects to make a purchase,

Top

Trigger commands are generally embedded within the video stream, but can actually come from a number of sources.

• Microsoft or Real streaming video - Commands can be embedded in the video stream using sofTV.TriggerMaker & sofTV.LiveShow or sofTV.LiveSync, in the case of live video, or using sofTV.Playlist, in the case of pre-recorded video.
  
  
• sofTV.Author Graphics regions - on click, on mouse-enter, on mouse-exit - commands can be attached to a graphic element in a sofTV web page using the "User Commands" tab of the Graphic Region Properties. You can specify one or more commands to be executed on the web page when a graphic is clicked, for instance.
• Javascript calls attached to any web page item - It is very easy to call sofTV trigger commands from within JavaScript on the web page. If you have some simple programming ability, you can attach trigger commands to any item on the web page, or even create sofTV triggers from within Flash.
  
  
• Trigger Commands embedded in the text displayed in a sofTV.net text region - sofTV.Author allows you to create text regions on a web page, and control how content is displayed in these regions. You can embed sofTV commands within the text displayed in a text region, allowing you to have the text area control other regions of the web page. For example, if you had a text item that contained news stories, you could have a graphic area change to match the current news story.
  
  
• Time of Day Schedules on a web page - Web pages created using sofTV.Author can run Time-Of-Day schedules. The schedule file is an XML file that can define any number of schedules. Each schedule item can fire off one or more sofTV trigger commands at the specified time. For more information about scheduling, check out these notes.

To help you create triggers with the appropriate syntax, you can use our TriggerBuilder web page. This web page allows you to specify all the parameters for a sofTV trigger, then generate the HTML or JavaScript code required to embed the trigger in a web page. Of course, this is done automatically when using sofTV.Author or sofTV.Playlist.

Top

Region refers to the name given to an area on the page created by sofTV.Author. For example, the default name for a text region is "Text". To refer to that region in a script command you would supply the value of "Text" to the region parameter.

When refering to a region in a script command you may also use what is called a wild card. The wild card is denoted by the "*" character. When a wild card is used the script command will attempt to find all regions whose names match that wild card.

For example:

Region Value	Affected Regions
*	Every region on the page.
Graphic*	Every region whose name started with "Graphic". This includes "Graphic1", "GraphicBox" and "Graphic".
*Text	Every region that ended with "Text". This includes "VideoText" and "Text".
A*X	Every region that beings with "A" and ends with "X". This includes "ApeX" and "AX".

Top

Top

sofTV_ChangeSrc

Description,  Parameters,  Examples

Description

Changes the document that is to be displayed in a region. A small restriction for video is that you may only change to a document the player is capable of displaying. It can also change the contents of a frame by name. If the frame doesn't exist a new window is opened displaying the document in the URL parameter.

Parameters

Examples:

Example 1: Changing an image region Region: Graphic URL: Highlight.jpg JavaScript: sendMessage( null, new sofTV_net_message( "sofTV_ChangeSrc", "Region", "Graphic", "URL", "Highlight.jpg") ); This would cause the image region named "Graphic" to display the image "Highlight.jpg".

Example 2: Changing a text region Region: News URL: Stories.htm This would cause the text region named "News" to display the HTML document "Stories.htm".

Example 3: Changing a frame Frame: BottomFeeder URL: HelloWorld.html This would cause the frame named "BottomFeeder" to display the HTML document "HelloWorld.html".

Top

Table of contents

sofTV_ChangeTxt

Description,  Parameters,  Examples

Description

Changes the text displayed in a text region.

Parameters

Examples

Table of contents

sofTV_Hide

Description,  Parameters,  Examples

Description

Causes a visible region to become invisible.

Parameters

Top

Examples

Table of contents

sofTV_Show

Description,  Parameters,  Examples

Description

Causes a hidden region to become visible.

Parameters

Examples

Table of contents

sofTV_Move

Description,  Parameters,  Examples

Description

Moves a region from one position on the page to another. This command can also have a time parameter that indicates the region is to move linearly to its new position in that many milliseconds. This can be used to create the effect of animation when moving a region.

NOTE: Move currently does not work for Windows Media Player video regions.

Top

Parameters

Examples

Table of contents

sofTV_Resize

Description,  Parameters,  Examples

Description

Changes the dimensions of a region in pixels. The time parameter can be used to create animation much like the time parameter in sofTV_Move.

NOTE: Resize does not work in Netscape. The layer does get resized but it does not re-paginate itself.

Top

Parameters

Examples

Table of contents

sofTV_Restore

Description,  Parameters,  Examples

Description

Sets a region to its original size, position and visibility as it was when the page was loaded.

Top

Parameters

Examples

Table of contents

sofTV_Play

Description,  Parameters,  Examples

Description

Starts a video playing in a video region.

Parameters

Examples

Table of contents

sofTV_Stop

Description,  Parameters,  Examples

Description

Parameters

Top

Examples

Table of contents

sofTV_Seek

Description,  Parameters,  Examples

Description

Seeks to a new position in the video. The video must be able to seek for this command to work. For example, a video streaming over HTTP will not be able to seek.

The "Seconds", "Text" and "Anchor" parameters are all mutually exclusive.

Parameters

Examples

Table of contents

sofTV_Rewind

Description,  Parameters,  Examples

Description

Changes to the previous video in a play list. A video must be playing some form of play list such as SMIL or ASX file.

Parameters

Top

Examples

Table of contents

sofTV_Forward

Description,  Parameters,  Examples

Description

Changes to the next video in a play list. A video must be playing some form of play list such as SMIL or ASX file.

Parameters

Examples

Table of contents

sofTV_PageFlip

Description,  Parameters,  Examples

Description

Page flip can be used to change the document displayed in the current browser, frame or new window.
Target refers to the target frame or window to change. If it is omitted, the current document is changed. If the target does not exist as a frame or window, a new window will be created with the feature if the parameter is specified. Sending multiple page flip commands with the same target will only cause the open window to change its document, it won't change any of the features including width, height, top and left.

Parameters

Top

Examples

Table of contents

sofTV_SchStart

Description,  Parameters,  Examples

Description

Starts playing a registered schedule.

Parameters

Examples

Table of contents

sofTV_SchStop

Description,  Parameters,  Examples

Description

Stops a schedule from sending messages.

Parameters

Examples

Top

Table of contents

sofTV_SchGoto

Description,  Parameters,  Examples

Description

Changes the time position of a schedule that³s playing.

Parameters

Examples

Table of contents

sofTV_ChangeSlide

Description,  Parameters,  Examples

Description

Changes the current slide. This cause the frame around the slide thumbnail to become visible and the CurrentSlide region to be set to the image of the slide specified. Sending a slide index that does not exist will cause the slide show to display the first slide.

Parameters

Examples

Table of contents

sofTV_NextSlide

Description

Description

Changes to the next slide in the slide show.

Table of contents

Top

sofTV_PrevSlide

Description

Description

Changes to the previous slide in the slide show.

Table of contents

sofTV_SetSlideThumbnail

Description,  Parameters,  Examples

Description

Sets the base name of the frame region. For example, a base name of "Frame" would include "Frame1", "Frame2" and so on.

Parameters

Examples

Table of contents

sofTV_SetSlide

Description,  Parameters,  Examples

Description

Sets the name of the image region to display the current slide in.

Parameters

Examples

Example 1: Setting the slide image region in a slide show Region: CurrentSlide This will cause all change slides to display in the region named CurrentSlide.

Top

Table of contents

sofTV_Script

Description,  Parameters,  Examples

Description

Executes JavaScript when the command is processed.

Parameters

Examples

Table of contents

Custom Triggers
(Creating your own triggers)

The simplest way to create to create custom triggers is to use the sofTV_Script command. This built-in command sofTV command allows you to call any JavaScript function.

If you need more control, you can create your own sofTV trigger commands. These could be called by web page functions, but can't be embedded within a video stream. 

The following information is intended for expert developers. 

Basically, triggers are names associated with functions. When a trigger is fired on a page a call to "sendMessage" is made. "sendMessage" then takes the global message listener and tells it to handle that message. The global listener takes the name of the message (like "sofTV_ChangeSrc") and looks for it in a table of functions. If a function is associated with that message, it is called with the message parameters. Creating custom messages is simply a matter of creating that function and registering it with the global listener.

A handling function must take two parameters, an origin object and an array of parameters. The origin object is not currently in use, so don³t worry about it. The array of parameters however is important. Messages have parameter lists. A parameter list is a parameter name and value pair. This name and value pair is implemented using an array as a map. For example:

 var arMyParameterList = new Array();
 arMyParameterList[ "NAME" ] = "Dr.Who";
 arMyParameterList[ "AGE" ] = 100;

This example creates a parameter list with two parameters, name and age. The following example shows how to extract these parameters:

 // Given arMyParameterList from above
 alert( "Hello:" + arMyParameterList[ "NAME" ] );
 alert( "You are:" + arMyParameterList[ "AGE" ] );

These parameter lists work the same way the ones in sofTV.net do. For example, in sofTV_ChangeSrc, the parameter URL is extracted from the parameter array like this:

 var sURL = arArgs[ "URL" ];

Any parameters you extract should be tested to see if they are null. If a parameter is null then it wasn³t specified when the message was sent.

Once you have extracted your parameters, you can write the code to do something. For example, the following message handler multiplies two numbers and displays the result with a provided label:

 function custom_Multiply( objOrigin, arArgs )
 {
  // Extract parameters
  var x = arArgs[ "X" ];
  var y = arArgs[ "Y" ];
  var sLabel = arArgs[ "LABEL" ];
 
  // Validate parameters
  if( x != null && y != null && sLabel != null )
  {
   // Calculate and display result
   var product = x * y;
   alert( sLabel + product );
  }
 }

Once you³ve created a message handler, you need to register it with the listener. Calling the function, "registerMessageHandler" does this. From the above example, the call would be:

registerMessageHandler("custom_Multiply", custom_Multiply );

The first parameter is the name to associate with your function and the second is the function itself. You should call this method somewhere in the global scope. Be sure to call it after the include file for "Messaging.js". So, now if a video has a "custom_Multiply" trigger it will call your message handler.

Top