<chapter id="adding-categories">
  <chapterinfo>
    <author>
      <firstname>Ivan</firstname>
      <surname>Frade</surname>
      <affiliation>
	<address>
	  <email>ivan.frade@@nokia.com</email>
	</address>
      </affiliation>
    </author>
  </chapterinfo>

  <title>Adding Categories &amp; Properties</title>

  <para>
    A category is something which identifies one or more files with
    particular attributes, for example, Files, Folders, Audio, Video,
    etc. These are all categories. This will help you understand how
    to add a category for your 3rd party application to integrate it
    with Tracker.
  </para>

  <section id="defining-categories">
    <title>Defining Categories</title>

    <para>
      The essential attributes are: 
      <programlisting>
[CategoryName]
DisplayName=CategoryName
Description=A description to the user
Parent=Parent category. Usually Files. [1]
Mimes=Mime types we want to assign to this category (e.g.
audio/x-playlist)
MimePrefixes=Prefix to match mimetypes (e.g. audio/ will match all mime types as audio/*)
HasMetadata=Should tracker extract meta-data from these files?
HasFullText=Shoudl tracker extract text content from these files?
HasThumb= Should tracker generate thumbnails from these files?
ShowServiceFiles=Do we want to see these files in the text search results?
      </programlisting>
    </para>
    <note>
      <para>
	[1] At the moment we only support two levels of hierarchy.
      </para>
    </note>

    <example>
      <title>A Play List</title>
      <programlisting>
[Playlist]
DisplayName=Playlists
Description=Music playlists
Mimes=audio/x-mpegurl
HasMetadata=true
HasFullText=false
HasThumbs=false 
ShowServiceFiles=true
      </programlisting>
    </example>

    <para>
      This is because we want to extract meta-data (i.e. the number of
      songs) but don't want to index the full text and don't want to
      generate thumbnails.
    </para>

    <para>
      In this case the properties will have the category name as
      prefix (we will call them Playlist.X). We can add the
      PropertyPrefix key in the category description to use a
      different prefix.
    </para>
  </section>

  <section id="defining-properties">
    <title>Defining Properties</title>

    <para>
      Properties are defined in a "category.metadata" file.
    </para>

    <para>
      Add a file in <filename>data/services/</filename> called
      CategoryName.metadata (don't forget to update the Makefile.am
      file in the same directory).
    </para>
    
    <para>
      In this file add the description of the properties you expect to
      obtain from the extractor. The mandatory information is:
    </para>

    <example>
      <title>Mandatory Properties</title>
      <programlisting>
[CategoryName:PropertyName]
DisplayName=Name to show to the user
Description=Long description of the property
DataType=(index, keyword, double, integer, date) [2]
      </programlisting>
    </example>
    <example>
      <title>Properties Recommended</title>
      <programlisting>
Weight=Relevance of this property
Parent=Parent property, usually from default.metadata
Embedded=The property is embedded on the file or can/will be set by the user or other applications
      </programlisting>
    </example>
    <note>
      <para>
	[2] The "index" and "keywords" are indexed as text. The
	difference is that "index" properties are analyzed (splitted in
	tokens and steemed), while keywords are indexed as they are. We
	can use "Filtered=false" combined with "index" data type to
	avoid steming.
      </para>
    </note>

    <para>
      So, for example, we can add a playlist.metadata file with the
      following content: 
    </para>
	
    <example>
      <title>Real Data</title>

      <programlisting>
[Playlist:TotalLength]
DisplayName=Length
Description=Total length of songs in the playlist in seconds
DataType=integer
Weight=1
Filtered=false

[Playlist:Songs]
DisplayName=Songs
Description=Numbers of tracks in the playlist
DataType=integer
Weight=1
Filtered=false

[Playlist:Name]
DisplayName=Name
Description=Name describing the playlist
DataType=index
Weight=10
Filtered=false
Embedded=false
      </programlisting>
    </example>

    <para>
      We have added two embedded properties (total length and the
      number of songs) and a non-embedded property "name". A media
      player could ask to the user to set a name to the playlist
      ("Boring music") and save that information in this property.
    </para>
  </section>

</chapter>

<!--
Local variables:
mode: sgml
sgml-parent-document: ("tracker-indexer-docs.sgml" "book" "part" "chapter")
End:
-->
