CshtmlComponent - ASP.NET Core MVC and Razor Pages Component V4.0.0

C# Code (ExampleComponent.cshtml.cs)

using Acmion.CshtmlComponent;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.AspNetCore.Razor.TagHelpers;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace SampleRazorPagesApplication.Pages.Components.Example
{
    // The associated tag of the component.
    [HtmlTargetElement("ExampleComponent")]
    public class ExampleComponent : CshtmlComponentBase
    {
        // Explicitly named attribute.
        [HtmlAttributeName("Title")]
        public string Title { get; set; } = "";

        public ExampleComponent(IHtmlHelper htmlHelper) : base(htmlHelper)
        {
            // The constructor. 
            // Note: Only dependency injected arguments.

            // This component resolves the name of the associated .cshtml file automatically. 
            // The path to the .cshtml file must match the namespace and class name perfectly.

            // For this component the resolving logic is the following:
            //      Namespace = SampleRazorPagesApplication.Pages.Components.Example
            //      Class Name = ExampleComponent
            //
            //      1. Remove first part of namespace and replace dots with '/'. 
            //      2. Append a '/'.
            //      3. Append Class Name.
            //      4. Append ".cshtml".
            //      
            //      Associated .cshtml file = /Pages/Components/Example/ExampleComponent.cshtml
        }
    }
}

Cshtml Code (ExampleComponent.cshtml)

@* Reference the associated component as model. *@
@using SampleRazorPagesApplication.Pages.Components.Example
@model ExampleComponent

<!-- The content of the component. -->
<div class="example-component" style="border: medium solid rgba(0, 0, 0, 0.1); padding: 1rem;">
    <h1>
        ExampleComponent: @Model.Title
    </h1>

    <div class="example-component-child-content">
        <!-- Render the child content. -->
        @Html.Raw(Model.ChildContent)
    </div>
</div>

Component Instantiation

<ExampleComponent Title="Some title">
    <div>
        Some custom HTML content.
        <Box>
            Supports nested components.
        </Box>
    </div>
</ExampleComponent>

C# Code (AdvancedExampleComponent.cshtml.cs)

using Acmion.CshtmlComponent;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.AspNetCore.Razor.TagHelpers;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace SampleRazorPagesApplication.Pages.Components.Example
{
    // The associated tag of the component.
    [HtmlTargetElement("AdvancedExampleComponent")]
    public class AdvancedExampleComponent : CshtmlComponentBase
    {
        // Explicitly named attribute.
        [HtmlAttributeName("Title")]
        public string Title { get; set; } = "";

        // These properties will default to their kebab-cased variants.
        public string FontSize { get; set; } = "1rem";
        public string BackgroundColor { get; set; } = "rgba(255, 0, 0, 0.1)";

        // A not HTML bound property, which can not be accessed as a attribute in the component tag.
        [HtmlAttributeNotBound]
        public string UppercaseTitle { get; set; } = "";

        public AdvancedExampleComponent(IHtmlHelper htmlHelper) : base(htmlHelper, "/Pages/Components/Example/AdvancedExampleComponent.cshtml", "div", TagMode.StartTagAndEndTag)
        {
            // The constructor. 
            // Note: Only dependency injected arguments.

            // "/Pages/Components/Example/AdvancedExampleComponent.cshtml" is the path to the associated .cshtml file.
            // "div" is the output tag name. Defaults to null.
            // TagMode.StartTagAndEndTag determines the tag structure, optional parameter. Defaults to TagMode.StartTagAndEndTag.

            // Properties should not be accessed here, because they will not yet be set.
        }

        protected override Task ProcessComponent(TagHelperContext context, TagHelperOutput output)
        {
            // This method is called just before the associated .cshtml file is executed.
            // Properties have been initialized and can be accessed.

            // The property ChildContent is a string that contains the child content.

            // Use this method to edit some other properties or fields.

            UppercaseTitle = Title.ToUpperInvariant();

            return base.ProcessComponent(context, output);
        }
    }
}

Cshtml Code (AdvancedExampleComponent.cshtml)

@* Reference the associated component as model. *@
@using SampleRazorPagesApplication.Pages.Components.Example
@model AdvancedExampleComponent

<!-- Content that is injected in to the <head> tag. -->
<!-- ---------------------------------------------- -->
<!-- ---------------------------------------------- -->
<!-- ---------------------------------------------- -->
<CshtmlHead>
    <!-- This content will be appended to <head>, when this component is first instantiated. -->
    <meta name="description" content="CshtmlHead, Key: default, ContentOrder: default" />
    <link rel="stylesheet" href="~/css/advanced-example-component.css" />
    <script>console.log("CshtmlHead, Key: default, ContentOrder: default");</script>
</CshtmlHead>

<CshtmlHead>
    <!-- This content will NOT be appended to <head>, because the default key is already used. -->
    <meta name="description" content="CshtmlHead, Key: default, ContentOrder: default" />
    <script>console.log("CshtmlHead, Key: default, ContentOrder: default");</script>
</CshtmlHead>

<CshtmlHead Key="0" ContentOrder="0">
    <!-- This content will be appended to <head> and will appear before <CshtmlHead>, when this component is first instantiated. -->
    <meta name="description" content="CshtmlHead, Key: default, ContentOrder: 0" />
    <script>console.log("CshtmlHead, Key: default, ContentOrder: 0");</script>
</CshtmlHead>

<CshtmlHead Key="-1" ContentOrder="-1">
    <!-- This content will be prepended to <head>, when this component is first instantiated. -->
    <meta name="description" content="CshtmlHead, Key: -1, ContentOrder: -1" />
    <script>console.log("CshtmlHead, Key: -1, ContentOrder: -1");</script>
</CshtmlHead>

<CshtmlHead Multiple="true" ContentOrder="-2">
    <!-- This content will be prepended to <head> and will appear before <CshtmlHead ContentOrder="-1">, every time this component is instantiated. -->
    <meta name="description" content="CshtmlHead, Multiple: true, ContentOrder: -2" />
    <script>console.log("CshtmlHead, Multiple: true, ContentOrder: -2");</script>
</CshtmlHead>




<!-- Content that is injected in to the <body> tag. -->
<!-- ---------------------------------------------- -->
<!-- ---------------------------------------------- -->
<!-- ---------------------------------------------- -->
<CshtmlBody>
    <!-- This content will be appended to <body>, when this component is first instantiated. -->
    <meta name="description" content="CshtmlBody, Key: default, ContentOrder: default" />
    <script>console.log("CshtmlBody, Key: default, ContentOrder: default");</script>
</CshtmlBody>

<CshtmlBody>
    <!-- This content will NOT be appended to <body>, because the default key is already used. -->
    <meta name="description" content="CshtmlBody, Key: default, ContentOrder: default" />
    <script>console.log("CshtmlBody, Key: default, ContentOrder: default");</script>
</CshtmlBody>

<CshtmlBody Key="0" ContentOrder="0">
    <!-- This content will be appended to <body> and will appear before <CshtmlBody>, when this component is first instantiated. -->
    <meta name="description" content="CshtmlBody, Key: default, ContentOrder: 0" />
    <script>console.log("CshtmlBody, Key: default, ContentOrder: 0");</script>
</CshtmlBody>

<CshtmlBody Key="-1" ContentOrder="-1">
    <!-- This content will be prepended to <body>, when this component is first instantiated. -->
    <meta name="description" content="CshtmlBody, Key: -1, ContentOrder: -1" />
    <script>console.log("CshtmlBody, Key: -1, ContentOrder: -1");</script>
</CshtmlBody>

<CshtmlBody Multiple="true" ContentOrder="-2">
    <!-- This content will be prepended to <body> and will appear before <CshtmlBody ContentOrder="-1">, every time this component is instantiated. -->
    <meta name="description" content="CshtmlBody, Multiple: true, ContentOrder: -2" />
    <script>console.log("CshtmlBody, Multiple: true, ContentOrder: -2");</script>
</CshtmlBody>




<!-- One off content that is rendered as is and wherever this component is instantiated. -->
<!-- ----------------------------------------------------------------------------------- -->
<!-- ----------------------------------------------------------------------------------- -->
<!-- ----------------------------------------------------------------------------------- -->
<CshtmlInitial>
    <!-- This content will be rendered, as is, wherever this component is first instantiated. -->
    <script>console.log("CshtmlInitial, Key: default");</script>
</CshtmlInitial>

<CshtmlInitial>
    <!-- This content will NOT be rendered, because the default key is already used. -->
    <script>console.log("CshtmlInitial, Key: default 2");</script>
</CshtmlInitial>

<CshtmlInitial Key="I1">
    <!-- Explicitly keyed. This content will be rendered, as is, wherever this component is first instantiated. -->
    <script>console.log("CshtmlInitial, Key: I1");</script>
    @{ 
        var a = 0;
    }
</CshtmlInitial>




<!-- The actual content of this component. -->
<!-- ------------------------------------- -->
<!-- ------------------------------------- -->
<!-- ------------------------------------- -->
<div class="advanced-example-component" style="background-color: @Model.BackgroundColor; font-size: @Model.FontSize">
    @{
        // Assign a variable to a component reference.
        // The Box component inherits CshtmlComponentReferenceableBase<Box> (a class that inherits CshtmlComponentBase),
        // which implements this logic. Useful if component properties have to be used outside the component's own context.

        // This is not the default behavior due to the mandatory, but slightly weird syntax:
        // public Box : CshtmlComponentReferenceableBase<Box> ....

        // See the source code of Pages/Components/Box.cshtml.cs for how the component class looks like.

        var boxReference = new CshtmlComponentReference<Box>();

        <Box Reference="boxReference">
            <h1>
                AdvancedExampleComponent: @Model.UppercaseTitle
            </h1>
            <p>
                The fontsize of the referenced Box is: @boxReference.Component.FontSize 
            </p>
        </Box>
    }

    <br />

    <div class="advanced-example-component-slot0">
        <!-- Render a named slot. -->
        @Html.Raw(Model.NamedSlots["SlotName0"])
    </div>

    <br />

    <div class="advanced-example-component-child-content">
        <!-- Render the child content. -->
        @Html.Raw(Model.ChildContent)
    </div>

    <br />

    <div class="advanced-example-component-slot1">
        <!-- Render a typed (or named) slot. -->
        @Html.Raw(Model.NamedSlots[AdvancedExampleComponentTypedSlot.SlotName])
    </div>

    <br />

    <div class="advanced-example-component-manual-render">
        <!-- Manually render a component. Note the constructor argument and that some properties have to be manually set. -->
        @{
            var manualBox = new Box(Html) { ChildContent = "Manually rendered box" };
        }

        @await manualBox.RenderAsync()

        <br />

        <!-- The content can also be rendered into a string. May be useful if templates must be passed to, for example, JavaScript. -->
        @{ 
            var manualBoxRenderedToString = await manualBox.RenderToStringAsync(preserveLineBreaks: false);
        }

        @Html.Raw(manualBoxRenderedToString)
    </div>
</div>

Component Instantiation

<AdvancedExampleComponent Title="Some title" font-size="1.2rem" background-color="rgba(0, 0, 255, 0.1)">
    <div>
        Some custom HTML content.
        <Box>
            Supports nested components.
        </Box>
    </div>
    <CshtmlSlot Name="SlotName0">
        Some custom HTML content within a named slot. The parent component decides where
        this content is placed.
    </CshtmlSlot>
    <AdvancedExampleComponentTypedSlot>
        Additional custom HTML content within a <strong>typed</strong> slot.
        See the source code of <code>/Pages/Components/Example/AdvancedExampleComponentTypesSlot.cs</code>.
        <Box>
            Supports nested components.
        </Box>
    </AdvancedExampleComponentTypedSlot>
</AdvancedExampleComponent>

Properties

The properties of CshtmlComponentBase (not including inherited).

Constructors

The constructors of CshtmlComponentBase, their arguments and the key properties that they set.

Methods

The methods of CshtmlComponentBase and what they do and return (not including inherited).

Properties

The properties of CshtmlComponentReferenceableBase<ReferencableComponentType> (not including inherited).

Constructors

The constructors of CshtmlComponentReferenceableBase<ReferencableComponentType> are exactly the same as those of CshtmlComponentBase.

Attributes

The attributes of CshtmlHead.

CshtmlHead Ordering Example

An example that shows how CshtmlHead affects the content of the head element.

<!DOCTYPE html>
<html>
    <head>
        <!-- 
            <CshtmlHead ContentOrder="int.MinValue"> content here.  
            <CshtmlHead ContentOrder="int.MinValue + 1"> content here.
            <CshtmlHead ContentOrder="int.MinValue + 2"> content here.
            ...
            <CshtmlHead ContentOrder="-999"> content here.
            <CshtmlHead ContentOrder="-998"> content here.
            <CshtmlHead ContentOrder="-997"> content here.
            ...
            <CshtmlHead ContentOrder="-3"> content here.
            <CshtmlHead ContentOrder="-2"> content here.
            <CshtmlHead ContentOrder="-1"> content here.
        -->

        <!--
            Standard <head> content here. Often specified in a _layout.cshtml file.
        -->

        <!--
            <CshtmlHead ContentOrder="0"> content here.
            <CshtmlHead ContentOrder="1"> content here.
            <CshtmlHead ContentOrder="2"> content here.
            ...
            <CshtmlHead ContentOrder="997"> content here.
            <CshtmlHead ContentOrder="998"> content here.
            <CshtmlHead ContentOrder="999"> content here.
            ...
            <CshtmlHead ContentOrder="int.MaxValue - 2"> content here.
            <CshtmlHead ContentOrder="int.MaxValue - 1"> content here.
            <CshtmlHead ContentOrder="int.MaxValue"> content here. Default location.
        -->
    </head>
    <body>
        <!-- Some content here. -->
    </body>
</html>

Attributes

The attributes of CshtmlBody.

CshtmlBody Ordering Example

An example that shows how CshtmlBody affects the content of the head element.

<!DOCTYPE html>
<html>
    <head>
        <!-- Some content here. -->
    </head>
    <body>
        <!-- 
            <CshtmlBody ContentOrder="int.MinValue"> content here.  
            <CshtmlBody ContentOrder="int.MinValue + 1"> content here.
            <CshtmlBody ContentOrder="int.MinValue + 2"> content here.
            ...
            <CshtmlBody ContentOrder="-999"> content here.
            <CshtmlBody ContentOrder="-998"> content here.
            <CshtmlBody ContentOrder="-997"> content here.
            ...
            <CshtmlBody ContentOrder="-3"> content here.
            <CshtmlBody ContentOrder="-2"> content here.
            <CshtmlBody ContentOrder="-1"> content here.
        -->

        <!--
            Standard <body> content here.
        -->

        <!--
            <CshtmlBody ContentOrder="0"> content here.
            <CshtmlBody ContentOrder="1"> content here.
            <CshtmlBody ContentOrder="2"> content here.
            ...
            <CshtmlBody ContentOrder="997"> content here.
            <CshtmlBody ContentOrder="998"> content here.
            <CshtmlBody ContentOrder="999"> content here.
            ...
            <CshtmlBody ContentOrder="int.MaxValue - 2"> content here.
            <CshtmlBody ContentOrder="int.MaxValue - 1"> content here.
            <CshtmlBody ContentOrder="int.MaxValue"> content here. Default location.
        -->
    </body>
</html>

Attributes

The attributes of CshtmlInitial.

Attributes

The attributes of CshtmlSlot.