Improvement: Display TV Show specials in logical order inside seasons

XBMC Remote/DetailViewController.m

@@ -2681,7 +2681,7 @@ - (UITableViewCell*)tableView:(UITableView*)tableView cellForRowAtIndexPath:(NSI
     }
     else if (episodesView) {
         UILabel *trackNumber = (UILabel*)[cell viewWithTag:ALBUM_VIEW_CELL_TRACKNUMBER];
-        trackNumber.text = item[@"episode"];
+        trackNumber.text = item[@"specialEpisode"] ?: item[@"episode"];
     }
     else if (channelGuideView) {
         runtimeyear.hidden = YES;
@@ -4823,6 +4823,25 @@ - (void)retrieveData:(NSString*)methodToCall parameters:(NSDictionary*)parameter
                                                                                  useBanner:tvshowsView
                                                                                    useIcon:recordingListView];
 
+                             // Use TV Show episode's "specialsort", if present, to place a copy of a special
+                             // within the common seasons. This is in line with Kodi behaviour.
+                             if ([methodName isEqualToString:@"VideoLibrary.GetEpisodes"]) {
+                                 // Flag specials for sorting reasons and provide track number in "Sx" scheme.
+                                 BOOL isTVShowSpecial = [newDict[@"season"] integerValue] == 0;
+                                 newDict[@"isTVShowSpecial"] = @(isTVShowSpecial);
+                                 if (isTVShowSpecial) {
+                                     newDict[@"specialEpisode"] = [Utilities formatTVShowStringForSpecialEpisode:item[@"episode"]];
+                                 }
+
+                                 // In case "specialsort" is valid, add an item copy with according season/episode.
+                                 if ([item[@"specialsortseason"] intValue] > 0 && [item[@"specialsortepisode"] intValue] > 0) {
+                                     NSMutableDictionary *specialSortedDict = [newDict mutableCopy];
+                                     specialSortedDict[@"season"] = [Utilities getStringFromItem:item[@"specialsortseason"]];
+                                     specialSortedDict[@"episode"] = [Utilities getStringFromItem:item[@"specialsortepisode"]];
+                                     [resultStoreArray addObject:specialSortedDict];
+                                 }
+                             }
+
                              // JSON API does not return the expected "filetype" when retrieving list of "sources".
                              // The correct "filetype" is "directory". But we also need to be aware this is a source
                              // and not a directory yet.
@@ -5107,7 +5126,20 @@ - (void)indexAndDisplayData {
     }
 
     if (episodesView) {
-        for (NSDictionary *item in self.richResults) {
+        // First run will ensure the specials are in correct order
+        SEL selector = [self buildSelectorForSortMethod:@"specialEpisode" inArray:copyRichResults];
+        copyRichResults = [self applySortByMethod:copyRichResults sortmethod:@"specialEpisode" ascending:YES selector:selector];
+
+        // Second run will ensure the specials are on top of the list
+        selector = [self buildSelectorForSortMethod:@"isTVShowSpecial" inArray:copyRichResults];
+        copyRichResults = [self applySortByMethod:copyRichResults sortmethod:@"isTVShowSpecial" ascending:NO selector:selector];
+
+        // Third run will sort by order of episodes
+        selector = [self buildSelectorForSortMethod:@"episode" inArray:copyRichResults];
+        copyRichResults = [self applySortByMethod:copyRichResults sortmethod:@"episode" ascending:YES selector:selector];
+
+        // Now pick the episodes top-down from the list into sections defined by seasons
+        for (NSDictionary *item in copyRichResults) {
             NSString *c = [NSString stringWithFormat:@"%@", item[@"season"]];
             BOOL found = [[self.sections allKeys] containsObject:c];
             if (!found) {

XBMC Remote/Utilities.h

@@ -111,6 +111,7 @@ typedef NS_ENUM(NSInteger, LogoBackgroundType) {
 + (void)imageView:(UIImageView*)view AnimDuration:(NSTimeInterval)seconds Image:(UIImage*)image;
 + (float)getPercentElapsed:(NSDate*)startDate EndDate:(NSDate*)endDate;
 + (void)createTransparentToolbar:(UIToolbar*)toolbar;
++ (NSString*)formatTVShowStringForSpecialEpisode:(id)episode;
 + (NSString*)formatTVShowStringForSeasonTrailing:(id)season episode:(id)episode title:(NSString*)title;
 + (NSString*)formatTVShowStringForSeasonLeading:(id)season episode:(id)episode title:(NSString*)title;
 + (NSString*)formatTVShowStringForSeason:(id)season episode:(id)episode;

XBMC Remote/Utilities.m

@@ -1257,6 +1257,10 @@ + (void)createTransparentToolbar:(UIToolbar*)toolbar {
          forToolbarPosition:UIBarPositionAny];
 }
 
++ (NSString*)formatTVShowStringForSpecialEpisode:(id)episode {
+    return [NSString stringWithFormat:@"S%i", [episode intValue]];
+}
+
 + (NSString*)formatTVShowStringForSeasonLeading:(id)season episode:(id)episode title:(NSString*)title {
     NSString *seasonAndEpisode = [Utilities formatTVShowStringForSeason:season episode:episode];
     NSString *text = [NSString stringWithFormat:@"%@%@%@", seasonAndEpisode, seasonAndEpisode.length ? @" " : @"", title];
@@ -1277,6 +1281,9 @@ + (NSString*)formatTVShowStringForSeason:(id)season episode:(id)episode {
         if ([season intValue] && [episode intValue]) {
             text = [NSString stringWithFormat:format, [season intValue], [episode intValue]];
         }
+        else if (![season intValue] && [episode intValue]) {
+            text = [self formatTVShowStringForSpecialEpisode:episode];
+        }
     }
     return text;
 }

XBMC Remote/mainMenu.m

@@ -4053,6 +4053,12 @@ + (NSMutableArray*)generateMenus {
                     @"title",
                 ],
             },
+            @"kodiExtrasPropertiesMinimumVersion": @{
+                @"12": @[
+                    @"specialsortseason",
+                    @"specialsortepisode",
+                ],
+            },
             @"extra_info_parameters": @{
                 @"properties": @[
                     @"episode",
@@ -4389,6 +4395,12 @@ + (NSMutableArray*)generateMenus {
                     @"title",
                 ],
             },
+            @"kodiExtrasPropertiesMinimumVersion": @{
+                @"12": @[
+                    @"specialsortseason",
+                    @"specialsortepisode",
+                ],
+            },
             @"extra_info_parameters": @{
                 @"properties": @[
                     @"episode",