rails_google_map 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c730ca865297fdd78afc25746eccf4de2b97b89b61ccf664387675da6239092
-  data.tar.gz: bfae7aa4b5883c2599ff1850b6b7a77369b7e38e0bd22927070edce3bd9c96f5
+  metadata.gz: 7526211ca0c5217b5f39c2e9724760e2c2dfaf639b60c216b622b9bc63beee0d
+  data.tar.gz: 85b6fc8fd7ccafb91636bae05abe1440a4d039eb93c8ea3a50e2afabd73a17da
 SHA512:
-  metadata.gz: 2f36c8ece99a43f71e0797bb46310341dc0e4c715bee3b94d95e691d74d6b31b8f6fe7e4f4c7c0acece0ab694eaa5d091a0797c0c884dbbca19fd03190861eae
-  data.tar.gz: 7e7c3d47db516653be733426afe6177e0cac2299f644b2bcf6f680f676d604247f99767a2979327ed6672f4a3893a112fa06750897d86a569c32de9a3394e514
+  metadata.gz: '0666917b75276658ab3e8d51b730094a7322ffdb84808ac3c6a2a95b24808f862870ce00bf6de0d2bcd34d18b3f822b60d25c94920273e229f1ed38ec2fd7dcf'
+  data.tar.gz: fff3ba9831489b023f4c39f662faf76414a465f747745185d6424446fe625eaf4832ca646f399b2646e9b1d12d8e015f650fb936a9b845ddff1f59ebc586e253

data/CHANGELOG.md

@@ -12,6 +12,13 @@
   so a map renders without a key or a billing account.
 - `RailsGoogleMap::Geocoder.coordinates_for` turns an address into coordinates
   via the Google Geocoding API.
+- `render_google_map` renders the map through an overridable partial, wrapper
+  div and all, and passes unrecognised options to it as extra locals.
+- `rails generate rails_google_map:views [--format slim|erb]` copies that partial
+  into the host app, where it takes precedence over the engine's.
+- `google_map_for` takes a `wrapper:` option (`true`, a CSS class, or a Hash of
+  attributes) for the same surrounding div without a template.
+- Configurable `wrapper_class`, `map_class` and `partial`.
 - Rails engine mixes the helpers into ActionView automatically.
 - Supports Ruby >= 2.5.1 and Rails (ActionView) 5.0 through 8.x.
 - Requires "logger" before ActionView, so Rails 5 and 6 still load against

data/README.md

@@ -13,6 +13,14 @@ for a staging box, a side project, or a page that just needs to show where you a
 <%= google_map_for("Thamel, Kathmandu") %>
 ```
 
+Three ways in, depending on how much of the markup you want to own:
+
+| | |
+| --- | --- |
+| `google_map_embed_url(query)` | just the URL — build your own markup |
+| `google_map_for(query, ...)` | an `<iframe>` tag, optionally wrapped in a div |
+| `render_google_map(query, ...)` | a partial you can copy into your app as ERB or Slim and edit |
+
 ## Installation
 
 Add it to your Gemfile:
@@ -63,6 +71,11 @@ RailsGoogleMap.configure do |config|
   config.width    = "100%"      # default iframe width
   config.height   = "450"       # default iframe height
   config.language = nil         # e.g. "en", "ne" — omitted when nil
+
+  # used by render_google_map and the partial
+  config.wrapper_class = "google-map"       # class on the surrounding div
+  config.map_class     = nil                # class on the iframe
+  config.partial       = "rails_google_map/map"
 end
 ```
 
@@ -105,10 +118,20 @@ Recognised options:
 | `language` | `nil` | Embed API only |
 | `api_key` | configured key | override the key for one call |
 | `lat` / `lng` | — | used when no address is given |
+| `wrapper` | `nil` | `true` for the configured wrapper class, a CSS class, or a Hash of div attributes |
 
 Any other option is passed straight through as an iframe attribute (`class`,
 `title`, `data`, …).
 
+By default it returns a bare `<iframe>`. Pass `wrapper:` to get the surrounding
+div without reaching for the partial:
+
+```erb
+<%= google_map_for("Thamel", wrapper: true) %>
+<%= google_map_for("Thamel", wrapper: "map-box", class: "partners-map") %>
+<%= google_map_for("Thamel", wrapper: { class: "map-box", data: { controller: "map" } }) %>
+```
+
 `google_map_for` returns `nil` when there is nothing to show — a blank address, or
 coordinates that are missing or `0,0`. So a caller can guard on it:
 
@@ -127,6 +150,72 @@ The same thing with a plain options hash, if that reads better at the call site:
 <%= embed_google_map(lat: 27.7172, long: 85.3240) %>
 ```
 
+### `render_google_map` — the full markup, from a partial you can edit
+
+`google_map_for` builds its tag in Ruby, so the markup is fixed. When you want to
+own the markup, `render_google_map` renders a partial instead — wrapper div and
+all:
+
+```slim
+= render_google_map(@business.map_query, title: t("partners.map_of", name: @business.name), map_class: "partners-map")
+```
+
+```erb
+<%= render_google_map(@business.map_query, title: t("partners.map_of", name: @business.name), map_class: "partners-map") %>
+```
+
+Both produce:
+
+```html
+<div class="google-map">
+  <iframe src="https://www.google.com/maps/embed?origin=mfe&amp;pb=!1m2!2m1!1sThamel%2C+Kathmandu"
+          class="partners-map" title="Map of Thamel" width="100%" height="450"
+          style="border:0;" loading="lazy"
+          referrerpolicy="no-referrer-when-downgrade"
+          allowfullscreen frameborder="0"></iframe>
+</div>
+```
+
+Like `google_map_for`, it returns `nil` when there is nothing to map, so the
+surrounding `if` is optional.
+
+Options: `title`, `wrapper_class`, `map_class`, `width`, `height`, plus the URL
+options (`zoom`, `map_type`, `language`, `api_key`) and `lat`/`lng`. Anything else
+is handed to the partial as an extra local, which is how a partial of your own
+receives its data:
+
+```erb
+<%= render_google_map(@business.address, partial: "maps/card", label: "Find us") %>
+```
+
+#### Editing the markup
+
+The gem ships the partial as ERB, which renders fine in a Slim app — Rails picks
+the handler per template. To change the markup, copy it into your app:
+
+```bash
+rails generate rails_google_map:views                 # app/views/rails_google_map/_map.html.erb
+rails generate rails_google_map:views --format slim   # app/views/rails_google_map/_map.html.slim
+```
+
+App view paths win over an engine's, so the copy takes over with no further
+configuration. The Slim copy is the markup you probably came here for:
+
+```slim
+- if url.present?
+  div class=wrapper_class
+    iframe src=url class=map_class title=title width=width height=height style="border:0;" loading="lazy" referrerpolicy="no-referrer-when-downgrade" allowfullscreen=true frameborder="0"
+```
+
+Or point at a partial of your own and leave the gem's alone:
+
+```ruby
+RailsGoogleMap.configure { |config| config.partial = "shared/google_map" }
+```
+
+Your partial receives `url`, `title`, `wrapper_class`, `map_class`, `width` and
+`height` as locals.
+
 ### `google_map_embed_url`
 
 Returns just the URL, for when you want to write the markup yourself:
@@ -158,7 +247,8 @@ API call fails.
 
 ### Outside Rails
 
-There's no dependency on a booted Rails app — include the helper anywhere:
+`google_map_embed_url` and `google_map_for` need no booted Rails app — include the
+helper anywhere. (`render_google_map` does need one, since it renders a template.)
 
 ```ruby
 require "rails_google_map"

data/app/views/rails_google_map/_map.html.erb

@@ -0,0 +1,42 @@
+<%#
+  Renders one embedded Google Map.
+
+  Locals -- #render_google_map passes all of them, and each falls back to a
+  configured default, so the partial also works when rendered directly:
+
+    url            the embed URL, from google_map_embed_url (required)
+    title          iframe title, read out by screen readers
+    wrapper_class  CSS class for the surrounding div
+    map_class      CSS class for the iframe; attribute omitted when blank
+    width, height  iframe dimensions
+
+  To change this markup, copy it into your own app and edit it there:
+    rails generate rails_google_map:views                  # ERB
+    rails generate rails_google_map:views --format slim   # Slim
+
+  content_tag drops attributes whose value is nil, which is how title and class
+  disappear when unset, and it escapes every value for us.
+%>
+<%
+  url           = local_assigns[:url]
+  title         = local_assigns[:title]
+  wrapper_class = local_assigns.fetch(:wrapper_class) { RailsGoogleMap.configuration.wrapper_class }
+  map_class     = local_assigns.fetch(:map_class)     { RailsGoogleMap.configuration.map_class }
+  width         = local_assigns.fetch(:width)         { RailsGoogleMap.configuration.width }
+  height        = local_assigns.fetch(:height)        { RailsGoogleMap.configuration.height }
+%>
+<% if url.present? %>
+  <div class="<%= wrapper_class %>">
+    <%= content_tag :iframe, "",
+          src: url,
+          class: map_class.presence,
+          title: title.presence,
+          width: width,
+          height: height,
+          style: "border:0;",
+          loading: "lazy",
+          referrerpolicy: "no-referrer-when-downgrade",
+          allowfullscreen: true,
+          frameborder: "0" %>
+  </div>
+<% end %>

data/lib/generators/rails_google_map/views/templates/_map.html.erb

@@ -0,0 +1,42 @@
+<%#
+  Renders one embedded Google Map.
+
+  Locals -- #render_google_map passes all of them, and each falls back to a
+  configured default, so the partial also works when rendered directly:
+
+    url            the embed URL, from google_map_embed_url (required)
+    title          iframe title, read out by screen readers
+    wrapper_class  CSS class for the surrounding div
+    map_class      CSS class for the iframe; attribute omitted when blank
+    width, height  iframe dimensions
+
+  To change this markup, copy it into your own app and edit it there:
+    rails generate rails_google_map:views                  # ERB
+    rails generate rails_google_map:views --format slim   # Slim
+
+  content_tag drops attributes whose value is nil, which is how title and class
+  disappear when unset, and it escapes every value for us.
+%>
+<%
+  url           = local_assigns[:url]
+  title         = local_assigns[:title]
+  wrapper_class = local_assigns.fetch(:wrapper_class) { RailsGoogleMap.configuration.wrapper_class }
+  map_class     = local_assigns.fetch(:map_class)     { RailsGoogleMap.configuration.map_class }
+  width         = local_assigns.fetch(:width)         { RailsGoogleMap.configuration.width }
+  height        = local_assigns.fetch(:height)        { RailsGoogleMap.configuration.height }
+%>
+<% if url.present? %>
+  <div class="<%= wrapper_class %>">
+    <%= content_tag :iframe, "",
+          src: url,
+          class: map_class.presence,
+          title: title.presence,
+          width: width,
+          height: height,
+          style: "border:0;",
+          loading: "lazy",
+          referrerpolicy: "no-referrer-when-downgrade",
+          allowfullscreen: true,
+          frameborder: "0" %>
+  </div>
+<% end %>

data/lib/generators/rails_google_map/views/templates/_map.html.slim

@@ -0,0 +1,19 @@
+/ Renders one embedded Google Map.
+  Locals -- #render_google_map passes all of them; each has a sensible default
+  so the partial also works when rendered directly:
+    url            the embed URL, from google_map_embed_url (required)
+    title          iframe title, read out by screen readers
+    wrapper_class  CSS class for the surrounding div
+    map_class      CSS class for the iframe; omitted when blank
+    width, height  iframe dimensions
+
+- url           = local_assigns[:url]
+- title         = local_assigns[:title]
+- wrapper_class = local_assigns.fetch(:wrapper_class) { RailsGoogleMap.configuration.wrapper_class }
+- map_class     = local_assigns.fetch(:map_class)     { RailsGoogleMap.configuration.map_class }
+- width         = local_assigns.fetch(:width)         { RailsGoogleMap.configuration.width }
+- height        = local_assigns.fetch(:height)        { RailsGoogleMap.configuration.height }
+
+- if url.present?
+  div class=wrapper_class
+    iframe src=url class=map_class title=title width=width height=height style="border:0;" loading="lazy" referrerpolicy="no-referrer-when-downgrade" allowfullscreen=true frameborder="0"

data/lib/generators/rails_google_map/views/views_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RailsGoogleMap
+  module Generators
+    # Copies the map partial into the host app so its markup can be edited:
+    #
+    #   rails generate rails_google_map:views
+    #   rails generate rails_google_map:views --format slim
+    #
+    # App view paths take precedence over the engine's, so the copy is picked
+    # up with no further configuration.
+    class ViewsGenerator < Rails::Generators::Base
+      FORMATS = %w[erb slim].freeze
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Copies rails_google_map's map partial into app/views so you can edit it."
+
+      # No short alias here on purpose: Thor already claims -f for --force.
+      class_option :format, type: :string, default: "erb",
+                            desc: "Template format to copy: #{FORMATS.join(' or ')}"
+
+      def copy_map_partial
+        format = options[:format].to_s.downcase
+        unless FORMATS.include?(format)
+          raise Thor::Error, "Unknown format #{options[:format].inspect}. Use #{FORMATS.join(' or ')}."
+        end
+
+        copy_file "_map.html.#{format}", "app/views/rails_google_map/_map.html.#{format}"
+      end
+    end
+  end
+end

data/lib/rails_google_map/configuration.rb

@@ -24,6 +24,14 @@ module RailsGoogleMap
     attr_accessor :width, :height
     # Language for map labels, e.g. "en" or "ne" (Embed API only).
     attr_accessor :language
+    # CSS class for the div the partial wraps the map in.
+    attr_accessor :wrapper_class
+    # CSS class applied to the iframe itself. Nil leaves the attribute off.
+    attr_accessor :map_class
+    # Partial that #render_google_map renders. Override it in your own app by
+    # creating a template at the same path -- app view paths win over the
+    # engine's -- or point this at a partial of your own.
+    attr_accessor :partial
 
     def initialize
       @api_key  = ENV["GOOGLE_MAPS_EMBED_KEY"] || ENV["GOOGLE_MAPS_API_KEY"]
@@ -32,6 +40,9 @@ module RailsGoogleMap
       @width    = "100%"
       @height   = "450"
       @language = nil
+      @wrapper_class = "google-map"
+      @map_class = nil
+      @partial = "rails_google_map/map"
     end
 
     # True when an API key is present, i.e. when the Maps Embed API can be used.

data/lib/rails_google_map/map_helper.rb

@@ -34,9 +34,10 @@ module RailsGoogleMap
     #
     # Any option other than the ones named below is passed straight through as
     # an iframe attribute, e.g. `class: "map"` or `title: "Our office"`.
-    def google_map_for(query = nil, width: nil, height: nil, zoom: nil,
+    def google_map_for(query = nil, wrapper: nil, width: nil, height: nil, zoom: nil,
                        map_type: nil, language: nil, api_key: nil, **html_options)
-      query = map_query(query, html_options.delete(:lat), html_options.delete(:lng) || html_options.delete(:long))
+      query = google_map_query(query, html_options.delete(:lat),
+                               html_options.delete(:lng) || html_options.delete(:long))
       src = google_map_embed_url(query, zoom: zoom, map_type: map_type,
                                         language: language, api_key: api_key)
       return if src.nil?
@@ -44,6 +45,7 @@ module RailsGoogleMap
       config = RailsGoogleMap.configuration
       attributes = {
         src: src,
+        class: config.map_class,
         width: width || config.width,
         height: height || config.height,
         style: "border:0;",
@@ -53,7 +55,45 @@ module RailsGoogleMap
         frameborder: "0"
       }.merge(html_options)
 
-      content_tag(:iframe, "", attributes)
+      iframe = content_tag(:iframe, "", attributes)
+      wrapper_attributes = google_map_wrapper_attributes(wrapper, config)
+      return iframe if wrapper_attributes.nil?
+
+      content_tag(:div, iframe, wrapper_attributes)
+    end
+
+    # Renders the map through a partial instead of building the tag in Ruby, so
+    # the markup is yours to change. Ships as ERB; run
+    #
+    #   rails generate rails_google_map:views --format slim
+    #
+    # to copy it into your app as Slim (or ERB) and edit it there -- app view
+    # paths win over the engine's, so the copy takes over automatically.
+    #
+    #   = render_google_map(@business.map_query, title: t("partners.map_of", name: @business.name))
+    #   = render_google_map(@business.address, map_class: "partners-map")
+    #
+    # Returns nil when there is nothing to map, exactly like #google_map_for.
+    # Options it does not recognise are passed to the partial as extra locals,
+    # which is how a custom partial receives its own data.
+    def render_google_map(query = nil, partial: nil, title: nil, wrapper_class: nil,
+                          map_class: nil, width: nil, height: nil, zoom: nil,
+                          map_type: nil, language: nil, api_key: nil, **locals)
+      query = google_map_query(query, locals.delete(:lat),
+                               locals.delete(:lng) || locals.delete(:long))
+      url = google_map_embed_url(query, zoom: zoom, map_type: map_type,
+                                        language: language, api_key: api_key)
+      return if url.nil?
+
+      config = RailsGoogleMap.configuration
+      render(partial: partial || config.partial, locals: {
+        url: url,
+        title: title,
+        wrapper_class: wrapper_class || config.wrapper_class,
+        map_class: map_class || config.map_class,
+        width: width || config.width,
+        height: height || config.height
+      }.merge(locals))
     end
 
     # The embeddable Google Maps URL for +query+ (an address or a "lat,lng").
@@ -100,12 +140,26 @@ module RailsGoogleMap
     # An address wins over coordinates: lat/lng columns are often unreliable
     # (many rows share one default pin), so they only stand in when no address
     # was given. Treats 0/nil coordinates as "no pin".
-    def map_query(address, lat, lng)
+    def google_map_query(address, lat, lng)
       return address.to_s.strip unless address.nil? || address.to_s.strip.empty?
       return if lat.nil? || lng.nil?
       return if lat.to_f.zero? && lng.to_f.zero?
 
       "#{lat},#{lng}"
     end
+
+    # wrapper: nil/false -> bare iframe; true -> the configured wrapper class;
+    # a String -> that class; a Hash -> attributes for the surrounding div.
+    def google_map_wrapper_attributes(wrapper, config)
+      case wrapper
+      when nil, false then nil
+      when true       then { class: config.wrapper_class }
+      when String, Symbol then { class: wrapper.to_s }
+      when Hash       then wrapper
+      else
+        raise ArgumentError,
+              "wrapper must be true, false, a CSS class or a Hash of attributes, got #{wrapper.class}"
+      end
+    end
   end
 end

data/lib/rails_google_map/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsGoogleMap
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/sig/rails_google_map.rbs

@@ -14,6 +14,9 @@ module RailsGoogleMap
     attr_accessor width: String | Integer | nil
     attr_accessor height: String | Integer | nil
     attr_accessor language: String?
+    attr_accessor wrapper_class: String?
+    attr_accessor map_class: String?
+    attr_accessor partial: String
 
     def initialize: () -> void
     def api_key?: () -> bool
@@ -27,7 +30,8 @@ module RailsGoogleMap
     EMBED_API_URL: String
     KEYLESS_EMBED_URL: String
 
-    def google_map_for: (?untyped query, ?width: untyped, ?height: untyped, ?zoom: Integer?, ?map_type: String?, ?language: String?, ?api_key: String?, **untyped) -> untyped
+    def google_map_for: (?untyped query, ?wrapper: untyped, ?width: untyped, ?height: untyped, ?zoom: Integer?, ?map_type: String?, ?language: String?, ?api_key: String?, **untyped) -> untyped
+    def render_google_map: (?untyped query, ?partial: String?, ?title: String?, ?wrapper_class: String?, ?map_class: String?, ?width: untyped, ?height: untyped, ?zoom: Integer?, ?map_type: String?, ?language: String?, ?api_key: String?, **untyped) -> untyped
     def google_map_embed_url: (untyped query, ?zoom: Integer?, ?map_type: String?, ?language: String?, ?api_key: String?) -> String?
     def embed_google_map: (?Hash[untyped, untyped] options) -> untyped
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_google_map
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Bikash Shrestha
@@ -46,6 +46,10 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- app/views/rails_google_map/_map.html.erb
+- lib/generators/rails_google_map/views/templates/_map.html.erb
+- lib/generators/rails_google_map/views/templates/_map.html.slim
+- lib/generators/rails_google_map/views/views_generator.rb
 - lib/rails_google_map.rb
 - lib/rails_google_map/configuration.rb
 - lib/rails_google_map/engine.rb
@@ -58,7 +62,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/sthaB-kash/rails_google_map
-  source_code_uri: https://github.com/sthaB-kash/rails_google_map/tree/v0.1.0
+  source_code_uri: https://github.com/sthaB-kash/rails_google_map/tree/v0.2.0
   changelog_uri: https://github.com/sthaB-kash/rails_google_map/blob/master/CHANGELOG.md
   bug_tracker_uri: https://github.com/sthaB-kash/rails_google_map/issues
   documentation_uri: https://github.com/sthaB-kash/rails_google_map#readme