WebEngine SDK

Introduction

Media Center 15 introduced the ability to browse, control, or play from a library on a phone or other Internet connected device using WebPlay and WebRemote. WebRemote has been replaced by WebGizmo from Media Center 17.

WebPlay, WebRemote and WebGizmo are fully customizable. This includes both the appearance and the functionality.

Location

The files used to customize WebPlay, WebRemote and WebGizmo are located at:

• WebPlay: [Media Center Install Path]\Data\Library Server\WebPlay\[Name]
• WebRemote: [Media Center Install Path]\Data\Library Server\WebRemote\[Name]
• WebGizmo: [Media Center Install Path]\Data\Library Server\Gizmo\[Name]

The default appearances are called 'Default'. They offer a good starting point. You can make a copy of the 'Default' folder and name it anything you like.

You will then be able to select your new customization in Options > Media Network inside the program.

Web Template Language

The HTML files in a customization are sent through a rendering engine that can fill in values based on the current view, perform translation, and do other helpful tasks.

Tokens

Any text between square braces will be considered a 'token'. Tokens are replaced by their corresponding values.

Tokens have the formatting:

• [Name]
• [Name(Index)]
• [Class.Name(Index]]
• [Class(Index).Name]
• [Class(Index).Name(Index)]

A list of available tokens is below.

Translation

Any text in curly braces {} will be translated using the current translation.

Loops

Loops provide a way to use far less HTML code for redundant sections. Showing an example is probably the easiest way to see how they work:

<!-- begin: loop(z, 0, min(4, [LibraryItemCount] - 1)) -->
<li>[LibraryItem([z]).Name]</li>
<!-- end: loop -->

You can use any loop variable you like. Above, we use the letter z.

You can use basic math and other tokens in the to and from range for the loop. Above, you can see it uses the function min(...), the token [LibraryItemCount], and subtraction.

It is important to remember that the loop is inclusive, so looping from 0 to 4 will do 5 steps: 0, 1, 2, 3, 4.

Inside a loop, you can put HTML inside a special block if you want it to be skipped on the first or last iteration of the loop. This is useful for separators between items. You can accomplish the same thing using conditionals, so this syntax is only a convenience feature.

<!-- begin: loop_no_first -->
... code that is not included on the first iteration of the loop ...
<!-- end: loop_no_first -->

<!-- begin: loop_no_last -->
... code that is not included on the last iteration of the loop ...
<!-- end: loop_no_last -->

Conditionals (if statements)

If statements can be coded (with math) like:

<!-- begin: if([z] < [ZoneCount]) -->
... code that gets included if condition is met ...
<!-- else -->
... code that gets included if condition is not met (using the else clause is optional) ...
<!-- end: if -->

Main WebEngine mechanisms

The WebEngine is acting as a standard webserver but it's managing the page library.html with a specific behavior.

The library.html file is allowing to browse the media collection from a root element referenced by the LibraryLocation query parameter.

If the LibraryLocation is referencing a node containing media files, the libraryfiles.html is used instead of library.html (the main URL doesn't change but the template is different).

Web Template Tokens

Below is a list of available web template tokens. The letters x and y are used as index variables for demonstrations purposes. They should be filled by your loop variable (or similar) when building actual pages.

Count tokens

• [ZoneCount]: the number of zones
• [LibraryItemCount]: the number of items in a library view
• [PlayingNowFileCount]: the number of files in Playing Now (in the active zone)
• [LibraryFilesCount]: the number of items in a library files view

Tokens with no class (name only)

• [LibraryLocation]: name of the current location when browsing
• [ProgramFullName]: full name of the program (i.e. J. River Media Center)
• [ProgramName]: name of the program (i.e. Media Center)
• [ProgramVersion]: version of the program (i.e. 15.0.75)
• [ActiveZoneName]: name of the current playback zone
• [PlaybackStatus]: status of playback in the current zone (i.e. Playing, Stopped, etc.)
• [LibraryServerLink]: URL to root of server
• [Token]: access token used for authorization (helpful to append to URLs to avoid the need for authentication)
• [ShowPlayingNow] : whether the playing now button should be shown on this screen
• [ShowSearch] : whether the search button should be shown on this screen

Class: Zone(index)

The index is the index (0-based) of the zone.

• [Zone(x).Name]: name of the zone
• [Zone(x).ID]: Identifier of the zone

Class: Mode

• [Mode.Display] : the current zone label Playing to ...
• [Mode.IsRemote) : whether it's playing in a zone
• [Mode.IsPlay] : whether it's local playing (on the remote)

Class: ModeZone

The current selected zone which is stored stored as a cookie named 'mode'

• [ModeZone.ID] : the id
• [ModeZone.Name] : the name

Class: CurrentLibraryItem

• [CurrentLibraryItem.ShowPlay] : is this item playable
• [CurrentLibraryItem.UseThumbnails] : is true for image and video and false for audio. It's there because we didn't want to repeat the same thumbnail next to every file for audio views.

Class: LibraryItem(index)

When browsing, the individual items that make up a library view. For example, they could be an artist, album, keyword, etc.

• [LibraryItem(x).Name]: name of item
• [LibraryItem(x).ImageLink]: URL to a thumbnail (JPEG) for the item
• [LibraryItem(x).IntoLink]: URL to navigate into this item
• [LibraryItem(x).ShowPlay]: whether it makes sense to show play commands for this item (0 or 1)
• [LibraryItem(x).PlayLink]: URL to play the library item on the server machine
• [LibraryItem(x).AddLink]: URL to add the library item to Playing Now on the server machine
• [LibraryItem(x).ShuffleLink]: URL to play (with shuffle) the library item on the server machine
• [LibraryItem(x).M3ULink]: URL that will provide an M3U playlist of the files in the library item
• [LibraryItem(x).ASXLink]: URL that will provide an ASX playlist of the files in the library item
• [LibraryItem(x).MPLLink]: URL that will provide an MPL playlist of the files in the library item
• [LibraryItem(x).WebPlayPlayLink]: URL that will play the library item files on the client
• [LibraryItem(x).WebPlayShuffleLink]: URL that will play (with shuffle) the library item files on the client

Class: PlayingFile

The playing file. Uses same variable names as 'LibraryFile', so see below for variable names.

Class: PlayingNowFile(index)

The file at the specified index in Playing Now (zero based). Uses same variable names as 'LibraryFile', so see below for variable names.

Class: LibraryFile(index)

The file at the specified index in the current LibraryItem (zero based).

• [LibraryFile(x).FileKey]: key of the file in the database (immutable, and safe to use between sessions)
• [LibraryFile(x).ImageLink]: URL to a thumbnail (JPEG) of the file
• [LibraryFile(x).Artist]: artist of the file
• [LibraryFile(x).Name]: name of the file
• [LibraryFile(x).PlayLink]: URL to play the file on the server
• [LibraryFile(x).AddLink]: URL to add the file to Playing Now on the server
• [LibraryFile(x).FileLink]: URL to provide the file to the client (on Android, provides MPL playlist pointing to file)

Class: Pagination

Tools and variables for splitting large lists into multiple pages.

• [Pagination.StartIndex]: the first index of the current page (can be used in loops)
• [Pagination.FinishIndex]: the last index of the current page (can be used in loops)
• [Pagination.ShowControls(item count)]: whether a page should show pagination controls for the given item count
• [Pagination.Controls(item count)]: links for the list of pages given an item count ( i.e. Previous 1 2 3 Next )

Functionality

The functionality to play, pause, etc. is provided by the Web Service Interface, called MCWS. Please see the documentation for the web service to learn about the possible functionality.

The default skins use AJAX to do some processing. For example, this allows the 'Playing Now' screen to update periodically using information from the server without requiring page reloads.