rectifyer/script.trakt — pull request #120 by nate1280 (2013-05-20 14:22:33+00:00)
Title: Add tagging support

# Tagging/List support!

## Overview:##
With this new feature, you'll now be able to create tags from your trakt.tv Lists, Watchlists, as well as Ratings (Watchlists and Ratings are enabled by a setting).

You can edit what lists an item belongs to directly within XBMC, and add new lists this item belongs to.

You'll also be able to fully edit your trakt.tv lists within XBMC, selecting items from your XBMC library.

There is also custom script/skin support for directly adding or removing items from lists.

When a movie is scrobbled, if you have watchlists enabled, and the move you've just watched happens to be in your watchlist, it will automatically remove the tag so you don't need to force an updatetags to re-sync your tags.

When you rate a movie or show, and you have ratings tags enabled, it will also update the rating tags, either removing (if unrate, or new rating is lower then minimum), or adding new rating tags, again so you don't have to force a re-sync.

**Notes:**
- All tags create by this feature, are prefixed with "trakt.tv - " to differentiate them from any other tags you might have in your library.
- All tagging actions will preserve any existing tags, it will only manipulate trakt.tv specific tags.
- updatetags sync is a one way sync, from trakt.tv to XBMC
- managelists can be used to to do manual 2-way updates within XBMC.
[/list]

## Supported Methods:
There are 5 new actions added with this feature, they are as follows:

```
RunScript(script.trakt,action=updatetags)
RunScript(script.trakt,action=managelists)
RunScript(script.trakt,action=itemlists[,media_type=,dbid=#])
RunScript(script.trakt,action=addtolist,list=[,media_type=,dbid=#])
RunScript(script.trakt,action=removefromlist,list=[,media_type=,dbid=#])
```

The actions **itemlists**, **addtolist** and **removefromlist** have optional parameters of media_type and dbid, these can be used (just like the rating actions) to act against a specific library item. Without these parameters, the currently selected item will be used.

**updatetags** can also be configured to run after a library sync, in tagging settings.

I have also added a temporary **timertest** action, this can be manually run from the Debug settings, or tied to a keyboard action like any others. Alls this action does, is times various JSON requests with/without tags and different ways lists are built. This was used to get a general idea of how long specific functions might have taken to load. If you do run this, the data will be in your log file, and I wouldn't mind seeing this information, send me a PM with it plus specs of the machine it was run on and whether you're using the internal SQLite DBs or a MySQL server (and what its running on). It will probably be removed before a merge happens (if it does). This is just for statistics gathering, to see how various calls behave.

## Information:
This feature can only work with library items, specifically only movies and shows. Even tho trakt.tv lists can have seasons and episodes in them, these 2 items do not have tagging support within XBMC so any items like these are ignored and left untouched in your lists.

Here is a sample keyboard setting for all function, you can set them up how ever you choose.

```

RunScript(script.trakt,action=updatetags)
RunScript(script.trakt,action=itemlists)
RunScript(script.trakt,action=addtolist,list=Watchlist)
RunScript(script.trakt,action=removefromlist,list=Watchlist)

RunScript(script.trakt,action=managelists)

```

## Changes
- Add new API function wrappers to traktAPI class.
- Added the ability for the plugin to create tags from lists on trakt, as well as from watchlists (if enabled), and from ratings (if enabled, with a minimum value).
- Add new settings section for tagging.
- Added 5 new actions, addtolist, removefromlist, updatetags, itemlists, and managelists.
- RunScript(script.trakt,action=updatetags) will cause xbmc tags to be updated from trakt lists based on settings.
- RunScript(script.trakt,action=itemlists) will allow a user to edit the lists a movie/show belongs to within XBMC, and add new lists.
- RunScript(script.trakt,action=managelists) will allow a user to edit there trakt.tv lists from within XBMC and add new lists.
- RunScript(script.trakt,action=addtolist,media_type=,dbid=<#>) will allow for adding an item to a specific list, media_type and dbid are optional, if not included, this will apply to the selected item.
- RunScript(script.trakt,action=removefromlist,media_type=,dbid=<#>) will allow for adding an item to a specific list, media_type and dbid are optional, if not included, this will apply to the selected item.
- Update service thread to handle new actions.
- Move find* functions to utilities file.
- Add loadsettings optional variable to traktAPI class declaration, for use when creating class in a script and doesn't need setting data.
- Cache the lists from trakt.tv, and refresh if 10 minutes have passed since last api call.
- Add temporary timerlist action, times JSON calls to get movies/shows with and without tags, can be triggered manually from Debug settings.
- Rewrote findInList, to loop through by index instead of by item, added ability to return index or item.
- Rewrote findMovie/findShow to use changes in findInList
- Added ability for Watchlist tag to be automatically removed on a scrobble, if tagging and watchlists is enabled, and only for movies.
- Added ability to add/remove rating tag when rating a movie/show, only if tagging and rating tags are enabled.