Custom Virtual Directories

Sapphire has the ability to create custom virtual directories. If you wished to create a directory which showed every movie with Bank in the Plot, you can create it with Sapphire’s virtual directory mechanism.

First create the file ~/Library/Application Support/Sapphire/virtualDirs.xml. As the name implies, this is an XML file. The definition of a virtual directory is quite complex, so we will take this step by step.

First, everything within the XML file must be contained within a virtualDirs tag:

<virtualDirs>
</virtualDirs>

Within the virtualDirs tag, one can define either movie or TV episodes virtual directories. The movie virtual directories are contained within a movieMatch tag and TV episodes are contained within a episodeMatch tag. Each match tag can have two properties, name and description. The name will be the name displayed in the directory listings and the description will be displayed in the preview when the directory is highlighted.

<virtualDirs>
  <movieMatch name="Favorites" description="My Favorite Movies">
  </movieMatch>
  <episodeMatch name="Fav" description="My Favorite TV Shows">
  </episodeMatch>
</virtualDirs>

Within each movieMatch or episodeMatch tag is a series of tags which define how Sapphire will determine the directory’s contents. By default, Sapphire requires a match on all criteria listed within each match. The following tags are used by both TV episodes and Movies:

• all – Match only items which match all items within this tag.
• any – Match items which match at least of of the times within this tag.
• not – Match items which do not match any items within this tag.
• duration – Match items who’s duration is equal to or greater than the number of minutes listed in this tag.
• watched – Match items which are unwatched if the content of the tag is 0 or matches items which are watched if the content of the tag is 1.
• videoDescription – Match items who’s video description matches the contents of this tag.
• audioDescription – Match items who’s audio description matches the contents of this tag.
• subtitlesDescription – Match items who’s subtitles description matches the contents of this tag.

Sapphire also includes methods of matching content specific to movies. The following are valid within a movieMatch tag:

• title – Match movies who’s title matches the content of this tag.
• plot – Match movies who’s plot matches the content of this tag.
• releasedate – Match movies released on or after the date specified in the contents of this tag.
• imdbuserrating – Matches movies rated at or higher than the contents of this tag.
• imdbtop250 – Matches movies ranked at or higher than the content of this tag.
• wonoscars – Matches movies that have won at least as many oscars as the content of this tag.
• mpaarating – Matches movies who’s MPAA rating is equal to the contents of this tag.
• cast – Matches movies with a cast member who matches the contents of this tag.
• genre – Matches movies with a genre that matches the contents of this tag.
• director – Matches movies with a director who matches the contents of this tag.

Sapphire also includes methods of matching content specific to TV episodes. The following are valid within a episodeMatch tag:

• season – Matches an episode with a season equal to the contents of this tag.
• episode – Matches an episode with an episode number (within a season) equal to the contents of this tag.
• episodenumber – Matches an episode with an episode number (counted from beginning) equal to the contents of this tag.
• showtitle – Matches an episode with a show title that matches the contents of this tag.
• title – Matches an episode with an episode title that matches the contents of this tag.
• description – Matches an episode with a description that matches the contents of this tag.
• airdate – Matches an episode with an air date title is on or later than the contents of this tag.

Several of the above tags match in a particular manner. For example, the airdate matches on or after the given date. In some cases, you may want to change how this match is done. For numeric or date match types, you can change the match by setting the value attribute to:

• greater – Match items greater than the contents of the tag.
• greaterequal – Match items greater than or equal to the contents of the tag.
• equal – Match items equal to the contents of the tag.
• lessequal – Match items less than or equal to the contents of the tag.
• less – Match items less than the contents of the tag.

Finally, for text matches, you can specify a wildcard * to match any content. So, *bank* will match any text with bank in it, including content with bankrupt and other words with bank within them. The * bank * will match the word bank that has a space both before and after it. The match bank* will match things starting with bank, and *bank will match those ending with bank. By default, Sapphire uses case insensitive matches, but you can make these case sensitive by setting the type attribute to s.

No good manual on something this complex would be complete without an example:

<virtualDirs>
  <movieMatch name="Highly Ranked Movies" description="Highly Ranked Movies">
    <imdbUserRating>8</imdbUserRating>
  </movieMatch>
  <movieMatch name="James Bond Movies" description="James Bond Movies">
    <any>
      <plot type="s">*James Bond*</plot>
      <plot type="s">Bond*</plot>
      <plot>*007*</plot>
    </any>
  </movieMatch>
  <movieMatch name="Bruce's Films" description="Bruce's Films">
    <cast>Bruce Willis</cast>
  </movieMatch>
  <episodeMatch name="All Recent Unwatched" description="All Unwatched TV Shows">
    <watched>0</watched>
    <airDate>11/01/08</airDate>
  </episodeMatch>
  <episodeMatch name="All Other Unwatched" description="All Unwatched TV Shows">
    <watched>0</watched>
    <airDate value="less">11/01/08</airDate>
  </episodeMatch>
</virtualDirs>

In the above example the following matches are made:

1. Any movie with an IMDB rating of 8 or higher
2. Any movie with a plot containing “James Bond”, a plot starting with “Bond” or a plot containing 007. The first two matches are case sensitive.
3. Any movie with “Bruce Willis” in the cast
4. Any episode that’s unwatched and aired on or after November 1st of 2008.
5. Any episode that’s unwatched and aired before November 1st of 2008.

We hope this gets you started in further customization of Sapphire. Be aware, these custom virtual directories are implemented by a generic database fetch. Sapphire built-in virtual directories have been heavily optimized for speed, so your custom virtual directories may not be as fast.