[Cookbook] Practical use of scoped slots with GoogleMaps #1754

mateuszRybczonek · 2018-08-14T19:56:09Z

@sdras a PR related to #1698

michalsnik · 2018-08-14T20:11:02Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+Imagine a component that configures and prepares an external API to be used in another component, but is not tightly coupled with any specific template. Such a component could then be reused in multiple places rendering different templates but using the same base object with specific API.
+
+We'll create a component (`GoogleMapLoader.vue`) that initializes `Google Maps API`, creates a `google` and `map` objects and exposes those objects to the parent component in which the `GoogleMapLoader` is used.


It sounds that the whole parent will have access to it, whereas it is limited to children of the rendered component in the parent context. What do you think about: and exposes those objects to its potential children via slot ?

and exposes those objects to its potential children in the template of a parent component in which the GoogleMapLoader is used

I think we should additionally point out that those children must exist in the parent template.

michalsnik · 2018-08-14T20:24:17Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+```html
+<template>
+  <div>
+    <div id="map" :style="{ height: mapHeight }"></div>


As this is a component that might be used in multiple places, I think you should avoid using id, and instead use .js- prefixed class or data attribute. WDYT?

Also shouldn't height ideally come from CSS - that is shouldn't the map element take 100% of available space? For the sake of simplicity.

michalsnik · 2018-08-14T20:30:19Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+<template>
+  <div>
+    <div id="map" :style="{ height: mapHeight }"></div>
+    <template v-if="!!this.google && !!this.map">


What do you think about using more semantic Boolean() function instead of double negation?

michalsnik · 2018-08-14T20:31:30Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+The template part will look as below
+
+```html
+<template>


I recommend adding comment above each code snippet - indicating what file is it. It makes reading way easier.

michalsnik · 2018-08-14T20:38:14Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+### Create component that uses our initializer component.
+
+`VesselsGoogleMap.vue`


Perhaps for the sake of this cookbook example you should use more generic example like ContactMap?

michalsnik · 2018-08-14T20:43:23Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+### Expose `google` and `map` properties to the parent component by adding a scoped slot.
+
+So finally we can add a scoped slot that will do the job and allow us to access the child component props in the parent component. We do that by adding the `<slot>` tag in the child component and passing the props that we want to expose (using `v-bind` directive or `:propName` shorthand). It does not differ from passing the props down to the child component, but by doing it in the `<slot>` tag reverse the direction of data flow.


I think the by in but by doing it in the ... sentence is redundant 🤔

michalsnik · 2018-08-14T20:57:07Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+- both of them receive `google` from which we extract required object (Marker or Polyline) and `map` which gives as a reference to the map on which we want to place our element.
+
+- each receive also a prop with data required to create a corresponding element.


WDYT? each component specifies/expects also an extra prop to create a ...

michalsnik · 2018-08-14T20:58:45Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+To add elements to our map we render the factory component and pass the `google` and `map` objects.
+
+We also need to provide data required by the element itself (in our case `marker` object with position of the marker, `path` object with polyline coordinates.


It looks like the parenthesis is not closed.

and keyword would probably sound a bit nicer: of the marker and .... WDYT?

michalsnik · 2018-08-14T21:02:36Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+  data () {
+    return {
+      mapSettings,


mapSettings in data seems to be redundant, isn't it?

michalsnik · 2018-08-14T21:34:19Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+  methods: {
+    initializeMap() {
+      const mapContainer = this.$el.querySelector("#map");
+      const { Map } = this.google.maps;


I'd be careful about destructuring Map as this is also a native constructor in ES6. I think we shouldn't avoid shadowing these kind of objects as it might have unintended consequences and might introduce confusion. Do you agree?

mateuszRybczonek · 2018-08-27T10:55:20Z

@sdras

Would you be able to take a look anytime soon? :)

sdras · 2018-08-27T13:59:47Z

Yes, sorry about the delay, I'll take a look in the next day or so.

phanan · 2018-09-16T13:13:58Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+    return {
+      google: null,
+      map: null
+    };


Let's follow Vue's code style by removing semicolons :)

phanan · 2018-09-16T13:16:12Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+## Wrapping Up
+That's it. With all those bits and pieces created we can now re-use the `GoogleMapLoader` component as a base for all our maps by passing different templates to each one of them. Imagine that you need to create another map with different Markers or just Markers without Polylines. By using the above pattern it becomes very easy as we just need to pass different content to the `GoogleMapLoader` component.
+This pattern is not strictly connected to Google Maps, it can be used with any library to set the base component and expose the library's API that might be then used in the component that summoned the base component.


Need an empty line.

Grammatically speaking, it should be a semicolon instead of a comma (; it can be…).

phanan · 2018-09-16T13:16:27Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+```
+
+## When To Avoid This Pattern
+It might be tempting to create a very complex solutions based on the example, but at some point we can get to the situation where this abstraction becomes an independent part of the code living in our codebase. If we get to that point it might be worth considering extraction to an add-on.


solution (singular).

phanan · 2018-09-16T13:17:25Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+Yeah, ok, but why would I do things like that, what is the use of all that?
+
+Scoped slots allow us to pass a template to the slot instead of passing a rendered element. It’s called a “scoped” slot because although the template is rendered in the parent component scope, it will have access to certain child component data. That gives us a freedom to fill the template with custom content from the parent component.


I'd suggest "This gives us the freedom" instead.

phanan · 2018-09-16T13:19:01Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+After doing that even though the `google` and `map` props does not exist in the `TravelMap` scope, the component has access to them and we can use them in the template.
+
+Yeah, ok, but why would I do things like that, what is the use of all that?


This question here is kind of out of the blue. We can instead go for something like "You might wonder…"

sdras

Overall this looks really good! I think it's a great addition, we really need something that covers scoped slots in depth and google maps is a great and common example.

I saw your post come through CSS-Tricks too, which is cool! I think it's cool to cross-post when it's good quality. Do you want to mention and link from one to the other?

I think there's a little bit of clean up work from comments from me and @phanan, but it's getting there. I also noticed some really nice additions in the CSS-Tricks version that might be stronger if added here as well.

Thanks!

sdras · 2018-09-20T21:13:36Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+---
+title: Practical use of scoped slots with GoogleMaps
+type: cookbook
+order: 11


This order needs to be updated as 11 is already taken now. I think we're on 13 with base 0 index but worth double checking.

sdras · 2018-09-20T21:14:24Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+```html
+<template>
+  <div>
+    <div class="google-map" data-google-map></div>


I think this would be better served as a ref like ref="googlemap" so you don't have to use a query selector below.

sdras · 2018-09-20T21:15:07Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+  methods: {
+    initializeMap() {
+      const mapContainer = this.$el.querySelector("[data-google-map]");


See earlier comment, this would become const mapContainer = this.$refs.googlemap

sdras · 2018-09-20T21:15:46Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+Inside the script part:
+
+- we receive props from the parent component which will allow us to set the Google Map:


All of these bullets should be capitalized as they are far from eachother.

I removed the bullets from here

sdras · 2018-09-20T21:17:10Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+  },
+```
+
+- on `mounted` hook we create an instance of `GoogleMapsApi` and `Map` object from the `GoogleMapsApi` and we set the values of `google` and `map` to the created instances


I think it's a bit confusing here to use the term "created" in the same sentence that you're using to describe another lifecycle hook as created is one as well. Please use a different word here, thanks.

sdras · 2018-09-20T21:18:32Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+So far so good, with that done we could continue adding the other objects to the map (Markers, Polylines, etc.) and using it as a ordinary map component. But we want to use our `GoogleMapLoader` component only as a loader that prepares the map, not renders anything on it.
+
+To achieve that we need to allow parent component that will use our `GoogleMapLoader` to access `this.google` and `this.map` that are set inside the `GoogleMapLoader` component. That's where `scoped slots` really shine. Scoped slots allow us to expose the properties set in a child component to the parent component. It may sound like an inception, but bear with me one more minute.


"inception" literally means to begin something, so it wouldn't apply in this case. I think what you're referring to is the movie. This would need then to be rephrased to "It may sound like Inception, but..."

sdras · 2018-09-20T21:19:52Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+<script>
+import GoogleMapLoader from './GoogleMapLoader'
+
+import {


We don't need this to be split across three lines- actually there's a bit of formatting that's off in this code sample. Can you please correct to:

import GoogleMapLoader from './GoogleMapLoader' import { mapSettings } from '@/constants/mapSettings' export default { components: { GoogleMapLoader }, computed: { mapConfig() { return { ...mapSettings, center: { lat: 0, lng: 0 } } } } }

sdras · 2018-09-20T21:20:40Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+};
+```
+
+- both of them receive `google` from which we extract required object (Marker or Polyline) and `map` which gives as a reference to the map on which we want to place our element


Please capitalize these as well :)

Bullets removed from here as well.

mateuszRybczonek · 2018-10-08T14:32:38Z

@sdras @phanan, suggestions applied, please re-check 👁 when you find some time.

sdras · 2018-10-08T21:22:04Z

This is looking really great! The order should actually be 14, I just looked and there is already a 13. That's probably why the netlify build is failing. I think we're almost there.

mateuszRybczonek · 2018-10-09T07:56:15Z

@sdras 14 looks good 👍, thanks.

mateuszRybczonek · 2018-10-19T11:54:57Z

@sdras any chance of getting another review round from you? :)

sdras · 2018-10-19T14:50:47Z

Yes, great job! Congrats!

alexdilley · 2018-10-19T18:07:33Z

src/v2/cookbook/practical-use-of-scoped-slots.md

+
+  methods: {
+    initializeMap() {
+      const mapContainer = this.$refs.googleMap)


You've got a parenthesis loitering at the end there.

Good catch! @mateuszRybczonek do you want to put in another PR for that or if not I can grab it sometime

PR with fix here - #1848, @alexdilley thanks for spotting that 👍

np! I'm selfishly only using merged commit notifications as a way to keep up to speed on new documentation hence not picking up sooner; your entry was an interesting read!

It's maybe not the remit of a recipe in a cookbook, but I, as a reader, was curious to understand why this approach is more appropriate than simply setting up the loader in the parent component, for example, or perhaps more globally in a Vuex store. I think the answer is "reusability", "encapsulation" and "separation of concerns", but I then question how many types of map-related workflows you'd typically find in a project whose requirements couldn't be satisfied by a single, general-purpose map component...splitting concerns and avoiding an unwieldy "god component", maybe? Please appreciate that I may be completely missing the point, for which I apologise!!

There's a lot of buzz around this pattern, with it being a common go-to for those "in the know", and it might be pertinent – with such an example as this as context – to explain why this would be the tool to reach for in this case.

Mateusz Rybczonek added 5 commits August 13, 2018 12:16

initial version

91fb9bb

minor corrections

3b96ae9

add codesandbox link

eced9f7

corrections

5e04b15

further corrections

8a53646

michalsnik reviewed Aug 14, 2018

View reviewed changes

apply CR corrections

3700fe9

phanan reviewed Sep 16, 2018

View reviewed changes

phanan requested changes Sep 16, 2018

View reviewed changes

sdras suggested changes Sep 20, 2018

View reviewed changes

apply CR suggestions

ada7126

set proper order value

7059fcd

phanan approved these changes Oct 9, 2018

View reviewed changes

sdras approved these changes Oct 19, 2018

View reviewed changes

sdras merged commit dbd90a2 into vuejs:master Oct 19, 2018

alexdilley reviewed Oct 19, 2018

View reviewed changes

mateuszRybczonek mentioned this pull request Oct 21, 2018

Cookbook - [14] - Practical use of scoped slots with GoogleMaps - follow-up #1848

Merged

NataliaTepluhina mentioned this pull request Feb 18, 2019

[Cookbook] Use of slot-scope #1513

Closed


		Imagine a component that configures and prepares an external API to be used in another component, but is not tightly coupled with any specific template. Such a component could then be reused in multiple places rendering different templates but using the same base object with specific API.

		We'll create a component (`GoogleMapLoader.vue`) that initializes `Google Maps API`, creates a `google` and `map` objects and exposes those objects to the parent component in which the `GoogleMapLoader` is used.


		### Create component that uses our initializer component.

		`VesselsGoogleMap.vue`


		### Expose `google` and `map` properties to the parent component by adding a scoped slot.

		So finally we can add a scoped slot that will do the job and allow us to access the child component props in the parent component. We do that by adding the `<slot>` tag in the child component and passing the props that we want to expose (using `v-bind` directive or `:propName` shorthand). It does not differ from passing the props down to the child component, but by doing it in the `<slot>` tag reverse the direction of data flow.


		- both of them receive `google` from which we extract required object (Marker or Polyline) and `map` which gives as a reference to the map on which we want to place our element.

		- each receive also a prop with data required to create a corresponding element.


		To add elements to our map we render the factory component and pass the `google` and `map` objects.

		We also need to provide data required by the element itself (in our case `marker` object with position of the marker, `path` object with polyline coordinates.


		Yeah, ok, but why would I do things like that, what is the use of all that?

		Scoped slots allow us to pass a template to the slot instead of passing a rendered element. It’s called a “scoped” slot because although the template is rendered in the parent component scope, it will have access to certain child component data. That gives us a freedom to fill the template with custom content from the parent component.


		After doing that even though the `google` and `map` props does not exist in the `TravelMap` scope, the component has access to them and we can use them in the template.

		Yeah, ok, but why would I do things like that, what is the use of all that?


		Inside the script part:

		- we receive props from the parent component which will allow us to set the Google Map:


		So far so good, with that done we could continue adding the other objects to the map (Markers, Polylines, etc.) and using it as a ordinary map component. But we want to use our `GoogleMapLoader` component only as a loader that prepares the map, not renders anything on it.

		To achieve that we need to allow parent component that will use our `GoogleMapLoader` to access `this.google` and `this.map` that are set inside the `GoogleMapLoader` component. That's where `scoped slots` really shine. Scoped slots allow us to expose the properties set in a child component to the parent component. It may sound like an inception, but bear with me one more minute.

[Cookbook] Practical use of scoped slots with GoogleMaps #1754

[Cookbook] Practical use of scoped slots with GoogleMaps #1754

Uh oh!

Conversation

mateuszRybczonek commented Aug 14, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mateuszRybczonek commented Aug 27, 2018

Uh oh!

sdras commented Aug 27, 2018

Uh oh!

phanan Sep 16, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sdras left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mateuszRybczonek commented Oct 8, 2018

Uh oh!

sdras commented Oct 8, 2018

Uh oh!

mateuszRybczonek commented Oct 9, 2018

Uh oh!

mateuszRybczonek commented Oct 19, 2018

Uh oh!

sdras commented Oct 19, 2018

phanan Sep 16, 2018 •

edited

Loading