XIMPEL - Documentation

Getting started - playlist / config

Step 1: Create a playlist

First we need to create a playlist that we will be using. Lets make a playlist that plays three youtube videos in a row for 10 seconds each.

Open a text editor and paste the following code into it. Save it as playlist.xml (you could name it anything but in our example we use playlist.xml).

playlist.xml

						<ximpel>
						    <playlist>
						        <subject>
						            <media>
						                <youtube id="AI0RTvlm0hw" startTime="300" duration="10" />
						                <youtube id="4_UVnsG7COM" startTime="300" duration="10" />
						                <youtube id="J_x-dIA7oeE" startTime="300" duration="10" />
						            </media>
						        </subject>
						    </playlist>
						</ximpel>

Step 2: Create a config

We also need a config file in which we can change some configuration settings. We use a config where we indicate that our XIMPEL player should show controls that are displayed as an overlay over the video.

Open a text editor and paste the following code into it. Save it as config.xml (you could name it anything but in our example we use config.xml).

config.xml

						<ximpel>
							<config>
								<enableControls>true</enableControls>
								<controlsDisplayMethod>overlay</controlsDisplayMethod>
							</config>
						</ximpel>

Copy the code above and paste it into a text editor. Save it as config.xml in the same directory as your playlist.xml.

Step 3: include XIMPEL into an HTML page

Now we are ready to create an HTML page that includes the XIMPEL engine. When you download XIMPEL and unarchive it you will get a ximpel folder containing:

ximpel/ximpel.css: the XIMPEL stylesheet
ximpel/ximpel.js: the XIMPEL javascript engine
ximpel/images/*: a folder containing some images used by XIMPEL.

Place this ximpel directory in the same place as where you put your playlist.xml and config.xml file earlier.

Now lets create a basic HTML page that includes jQuery, ximpel.css and ximpel.js. Copy the code below in a text editor and store it as ximpel_example.htm in the same directory as where you stored the playlist.xml, config.xml and ximpel directory.

ximpel_example.htm

						<!DOCTYPE html>
						<html>
							<head>
								<link rel="stylesheet" href="ximpel/ximpel.css" type="text/css" />
								<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
								<script type="text/javascript" src="ximpel/ximpel.js"></script>
							</head>
							<body>

							</body> 
						</html>

Right now we have defined a XIMPEL presentation in the playlist.xml and config.xml and we have made the XIMPEL engine available by importing jquery, ximpel.css and ximpel.js. We have everything ready to start playing our playlist. We just need to tell XIMPEL to load and play our presentation.

Step 4: tell XIMPEL to run the presentation.

We need to tell XIMPEL to start running our playlist by adding a snippet of javascript that runs when the document is fully loaded. In that snippet we create a new XimpelApp object to which we pass a unique ID, the playlist.xml file and the config.xml file.

Lets add the snippet of javascript to the HTML file we created in step 3. Copy the snippet from the code below and paste it into your HTML file.

ximpel_example.htm

					<!DOCTYPE html>
					<html>
						<head>
							<link rel="stylesheet" href="ximpel/ximpel.css" type="text/css" />
							<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
							<script type="text/javascript" src="ximpel/ximpel.js"></script>

							<!-- NEW SNIPPET -->
							<script type="text/javascript">
								$( document ).ready(function(){
									var myXimpelApp = new ximpel.XimpelApp(
										'someappid',
										'playlist.xml', 
										'config.xml'
									);
									myXimpelApp.load();
								});
							</script>
							<!-- NEW SNIPPET -->
						</head>
						<body>

						</body> 
					</html>

By creating the XimpelApp like we did above, XIMPEL will start playing the presentation automatically. It will create a new HTML element and use that element to show our presentation in.

Note: There are some configuration options that you can use when creating a XimpelApp object. These options are explained here.

Step 5: open the HTML page with the presentation.

There it is, our XIMPEL presentation is ready to run. There is still one problem though. Due to a number of reasons, it is not always possible to run the presentation locally without a webserver. these reasons include:

Browsers often have security restrictions that cause AJAX requests for files to be blocked when running from the local filesystem even if the ajax requests are also directed to the local file system.
The youtube API does not work locally in (some versions of) Internet Explorer due to security restrictions

So in order to test our XIMPEL HTML page we need to serve the files from a webserver (either a local webserver or a hosted webserver). A few suggestions:

Install apache on your local machine (or WAMP which is probably more simple).
Get access to a webhost to host your files somewhere online.
Install an extension for chrome called "Web Server for Chrome". This is probably the easiest method. When you run the extension you can choose a local folder that is the document-root of your chrome-webserver.

Once you have access to a webserver you copy the following items to your webserver all in the same directory:

The playlist.xml file
The config.xml file
The ximpel_example.htm HTML page
The ximpel directory (which contains ximpel.js, ximpel.css and an images folder

Then open ximpel_example.htm by going to: <your-webserver-url>/ximpel_example.htm. For example if you run a local webserver then it will be something like: http://localhost/ximpel_example.htm

If your webserver is working you will see that XIMPEL starts playing our presentation.