Aspnetcore.docs: [Preview 7] Add Blazor documentation for Splatting/CaptureUnmatchedParameters

[rynowak]

This is a new feature for Blazor in preview6. Design details here: https://github.com/aspnet/AspNetCore/issues/5071#issuecomment-386045586

[rynowak]

@guardrex - this should go into preview 7. The language feature didn't make it.

The changes that we did get in is that the form controls now support arbitrary attributes. I'll send a PR for that small update.

[guardrex]

@rynowak Gotcha ... thx.

We'll leave this on-hold then in the Blazor project with an updated title "[Preview 7]."

https://github.com/aspnet/AspNetCore.Docs/projects/35

[rynowak]

Summary

The @attributes directive allows you to specify a collection of attributes to pass to a markup element or component. This is valuable because the set of key-value-pairs specified as attributes can come from a .NET collection and do not need to specified in the source code of the component.

This feature is especially valuable when defining a component that produces a markup element that supports a variety of customizations. For instance if you were defining a component that produces an <input> element, it would be tedious to define all of the attributes <input> supports like maxlength or placeholder as component parameters.

Accepting arbitrary parameters

Components also can be defined to accept arbitrary attributes. The CaptureUnmatchedAttributes property on [Parameter] allows that parameter to match all attributes that do not match any other parameter.

Example:

@code {
    [Parameter(CaptureUnmatchedAttributes = true)]
    Dictionary<string, object> Attributes { get; set; }
}

The type of property used with CaptureUnmatchedAttributes must be assignable from Dictionary<string, object> - that means that IEnumerable<KeyValuePair<string, object>> or IReadOnlyDictionary<string, object> are also options.

A component can only define a single parameter with CaptureUnmatchedAttributes.

Using @attributes to pass arbitrary attributes

A component can pass arbitrary attributes to another component or markup element using the @attributes directive attribute.

Example:

<input class="form-field" @attributes="Attributes" type="text" />

@code {
    [Parameter(CaptureUnmatchedAttributes = true)]
    Dictionary<string, object> Attributes { get; set; }
}

Evaluation of attributes occurs from left to right. In this example if Attributes also contained a value for class it would supercede class="form-field". If Attributes contained a value for type, then that would be superceded by type="text".

[guardrex]

@mkArtakMSFT Since the content is here, should I take this? If so ...

• Do you want me to remove your labels?
• I'll track it on the Blazor.Docs project and have it submitted by EOD on release day.

[guardrex]

@mkArtakMSFT I'm going to go ahead with this.