LOGIN

Welcome Developers!

Ready to start creating interactive content for use in TouchCasts? Interactivity within TouchCasts revolves around the concept of a Video App, or vApp for short. So, what exactly is a vApp?

vApps

TouchCast vApps are actually just interactive web pages added on top of video. Usually, videos exist in their own box on web pages. vApps reverse this: they are little boxes of the web inside a video. When you add a vApp to a TouchCast video, you are really adding a viewport in which a web page is displayed. And because these web pages are html5, you can do the same things in vApps that you are used to doing on web pages... like play a game, buy things and everything else the web offers.

As TouchCast vApps are web content at their core, familiarity with HTML, JavaScript, and CSS is assumed.

For the time being, the vApps you build are for use by only you in the Cast-side of TouchCast (where you create the videos), BUT all of your viewers on the Touch-side (including the website and on embedded web players) can interact with your vApp. This means that right now you can create a vApp that communicates to and from your server for all of your viewers to interact with -- just like building any webpage.

Soon, you'll be able to share the vApps you've built with other creators to use in their TouchCasts. TouchCast will also soon provide the option to automatically render a vApp 'live' on playback without needing the viewer to interact to get a live (updated) vApp feed. Make sure to stay tuned to this page for updates.

Your First vApp

Now that you're up to speed, see our tutorials and examples on how to create your own vApp.

Go to TouchCast Tutorials

Tutorials

The tutorials and examples below will show you how to create your own custom vApps. For the purposes of these tutorials 'TouchCast' refers to the TouchCast app on the iPad.

  • Tutorial 1: Hello World!

    The first vApp we will make is a 'Hello World!' vApp. It displays simple text and has very limited interactivity.

  • Tutorial 2: Pick a Color

    In this tutorial we will show you how to use TouchCast's simple command syntax, along with some JavaScript and PHP to make a vApp with a setup screen.

  • Tutorial 3: Weather vApp

    Complete code and assets for a simple local weather vApp.

Tutorial 1: Hello World

The first vApp to try to create is a 'Hello World!' vApp. It displays simple text and has very limited interactivity.

Here is the code for the 'Hello World!' vApp:

	
	<!DOCTYPE html>
	<html onclick="hello()">
		<head> 
			<title>Hello World</title>
		</head>
		<body>
			<h1 id="howdy">Hello</h1>
		</body>
			<script type="text/javascript">
				function hello(){
					if(document.getElementById("howdy").innerHTML == "Hello"){
						document.getElementById("howdy").innerHTML = "World";
					}else{
						document.getElementById("howdy").innerHTML = "Hello";
					}
				}
			</script>
			<style type="text/css">
				body{
					background-color:#888888;
				}
				h1{
					font-family:arial;
					font-size:72pt;
					color:#FFFFFF;
				}
			</style>
	</html>
	

That's it! We're keeping it simple to start. Just an html element and a little JavaScript to make it interactive. Copy this code, and save it as 'hello.html'. Use an FTP client to upload it wherever you like. You must host your own vApps.

Now if you open hello.html in a web browser, as you can see it is just a web page with title text that changes when a user clicks on it. If we want it to be a vApp, we just have to add it to video with TouchCast:

1. Open up TouchCast on an iPad

2. Select 'Create New TouchCast' from the Cast side under the New TouchCast tab

3. On the 'vApps' tab, press the "ADD A VAPP" button

4. From here, you can see icons for all the vApps you have available to add to a TouchCast, as well as the 'Developer' icon. That's you! Tap it.

5. The next screen is the vApp setup screen. Enter the URL of your vApp (http://www.yourdomain.com/path/to/hello.html). And enter 'Hello World!' in the name field. Leave the default icon for now, and tap "add vApp". The Hello World! vApp is now available to add to a TouchCast.

6. If you tap the 'Hello world!' vApp icon, you get taken to its setup screen. Since this vApp only has one page, and doesn't get any data input from the user, the only thing to do here is position and scale the page, as required. Then try putting it in a TouchCast! Maybe one about how easy it was to make your first vApp?

In the next tutorial, you'll learn how to make a vApp with a setup screen.

Go to Tutorial 2

Tutorial 2: Pick a Color

If you take a look at the vApps that come with TouchCast, most of them consist of two separate pages. When you add a vApp there is an edit page -- where the user enters data; and then a live page -- which displays content based on the data entered. The Twitter vApp, for instance, asks for search terms on the edit page and then displays tweets related to those terms on the live page.

On the vApp setup screen -- after you select a vApp but before you add it to a TouchCast -- the user can switch between the edit and live pages once there is enough data on the edit page. The live page is the vApp as it is to appear in the actual TouchCast.

In this tutorial we will show you how to use TouchCast's simple command syntax, along with a smattering of JavaScript and a tiny bit of PHP to fully integrate vApps with this functionality. You can download all the code for this tutorial here

The Color Picker vApp's edit page gives the user a choice between red, green, or blue. Once the user makes a choice, the live page simply displays the chosen color. The files for this vApp are:

  • setup.html the edit page for the vApp
  • live.php the live page for the vApp
  • style.css a short stylesheet

setup.html

1. The viewport meta tag:

<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>

Because we are going to set the width and height of the vApp later in TouchCast, and we don’t have any reason for the user to need to zoom in and out of the vApp, we set the scale and turn off user scaling. This will help our vApp look more like a regular UI menu, as opposed to a web page. Most of the vApps that come with TouchCast use this meta tag to constrain interaction.

2. The Form:

The vApp uses an HTML form with radio buttons for the user to choose a color. Notice that the form does not have an action attribute or a submit button. Instead, we are going to send the form data to the next page using a TouchCast widget action.


 <form id ="colors" name="colors">
 <!-- Just a simple form with three radio buttons. Note that there is no sumbit button or action attribute.-->
 <input type="radio" name="color" value="red" onclick="ready(‘red’)">RED<br/>
 <input type="radio" name="color" value="green" onclick="ready(‘green’)">GREEN<br/>
 <input type="radio" name="color" value="blue" onclick="ready(‘blue’)">BLUE<br/>
 </form>
 

3. Introducing Widget Actions:

Each of the radio buttons calls the JS function ready(), giving it the corresponding color name as an argument. The ready() function looks like this:


 function ready(c){
	chosenColor = c;
	//We send commands from the vApp to TouchCast using location.href.
	//This command tells TouchCast that the user has input data, and we should show the "Preview" button.
	location.href = 'widget-action:cmd=widget-is-ready-to-go-live&value=1';
 }
 

First, it just sets the variable chosenColor to whichever color was picked. The next line of code probably looks a little unfamiliar. This is where we send our first widget action command to TouchCast:

location.href = 'widget-action:cmd=widget-is-ready-to-go-live&value=1';

Widget actions are special instructions that your vApp can send to TouchCast by changing the location.href attribute in JavaScript. When a vApp uses javascript to change location, TouchCast interrupts the default action (changing the web page) and instead looks for a widget action command in the assigned string. The structure for widget actions looks like this:

widget-action:cmd=<command>&<other-arguments>

TouchCast widget actions require a command name, and then a number of other arguments, depending on what the command is doing.

The “widget-is-ready-to-go-live” command tells TouchCast to turn the “preview” button in the vApp setup screen either on or off. Assigning 1 to it’s “value” argument means we want the preview button to show up. We are ready to see the widget in live mode. The Twitter vApp, for example, sends this command to TouchCast as soon as the user inputs terms into the search field. for Color Picker, we activate the preview button as soon as the user has picked a color.

More information on commands, as well as a complete list and description of each one, can be found in our documentation.

4. Switching between the edit page and the live page.

Now that we have told TouchCast that we are ready for the user to preview the vApp’s live page, we need to define what happens when the user presses the preview button. We do that with this function:


 function WidgetIsAboutToGoLive(){
	//TouchCast calls this function when the TouchCast user presses the "Preview" button.
	//Change this to reflect your URL:
	var theURL = "http://www.YOURDOMAIN.com/PATH/TO/colorpicker/live.php?color="+chosenColor;
	//This function must return a string representing a JSON object to be parsed by TouchCast.
	//The JSON string contains the URL of the live page, and tells TouchCast to load that page.
	return '{"url":"'+theURL+'","reload-page":"1"}';
 }
 

Make sure to change the URL that gets assigned to the theURL variable to the actual absolute URL of the live page, while still appending our JS variable chosenColor as a php argument.

TouchCast automatically calls the WidgetIsAboutToGoLive() function when the user presses the preview button. TouchCast expects this function to return a string, formatted as a JSON object. This object requires two values, one for "url", which is the location of the live page (including our $_GET variable for the color), and one for "reload-page", which we set to either one or zero, depending on whether we want to load the live page immediately or not.

So we use a widget action to tell TouchCast to show the preview, and then use WidgetIsAboutToGoLive() to listen for that button press and react accordingly.

That’s it for the edit page. now it’s time to check out what the the live page does with the color we sent it.

The live, page, live.php, has an even simpler structure than the edit page. There’s just a wrapper div without the form in it, and a single JS function. In the opening tag of the wrapper div, we use PHP $_GET to assign it the proper background color.

It also has this JavaScript function:


  function WidgetIsAboutToSwitchToEditing(){
	 location.href = 'widget-action:cmd=widget-is-ready-to-go-live&value=0';
	 var theURL = “http://www.YOURDOMAIN.com/PATH/TO/colorpicker/setup.html”;
	 return '{"url":"'+theURL+'", "reload-page": "1"}';
  }
 

WidgetIsAboutToSwitchToEditing() is the mirror opposite of WidgetIsAboutToGoLive(), wich we saw on the edit page. This is the function that TouchCast calls automatically when the user presses the “edit” button once we are already in preview mode. First, we turn off the preview/edit button with the same widget action, so the user must select a color before coming back to live mode.

Then we once again return a JSON formatted string to tell TouchCast to where to go. In this case, we are going back to setup.html.

You can learn more about these functions and additional values you can send via JSON in our documentation.

5. The advanced developer settings panel:

Now that our code is ready, it is time to add our vApp to TouchCast. Create a new TouchCast, go to add vApps, and press the dev icon, just as you did in the first tutorial. Enter the URL to setup.html where you’ve hosted it and enter the name “Color Picker”. This time though, press the “advanced” button, to open the advanced developer vApp settings panel:

On this panel, you can exert a little more control over the appearance of your vApps. For Color Picker, set Width and Height each to 400. These settings are the size of the vApp viewport in pixels on the iPad screen. “Show Shadow” just turns the drop shadow behind the vApp on or off in TouchCast videos. “Open in Edit Mode” is the most important setting for this tutorial. Turn it ON. This means that when you load the vApp on the setup screen, TouchCast will expect it to have a edit page and a live page, and enable switching between the two. If this setting is OFF, TouchCast will expect only a single page.

Now you can pick a color, and add it to a TouchCast!

Go to Tutorial 3

Tutorial 3: Local Weather

Now that you know how vApps are created, and how they communicate with TouchCast, you are well on your way to making vApps on our own, and we can't wait to see what you come up with.

To get you started on your way, we are providing complete code and assets for a simple but useful local weather vApp. This vApp asks a user to input their ZIP code and preferred temperature units on the edit screen, and then shows them their location with the current local temperature and an icon representing the weather conditions.

The vApp uses the jQuery library for scripting, and uses PHP to parse XML and pass data between the edit page and the live page. Weather data is provided by the Yahoo! Weather RSS Feed.

Once you download the weather vApp, you must upload the "weatherVapp" directory and its contents to your own server using an FTP client. You can also see this vApp in action by selecting "Developer" on the "Add a vApp" screen, and inputting this url: http://www.touchcast.com/examples/weathervapp.

Important: On line 66 of index.php and on line 92 of results.php are absolute URLs that the vApp is sending to TouchCast. These must be changed to reflect the actual absolute path to the files once they are uploaded to your server.

The Weather vApp Code Files:

Index.php serves as the edit page for this vApp. It's just a styled text input and two buttons for users to choose their favored temperature units, Celsius or Fahrenheit. When a user inputs a five digit number, it enables the TouchCast "Preview" button. If the user input is invalid, it shows a prompt asking for a five-digit zip code.

results.php is where we actually get the weather data. This file uses the user input from index.php to request XML weather data from Yahoo! and populate the page. If the 5 digit sequence we got from page 1 is not recognized by Yahoo! as a valid US zip code, this page shows a prompt asking the user to return to the edit page and double check  their input. The large icon displaying weather conditions is displayed by assigning a unique class to an html element based on a weather code from Yahoo!.

style.css is a straightforward stylesheet. It is important to note the section near the end of this file though, where classes are defined for each of the Yahoo! weather codes, and given a corresponding icon.

The assets folder contains all of the weather condition icons as PNGs, as well as an icon for the vApp itself. If you move this icon onto the iPad where this vApp will be used, you can use it as the vApps icon on the "Add a vApp" screen.

You can download the WeatherVapp files here.

Challenges:

See if you can improve the Weather vApp by adding one or all of the following:

  • Ask the user to access their location data, and use that data to automatically serve up the weather.

  • Include text descriptions of the weather conditions, in addition to the icons.

  • Add a way to change location on the live screen, so that viewers of a TouchCast with the Weather vApp in it can point it to their own location.

  • Using the create-web-element Widget Action, add an additional vApp to the screen showing a web site with information contextual to the weather shown. An online store for fancy umbrellas when it's raining, a site with barbeque recipes on a hot summer day, etc.

Documentation

Overview:

vApps communicate with TouchCast by sending Widget Actions from JavaScript. These widget actions are specially formatted strings specifying a specific command, then assigning values to that command's parameters.

They look like this:

"widget-action:cmd=<command-name>& <a-parameter>=<a-value>& <another-parameter>=<another-value>"

Widget Actions are used to inform TouchCast about the state of a vApp, or to tell TouchCast to change the vApp in certain ways. Actions are sent by using JavaScript to change your vApps location.href property. When you assign a string containing a widget action to location.href, TouchCast interrupts the default action (changing the location of the page), and instead parses and executes the widget action.

To tell TouchCast that your vApp is ready to enter live mode, for example, you use this line of JavaScript once the user enters the appropriate data in preparation mode:

location.href="widget-action:cmd=widget-is-ready-to-go-live&value=1";

All Commands:

create-web-element

Creates a new web element in the TouchCast. The new web element may either be a regular web page, or a new vApp.

Command: create-web-element

Parameters:

Name Type Description
widget number Optional. If 0 the new web element will be created as regular web page, otherwise a new vApp will be created. If not specified regular web page will be created.
preparation-required number Optional. This parameter indicates if the vApp needs to be created in normal or edit mode. This parameter is ignored if widget parameter is 0. If parameter is not specified then widget will be created in regular mode.
x integer Optional. x coordinate of the new element's top left corner in pixels
y integer Optional. y coordinate of the new element's top left corner in pixels
width integer Optional. width of the new element
height integer Optional. width of the new element
url integer Unencoded absolute URL of the new web element.

N.B. When sending a URL as a Widget Action parameter, the URL MUST be the final parameter, and must not be encoded.

Example JavaScript Call:

location.href="widget-action:cmd=create-web-element&x=600&y=600&width=200&height=400&widget=0&url=http://www.mydomain.com/path/to/document.php";

preload-resources

The preload-resources command is used to preload online resources for live mode. It is optional but recommended.

Command: preload-resources

Parameters:

Name Type Description
value string A string representing a JSON object. See the JS function "WidgetIsAboutToGoLive()" for structure.

request-to-go-live

The request-to-go-live command is used to switch to live mode from edit mode to live mode without the user pressing the "preview" button. When this command is sent, TouchCast will call the WidgetIsAboutToGoLive() JavaScript function.

Command: request-to-go-live

Parameters:

This command has no additional parameters.

Example JavaScript Call:

location.href="widget-action:cmd=request-to-go-live";

set-position

location.href="widget-action:cmd=set-position&x=int&y=int&width=int&height=int";

Use this command to change the position AND the size of a vApp. All of the parameters for set-position are optional, but at least one parameter must be specified.

Parameters:

Name Type Description
x Integer Optional. x coordinate of top left corner.
y Integer Optional. y coordinate of top left corner
width Integer Optional. y coordinate of top left cornerOptional. New width of the vApp in pixels
height Integer Optional. New height of the vApp in pixels

Example Call in JavaScript:

location.href="widget-action:cmd=set-position&x=600&y=600&width=200&height=400";

update-thumbnail

The update-thumbnail command updates the thumbnail for this vApp in the TouchCast vApp tray to reflect the vApps current appearance.

Command: update-thumbnail

Parameters:

This command has no additional parameters.

Example JavaScript Call:

location.href="widget-action:cmd=update-thumbnail";

JavaScript Functions

TouchCast uses two JavaScript functions to communicate with vApps switching between edit and live mode: WidgetIsAboutToGoLive() and WidgetIsAboutToSwitchToEditing(). These functions are called automatically when the user presses the preview/edit button on the vApp setup screen. You can also use the request-to-go-live command in your code, to ask TouchCast to call the WidgetIsAboutToGoLive() function. Both functions must return a string formatted as a JSON object, specifying the location of the page to navigate to, and whether or not TouchCast should load the new page at the time of the function call.

WidgetIsAboutToGoLive()

This function is called by TouchCast when the user presses the "Preview" button on the vApp setup screen while the vApp is on its edit page. It can also be called from inside the vApp code by using the request-to-go-live command. The JSON-formatted string it returns should look like this:

' {"url":"http://www.yourdomain.com/path/to/edit/page.php" ,"reload-page":"1"}'

The above JSON string tells TouchCast where the live page for the vApp is located (in this case, it's a file called "page.php" somewhere on your domain), and whether or not that page should be loaded now.

WidgetIsAboutToSwitchToEditing()

This function is called by TouchCast when the user presses the "Edit" button on the vApp setup screen while the vApp is on its live page. It should return the same type of JSON formatted string as WidgetIsAboutToGoLive() but in this case "url" should be set to the location of the edit page.

Additional Parameters:

The JSON string returned by these functions may contain the following keys: