Sharing Component Data / Using Block Params

[MarkMT]

I think there are a number of issues with the way the use of block parameters with components is described that need addressing. I'd like to do some work on this but want to summarize my concerns before I get started in case others have some input.

1.. Organization Block parameters are currently dealt with in two different places:

• Sharing Component Data with its Wrapped Content under page heading Components - Wrapping Content in a Component. This deals principally with contextual components yet uses concepts that are not introduced till much later in:
• Components - Using Block Params

I propose to get rid of the latter page and incorporate the material it contains into the former, so the idea of sharing data with a block can be made clear in the general sense before contextual components are discussed as a particular case. Currently, under the heading Sharing Component Data with its Wrapped Content, the only examples provided involve sharing of components.

2.. Terminology In Components - Using Block Params, the terminology of "return values" from a component to describe block parameters seems like a poor choice of words. In the context of functions or methods, return values represent what is returned to the calling context after the code in question has terminated, but that's not what is happening here. The construct is essentially the same as a block in ruby, where parameters passed to the block are said to be yielded.

3.. Component Naming Under Sharing Component Data with its Wrapped Content there's an example of a component used as follows:

{{#blog-post editStyle="markdown"}}
  <p class="author">by {{author}}</p>
  {{body}}
{{/blog-post}}

and defined as:

<h2>{{title}}</h2>
<div class="body">{{yield (hash body=(component editStyle))}}</div>

However this seems to amount to the component being specified with the name markdown, which is invalid without a dash.

4.. Variable Naming In the preceding example, editStyle is said to represent a choice between 'html' and 'markdown' and is used to define the component that is used in the block. But in this example:

{{#blog-post editStyle="markdown" as |post|}}
  <p class="author">by {{author}}</p>
  {{post.body editStyle="compact"}}
{{/blog-post}}

editStyle is used twice, and the second seems to represent something different, not how the text is edited but how it is rendered - "a text style option which will dictate the style of body text we want in our post."

5.. Contextual Component Arguments This example:

<h2>{{title}}</h2>
<div class="body">{{yield (hash body=(component editStyle postData=postData))}}</div>

uses postData to represent a "model of the data a user fills out for the post", but there's no indication of where that's defined. Should it be passed into blog-post like this? -

{{#blog-post editStyle="markdown" postData=postData as |post|}}
   ...
{{/blog-post}}

[MarkMT]

One more point to add to this... 6.. Organization In Components - Wrapping Content in a Component the block form of a component is introduced as if this is a departure from what has been described up to this point, e.g. -

In addition to the simple form you've learned so far, components also support being
used in block form. 

This gradual adding of complexity is undoubtedly a good thing, yet the block form is actually used in the very first example when components are first introduced back in Components - Defining a Component. That initial example would be better as a simple block-less component.

[locks]

We talk about inline/block at https://guides.emberjs.com/v2.8.0/templates/conditionals/, need to tie in somehow.

[MarkMT]

Thanks. Good to know.