Overview

Skinner's Guide to skinning the My Films plugin - skin properties, required controls, xmls, visibility conditions etc.

Introduction

Thank you for your support of the new version of My Films.

The 'Skinning My Films' Wiki pages are provided to help you understand how the My Films plugin interacts with the skin so you can create fantastic looking skins or even modify skins for your own personal use.

You can use whatever skin you like as a base, but your best bet is the Default\wide skin files installed with the release. They are written by the same people who write the plug-in, so if you are having trouble getting something to work right, refer to these skin files.

If you are new to skinning, please refer to Skin Architecture for details on using skin controls in MediaPortal.

The main reference you require is the Skin Properties document.

Skin Changes

If you want to see what's NEW in a particular version, search for the version throughout this page or the Skin properties page - e.g. To see what has changed in v 6.0.0, perform a search on term '6.0.0'.

Sample Database

If you do not use My Films personally, a sample database is provided to enable you to see and skin all features and skin properties. See Sample Movies DB.

Note: To see all the new features in v 6.0.0, you must create a new config for Sample Movies using the Setup Wizard in 6.0, and select the new Sample Movies folder: \MediaPortal\MyFilms\SampleMovies data folder (not the previous folder in MediaPortal\thumbs\MyFilms\SampleMovies.

As of v 6.0.0 you may select 'USA (Full Detail grabbing)' as your country in the Setup Wizard to use the IMDB-Full grabber script which grabs more data, such as writers, AKA (alternate titles). Thus all skin properties will be populated with data.

Debugging

As of v 6.0.0 you can enable property logging If you want to verify what values My Films sets to the properties.

In MyFilms.xml config file, section "MyFilms", set or add a setting "PropertyLogging" and set the value to "true".

_<section name="MyFilms">
[...]
    <entry name="PropertyLogging">false</entry>_

The MyFilms.log will then display each field and value set, so you can determine if an issue is with data or an actual issue in your skin files.

Skin Version Check (6.0.0)

As of v 6.0.0 My Films has implemented a new skin version check to warn users if their skin files are outdated.

Skins must add the following code to MyFilms.xml (only required for the main MyFilms.xml):

<settings>
 <skininterfaceversion>
  <version>
    <major>1</major>
    <minor>0</minor>
    <build>0</build>
    <revision>0</revision>
  </version>
 </skininterfaceversion>
</settings>

<major> version number indicates required skin changes - i.e. the skin will not function correctly without making skin changes.  Users will receive a warning message to update their skin or use a skin that supports the current version of My Films, and My Films will not open.  skinners may also tell if there are required skin changes by viewing the <skininterfaceversion> info in the Default skin files.

Note: MyFilms will always attempt to make new features backwards compatible, so the major version number will not likely change often!

<minor> version number indicates skin changes that support additional features added to My Films but the skin will still work without them. Users will received a warning message that the skin is not fully compatible, but My Films will still open and can be used.

<build> and <revision> numbers are not used currently for skin version compatibility. Skinners may choose to use them to track their own skin updates.

Optiona*l changes on the Skin Changes wiki page, such as additional skin properties to add skinners or offer various ways to display informatino or images in their skins, will *not increase the skin version number.

Note: A 'grace' period will be offered for skinners to implement the new skin version check.  In v 6.0.0 if no skin version information exists in MyFilms.xml, or it is incorrect, the plugin will still open after the warning. However in future versions, skin version information will be required.

Views (6.0.0)

v 6.0.0 introduces the ability to view data by any field, or to create almost unlimited Custom Views which can be added to the new Views menu. 

It is important to understand the types and 'hierarchy' of views:

Views Menu

The new Views menu (dummy visibility control ID 40) - displays a list of all Custom Views - several are preset by Default (e.g. Films, Year, Category, Country, Recently Added,  Original Title (Indexed), Actors (Indexed) and Producers.

Currently only the list layout is supported for the Views Menu, and it uses the same listcontrol as all views and film lists.

The Views menu uses #myfilms.menuimage to display the custom view images (or default images) a user selects in Setup. My Films provides a set of default images for Custom Views stored in the \MediaPortal\thumbs\MyFilms\DefaultImages folder. However, users may add and select their own images. Skins may choose to provide images that suit their skin style so users can select those.

Indexed Views

Any view can be indexed to display an alphabetical grouping of films or persons. The Indexed View level (dummy visibility control ID 41) displays the alpha images from the skin - \media\alpha folder. 

In addition, #myfilms.index (6.0.0) exposes the indexed 'level' - values are: 0 (not indexed), 1 or 2 and reflect the settings users select in Setup for Index level. Skins may use this property to display different elements when an index is using 1 or 2 characters.

Custom Views

There are two main types of Custom Views:

1. 'normal' views (Year, Category, etc) - (dummy visibility control 37) - which displays #myfilms.viewcoverimage
2. 'persons' views (Actors, Directors, Writers, etc)  - (dummy visibility control 37) - which displays #myfilms.personcoverimage 

Note: You may still use dummy visibility control 34 for both views.

The above also applies to generic database field views - i.e. if it is selected from the list of fields in the *Show ALL* option on the VIews Menu (or via the 'View by' Menu option)

Persons Views

As of v 6.0.0 info for persons are published by separate properties - as well as a person image. So it is possible to construct a different layout (except facade) for person views.

Note: the new person's info properties (name, birthdate, place, biography) are only populated and visible when info grabbing is active (Enable Downloads for persons' views in Setup - enabled by default)

As of v 6.0.2, the movie title can be displayed separately (via '#myfilms.moviecontext.value')  in persons views when 'Info for Related Persons is selected)

Film Lists

Film lists (dummy visibility control 36), apply when viewing the main Films View, a list of films within a View, or search results, and use #myfilms.coverimage.

Multiple Images

MyFilms can display more than just the "selected cover" thumb, when using the respective controls/properties.
Skins can display a max of 3 covers at the same time:

1. movie cover - (#myfilms.coverimage) displays higher resolution covers with improved performance rather than #selectedthumb
2. group/collection cover (#myfilms.groupcoverimage) -  when entering a group hierarchy (box-set), the group cover can animate (even zoom to a smaller position/location) and display in addition to the movie cover 
3. person or view image  (#myfilms.personcoverimage or #myfilms.viewcoverimage) - when viewing the list of movies from a person or other view like categories/genres the person or view image can display as well as the movie cover and group cover, and can animate (even zoom to a different position than the group cover

See visibility conditions below, and Default skin for examples.-

Group Lists

When displaying Box Sets, Hierarchies or Groups of films, the Group list (dummy visibility control 39), uses #myfilms.groupcoverimage.

View Images

v 6.0.0 provides separate image controls (as above) for different views, so you may skin them differently, or even display multiple images - e.g. a small actors image when viewing the list of films for that actor (see example in Default skin):

View images use special processing to speed up display, and also delay display slightly when scrolling list layouts quickly so you don't get a lot of flashing images.  Thus they are recommended for better quality and performance, rather than using #selectedthumb:

• #myfilms.viewcoverimage - 'normal' views 
• #myfilms.personcoverimage - 'persons' views 
• #myfilms.coverimage - film lists 
• #myfilms.groupcoverimage - group lists 

Facade Layouts

Big Icon List layout

As of v 6.0.0, My Films supports the Big Icon List layout (type listcontrol, subtype album) to allow users to display more details in lists, such as Edition Names, watched status icons.

Properties exposed to skin

My Films now exposes all fields of the underlying Database plus, user defined fields defined in Setup, as properties to the skin.  This includes many new extended fields supported by Ant Movie Catalog (AMC) v 4.

General Notes

Items usually have a label and a value. Some have a unit in addition.

Examples:

• #myfilms.db.length.label
• #myfilms.db.length.value
• #myfilms.db.length.unit

Control IDs

In most cases you no longer need to use specific control IDs, you may use ID 0 or 1 for most property controls. See Skin Properties for a list of the controls which require specific IDs - e.g. menu buttons, fanart and logos. Cover/Thumb image controls no longer require unique Control IDs.

Static Mapped Properties

All fields of the underlying database are exposed as:

• #myfilms.db.<DB-field>

Calculated Static Mapped Properties

Fields, that are not in the DB, but calculated (e.g. aspectratio, imageformat)

• #myfilms.db.calc.<field>

v 6.0.0 supports Ant Movie Catalog 4.x with extended fields:

• Aspect Ratio (note the previous calc field is still supported for AMC3 catalogs)
• Audio Channels (count)
• Categories (Trakt)
• Certification
• CustomField1
• CustomField2
• CustomField3
• Edition
• Fanart
• Favorite
• IMDB_Id
• IMDB_Rank (Top List)
• Online Status
• Online Status Trailer
• LastPosition
• User Rating
• Trailer (source)
• Studio
• TagLine
• Tags
• TMDB_Id
• Watched
• Writer

See Skin Properties for details. 

Note: You do not need to add all db fields to your skin. Some are used internally, while others can be selected by users as Custom Display Properties using #myfilms.user.item#.value. 

User defined Properties

All user defined fields are exposed as:

• #myfilms.user.<DB-field>

These are based on settings in the My Films configuration.

Whenever possible, use the user defined properties for skinning, as they follow the configuration of the user in the setup and allow them to customize display in your skin.

Examples:

• #myfilms.user.mastertitle.value
• #myfilms.user.secondarytitle.value
• #myfilms.user.source.label  #myfilms.user.source.value
• #myfilms.user.item(1-5).label  #myfilms.user.item(1-5).value - for Main window
• #myfilms.detailsitem(1-6).label  #myfilms.detailsitem(1-6) .value - for Details window (new as of v 6.0.0)

Note: as of v 6.0.0, separate user-defined items are provided for the details screen.  That way, users can change the content to be displayed separately for main screen and details screen. The existing #myfilms.user.item(1-5).value should now only be used for main screen.

Skinners are kindly asked to support user-defined fields on both Main and Details (overview) windows, as they allow users to customize  the display via setup and from MyFilms GUI ("Display Options") - for usage details see Custom Display Fields. 

Localization

All Menu labels, context menu options and plugin messages in GUI are localized. The plugin provides language files for English, German, French, Italian and Spanish so far. More will be added as translations are provided. They are stored in:

• [userdata]\Team MediaPortal\MediaPortal\language\MyFilms

Virtual Views/Menu buttons have been added to the Details View (see Skinning Details Views). To make the virtual Views easier to implement, their localized names are exposed as

• #myfilms.menu.<menuname> e.g. #myfilms.menu.overview

See Default skin xml files for examples how to use them.

Plugin and Configuration Name

The plugin allows users to specify (and localize) the plugin name, and supports multiple configurations for different users or purposes.  These properties are exposed to the skin as:

• #myfilms.config.currentconfig    -> currently active DB-config
• #myfilms.config.pluginname      -> PluginName as configured in setup
• #myfilms.config.configfilter        ->  User Defined Config filter selected by user in Setup > Views tab

Note: As of version 6.0.0 skins may alternately use #currentmodule to display the plugin name, current config, view and selection grouped together.

Views

Several different views (e.g. Category, Year, Country) are provided with the plugin and users may create custom views as well.  The View, and selected parameters are exposed to the skin as:

• #myfilms.view - the current selected view, e.g. Films [all], Category, Year, Country, Storage including the user defined customs views.
• #myfilms.select - the current selection, e.g. filter setting, search, category name, etc.

Note: As of version 6.0.0 skins may alternately use #currentmodule to display the plugin name, current config, view and selection grouped together.

Global Filters

My Films supports global filters which apply to all views, search results, etc.:

• #myfilms.globalfilter.unwatched - True if filter is turned on either in Setup or GUI
• #myfilms.globalfilter.trailersonly - True if filter is turned on in GUI
• #myfilms.globalfilter.minrating - True if filter is turned on in GUI
• #myfilms.globalfilter.minratingvalue - displays the minimum rating value selected in GUI

Media Availability

My Films offers users an option to check and display availability of media files, both films and local trailers.  This is particularly useful when using My Films on a network where movies may be stored on a server, network drives, clients, etc. which may not be currently accessible.

Skins may choose to display media availability using icons with visibility conditions.  The Default skin uses:

1. Green = available (led_green.png)
2. Yellow = available but not accessible for playback (led_yellow.png)
3. Red = no local file available for this film (led_red.png)
4. Grey = availability status unknown (i.e. no search has been performed to determine if trailer is available) (led_grey.png)

Visibility conditions use:

• #myfilms.user.source.isonline - values = available, unavailable, offline, unknown
  • example: to display the ''available' icon (green led)  when a film is available for playback:
    <visible>string.equals(#myfilms.user.sourcetrailer.isonline,available)</visible>
• #myfilms.user.sourcetrailer.isonline - values = available, unavailable, offline, unknown
  • example: to display the offline or 'not accessible for playback' icon (i.e. yellow led) for a local trailer that exists, but is not currently accessible:
    <visible>string.equals(#myfilms.user.sourcetrailer.isonline,offline)</visible>

Watched Status

My FIlms provides the following icons with the Default Skin files for watched status using visibility conditions:

• \Media\MyFilms\overlaywatched.png - +string.contains(#myfilms.user.watched.value)
• \Media\MyFilms\overlayunwatched.png - +!string.contains(#myfilms.user.watched.value)

Watched Status Icons in List Facade View  (v 6.0.0)

Skins may display status icons (watched and unwatched for local and remote) in the list facade view:

My Films checks if the following images are available:

• \Media\MyFilms\overlaywatched.png (watched & local)
• \Media\MyFilms\overlayunwatched.png (not watched and local)
• \Media\MyFilms\overlayNAwatched.png (watched and not available)
• \Media\MyFilms\overlayNAunwatched.png (not watched and not available)

If images are available,  PinIcon for facade listcontrol will be populated accordingly. Skins must set PinIcon for the facade such as:

<PinIconXOff>49</PinIconXOff>
<PinIconYOff>36</PinIconYOff>

Note: see Default Skins Big Icon List layout (liscontrol subtype album) provided with My Films. (new as of v 6.0.0) 

Multi User States

Note: most of these skin properties are changed or new as of v 6.0.0

My Films supports the display of the following data for the currently selected user:

• #myfilms.user.name.label / #myfilms.user.name.value - selected user profile name (either local user or Trakt user name)
• #myfilms.user.onlinestatus - gives user feedback if local or Trakt user and if successfully logged into Trakt (or not) 
• #myfilms.user.watcheddate.label / #myfilms.user.watcheddate.value -  last seen/date watched
• #myfilms.user.watchedcount.label/ #myfilms.user.watchedcount.value - watched count of current user
• #myfilms.watchedcountglobal.value - watched count of all users (i.e. total times the film has been played/watched by all users)
• #myfilms.user.rating.label / #myfilms.user.rating.value - current user rating entered via User Rating Dialog in My Films, or via Trakt pop-up rating dialog. 

These properties can be used with visibility controls to display only when you wish, e.g. only when a username exists (i.e. multiple users are supported), or only when a global watched count is available etc.

Status Icons/Indicators

In addition to watched and global filter icons, as of v 6.0.0 My Films supports:

• #myfilms.statusmessage - status message only visible when certain background activities are in process
• #myfilms.details.downloadstatus - download indicator for persons images/info - only visible when download is active - if Enable downloads is selected in Setup for Persons Views (Artwork tab) and Details View is accessed (or Get Persons Info from context menu)
• #OnlineVideos.currentDownloads - a global property supported by OnlineVideos plugin - can be used to display a download indicator for OnlineVideos - visible only when trailer support is enabled (requires Online Videos plugin installed and enabled) and a video is downloaded via Online Videos plugin

Visibility Conditions

My Films now supports the use of all MediaPortal visibility conditions.

For example, if you wish to display labels only when the db field has a value you can use:

<visible>string.equals(#myfilms.user.item1.value)</visible>

In addition, the plugin provides dummy controls to control visibility of skin elements in the plugin:

Note: Visibility is backwards compatible, however the new visibility controls are required to implement the new skin features (such as images on the Views menu). 

Customize OSD

As of v 6.0.0, skins my use #myfilms.isplaying to customize the OSD when media is played via My Films.

What's Next

Now you have a general idea or overview of what is involved in skinning My Films.  For the gory details, proceed on to Skin Properties.

Related

Tutorials

• Hyperlink Parameters (Intermediate)
• Movie Thumbs (Intermediate)
• Skinning Detail Views (Advanced)
• Skinning Logos (Advanced)
  References
• Skin Changes
• Skin Properties