Refactor Mixins page into a more thorough Component Composition page #1221

chrisvfritz · 2017-10-15T03:53:51Z

Since this is a pretty significant addition, I'd like some team and community review before merging.

dennythecoder

Looks great, Chris. The heavy use of template literals may put off people programming directly in older browsers, as I can't remember anything that would have trouble running in IE in the guide (outside of single-file components).

dennythecoder · 2017-10-15T06:23:22Z

src/v2/guide/composition.md

+Using this strategy, all notes in the app maintain unified behavior, but _you_ control the API for creating them. This can be especially useful when you want to:
+
+- Create many variations of a component, abstracting away the specific implementation details.
+- Give designers, less experienced developers, or members of a very large team the ability to create new component variations, but strictly control what they're allowed to change.


How would this strictly control what they're allowed to change? They could change the returned object, right?

It restricts the changes that can be made to component options through the "normal" means (i.e. the API exposed by the function's arguments). Changing the object generated by a factory function built to abstract away the concern would be considered not normal and easier to clearly identify as a smell.

There are additional measures one could take if you're worried about this, such as freezing the returned object - but really, nothing can keep you safe from a colleague that doesn't respect exposed APIs. 😅 They could just as easily overwrite built-in browser methods or delete internal Vue properties.

chrisvfritz · 2017-10-15T07:23:20Z

@dennythecoder Thanks for the review! 🙂

The heavy use of template literals may put off people programming directly in older browsers, as I can't remember anything that would have trouble running in IE in the guide (outside of single-file components).

For pages beyond the Essentials, I've decided to make an exception for multi-line templates, simply because they're so much more readable with template literals. My hope is that users reading the more advanced content will also have a slightly more advanced knowledge of JavaScript, but do you think I should add a note at the beginning of the page about them just in case?

Akryum · 2017-10-15T07:51:54Z

A note wouldn't hurt.

KatieMFritz · 2017-10-16T22:31:39Z

src/v2/guide/composition.md

+order: 301
+---
+
+Vue offers many strategies for building components and sharing functionality between them. Below, we'll provide a description of each strategy, followed by more in-depth explanations of when and how to apply them.


I'm not clear on how this is different from just creating components. Maybe change the name or make the intro more clear.

Good call. I'll qualify with "advanced strategies" to make it clear that this isn't just building basic components.

KatieMFritz · 2017-10-16T22:32:04Z

src/v2/guide/composition.md

+Vue offers many strategies for building components and sharing functionality between them. Below, we'll provide a description of each strategy, followed by more in-depth explanations of when and how to apply them.
+
+## Overview
+


I like this overview structure.

KatieMFritz · 2017-10-16T22:33:10Z

src/v2/guide/composition.md

+You might use it to display an error like this:
+
+``` html
+<info-note type="danger">


should be <app-note>, no?

Yes! Whoops. 😅

KatieMFritz · 2017-10-16T22:34:12Z

src/v2/guide/composition.md

+```
+
+This is the simplest option and sometimes it's appropriate, when two components only _incidentally_ share a lot in common. In this case, however, we probably want all the notes in our application to work mostly the same. For example, if we later added a close button to `AppNote`, we'd now have to add the exact same code to `ErrorNote` and any other variations we created.
+


A close button on a note seems a little weird to me. What about changing note to announcement, or making it an expand/collapse button instead? You could expand/collapse both note details and error details.

Yeah, I like the announcement idea. I agree a close button makes more sense in that context.

KatieMFritz · 2017-10-16T22:36:50Z

src/v2/guide/composition.md

+
+### Mixins vs Extension
+
+**Mixins** work [like extension](#Merging-of-Instance-Properties), but allow you to define an array of configs instead of only one. For example, these two options do exactly the same thing:


Should this be "like extensions"? (plural)

Not actually in this case - "extension" refers to the strategy. Does that make sense?

Okay, I see what you're saying.

KatieMFritz · 2017-10-16T22:42:41Z

src/v2/guide/composition.md

+
+## Custom Merge Strategies
+
+Plugins often define custom options, which use the default strategy of overwriting any existing value. If you're the author a plugin where this is undesirable, you can define a **custom merge strategy** for your options with `Vue.config.optionMergeStrategies`.


I don't know anything about Vue plugins! Assuming I don't need to worry about this section for my own development.

Yes, this is correct. 😄

KatieMFritz · 2017-10-16T22:43:59Z

src/v2/guide/composition.md

+## Wrapper Components
+
+As you've seen, advanced composition with extends and mixins can quickly grow complicated. One simpler alternative is creating **wrapper components**, which provide an interface for another component typically used as its root element.
+


This took me several reads to grok. Particularly "provide an interface for another component typically used as its root element." No advice for making it clearer, unfortunately. 🙁

Hmm, I'll try to come up with a way to rephrase/simplify.

... which provide an interface for another component typically used as its root element.

What about:
... which can be used to wrap the current component while assigning the necessary default values using the template.

KatieMFritz · 2017-10-16T22:45:13Z

src/v2/guide/composition.md

+}
+```
+
+Instead of inheriting and building on the interface of a base component, this strategy does **not** provide direct access to the wrapped component. So unlike the `ErrorNote` using extension, this one has its own props (currently none) and its own slots (currently just the default slot).


Instead of inheriting and building on the interface of a base component, this strategy does not provide direct access to the wrapped component.

Not completely sure what this means ("interface" and "direct access").

What would you think about rewriting this paragraph as below?

Unlike extension, where props and slots were inherited from AppNote into ErrorNote, this strategy does not allow passing props or slots directly to the base component (AppNote). Instead, ErrorNote acts as a middleman, strictly controlling what AppNote receives. It has its own props (currently none) and its own slots (currently just the default slot).

KatieMFritz · 2017-10-16T22:46:10Z

src/v2/guide/composition.md

+
+Above, a developer has hijacked the component for a new kind of note that is not actually an error. The wrapper version of this component more strictly controls the API, so does not allow this kind of abuse.
+
+<p class="tip">In the example above, <code>type="success"</code> <em>would</em> actually affect the wrapped <code>AppNote</code> component, but as an attribute rather than a prop. To prevent attributes from automatically being added to the root element of a component, use the <a href="../api/#inheritAttrs"><code>inheritAttrs: false</code></a> option.</p>


So it would give it type="success" but it would be the HTML type attribute instead of the type prop you defined?

Yes, I'll add "HTML" before the first "attribute" just to be extra clear.

KatieMFritz · 2017-10-16T22:48:56Z

src/v2/guide/composition.md

+  {{ headingContent }}
+</dynamic-heading>
+```
+


For this whole section, I struggle because I don't get why you'd want this. The linked render function example, where you are dynamically applying anchor tags, is clearer to me. Can you use that here?

Yeah, I was previously including more render function code here and simplified the examples so as not to dive too deeply into render functions, but I think it should be possible now.

I have an example with SVG avatars that I was working on, but I'm not sure if that would leave out people who don't know SVG

@sdras That'd be something I'd worry about too, but I'd still love to see it as an example to learn from. It could possibly even be adapted into something simpler.

Update on this, @codebryo might be up for writing a cookbook entry to do a bit more of a deep dive into this, so if we get that, we can keep this example simple and link his up for further clarification :)

I will actually write that entry :)

yyx990803 · 2017-10-20T14:59:27Z

I'd like to give this a thorough review but is really short on time this week and next. Let's hold till I come back from ReactiveConf on 29th.

sdras

This is really well done and I think will be really useful! One thing it made me think about is the fidelity of the examples. I assume we're just giving them enough information to get going, but I wonder- if people are unfamiliar with these concepts, do they need more? Or alternatively, do they need to see the same example, composed with each different option to see how it changes in more of a 1:1? Either way, this is a great addition! Awesome work.

sdras · 2017-10-22T18:39:09Z

src/v2/guide/composition.md

+As you've seen, advanced composition with extends and mixins can quickly grow complicated. One simpler alternative is creating **wrapper components**, which provide an interface for another component typically used as its root element.
+
+For example, the `ErrorNote` component we [created earlier with extension](#An-Example-Use-Case) could be refactored to:
+


Should we make mention of Higher Order Components for people coming from a React background? It might be a comparison that would help some people get the idea a bit faster

Yeah, will do.

sdras · 2017-10-22T18:42:49Z

src/v2/guide/composition.md

+  {{ headingContent }}
+</dynamic-heading>
+```
+


I have an example with SVG avatars that I was working on, but I'm not sure if that would leave out people who don't know SVG

sdras · 2017-10-22T18:45:04Z

src/v2/guide/composition.md

+```
+
+Check out [VueFire's source](https://github.com/search?utf8=%E2%9C%93&q=%22Vue.mixin%22+repo%3Avuejs%2Fvuefire+path%3A%2Fsrc&type=Code) for a complete example.
+


Do you think a small example with console.logs (all of a sudden every component is console logging) would be sufficient to clear it up, Katie?

I only ask if we should add more to this to make it more clear because global mixins verge on anti-pattern

sdras · 2017-10-22T18:46:24Z

src/v2/guide/composition.md

+    </AppNote>
+  `
+}
+```


I wonder if we should have one more example for styling with a scoped slot because that's pretty useful for theming. That could also go in the cookbook.

I was reluctant to include it, because I prefer other patterns for most use cases, but between you, @Akryum, and others, I've been convinced we need a section for it. 🙂

OK, I did some work on this today, but I just couldn't make scoped props fit because unlike all the other strategies on this page, they're not about sharing functionality between components. Instead, they're really more for communication between parent-child components, so the examples I came up with will be in a new page on advanced communication between components instead.

yyx990803 · 2017-12-14T16:03:57Z

src/v2/guide/composition.md

+
+Nothing is removed, prop definitions with the same name are replaced, and any new props are added.
+
+### Merging of Event Handlers


I think it's more accurate to just use "Merging of Lifecycle Hooks" here. Event handlers may be confused with handlers added via this.$on.

Good point!

yyx990803 · 2017-12-14T16:07:37Z

src/v2/guide/composition.md

+
+- JavaScript's [`Function.prototype.apply`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/apply).
+
+- Vue's internal `_render` method, which will either reference a user-provided render function or one created from a compiled, user-provided template.


I'm in general against relying on any internal methods that start with an underscore - these methods may change behavior, be renamed or removed without notice (not connected to semver at all). Even with the warning tip below this is still in my opinion something that should not be demonstrated in the official docs.

Hacking the render function of the host component is also IMO prone to problems / conflicts if multiple mixins rely on similar strategies.

In this case it's more explicit to let the host component just add <div v-if="!isClosed">.

I agree. When talking with other people I often see them already abusing some internals of Vue and whenever something breaks there, it's hard to figure out for them as they relied on the hack completely.
I don't see it a good pattern to encourage people to go down that route.

yyx990803 · 2017-12-14T16:29:39Z

src/v2/guide/composition.md

+
+We'll demonstrate the last advantage in the next section.
+
+### Computed Components


Not really a fan of computed components - creating component definitions on the fly is always inefficient, especially when it involves dynamically generating template strings. I'd just suggest people stick to render functions and remove this section.

I disagree. This is one of the most asked questions on the forum, in a sense.

there seem to be many people out there who are stuck with backends that send string templates to the frontend, and they all end up trying to insert them into their apps with v-html and wonder why the template syntax is not being processed.

The solution for these people is to create a dynamic component from the template string that they received, often by using a computed property. It's actually kind of a selling point we have over Angular or React - we can integrate with such a backend (even if it's not without it's downsides) - these other libs simply can't.

So I strongly vote for keeping this in the guide, maybe even change it a bit to be a better fit for the usecase I described, and just mention the downsides of that approach.

That would give me a piece of documentation that I can refer these people to. :-P

Could you point to an explicit example in the Forum that you refer to? I would be curious if there isn't another way of succeeding. I am not sure the current example covers the use case you refer to in an approachable way.

I will look one up tomorrow.

This is one, but maybe not the best one:

https://forum.vuejs.org/t/innerhtml-compilation-vue-2/8780

I'll dig for some more.

https://forum.vuejs.org/t/dynamically-compile-router-link/7410

https://forum.vuejs.org/t/dynamic-template/20679

https://forum.vuejs.org/t/mount-for-dynamic-vue-templates/14203

Thanks @LinusBorg , The "dynamic router links" one is probably the example that mostly drives home the point. I would probably still try to direct users in the direction of using "funcitonal" components for this kind of behavior, yet if we are going to add this, I would recommend using the router example as it's more clear for what it tries to achieve.

codebryo

Overall, great content @chrisvfritz and very helpful regarding the overview of different strategies.

codebryo · 2018-03-13T09:12:48Z

src/v2/guide/composition.md

+
+- JavaScript's [`Function.prototype.apply`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/apply).
+
+- Vue's internal `_render` method, which will either reference a user-provided render function or one created from a compiled, user-provided template.


I agree. When talking with other people I often see them already abusing some internals of Vue and whenever something breaks there, it's hard to figure out for them as they relied on the hack completely.
I don't see it a good pattern to encourage people to go down that route.

codebryo · 2018-03-13T09:16:52Z

src/v2/guide/composition.md

+```
+
+Check out [VueFire's source](https://github.com/search?utf8=%E2%9C%93&q=%22Vue.mixin%22+repo%3Avuejs%2Fvuefire+path%3A%2Fsrc&type=Code) for a complete example.
+


I think console.log clears it up for sure. As addition though, I think it's fine to reference another project where maybe Global Mixins are used in a appropriate way. Maybe not VueFire though as the documentation there is not ideal, and it also requires people to understand Firebase to fully grock what's going on. (I recently failed with VueFire and switched to VueFirestore)

codebryo · 2018-03-13T09:23:02Z

src/v2/guide/composition.md

+## Wrapper Components
+
+As you've seen, advanced composition with extends and mixins can quickly grow complicated. One simpler alternative is creating **wrapper components**, which provide an interface for another component typically used as its root element.
+


... which provide an interface for another component typically used as its root element.

What about:
... which can be used to wrap the current component while assigning the necessary default values using the template.

codebryo · 2018-03-13T09:29:11Z

src/v2/guide/composition.md

+
+Instead of inheriting and building on the interface of a base component, this strategy does **not** provide direct access to the wrapped component. So unlike the `ErrorNote` using extension, this one has its own props (currently none) and its own slots (currently just the default slot).
+
+This is useful when we'd really like to _remove_ options from a base interface. For example, in the case of `ErrorNote`, it'd be very strange for it to be used like this:


I think we need to be careful here. With all the changes we now avoided using the word "interface" as reference to the components API/props. Can we just replace interface with component?

codebryo · 2018-03-13T09:32:49Z

src/v2/guide/composition.md

+  {{ headingContent }}
+</dynamic-heading>
+```
+


I will actually write that entry :)

LinusBorg · 2018-03-13T14:58:12Z

Awesome work so far.

One thing I was thinking about is that patterns involving scoped slots could also fit nicely into this section.

There's currently a big trend in React land to leave HOCs (wrapper components) and move to render props (scoped slots) to compose components in various scenarios.

Michael Jackson from ReactTraining gave a great talk about how Render Props are superios to HOCs in many ways and use cases: https://www.youtube.com/watch?v=BcVAq3YFiuc

And I think the same holds true for Vue scoped Slots vs. Mixins / Wrapper components, in a way even more so since HOCs are evern more notoriously tricky to get right in Vue with it's bigger API surface.

So while I think this doesn't have to be added before we publish this, we might put it on the list of possible additions to do later?

chrisvfritz · 2018-03-17T00:56:24Z

@LinusBorg After merging #1482, I'll be coming back to re-evaluate this page and there will definitely be some scoped slots love. 🙂

LinusBorg · 2018-11-28T20:11:44Z

@chrisvfritz just stumbled upon this. Is this still relevant?

sdras · 2019-04-08T04:03:39Z

@chrisvfritz we've now got ~~hooks~~ composition components coming out, do you want to include it here or should we start fresh with 3.0?

refactor mixins into a new component composition page

29f957a

dennythecoder approved these changes Oct 15, 2017

View reviewed changes

add note about template literals on composition page

df1036b

KatieMFritz suggested changes Oct 16, 2017

View reviewed changes

vuejs deleted a comment from KatieMFritz Oct 16, 2017

sdras reviewed Oct 22, 2017

View reviewed changes

chrisvfritz added 7 commits November 11, 2017 12:00

clarify intro paragraph of composition.md

087a891

correct <info-note> typo in composition.md

0d704f6

update composition.md close button examples to make more sense

5028f42

add link to render function page in composition.md

13120b4

add console.log example to demo global mixins

be6ab0d

add note about higher order components on composition.md

6e8be5a

add link to explanation of factory functions in composition.md

46f4fa0

yyx990803 requested changes Dec 14, 2017

View reviewed changes

codebryo reviewed Mar 13, 2018

View reviewed changes

		Vue offers many strategies for building components and sharing functionality between them. Below, we'll provide a description of each strategy, followed by more in-depth explanations of when and how to apply them.

		## Overview

		```

		This is the simplest option and sometimes it's appropriate, when two components only _incidentally_ share a lot in common. In this case, however, we probably want all the notes in our application to work mostly the same. For example, if we later added a close button to `AppNote`, we'd now have to add the exact same code to `ErrorNote` and any other variations we created.


		### Mixins vs Extension

		Mixins work [like extension](#Merging-of-Instance-Properties), but allow you to define an array of configs instead of only one. For example, these two options do exactly the same thing:


		## Custom Merge Strategies

		Plugins often define custom options, which use the default strategy of overwriting any existing value. If you're the author a plugin where this is undesirable, you can define a custom merge strategy for your options with `Vue.config.optionMergeStrategies`.

		## Wrapper Components

		As you've seen, advanced composition with extends and mixins can quickly grow complicated. One simpler alternative is creating wrapper components, which provide an interface for another component typically used as its root element.


		Above, a developer has hijacked the component for a new kind of note that is not actually an error. The wrapper version of this component more strictly controls the API, so does not allow this kind of abuse.

		<p class="tip">In the example above, <code>type="success"</code> <em>would</em> actually affect the wrapped <code>AppNote</code> component, but as an attribute rather than a prop. To prevent attributes from automatically being added to the root element of a component, use the <a href="../api/#inheritAttrs"><code>inheritAttrs: false</code></a> option.</p>

		As you've seen, advanced composition with extends and mixins can quickly grow complicated. One simpler alternative is creating wrapper components, which provide an interface for another component typically used as its root element.

		For example, the `ErrorNote` component we [created earlier with extension](#An-Example-Use-Case) could be refactored to:

		```

		Check out [VueFire's source](https://github.com/search?utf8=%E2%9C%93&q=%22Vue.mixin%22+repo%3Avuejs%2Fvuefire+path%3A%2Fsrc&type=Code) for a complete example.


		Nothing is removed, prop definitions with the same name are replaced, and any new props are added.

		### Merging of Event Handlers


		- JavaScript's [`Function.prototype.apply`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/apply).

		- Vue's internal `_render` method, which will either reference a user-provided render function or one created from a compiled, user-provided template.


		We'll demonstrate the last advantage in the next section.

		### Computed Components


		Instead of inheriting and building on the interface of a base component, this strategy does not provide direct access to the wrapped component. So unlike the `ErrorNote` using extension, this one has its own props (currently none) and its own slots (currently just the default slot).

		This is useful when we'd really like to _remove_ options from a base interface. For example, in the case of `ErrorNote`, it'd be very strange for it to be used like this:

Refactor Mixins page into a more thorough Component Composition page #1221

Are you sure you want to change the base?

Refactor Mixins page into a more thorough Component Composition page #1221

Conversation

chrisvfritz commented Oct 15, 2017

Uh oh!

dennythecoder 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!

chrisvfritz commented Oct 15, 2017

Uh oh!

Akryum commented Oct 15, 2017

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!

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!

yyx990803 commented Oct 20, 2017

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!

LinusBorg Mar 13, 2018 •

edited

Loading