diff options
Diffstat (limited to 'platform/darwin')
4 files changed, 257 insertions, 69 deletions
diff --git a/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs b/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs index 7745ab07a1..e41ac1c832 100644 --- a/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs +++ b/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs @@ -1,9 +1,9 @@ - <% const os = locals.os; const iOS = os === 'iOS'; const macOS = os === 'macOS'; const cocoaPrefix = iOS ? 'UI' : 'NS'; + const guide = 'UsingStyleFunctionsAtRuntime'; -%> <!-- This file is generated. @@ -36,13 +36,7 @@ The documentation for each individual style layer property notes which style fun Stops are key-value pairs that that determine a style value. With a `MGLCameraSourceFunction` stop, you can use a dictionary with a zoom level for a key and a `MGLStyleValue` for the value. For example, you can use a stops dictionary with zoom levels 0, 10, and 20 as keys, and yellow, orange, and red as the values. A `MGLSourceStyleFunction` uses the relevant attribute value as the key. -```swift -let stops = [0: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .yellow), - 2.5: MGLStyleValue(rawValue: .orange), - 5: MGLStyleValue(rawValue: .red), - 7.5: MGLStyleValue(rawValue: .blue), - 10: MGLStyleValue(rawValue: .white)] -``` +<%- guideExample(guide, 'Stops', os) %> ## Interpolation mode @@ -54,28 +48,7 @@ The effect a key has on the style value is determined by the interpolation mode. The stops dictionary below, for example, shows colors that continuously shift from yellow to orange to red to blue to white based on the attribute value. -```swift -let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson")! -let symbolSource = MGLSource(identifier: "source")! -let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbolSource) - -let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil) -style.addSource(source) - -let stops = [0: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .yellow), - 2.5: MGLStyleValue(rawValue: .orange), - 5: MGLStyleValue(rawValue: .red), - 7.5: MGLStyleValue(rawValue: .blue), - 10: MGLStyleValue(rawValue: .white)] - -let layer = MGLCircleStyleLayer(identifier: "circles", source: source) -layer.circleColor = MGLStyleValue(interpolationMode: .exponential, - sourceStops: stops, - attributeName: "mag", - options: [.defaultValue: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .green)]) -layer.circleRadius = MGLStyleValue(rawValue: 10) -style.insertLayer(layer, below: symbolLayer) -``` +<%- guideExample(guide, 'Linear', os) %>  @@ -90,15 +63,7 @@ Here’s a visualization from Mapbox Studio (see [Working with Mapbox Studio](wo The example below increases a layer’s `circleRadius` exponentially based on a map’s zoom level. The `MGLStyleFunctionOptionInterpolationBase` is `1.5`. -```swift -let stops = [12: MGLStyleValue<NSNumber>(rawValue: 0.5), - 14: MGLStyleValue(rawValue: 2), - 18: MGLStyleValue(rawValue: 18)] - -layer.circleRadius = MGLStyleValue(interpolationMode: .exponential, - cameraStops: stops, - options: [.interpolationBase: 1.5]) -``` +<%- guideExample(guide, 'Exponential', os) %> ### Interval @@ -106,18 +71,7 @@ layer.circleRadius = MGLStyleValue(interpolationMode: .exponential, When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow, 2.5 to just less than 5 would be orange, and so on. -```swift -let stops = [0: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .yellow), - 2.5: MGLStyleValue(rawValue: .orange), - 5: MGLStyleValue(rawValue: .red), - 7.5: MGLStyleValue(rawValue: .blue), - 10: MGLStyleValue(rawValue: .white)] - -layer.circleColor = MGLStyleValue(interpolationMode: .interval, - sourceStops: stops, - attributeName: "mag", - options: [.defaultValue: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .green)]) -``` +<%- guideExample(guide, 'Interval', os) %>  @@ -127,17 +81,7 @@ At each stop, `MGLInterpolationModeCategorical` produces an output value equal t There are three main types of events in the dataset: earthquakes, explosions, and quarry blasts. In this case, the color of the circle layer will be determined by the type of event, with a default value of blue to catch any events that do not fall into any of those categories. -```swift -let categoricalStops = ["earthquake": MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .orange), - "explosion": MGLStyleValue(rawValue: .red), - "quarry blast": MGLStyleValue(rawValue: .yellow)] - -layer.circleColor = MGLStyleValue(interpolationMode: .categorical, - sourceStops: categoricalStops, - attributeName: "type", - options: [.defaultValue: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .blue)]) - -``` +<%- guideExample(guide, 'Categorical', os) %>   @@ -145,12 +89,7 @@ layer.circleColor = MGLStyleValue(interpolationMode: .categorical, `MGLInterpolationModeIdentity` uses the attribute’s value as the style value. For example, you can set the `circleRadius` to the earthquake’s magnitude. Since the attribute value itself will be used as the style value, `sourceStops` should be set to `nil`. -```swift -layer.circleRadius = MGLStyleValue(interpolationMode: .identity, - sourceStops: nil, - attributeName: "mag", - options: [.defaultValue: MGLStyleValue<NSNumber>(rawValue: 0)]) -``` +<%- guideExample(guide, 'Identity', os) %>  diff --git a/platform/darwin/scripts/generate-style-code.js b/platform/darwin/scripts/generate-style-code.js index 5d5adbbef6..330a8f1d03 100644 --- a/platform/darwin/scripts/generate-style-code.js +++ b/platform/darwin/scripts/generate-style-code.js @@ -600,6 +600,41 @@ for (var layer of layers) { fs.writeFileSync(`platform/darwin/test/${prefix}${camelize(layer.type)}${suffix}Tests.mm`, testLayers(layer)); } +// Extract examples for guides from unit tests. +let examplesSrc = fs.readFileSync('platform/darwin/test/MGLDocumentationGuideTests.swift', 'utf8'); +const exampleRegex = /func test([\w$]+)\s*\(\)\s*\{[^]*?\n([ \t]+)\/\/#-example-code\n([^]+?)\n\2\/\/#-end-example-code\n/gm; + +let examples = {}; +let match; +while ((match = exampleRegex.exec(examplesSrc)) !== null) { + let testMethodName = match[1], + indentation = match[2], + exampleCode = match[3]; + + // Trim leading whitespace from the example code. + exampleCode = exampleCode.replace(new RegExp('^' + indentation, 'gm'), ''); + + examples[testMethodName] = exampleCode; +} + +global.guideExample = function (guide, exampleId, os) { + // Get the contents of the test method whose name matches the symbol path. + let testMethodName = `${guide}$${exampleId}`; + let example = examples[testMethodName]; + if (!example) { + console.error(`MGLDocumentationExampleTests.test${testMethodName}() not found.`); + process.exit(1); + } + + // Resolve conditional compilation blocks. + example = example.replace(/^(\s*)#if\s+os\((iOS|macOS)\)\n([^]*?)(?:^\1#else\n([^]*?))?^\1#endif\b\n?/gm, + function (m, indentation, ifOs, ifCase, elseCase) { + return (os === ifOs ? ifCase : elseCase).replace(new RegExp('^ ', 'gm'), ''); + }).replace(/\n$/, ''); + + return '```swift\n' + example + '\n```'; +}; + fs.writeFileSync(`platform/ios/docs/guides/For Style Authors.md`, guideMD({ os: 'iOS', renamedProperties: renamedPropertiesByLayerType, diff --git a/platform/darwin/scripts/update-examples.js b/platform/darwin/scripts/update-examples.js index 404cda102a..d453c0e4ba 100644 --- a/platform/darwin/scripts/update-examples.js +++ b/platform/darwin/scripts/update-examples.js @@ -103,7 +103,7 @@ function completeExamples(os) { let testMethodName = symbolPath.join('$').replace(/\$[+-]/, '$').replace(/:/g, '_'); let example = examples[testMethodName]; if (!example) { - console.error(`MGLDocumentationExampleTests.${testMethodName}() not found.`); + console.error(`MGLDocumentationExampleTests.test${testMethodName}() not found.`); process.exit(1); } diff --git a/platform/darwin/test/MGLDocumentationGuideTests.swift b/platform/darwin/test/MGLDocumentationGuideTests.swift new file mode 100644 index 0000000000..c71f1b46c7 --- /dev/null +++ b/platform/darwin/test/MGLDocumentationGuideTests.swift @@ -0,0 +1,214 @@ +import Foundation +import Mapbox +#if os(iOS) + import UIKit +#else + import Cocoa +#endif + +/** + Test cases that ensure the inline examples in the jazzy guides compile. + + To add an example: + 1. Add a test case named in the form `testGuideName$ExampleName`. + 2. Wrap the code you’d like to appear in the documentation within the + following comment blocks: + ``` + //#-example-code + ... + //#-end-example-code + ``` + 3. Insert a call to `guideExample()` where you’d like the example code to be + inserted in the guide’s Markdown. + ``` + <%- guideExample('GuideName', 'ExampleName', 'iOS') %> + ``` + 4. Run `make darwin-style-code` to extract example code from the test method + below and insert it into the guide. + */ +class MGLDocumentationGuideTests: XCTestCase, MGLMapViewDelegate { + var mapView: MGLMapView! + var styleLoadingExpectation: XCTestExpectation! + + override func setUp() { + super.setUp() + let styleURL = Bundle(for: MGLDocumentationGuideTests.self).url(forResource: "one-liner", withExtension: "json") + mapView = MGLMapView(frame: CGRect(x: 0, y: 0, width: 256, height: 256), styleURL: styleURL) + mapView.delegate = self + styleLoadingExpectation = expectation(description: "Map view should finish loading style") + waitForExpectations(timeout: 1, handler: nil) + } + + override func tearDown() { + mapView = nil + styleLoadingExpectation = nil + super.tearDown() + } + + func mapView(_ mapView: MGLMapView, didFinishLoading style: MGLStyle) { + styleLoadingExpectation.fulfill() + } + + func testUsingStyleFunctionsAtRuntime$Stops() { + //#-example-code + #if os(macOS) + let stops = [ + 0: MGLStyleValue<NSColor>(rawValue: .yellow), + 2.5: MGLStyleValue(rawValue: .orange), + 5: MGLStyleValue(rawValue: .red), + 7.5: MGLStyleValue(rawValue: .blue), + 10: MGLStyleValue(rawValue: .white), + ] + #else + let stops = [ + 0: MGLStyleValue<UIColor>(rawValue: .yellow), + 2.5: MGLStyleValue(rawValue: .orange), + 5: MGLStyleValue(rawValue: .red), + 7.5: MGLStyleValue(rawValue: .blue), + 10: MGLStyleValue(rawValue: .white), + ] + #endif + //#-end-example-code + + let _ = MGLStyleValue(interpolationMode: .exponential, cameraStops: stops, options: nil) + } + + func testUsingStyleFunctionsAtRuntime$Linear() { + //#-example-code + let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson")! + let symbolSource = MGLSource(identifier: "source") + let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbolSource) + + let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil) + mapView.style?.addSource(source) + + #if os(macOS) + let stops = [ + 0: MGLStyleValue<NSColor>(rawValue: .yellow), + 2.5: MGLStyleValue(rawValue: .orange), + 5: MGLStyleValue(rawValue: .red), + 7.5: MGLStyleValue(rawValue: .blue), + 10: MGLStyleValue(rawValue: .white), + ] + #else + let stops = [ + 0: MGLStyleValue<UIColor>(rawValue: .yellow), + 2.5: MGLStyleValue(rawValue: .orange), + 5: MGLStyleValue(rawValue: .red), + 7.5: MGLStyleValue(rawValue: .blue), + 10: MGLStyleValue(rawValue: .white), + ] + #endif + + let layer = MGLCircleStyleLayer(identifier: "circles", source: source) + #if os(macOS) + layer.circleColor = MGLStyleValue(interpolationMode: .exponential, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<NSColor>(rawValue: .green)]) + #else + layer.circleColor = MGLStyleValue(interpolationMode: .exponential, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)]) + #endif + layer.circleRadius = MGLStyleValue(rawValue: 10) + mapView.style?.insertLayer(layer, below: symbolLayer) + //#-end-example-code + } + + func testUsingStyleFunctionsAtRuntime$Exponential() { + let source = MGLShapeSource(identifier: "circles", shape: nil, options: nil) + let layer = MGLCircleStyleLayer(identifier: "circles", source: source) + + //#-example-code + let stops = [ + 12: MGLStyleValue<NSNumber>(rawValue: 0.5), + 14: MGLStyleValue(rawValue: 2), + 18: MGLStyleValue(rawValue: 18), + ] + + layer.circleRadius = MGLStyleValue(interpolationMode: .exponential, + cameraStops: stops, + options: [.interpolationBase: 1.5]) + //#-end-example-code + } + + func testUsingStyleFunctionsAtRuntime$Interval() { + let source = MGLShapeSource(identifier: "circles", shape: nil, options: nil) + let layer = MGLCircleStyleLayer(identifier: "circles", source: source) + + //#-example-code + #if os(macOS) + let stops = [ + 0: MGLStyleValue<NSColor>(rawValue: .yellow), + 2.5: MGLStyleValue(rawValue: .orange), + 5: MGLStyleValue(rawValue: .red), + 7.5: MGLStyleValue(rawValue: .blue), + 10: MGLStyleValue(rawValue: .white), + ] + + layer.circleColor = MGLStyleValue(interpolationMode: .interval, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<NSColor>(rawValue: .green)]) + #else + let stops = [ + 0: MGLStyleValue<UIColor>(rawValue: .yellow), + 2.5: MGLStyleValue(rawValue: .orange), + 5: MGLStyleValue(rawValue: .red), + 7.5: MGLStyleValue(rawValue: .blue), + 10: MGLStyleValue(rawValue: .white), + ] + + layer.circleColor = MGLStyleValue(interpolationMode: .interval, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)]) + #endif + //#-end-example-code + } + + func testUsingStyleFunctionsAtRuntime$Categorical() { + let source = MGLShapeSource(identifier: "circles", shape: nil, options: nil) + let layer = MGLCircleStyleLayer(identifier: "circles", source: source) + + //#-example-code + #if os(macOS) + let categoricalStops = [ + "earthquake": MGLStyleValue<NSColor>(rawValue: .orange), + "explosion": MGLStyleValue(rawValue: .red), + "quarry blast": MGLStyleValue(rawValue: .yellow), + ] + + layer.circleColor = MGLStyleValue(interpolationMode: .categorical, + sourceStops: categoricalStops, + attributeName: "type", + options: [.defaultValue: MGLStyleValue<NSColor>(rawValue: .blue)]) + #else + let categoricalStops = [ + "earthquake": MGLStyleValue<UIColor>(rawValue: .orange), + "explosion": MGLStyleValue(rawValue: .red), + "quarry blast": MGLStyleValue(rawValue: .yellow), + ] + + layer.circleColor = MGLStyleValue(interpolationMode: .categorical, + sourceStops: categoricalStops, + attributeName: "type", + options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .blue)]) + #endif + //#-end-example-code + } + + func testUsingStyleFunctionsAtRuntime$Identity() { + let source = MGLShapeSource(identifier: "circles", shape: nil, options: nil) + let layer = MGLCircleStyleLayer(identifier: "circles", source: source) + + //#-example-code + layer.circleRadius = MGLStyleValue(interpolationMode: .identity, + sourceStops: nil, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<NSNumber>(rawValue: 0)]) + //#-end-example-code + } +} |