[ios, macos] Use MGLAttributionInfo for source attribution

Made MGLAttributionInfo public. Replaced MGLTileSource’s attribution property with an attributionInfos property set to an array of MGLAttributionInfo objects. Added an MGLTileSourceOption for specifying an array of MGLAttributionInfo objects instead of an HTML string (either is acceptable when creating an MGLTileSource).

Author: 1ec5

platform/darwin/src/MGLAttributionInfo.h

@@ -13,45 +13,49 @@ NS_ASSUME_NONNULL_BEGIN
 @interface MGLAttributionInfo : NSObject
 
 /**
- Parses and returns the attribution infos contained in the given HTML source
- code string.
+ Returns an initialized attribution info object with the given title and URL.
  
- @param htmlString The HTML source code to parse.
- @param fontSize The default text size in points.
- @param linkColor The default link color.
+ @param title The attribution statement’s title.
+ @param URL A URL to more information about the entity named in the attribution.
+ @return An initialized attribution info object.
  */
-+ (NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfosFromHTMLString:(nullable NSString *)htmlString fontSize:(CGFloat)fontSize linkColor:(nullable MGLColor *)linkColor;
-
 - (instancetype)initWithTitle:(NSAttributedString *)title URL:(nullable NSURL *)URL;
 
+/**
+ The attribution statement’s attributed title text.
+ */
 @property (nonatomic) NSAttributedString *title;
-@property (nonatomic, nullable) NSURL *URL;
-@property (nonatomic, getter=isFeedbackLink) BOOL feedbackLink;
-
-- (nullable NSURL *)feedbackURLAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate zoomLevel:(double)zoomLevel;
 
-@end
-
-@interface NSMutableArray (MGLAttributionInfoAdditions)
+/**
+ The URL to more information about the entity named in the attribution.
+ 
+ If this property is set, the attribution statement should be displayed as a
+ hyperlink or action button. Otherwise, if it is `nil`, the attribution
+ statement should be displayed as plain text.
+ */
+@property (nonatomic, nullable) NSURL *URL;
 
 /**
- Adds the given attribution info object to the receiver as long as it isn’t
- redundant to any object already in the receiver. Any existing object that is
- redundant to the given object is replaced by the given object.
+ A Boolean value indicating whether the attribution statement is a shortcut to a
+ feedback tool.
  
- @param info The info object to add to the receiver.
- @return True if the given info object was added to the receiver.
+ If this property is set, the statement should be treated as a way for the user
+ to provide feedback rather than an attribution statement.
  */
-- (void)growArrayByAddingAttributionInfo:(MGLAttributionInfo *)info;
+@property (nonatomic, getter=isFeedbackLink) BOOL feedbackLink;
 
 /**
- Adds each of the given attribution info objects to the receiver as long as it
- isn’t redundant to any object already in the receiver. Any existing object that
- is redundant to the given object is replaced by the given object.
+ Returns a copy of the `URL` property modified to account for the given center
+ coordinate and zoom level.
  
- @param infos An array of info objects to add to the receiver.
+ @param centerCoordinate The map’s center coordinate.
+ @param zoomLevel The map’s zoom level. See `MGLMapView`’s `zoomLevel` property
+    for more information.
+ @return A modified URL containing a fragment that points to the specified
+    viewport. If the `feedbackLink` property is set to `NO`, this method returns
+    `nil`.
  */
-- (void)growArrayByAddingAttributionInfosFromArray:(NS_ARRAY_OF(MGLAttributionInfo *) *)infos;
+- (nullable NSURL *)feedbackURLAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate zoomLevel:(double)zoomLevel;
 
 @end
 

platform/darwin/src/MGLAttributionInfo.mm

@@ -1,4 +1,4 @@
-#import "MGLAttributionInfo.h"
+#import "MGLAttributionInfo_Private.h"
 
 #if TARGET_OS_IPHONE
     #import <UIKit/UIKit.h>
@@ -7,6 +7,7 @@
 #endif
 
 #import "MGLMapCamera.h"
+#import "NSArray+MGLAdditions.h"
 #import "NSString+MGLAdditions.h"
 
 #include <string>
@@ -88,6 +89,18 @@ @implementation MGLAttributionInfo
     return infos;
 }
 
++ (NSAttributedString *)attributedStringForAttributionInfos:(NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfos {
+    NSMutableArray *titles = [NSMutableArray arrayWithCapacity:attributionInfos.count];
+    for (MGLAttributionInfo *info in attributionInfos) {
+        NSMutableAttributedString *title = info.title.mutableCopy;
+        if (info.URL) {
+            [title addAttribute:NSLinkAttributeName value:info.URL range:title.mgl_wholeRange];
+        }
+        [titles addObject:title];
+    }
+    return [titles mgl_attributedComponentsJoinedByString:@" "];
+}
+
 - (instancetype)initWithTitle:(NSAttributedString *)title URL:(NSURL *)URL {
     if (self = [super init]) {
         _title = title;

platform/darwin/src/MGLAttributionInfo_Private.h

@@ -0,0 +1,48 @@
+#import <Foundation/Foundation.h>
+#import <CoreGraphics/CoreGraphics.h>
+#import <CoreLocation/CoreLocation.h>
+
+#import "MGLAttributionInfo.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface MGLAttributionInfo (Private)
+
+/**
+ Parses and returns the attribution infos contained in the given HTML source
+ code string.
+ 
+ @param htmlString The HTML source code to parse.
+ @param fontSize The default text size in points.
+ @param linkColor The default link color.
+ */
++ (NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfosFromHTMLString:(nullable NSString *)htmlString fontSize:(CGFloat)fontSize linkColor:(nullable MGLColor *)linkColor;
+
++ (NSAttributedString *)attributedStringForAttributionInfos:(NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfos;
+
+@end
+
+@interface NSMutableArray (MGLAttributionInfoAdditions)
+
+/**
+ Adds the given attribution info object to the receiver as long as it isn’t
+ redundant to any object already in the receiver. Any existing object that is
+ redundant to the given object is replaced by the given object.
+ 
+ @param info The info object to add to the receiver.
+ @return True if the given info object was added to the receiver.
+ */
+- (void)growArrayByAddingAttributionInfo:(MGLAttributionInfo *)info;
+
+/**
+ Adds each of the given attribution info objects to the receiver as long as it
+ isn’t redundant to any object already in the receiver. Any existing object that
+ is redundant to the given object is replaced by the given object.
+ 
+ @param infos An array of info objects to add to the receiver.
+ */
+- (void)growArrayByAddingAttributionInfosFromArray:(NS_ARRAY_OF(MGLAttributionInfo *) *)infos;
+
+@end
+
+NS_ASSUME_NONNULL_END

platform/darwin/src/MGLRasterSource.mm

@@ -85,7 +85,7 @@ - (void)setRawSource:(mbgl::style::RasterSource *)rawSource {
     super.rawSource = rawSource;
 }
 
-- (NSString *)attribution {
+- (NSString *)attributionHTMLString {
     auto attribution = self.rawSource->getAttribution();
     return attribution ? @(attribution->c_str()) : nil;
 }

platform/darwin/src/MGLStyle.mm

@@ -22,7 +22,7 @@
 #import "MGLRasterSource.h"
 #import "MGLShapeSource.h"
 
-#import "MGLAttributionInfo.h"
+#import "MGLAttributionInfo_Private.h"
 
 #include <mbgl/util/default_styles.hpp>
 #include <mbgl/sprite/sprite_image.hpp>

platform/darwin/src/MGLTileSource.h

@@ -5,6 +5,8 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+@class MGLAttributionInfo;
+
 /**
  Options for `MGLTileSource` objects.
  */
@@ -32,20 +34,43 @@ extern const MGLTileSourceOption MGLTileSourceOptionMaximumZoomLevel;
 
 #if TARGET_OS_IPHONE
 /**
- A string to be displayed in an action sheet when the source is part of a map
- view’s style and the map view’s attribution button is pressed.
+ An HTML string defining the buttons to be displayed in an action sheet when the
+ source is part of a map view’s style and the map view’s attribution button is
+ pressed.
+ 
+ By default, no attribution statements are displayed. If the
+ `MGLTileSourceOptionAttributionInfos` option is specified, this option is
+ ignored.
+ */
+extern const MGLTileSourceOption MGLTileSourceOptionAttributionHTMLString;
+
+/**
+ An array of `MGLAttributionInfo` objects defining the buttons to be displayed
+ in an action sheet when the source is part of a map view’s style and the map
+ view’s attribution button is pressed.
  
- The default value for this option is `nil`.
+ By default, no attribution statements are displayed.
  */
-extern const MGLTileSourceOption MGLTileSourceOptionAttribution;
+extern const MGLTileSourceOption MGLTileSourceOptionAttributionInfos;
 #else
 /**
- A string to be displayed in the map view’s attribution view when the source is
- part of the map view’s style.
+ An HTML string defining the buttons to be displayed in the map view’s
+ attribution view when the source is part of the map view’s style.
+ 
+ By default, no attribution statements are displayed. If the
+ `MGLTileSourceOptionAttributionInfos` option is specified, this option is
+ ignored.
+ */
+extern const MGLTileSourceOption MGLTileSourceOptionAttributionHTMLString;
+
+/**
+ An array of `MGLAttributionInfo` objects defining the buttons to be displayed
+ in the map view’s attribution view when the source is part of the map view’s
+ style.
  
- The default value for this option is `nil`.
+ By default, no attribution statements are displayed.
  */
-extern const MGLTileSourceOption MGLTileSourceOptionAttribution;
+extern const MGLTileSourceOption MGLTileSourceOptionAttributionInfos;
 #endif
 
 /**
@@ -140,13 +165,14 @@ typedef NS_ENUM(NSUInteger, MGLTileCoordinateSystem) {
 #pragma mark Accessing Attribution Strings
 
 /**
- An `NSString` object that contains an attribution to be displayed when the map
- is shown to a user.
+ An array of `MGLAttributionInfo` objects that define the attribution
+ statements to be displayed when the map is shown to the user.
  
- The default value is `nil`. If the source is initialized with a configuration
- URL, this property is also `nil` until the configuration JSON file is loaded.
+ By default, this array is empty. If the source is initialized with a
+ configuration URL, this array is also empty until the configuration JSON file
+ is loaded.
  */
-@property (nonatomic, copy, nullable, readonly) NSString *attribution;
+@property (nonatomic, copy, readonly) NS_ARRAY_OF(MGLAttributionInfo *) *attributionInfos;
 
 @end
 

platform/darwin/src/MGLTileSource.mm

@@ -1,12 +1,20 @@
 #import "MGLTileSource_Private.h"
 
-#import "MGLAttributionInfo.h"
+#import "MGLAttributionInfo_Private.h"
+#import "NSString+MGLAdditions.h"
+
+#if TARGET_OS_IPHONE
+    #import <UIKit/UIKit.h>
+#else
+    #import <Cocoa/Cocoa.h>
+#endif
 
 #include <mbgl/util/tileset.hpp>
 
 const MGLTileSourceOption MGLTileSourceOptionMinimumZoomLevel = @"MGLTileSourceOptionMinimumZoomLevel";
 const MGLTileSourceOption MGLTileSourceOptionMaximumZoomLevel = @"MGLTileSourceOptionMaximumZoomLevel";
-const MGLTileSourceOption MGLTileSourceOptionAttribution = @"MGLTileSourceOptionAttribution";
+const MGLTileSourceOption MGLTileSourceOptionAttributionHTMLString = @"MGLTileSourceOptionAttributionHTMLString";
+const MGLTileSourceOption MGLTileSourceOptionAttributionInfos = @"MGLTileSourceOptionAttributionInfos";
 const MGLTileSourceOption MGLTileSourceOptionTileCoordinateSystem = @"MGLTileSourceOptionTileCoordinateSystem";
 
 @implementation MGLTileSource
@@ -19,13 +27,17 @@ - (instancetype)initWithIdentifier:(NSString *)identifier tileURLTemplates:(NS_A
     return [super initWithIdentifier:identifier];
 }
 
-- (nullable NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfosWithFontSize:(CGFloat)fontSize linkColor:(nullable MGLColor *)linkColor {
-    return [MGLAttributionInfo attributionInfosFromHTMLString:self.attribution
+- (NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfos {
+    return [self attributionInfosWithFontSize:0 linkColor:nil];
+}
+
+- (NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfosWithFontSize:(CGFloat)fontSize linkColor:(nullable MGLColor *)linkColor {
+    return [MGLAttributionInfo attributionInfosFromHTMLString:self.attributionHTMLString
                                                      fontSize:fontSize
                                                     linkColor:linkColor];
 }
 
-- (NSString *)attribution {
+- (NSString *)attributionHTMLString {
     [NSException raise:@"MGLAbstractClassException"
                 format:@"MGLTileSource is an abstract class"];
     return nil;
@@ -61,14 +73,35 @@ - (NSString *)attribution {
                     format:@"MGLTileSourceOptionMinimumZoomLevel must be less than MGLTileSourceOptionMaximumZoomLevel."];
     }
 
-    if (NSString *attribution = options[MGLTileSourceOptionAttribution]) {
+    if (NSString *attribution = options[MGLTileSourceOptionAttributionHTMLString]) {
         if (![attribution isKindOfClass:[NSString class]]) {
             [NSException raise:NSInvalidArgumentException
-                        format:@"MGLTileSourceOptionAttribution must be set to a string."];
+                        format:@"MGLTileSourceOptionAttributionHTMLString must be set to a string."];
         }
         tileSet.attribution = attribution.UTF8String;
     }
 
+    if (NSArray *attributionInfos = options[MGLTileSourceOptionAttributionInfos]) {
+        if (![attributionInfos isKindOfClass:[NSArray class]]) {
+            [NSException raise:NSInvalidArgumentException
+                        format:@"MGLTileSourceOptionAttributionInfos must be set to a string."];
+        }
+        
+        NSAttributedString *attributedString = [MGLAttributionInfo attributedStringForAttributionInfos:attributionInfos];
+#if TARGET_OS_IPHONE
+        static NSString * const NSExcludedElementsDocumentAttribute = @"ExcludedElements";
+#endif
+        NSDictionary *documentAttributes = @{
+            NSDocumentTypeDocumentAttribute: NSHTMLTextDocumentType,
+            NSCharacterEncodingDocumentAttribute: @(NSUTF8StringEncoding),
+            // The attribution string is meant to be a simple, inline fragment, not a full-fledged, validating document.
+            NSExcludedElementsDocumentAttribute: @[@"XML", @"DOCTYPE", @"html", @"head", @"meta", @"title", @"style", @"body", @"p"],
+        };
+        NSData *data = [attributedString dataFromRange:attributedString.mgl_wholeRange documentAttributes:documentAttributes error:NULL];
+        NSString *html = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
+        tileSet.attribution = html.UTF8String;
+    }
+    
     if (NSNumber *tileCoordinateSystemNumber = options[MGLTileSourceOptionTileCoordinateSystem]) {
         if (![tileCoordinateSystemNumber isKindOfClass:[NSValue class]]) {
             [NSException raise:NSInvalidArgumentException

platform/darwin/src/MGLTileSource_Private.h

@@ -12,14 +12,22 @@ namespace mbgl {
 
 @interface MGLTileSource (Private)
 
+/**
+ An HTML string to be displayed as attribution when the map is shown to a user.
+ 
+ The default value is `nil`. If the source is initialized with a configuration
+ URL, this property is also `nil` until the configuration JSON file is loaded.
+ */
+@property (nonatomic, copy, nullable, readonly) NSString *attributionHTMLString;
+
 /**
  A structured representation of the `attribution` property. The default value is
  `nil`.
  
- @param fontSize The default text size in points.
- @param linkColor The default link color.
+ @param fontSize The default text size in points, or 0 to use the default.
+ @param linkColor The default link color, or `nil` to use the default.
  */
-- (nullable NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfosWithFontSize:(CGFloat)fontSize linkColor:(nullable MGLColor *)linkColor;
+- (NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfosWithFontSize:(CGFloat)fontSize linkColor:(nullable MGLColor *)linkColor;
 
 @end
 

platform/darwin/src/MGLVectorSource.mm

@@ -69,7 +69,7 @@ - (void)setRawSource:(mbgl::style::VectorSource *)rawSource {
     super.rawSource = rawSource;
 }
 
-- (NSString *)attribution {
+- (NSString *)attributionHTMLString {
     auto attribution = self.rawSource->getAttribution();
     return attribution ? @(attribution->c_str()) : nil;
 }

platform/darwin/src/NSArray+MGLAdditions.h

@@ -6,4 +6,7 @@
 
 - (std::vector<mbgl::Value>)mgl_vector;
 
+/** Returns a string resulting from inserting a separator between each attributed string in the array */
+- (NSAttributedString *)mgl_attributedComponentsJoinedByString:(NSString *)separator;
+
 @end