diff --git a/README.md b/README.md index 690dc07..8cb9159 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # jekyll-apple-maps [![CircleCI](https://dl.circleci.com/status-badge/img/circleci/aW12qZgMpxbXNYTbdzFe5/FS3eDPqnpMpZJ2cKYi2aN9/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/circleci/aW12qZgMpxbXNYTbdzFe5/FS3eDPqnpMpZJ2cKYi2aN9/tree/main) [![codecov](https://codecov.io/gh/ZekeSnider/jekyll-apple-maps/graph/badge.svg?token=2V7NFD77OL)](https://codecov.io/gh/ZekeSnider/jekyll-apple-maps) -Apple Maps plugin for Jekyll +![Hero image for jekyll-apple-maps](/assets/hero_image.png) -This gem provides [Jekyll](https://jekyllrb.com) integrations for [Apple Maps server APIs](https://developer.apple.com/documentation/applemapsserverapi/). Currently it supports the following APIs: +This gem provides [Jekyll](https://jekyllrb.com) integrations for the [Apple Maps server APIs](https://developer.apple.com/documentation/applemapsserverapi/). It allows you to include Apple Maps content in your site using Jekyll Liquid tags. Currently it supports the following APIs: + [Snapshots](https://developer.apple.com/documentation/snapshots) + Supports both light and dark modes with dynamic `picture` tags @@ -59,6 +59,7 @@ The following parameters are accepted by the block: + `zoom` - Zoom level with the range of `3` to `20`. Defaults to `12`. + `width` - Pixel width of the image. Defaults to `600`. + `height` - Pixel height of the image. Defaults to `300`. ++ `scale` - The pixel density of the image. Valid values are `1`, `2`, `3`. Defaults to `2`. + `color_schemes` - Array of which color schemes to generate for the map. Options are `light` and `dark`. Defaults to both (`['light', 'dark']`). + `overlays` - An array of [overlay objects](https://developer.apple.com/documentation/snapshots/overlay). Defaults to empty `[]`. + `annotations` - An array of [annotation objects](https://developer.apple.com/documentation/snapshots/annotation). Defaults to empty `[]`. @@ -66,23 +67,89 @@ The following parameters are accepted by the block: + `images` - An array of [image objects](https://developer.apple.com/documentation/snapshots/image) for annotations. Defaults to empty `[]`. #### Examples +A map with a single annotation ``` {% apple_maps_snapshot_block %} - center: "33.24767,115.73192" - show_poi: 1 - zoom: 14 + center: "33.24767,-115.73192" + show_poi: true + zoom: 6 width: 600 - height: 150 + height: 400 annotations: [ { - "point": "33.24767,115.73192", - "color": "449944", - "glyphText": "Salton Sea", + "point": "33.24767,-115.73192", + "color":"449944", + "glyphText": "S", "markerStyle": "large" } ] {% endapple_maps_snapshot_block %} ``` +![Example map using a single annotation](/assets/single_annotation.png) + +Using an image annotation +``` +{% apple_maps_snapshot_block %} + center: "33.24767,-115.73192" + show_poi: false + zoom: 8 + width: 600 + height: 400 + color_schemes: ["dark"] + annotations: [ + { + "markerStyle": "img", + "imgIdx": 0, + "point":"33.24767,-115.73192", + "color":"449944", + "offset": "0,15" + } + ] + images: [ + { + "url": "https://www.iconfinder.com/icons/2376758/download/png/48", + "height": 48, + "width": 48 + } + ] +{% endapple_maps_snapshot_block %} +``` +![Example map using an image annotation](/assets/image_annotation.png) + +A map with multiple annotations +``` +{% apple_maps_snapshot_block %} + center: "37.772318, -122.447326" + zoom: 11.5 + width: 600 + height: 400 + annotations: [ + { + "point": "37.819724, -122.478557", + "color":"red", + "glyphText": "G", + "markerStyle": "large" + }, + { + "point": "37.750472,-122.484132", + "color": "blue", + "glyphText": "S", + "markerStyle": "large" + }, + { + "point": "37.755217, -122.452776", + "color": "red", + "markerStyle": "balloon" + }, + { + "point": "37.778457, -122.389238", + "color": "orange", + "markerStyle": "dot" + } + ] +{% endapple_maps_snapshot_block %} +``` +![Example map using multiple annotations](/assets/multiple_annotations.png) ## Rate limiting Apple specifies the following limits on usage of the Apple Maps Server APIs. This plugin caches snapshot images for the same parameters to avoid regenerating images. But if you initially generate a large number of snapshots (>25,000), you may exceed this limit. @@ -107,6 +174,17 @@ gem build jekyll-apple-maps.gemspec gem install ./jekyll-apple-maps-1.0.0.gem ``` +You can also use the local version of this gem from your gemfile: ``` gem 'jekyll-apple-maps', path: '/PathHere/jekyll-apple-maps' +``` + +There's also a CLI utility for testing templates. ++ `-s` Is the source directory where the maps assets should be written to ++ `-r` Is the referer header to use for the request ++ `-h` prints help options + +When you execute the script you'll paste in the full template text (as seen above in examples). +``` +./script/render.rb -s /YourUser/Developer/jekyll-test -r https://example.com ``` \ No newline at end of file diff --git a/assets/hero_image.png b/assets/hero_image.png new file mode 100644 index 0000000..fae4eeb Binary files /dev/null and b/assets/hero_image.png differ diff --git a/assets/image_annotation.png b/assets/image_annotation.png new file mode 100644 index 0000000..75e6cde Binary files /dev/null and b/assets/image_annotation.png differ diff --git a/assets/multiple_annotations.png b/assets/multiple_annotations.png new file mode 100644 index 0000000..26fc4b1 Binary files /dev/null and b/assets/multiple_annotations.png differ diff --git a/assets/single_annotation.png b/assets/single_annotation.png new file mode 100644 index 0000000..f49baf0 Binary files /dev/null and b/assets/single_annotation.png differ diff --git a/jekyll-apple-maps.gemspec b/jekyll-apple-maps.gemspec index 0c19d04..68e2496 100644 --- a/jekyll-apple-maps.gemspec +++ b/jekyll-apple-maps.gemspec @@ -5,7 +5,7 @@ Gem::Specification.new do |spec| spec.email = ["zekesnider@me.com"] spec.summary = %q{Apple Maps plugin for Jekyll} - spec.description = %q{Longer description of your plugin} + spec.description = %q{Provides tags for the Jekyll blogging engine to generate Apple Maps content for your site.} spec.homepage = "https://github.com/zekesnider/jekyll-apple-maps" spec.license = "Apache-2.0" diff --git a/script/render.rb b/script/render.rb new file mode 100755 index 0000000..d6f1f51 --- /dev/null +++ b/script/render.rb @@ -0,0 +1,72 @@ +#!/usr/bin/env ruby + +require 'jekyll' +require 'liquid' +require 'optparse' +require_relative '../lib/jekyll/apple_maps/snapshot_block' + +# Parse command line options +options = {} +OptionParser.new do |opts| + opts.banner = "Usage: #{$PROGRAM_NAME} [options]" + + opts.on("-s", "--source DIR", "Specify the source DIR") do |dir| + options[:source] = dir + end + + opts.on("-r", "--referer URL", "Specify the referer URL") do |url| + options[:referer] = url + end + + opts.on("-h", "--help", "Prints this help") do + puts opts + exit + end +end.parse! + +# Check for required options +if options[:source].nil? || options[:referer].nil? + puts "Error: Both source directory (-s) and referer URL (-r) are required." + puts "Use -h or --help for usage information." + exit 1 +end + +# Mock site and context +class MockSite < Jekyll::Site + attr_reader :source, :config + + def initialize(source, referer) + @config = Jekyll.configuration({'source' => source}) + @config['apple_maps'] = { 'referer' => referer } if referer + super(@config) + @static_files = [] + @source = source + end +end + +site = MockSite.new(options[:source], options[:referer]) +context = Liquid::Context.new({}, {}, { site: site }, { strict_variables: true, strict_filters: true }) + +# Register the custom tag +Liquid::Template.register_tag('apple_maps_snapshot_block', Jekyll::AppleMaps::SnapshotBlock) + +puts "Enter your Apple Maps Snapshot template (press Ctrl+D when finished):" +template = STDIN.read + +begin + # Parse the entire template + template = Liquid::Template.parse(template) + + # Render the template + result = template.render(context) + + puts "\nRendered output:" + puts result +rescue => e + puts "\nError occurred:" + puts e.message + puts e.backtrace.join("\n") +end + +puts "\nSite source directory: #{site.source}" +puts "Apple Maps referer: #{site.config.dig('apple_maps', 'referer') || ''}" diff --git a/spec/jekyll/apple_maps/snapshot_block_spec.rb b/spec/jekyll/apple_maps/snapshot_block_spec.rb index 32a7e04..e00398b 100644 --- a/spec/jekyll/apple_maps/snapshot_block_spec.rb +++ b/spec/jekyll/apple_maps/snapshot_block_spec.rb @@ -17,7 +17,7 @@ { "point": "33.24767,115.73192", "color":"449944", - "glyphText": "Salton Sea", + "glyphText": "S", "markerStyle": "large" } ] @@ -81,7 +81,7 @@ def image_assets context 'with light and dark mode' do it 'generates a picture tag' do expected_params = { - :annotations=>"[{\"point\":\"33.24767,115.73192\",\"color\":\"449944\",\"glyphText\":\"Salton Sea\",\"markerStyle\":\"large\"}]", + :annotations=>"[{\"point\":\"33.24767,115.73192\",\"color\":\"449944\",\"glyphText\":\"S\",\"markerStyle\":\"large\"}]", :center=>"auto", :imgs=>"[]", :lang=>"en-US", @@ -91,7 +91,7 @@ def image_assets :scale=>2, :size=>"600x150", :t=>"standard", - :z=>14 + :z=>14, } expect(client).to receive(:fetch_snapshot) @@ -102,7 +102,7 @@ def image_assets .once rendered_content = subject.render(context) - expect(rendered_content).to eq("Map of location") + expect(rendered_content).to eq("Map of location") # Re-render to test regeneration of the same hash subject.render(context) @@ -163,8 +163,8 @@ def image_assets expect(image_assets.length).to eq(4) Jekyll::Hooks.trigger :site, :post_write, site expect(image_assets.length).to eq(2) - expect(image_assets).to contain_exactly("/tmp/test_site/assets/maps/apple_maps_snapshot_72371e4c60df063e0bfa66136639392ddaae749743afbf4440b9998405ebeb2a.png", - "/tmp/test_site/assets/maps/apple_maps_snapshot_d8c698f67c560f562a3c46f07199bea93cf10c53832f60281725e4a58118cd6c.png") + expect(image_assets).to contain_exactly("/tmp/test_site/assets/maps/apple_maps_snapshot_7781e90ed95e1f4e0cc83da226eb2c8ee88de95a958cf31ed696979a4f2e3c15.png", + "/tmp/test_site/assets/maps/apple_maps_snapshot_a5aaa99bc91e5c070fb09cf89bbacadc95e6a9651a151d0f7a2a7e0192fc968a.png") end end end diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb index 113da7d..b277760 100644 --- a/spec/spec_helper.rb +++ b/spec/spec_helper.rb @@ -9,6 +9,8 @@ ] SimpleCov.start do add_filter '/spec/' + add_filter '/script/' + add_filter '/assets/' end RSpec.configure do |config|