Skinners guide

NOTE: This page is a work in progress and is not yet complete.

Skinning support has been introduced in WebMediaPortal 0.5.

Getting started

WebMediaPortal is built using the Model-View-Controller (MVC) pattern. This means that the functional code is completely separated from the user interface, making it easy to change the interface without too much knowledge about the inner workings. Generally, each page is build from two views, one for the generic layout used on each page, and one for the content of each specific page.

These views are each one file. We use the Razor view engine, so these files are cshtml files and follow the Razor syntax. Basically, that means that it are normal HTML files, which have some C#-code mixed in to make them dynamic. The C# code is prefixed with an at sign (@). You should be able to copy most of the C# code from the default skin without any problems. You can find an introduction to Razor syntax here.

Creating your first skin is very easy:

1. Create a new folder in the Skins directory in your WebMediaPortal installation, usually in C:\Program Files (x86)\MPExtended\WebMediaPortal\www\Skins. Name the directory after your skin.
2. Copy the Web.config and _ViewStart.cshtml file from the Views folder into your skin folder.
3. (Optionally, but recommended): Create a Content folder in your skin folder.
4. Restart the MPExtended WebMediaPortal service (or IIS if you're using the IIS edition)
5. Done! You can now configure WebMediaPortal to use your own skin on the settings page.

Distributing your skin is as simple as sharing this directory with someone. They can put the directory in their own Skins folder, restart WebMP and start using it.

Customizing the layout

The main layout is stored in the Shared/_Layout.cshtml file. To change the layout, copy this file from the Views folder to a Shared subfolder in your skin folder. You can now start changing this file. If everything has gone ok, changes should show up immediately in WebMediaPortal (after a refresh of the page). Make sure to keep the C# code in the head, as things will break otherwise. Of course, you can add your own tags.

The menu is stored in Site/Menu.cshtml, and included in the layout with @{Html.RenderAction("Menu", "Site");}. You can move this code block around in the layout file to place the menu in another problem. If you want to change the HTML of the menu, copy Site/Menu.cshtml to the Site subfolder of your skin, and edit it.

Customizing a view

Customizing a view isn't much harder. Copy the original version from the Views folder to the same path inside your skin folder, and you should be ready to go. For most pages, the name of the view can be deduced from the URL: often, the first part in the URL is the directory name, and the second part the filename (for example, http://localhost:8080/Television/TVGuide is Television/TVGuide.cshtml). When there is no second part in the URL, the view is probably named Index.cshtml is used. 

Referencing stylesheets and scripts

Often you'll need to reference other files (images, stylesheets and scripts, called "content" from now on) from your views. These are distinguished into two categories: "normal" and "view" content. Normal content is everything used globally in the skin, such as site-wide stylesheets. These should be put in the Skins/<your skin>/Content directory. View content is everything used by a single view, and is put next to the .cshtml files in the view directory (for example, Skins/<your skin>/Television/TVGuide.css).

The best way to link to these files is to use the custom methods provided by WebMediaPortal. If the file doesn't exist in your skin, they automatically load the file with the same name from the default skin. This allows you to copy just a single view from the default skin into your skin folder, without having to copy all the other files that you didn't change. It also makes your skin forward-compatible with new WebMediaPortal versions.

The recommended way to link to stylesheets and scripts in your cshtml files is to reference them using the AssetManager. This ensures that the code ends up in the correct place in the HTML. Use the AddContentStylesheet() and AddContentScript() methods to reference "normal" content, and the AddViewScript() and AddViewContent() methods to reference "view" content.

// adds a <link> tag referencing Skins/<your skin>/Content/Site.css to the <head> section of the page
@Html.Assets().AddContentStylesheet("Site.css")
// adds a <script> tag referencing the Skins/<your skin>/Television/TVGuide.js files to the <head> section
@Html.Assets().AddViewScript("Television/TVGuide.js")

If you need to generate an url to a content file, for example to link to an image, you can use the ContentLink() and ViewContentLink() methods in the UrlHelper:

// generates an URL to the Skins/<your skin>/Content/Images/bg.png file
@Url.ContentLink("Images/bg.png")
// generates an URL to the Skins/<your skin>/Television/TVGuide.css file
@Url.ViewContentLink("Television/TVGuide.css")