Editing Views

[stuckless]

Complete List of Filters, Sorters, Groupers, and Sources - This is an autogenerated list of all the filters, groupers, sorters, and sources, including their possible configuration options and configuration option values. This should be consulted any time you need to know what options can be passed to a filter, source, etc. It also contains examples for sorters, filters, groupers, and sources.

Phoenix uses a VFS (Virtual File System) to organize content. The main concept of the VFS is that media sources, ie, sage media files, online videos, file system, etc, are organized into Views. Views take one or more sources of media files and it presents it by filtering it, sorting it, and grouping it to form a heirarchy of media files that is then presented in the STV.

The VFS is quite flexible, and with that flexibility comes some complexity. This post will attempt to describe enough about the VFS that people can being creating their own views, but it will not cover the vfs in complete detail.

The core vfs files for Phoenix are located in STVs/Phoenix/vfs/. There may be one or more files in that location, but do not edit these files. Rather use these files as a guide for editing your own views, and create your view files in userdata/Phoenix/vfs/. The filename is not important but it must end in .xml.

To better understand views, let's look at a common task. Take all recordings and video files and filter ONLY the TV files and then show them first grouped by series, and then by season. Here is the view.

		<view name="tvseriesseason" label="TV">
			<description>TV Grouped by Series and then Season</description>
			<tag value="tv"/>
			
			<view-source name="recordings"/>
			<view-source name="archivedrecordings"/>
			<view-source name="videos" >
				<filter by="mediatype" value="tv" />
			</view-source>

			<presentation level="1">
				<group by="show"/>
				<sort by="title"/>
				<hint value="series"/>
			</presentation>
			
			<presentation level="2">
				<group by="season">
					<option name="prune-singe-item-groups" value="true"/>
				</group>
				<sort by="title"/>
			</presentation>
			
			<presentation level="3">
				<sort by="seasonepisode" />
			</presentation>
		</view>

Every view must have a name and a label. The <description> is optional, but you should try to describe your view.

A View must have a <tag>. Tags are basically view categories. A core set of tags are defined in the master vfs and include the following...

	<tags>
		<tag value="tv" label="TV"/>
		<tag value="video" label="Videos"/>
		<tag value="dvd" label="DVD"/>
		<tag value="bluray" label="Blu-Ray"/>
		<tag value="picture" label="Pictures"/>
		<tag value="music" label="Music"/>
		<tag value="videodisc" label="DVD or Blu-Ray"/>
		<tag value="epg" label="Program Guide"/>
		<tag value="metadata" label="Metadata"/>
		<tag value="online" label="Online"/>
		<tag value="web" label="Web" visible="false"/>
		<tag value="android" label="Android" visible="false"/>
	</tags>

When creating a view, give a tag from this list, or you can create your own tags in your vfs xml file. You cannot use a tag unless it is first defined.

The Next part of the view, is the sources. Phoenix contains a number of sources (which I'll get into later) or you can use another view as a source. In the example above, I'm using recordings, archivedrecordings, and videos views. Note that when I pulled in the videos view, I filtered the view by MediaType of TV so that I'd only get the TV mediafiles from that view.

The next sections of the view describe how to present the items of that view. A view can have any number of <presentation> sections and each <presentation> describes how to render the items for that heirarchy level. levels start at 1, where 1 is the root of the view, and increase by 1 for each sub level.

In the first <presentation> section, we are grouping all the items by "show" and then sorting by "title". A group will create a folder for each show. The sort by "title" will basically sort those show folder names alphabetically. For now you can ignore the <hint> since it's not implemented in the stv, but it's simply a way to pass a hint about content of a given presentation, that can be used by a rendering engine such as the STV, web ui, etc.

In the next <presentation>, level 2, we are taking items in each series/show folder and then grouping those items by Season. The result is that for each SeasonNumber there will be a folder created, like, "Season 1", "Season 2", etc. The <option name="prune-singe-item-groups" value="true"/> passes an option to the grouper telling it to prune or remove any grouped folders that have a single item child. ie, after grouping, if there is only a single media file in "Season 2", then the Season 2 folder is removed and the media item remains ungrouped.

And finally the last <presentation>, level 3, asks that the children of the Season folders be sorted by their season and espisode numbers.


View Sources
As mentioned, views require at least one source for their mediafiles. Views can use other views as a source, but at some point, a view will have to be created that obtains its files from a native source.

expression Source
An expression source is a source that gets it mediafiles by invoking a SageTV expression. An expression must return an Array of SageTV media files, but the expression can do just about anything, as long as the result is an array of media files.
An example of an expression is the expression used in the recordings view.

			<source name="expression">
				<option name="expression">
					phoenix_util_ToArray(phoenix_util_RemoveAll(GetMediaFiles("T"), GetMediaFiles("TL")))
				</option>
			</source>

That expression basically takes the TV Media Files and removes any Library (ie, archived media files) and returns the result an Array.

mediafiles Source
This source builds a source using a SageTV mediafile mask as documented by the GetMediaFiles() api call. An example of the mediafiles source is used by the pictures view.

			<source name="mediafiles">
				<option name="mediamask" value="PL"/>
			</source>

Grouping
Grouping is the act of taking files that share a common element and putting them in the same folder. ie, all files that share the same series name go in the same series folder, or all files that share the same year go in the year folder.

Phoenix has a number of specific groupers, such as, show, title, parental-ratings, season, year, cd, genre, album and artist. And phoenix has a generic grouper, metadata, than enables you to group on any known SageTV metadata element.

Groups can accept 2 optional <option> elements.

			<option name="empty-foldername" value="No Title"/>
			<option name="prune-single-item-folders" value="true"/>

empty-foldername is the name of folder that is used when a grouper fails to find a group for given mediafile. For example, if you group by year, but a media file doesn't have a year, then you can set the empty-foldername to be "Missing Year", and all files that are missing the year will go into that grouped folder name.

prune-single-item-folder was described above, and simply means that don't group items if there is only one of them.

The metadata grouper can accept the above 2 options, but it requires a 3rd option.

      <option name="field" value="Year"/>

The "field" value is the name of the metadata field on which you want to group. I'll post a complete list of metadata fields later.


Filters
Phoenix supports filters on a <source>, <view-source>, on the <view>, and in each presentation level. Filters can be either include or exclude. The following filters are provided; hd, channel, genre, rating, watched, mediatype, fileext, filename, title, and metadata. All filters support the following options...

<option name="value" value="filtered value"/>
<option name="scope" value="include|exclude"/>

So, if you wanted to filter the entire view for ONLY HD videos you might do something like this...

<view name="myview" labe="My View">
    ...
    <filter by="hd" value="true">
         <option name="scope" value="include"/>
    </filter>
    ...
    <presentation>
        ....
    </presentation>
</view>

When you put a <filter> before the presentations, it will filter the content BEFORE it gets to the presentation.

Sorting
A <presentation> can be sorted by the following sorters; starttime, title, seasonepisode, artist and metadata.

Each sort can have the following options

<option name="sort-order" value="asc|desc"/>
<option name="folders-first" value="true|false"/>

sort-order is pretty self explanatory, but folders-first means that folder will be sorted before mediafiles. So if you want to have all the folders listed before the mediafiles, then set folders-first=true. But if you want the folders to be treated like regular media files, then set folders-first=false.

Example of a presentation sorted first by title and then by start title.

<presentation>
     <sort by="title"/>
     <sort by="starttime"/>
</presentation>

When multiple sorters are present in a view, the items sorted using all the <sort> the are provides. ie, in the above example, items are first sorted by title, and then by starttime.

Sample Views

TODO

[stuckless]

Recently a new filter was added to Phoenix, called, 'pql' for "Phoenix Query Language". PQL is a SQL like query syntax that enables you to build complex queries as filters, allowing you to filter based on any existing metadata field.

For example, the following PQL filter basically does what the current Missing Metadata filter does... ie, it returns items that are missing a MediaType or MediaTitle, or missing the EpisodeNumber when the MediaType is 'TV'

    <filter by="pql" value="MediaType is null or MediaTitle is null or (MediaType = 'TV' and EpisodeNumber = 0)"/>

PQL does offer some advantages over other types of filters....
1. You can have complex, grouped, expressions using and,or, and parenthesis.
2. As a root level filter, you can filter on multiple conditions (without pql, you'd have to define a filter-group in the filters section and then reference it as the root filter)
3. PQL supports the following operands, >, <, <>, =, 'is null', 'is not null', and contains.

Some other examples....

    <filter by="pql" value="Genre contains 'Horror' or Genre contains 'Thriller'"/>

    <filter by="pql" value="MediaTitle = 'Bones' and SeasonNumber > 4"/>

Currently PQL ONLY supports known metadata fields.

[HokiePerogi]

Originally Posted by stuckless

3. PQL supports the following operands, >, <, <>, =, 'is null', 'is not null', and contains.

Is it possible to put in a feature request for a 'does not contain' operand too?

[stuckless]

Originally Posted by HokiePerogi

Is it possible to put in a feature request for a 'does not contain' operand too?

Yeah.. I'll be doing some work on the PQL stuff in the near future.. that as come up as well. I'll be adding new keywords and functions.

[HokiePerogi]

Originally Posted by stuckless

3. PQL supports the following operands, >, <, <>, =, 'is null', 'is not null', and contains.

Is the <> operand broken?

I am trying the following without any luck:

<!DOCTYPE vfs SYSTEM "vfs.dtd">
<vfs>
	<views>
		<view name="dp_all_movies_no_adult" label="Family Movies" flat="true" visible="true">
			<description>Grab non-adult content from the combined import paths</description>
			<view-source name="sagevideoimportsv7" />
			<filter by="pql" value="UserRating <> XXX or UserRating <> XX or UserRating <> X" />
		</view>
	</views>
</vfs>

I keep getting the following message when refreshing my configuration in BMT:

unknown xml
The value of attribute "value" associated with an element type "null" must not contain the '<' character. at line 7 and column 39

[PiX64]

Enclose your string in ' '

UserRating <> 'XXX'

U can also test your query in bmt..

[stuckless]

The thing with xml is that there are some "special" characters that you can't really use in xml, such as <> This can be inconvenient for pql, but there are ways to get around it...

<filter by="pql" value="UserRating &lt;&gt; 'XXX' or UserRating &lt;&gt; 'XX' or UserRating &lt;&gt; 'X'" />

Now, UserRating is value between 0 and 100 (ie, numeric) so you may want to do something like...

<filter by="pql" value="UserRating &gt; 60" />

If you don't like using the xml entities (ie, &gt then you can use an alternat style in creating your pql query.

<filter by="pql">
   <option name="value"><![CDATA[UserRating > 60]]></option>
</filter>

<filter by="pql">
   <option name="value"><![CDATA[UserRating <> 'XXX' or UserRating <> 'XX' or UserRating <> 'X']]></option>
</filter>

Hope this helps. But keep in mind that if you are using "string" fields (as Pix64 noted) then you need to quote them (as I've done as well)

[HokiePerogi]

Thanks stuckless. URL encoding the greater than and less than symbols worked like a charm.

I should have known to do this, or use CDATA, since I work for a software company who's product does web services testing. DOH!

[HokiePerogi]

Next question about this pql stuff....

I'd like to filter ratings in some of my views. I tried creating a pql filter using ParentalRating = 'G'. But it returns no results, even in the web UI of BMT.

So then I tried ParentalRating contains 'G'. This came back with many recordings and imports. Going through them, I see some have an MPAA Rating of PG-13.

So next I tried ParentalRating = "PG-13". This returned no results. What the heck, I said.

I went back to ParentalRating contains 'G' and looked through the metadata of the returned results. I see there are definitely imports with a "MPAA Rating" of PG-13.

Looking through the list of Phoenix metadata field names here:http://code.google.com/p/sagephoenix...FieldName.java I only see a ParentalRating field.

Are there discreet fields for "MPAA Rating" and "TV Rating". Thanks!

[wrems]

All you need is:

Rated='G'

Use BMT to test PQL then apply it to VFS.

[HokiePerogi]

Does the "Rated" metadata field apply to both movies and tv recordings?

[stuckless]

Originally Posted by HokiePerogi

Next question about this pql stuff....

I'd like to filter ratings in some of my views. I tried creating a pql filter using ParentalRating = 'G'. But it returns no results, even in the web UI of BMT.

So then I tried ParentalRating contains 'G'. This came back with many recordings and imports. Going through them, I see some have an MPAA Rating of PG-13.

So next I tried ParentalRating = "PG-13". This returned no results. What the heck, I said.

I went back to ParentalRating contains 'G' and looked through the metadata of the returned results. I see there are definitely imports with a "MPAA Rating" of PG-13.

Looking through the list of Phoenix metadata field names here:http://code.google.com/p/sagephoenix...FieldName.java I only see a ParentalRating field.

Are there discreet fields for "MPAA Rating" and "TV Rating". Thanks!

I could be wrong but I think that ParentalRating holds the TV ratings when the type is TV and that Rated holds the MPAA rating when the type is MOVIE. You can verify this youself in the BMT web ui by using the batch editor on a given item... since there I list all field names and their values (whereas the standard editor uses lots of logic to suppress fields, and uses more readable labels)

[toricred]

I'm finding that the instant status view has a bunch of stuff I don't care about. Is there a visible flag I can set to false so that some sections just don't show up?

[wrems]

You can do it from the ui or manually.

Options>Landing Zone Options Instant Status

or

From the Phoenix>Menus folder inside STV's folder of the sage_home directory. There's a instantstatus.xml. Where you can manipulate them.

The UI is probably just a whole lot easier...

[toricred]

For some reason I'm not seeing Instant status in the options menu. Do I need to be ina particular landingzone style to see the option?

[bialio]

Instant Status refers to a portion of the Box Landing Zone. The Global Status Menu is what you see when you hit Info.

Which one are you dealing with?

[toricred]

That was my problem. I should have said global status. I ended up making a copy of newstatusmenu.xml in the usersata folder and changing it there. It would be nice to have been able to do it through the GUI though.

[HokiePerogi]

Is there a way to exclude items in another view from the current view?

Here is what I'm trying to do. I have a view for "special interest" imports that is created using a bookmark to point a specific folder within my master imports folders. I also have a view for "adult" imports using a pql filter and a view for "children" imports using a pql filter.

I now what to create an "everything else" view. This view should exclude the imports found in the "special interest", "adult" and "children" views.

Any recommendations on how I can go about doing this?

[wrems]

Originally Posted by HokiePerogi

Is there a way to exclude items in another view from the current view?

Here is what I'm trying to do. I have a view for "special interest" imports that is created using a bookmark to point a specific folder within my master imports folders. I also have a view for "adult" imports using a pql filter and a view for "children" imports using a pql filter.

I now what to create an "everything else" view. This view should exclude the imports found in the "special interest", "adult" and "children" views.

Any recommendations on how I can go about doing this?

I'm not sure if a vfs can be excluded. Sean will have to comment on that one, I'd like to know too.

Even so you can still do what you want with multiple vfs' since you can exclude pql statements. I think you can only do one exclude filter per vfs so you would have a series of views being passed to one another peeling out the pql statements you don't want to be included. Leaving you with an everything else view when it's done. The intermediary/helper views can be set to visible=false so they don't show and then link the last statement to a menu item.

[stuckless]

We don't have an option to exclude the entire contents of another view. That would be interesting... but I'd think that we'd run into performance issues in trying to create the view.