V9 Razor TagHelpers - Can we make your Razor HTML markup easier?

[warrenbuckley]

Suggestion 💡

My suggestion is to ship Umbraco V9 with some C# TagHelpers to help make the life's easier for Developers implementing HTML markup in Razor .cshtml views.

What are TagHelpers ❓

Tag Helpers enable server-side code to participate in creating and rendering HTML elements in Razor files.
Tag Helpers are authored in C#, and they target HTML elements based on element name, attribute name, or parent tag.

More Resources

Microsoft Docs: Intro to TagHelpers
Microsoft Docs: Comparing TagHelpers to HTML Helpers
Microsoft Docs: Authoring TagHelpers

Examples 👀

umb-if

One example is to have a new taghelper attribute umb-if that can be applied to any HTML dom element

<div umb-if="(DateTime.UtcNow.Minute % 2) == 0">This paragraph will only render during <em>even</em> mintues.</div>
<div umb-if="(DateTime.UtcNow.Minute % 2) == 1">This paragraph will only render during <em>odd</em> mintues.</div>

Another use case of umb-if for easier to read IMO than nested if Razor code blocks

<h2>Current Approach</h2>
@if (Model.ContentPickerThing != null)
{
    <a href="Model.ContentPickerThing.Url()" class="btn btn-action">
        <span>@Model.ContentPickerThing.Name</span>

        @if (Model.LinkMediaPicker != null)
        {
            <img src="@Model.LinkMediaPicker.Url()" class="img-circle" />
        }
    </a>
}

<h2>Suggested Approach</h2>
<a umb-if="Model.ContentPickerThing != null" href="@Model.ContentPickerThing?.Url()" class="btn btn-action">
    <span>@Model.ContentPickerThing.Name</span>
    <img umb-if="Model.LinkMediaPicker != null" src="@Model.LinkMediaPicker?.Url()" class="img-circle" />
</a>

You can see with this screenshot Visual Studio tooling highlights and give IntelliSense for the custom tag helpers and it is thus easy to see this is not a normal HTML attribute but something custom that will run against some C# code

IfTagHelper.cs

using Microsoft.AspNetCore.Razor.TagHelpers;

namespace Umbraco.Cms.Web.Common.Mvc.TagHelpers
{
    /// <summary>
    /// Add umb-if to any HTML element
    /// Which allows you to remove the HTML and its child elements from the page
    /// If the bool condition passed in equals <c>false</c>
    /// </summary>
    /// <example>
    /// <h1 umb-if="5 > 1">Are you Awesome?</h1>
    /// </example>
    [HtmlTargetElement("*", Attributes = "umb-if")]
    public class IfTagHelper : TagHelper
    {
        [HtmlAttributeName("umb-if")]
        public bool Predicate { get; set; }

        public override int Order => -2000;

        public override void Process(TagHelperContext context, TagHelperOutput output)
        {
            if (!Predicate)
            {
                output.SuppressOutput();
            }
        }
    }
}

umb-inlinesvg

This taghelper is a bool attribute where its presence on a SVG or IMG html element with a src attribute set from a SVG file in the media library, it will read the file contents (no matter where the media stored, local, Azure blob, AWS etc) and sanitize the SVG for any script tags and then add the SVG file contents directly to the DOM to make the SVG inlined.

<h1>@Model.Header</h1>
<svg umb-inlinesvg src="@Model.MyAwesomeSvg?.Url()" id="globe" class="my-awesome-svg" data-something="heya"></svg>

<svg umb-inlinesvg="true" src="@Model.MyAwesomeSvg?.Url()" id="globe" class="my-awesome-svg" data-something="heya"></svg>

<img umb-inlinesvg src="@Model.MyAwesomeSvg?.Url()" id="globe" class="my-awesome-svg" data-something="heya" />

InlineSvgTagHelper.cs

using System.IO;
using System.Text.RegularExpressions;
using Microsoft.AspNetCore.Razor.TagHelpers;
using Microsoft.Extensions.Logging;
using Umbraco.Cms.Core.IO;

namespace Umbraco.Cms.Web.Common.Mvc.TagHelpers
{
    [HtmlTargetElement("img", Attributes = "umb-inlinesvg")]
    [HtmlTargetElement("svg", Attributes = "umb-inlinesvg")]
    public class InlineSvgTagHelper : TagHelper
    {
        private MediaFileManager _mediaFileManager;
        private ILogger<InlineSvgTagHelper> _logger;

        public InlineSvgTagHelper(MediaFileManager mediaFileManager, ILogger<InlineSvgTagHelper> logger)
        {
            _mediaFileManager = mediaFileManager;
            _logger = logger;
        }

        [HtmlAttributeName("umb-inlinesvg")]
        public bool Inline { get; set; }

        public override void Process(TagHelperContext context, TagHelperOutput output)
        {
            if (!Inline)
            {
                return;
            }

            // Get the value set in the src attribute
            var src = output.Attributes["src"];            
            if (src == null)
            {
                return;
            }

            var filePath = string.Empty;
            filePath = src.Value?.ToString();


            // Check filepath ends with .svg file ext
            if (filePath.EndsWith(".svg") == false)
            {
                // Log a warning - that the supplied filepath value did not end with .svg
                // and hence nothing was outputted to HTML
                _logger.LogWarning("The filepath '{FilePath}' set in src attribute of <svg> does not end in .svg", filePath);
                output.SuppressOutput();
            }

            // Open/read the file from FileSystemProvider (Could be local, could be on blob or somewhere else)
            if (_mediaFileManager.FileSystem.FileExists(filePath) == false)
            {
                // Log a warning - that was unable to find the SVG at filepath
                // and hence nothing was outputted to HTML
                _logger.LogWarning("The Media File Manager & underlying FileSystem is unable to find the svg at filepath '{FilePath}", filePath);
                output.SuppressOutput();
            }

            // Read its contents (get its stream)
            var fileStream = _mediaFileManager.FileSystem.OpenFile(filePath);
            using var reader = new StreamReader(fileStream);
            var fileContents = reader.ReadToEnd();

            // Sanatize SVG
            // https://stackoverflow.com/questions/65247336/is-there-anyway-to-sanitize-svg-file-in-c-any-libraries-anything/65375485#65375485
            var cleanedFileContents = Regex.Replace(fileContents,
                @"<script.*?script>",
                @"",
                RegexOptions.IgnoreCase | RegexOptions.Singleline);

            cleanedFileContents = Regex.Replace(cleanedFileContents,
                @"javascript:",
                @"syntax:error:",
                RegexOptions.IgnoreCase | RegexOptions.Singleline);

            // Remove the src attribute from the <svg>
            output.Attributes.Remove(src);

            // Update the output to inline the svg
            if(output.TagName == "img")
            {
                // Will remove the original <img> element
                output.PreElement.Clear();
                output.TagName = "svg";
            }
            
            output.TagMode = TagMode.StartTagAndEndTag;
            output.Content.SetHtmlContent(cleanedFileContents);            
        }
    }
}

Question to community

Can you think of any examples of scenarios that can be cumbersome or tricky with Razor currently and are there any potential taghelpers that we could ship with to help ease any pain.

[warrenbuckley]

Note

Can I ask if you upvote this to please let me know who you are so I can reach out and discuss with you your thoughts on this.
As the GitHub Upvote doesn't let us know who you are :)

[AaronSadlerUK]

I think the GetBlockListHtml and GetGridHtml should be tag helpers just to follow the flow of this kinda thing in core in general

[ronaldbarendse]

Agreed, but they should also be written in a more generic way to begin with: #8840.

[prjseal]

I like these. It would be great to have them available in Core to make our lives easier and reduce the need to write them ourselves or depend on external package for them

[warrenbuckley]

That would be my intention if there is enough support and we can agree on some sensible ones to ship in the core :)
Glad you like the idea Paul :)

[AaronSadlerUK]

Another useful one...

To be able to have a @section type of thing for partials...

So for example be able to load scripts included in block list items in the correct place within the master / layout, I'm not sure if that would be possible with a tag helper however.

It's annoying to have to add this as a extension everytime...

[AaronSadlerUK]

This should also extend to css files / inline css / inline js

[ronaldbarendse]

Smidge uses tag helpers, but only for rendering. Adding scripts/CSS in partial views can already be done by using the view based declarations.

[warrenbuckley]

Yep take a look at Smidge and the links Ronald suggested Aaron, plus I done a PR to make it easier as the _viewImports.cshtml has the Smidge TagHelper and also Injects the SmidgeHelper so its a little easier to get started.

#10877

[mistyn8]

Had a discussion with @Shazwazza on the topic of view based declarations, and upshot was it's not a recommended approach, as no control over ordering, as well as the single anonymous container restriction.
Shazwazza/Smidge#115 (comment)

[warrenbuckley]

@mistyn8 thanks for sharing and good to know :)

[skttl]

I'm in the middle of writing my own svg-inliner. Mine needs to support both media file system and local file system.
And then we've previously experienced that inline css in svgs will collide with inline css in other svgs when inlining. So I am doing a lot of tricks with HtmlAgilityPack to scope that css to the specific inlined svg.

I'll dig through some older projects to see patterns in views that could be better as TagHelpers. Your umb-if helper looks really useful!

[warrenbuckley]

Thanks @skttl means alot coming from you, that my hacks today were useful :)
In regards to the inline SVG I can try to make it work with items served from wwwroot as well.

In might be worth swapping notes or working together collaboratively on a the SVG inliner if its something that makes sense to ship

[tcmorris]

Nice idea Warren. I think doing something similar with an img and defining the crop would be useful, provide some configurable options (with some useful defaults perhaps). Tie it in with the new media picker.
https://docs.microsoft.com/en-us/aspnet/core/mvc/views/tag-helpers/built-in/image-tag-helper?view=aspnetcore-5.0

<img src="~/images/example.png" umb-crop="cropname" umb-quality="80">

[warrenbuckley]

Yep I can see some benefits with images and crops for sure, I just need to know what's the best ideas to implement.
As there is srcset and picture to take into consideration as well

Happy for ideas and specifics

[ronaldbarendse]

Rendering Umbraco specific items like media with crops would indeed be very useful 👍🏻 Writing <img umb-for="Image" umb-crop="Product" width="500" /> will be a lot cleaner then <img src="@Model.Image.GetCropUrl(500, cropAlias: "Product")" width="500" />.

We could do a similar thing for the Link model (returned by the Multi URL Picker), so you could write <a umb-for="Button" /> instead of <a href="@Model.Button.Url">@Model.Button.Name</a>.

As additional bonus, these tag helpers can suppress the HTML when the item is null, so you don't have to add null checks everywhere in your views to prevent NullReferenceExceptions or broken images/links!

[deMD]

I have some helpers written for this in the past, and am in the process of turning them into taghelpers. In short I have two versions, one for img tags and one for picture elements so if Umbraco is going to implement something in core I would also consider making them separate. However, there are a bunch of more complex scenario's with images that might make it difficult, like lazy loading, as there are multiple ways to do that and those will all need to be supported.

[tcmorris]

Yeah that's partly what I was thinking here, the umb-if and umb-inlinesvg options could definitely be handy but aren't really specific to Umbraco. Not sure how far we want to take this, perhaps it could be a separate package which is opt in.

Replacing Html.GetBlockListHtml with a tag helper version could be core for example. Umbraco Forms would be another (render form, render scripts). Maybe something to do with rendering content from the rich text editor?

[tcmorris]

Framework type options I've seen elsewhere: https://nextjs.org/docs/basic-features/image-optimization

Images are likely to be more complex than others, but can have a big impact on performance so simplifying that up front would be really handy.

[mattbrailsford]

As raised on Twitter. These do make for a cleaner razor view file, but I do have a slight concern about dom elements / attributes being "server side" especially when working in teams with front end and back end devs.

It's not uncommon in front end frameworks to create custom dom elements, or custom attributes. But mixing these with tag helpers could become really pretty confusing. "Is this thing a server side helper, or a client side component"?

Compounded with this is the usage of additional attributes to provide data to the server side component. For example the umb-inlinesvg demo above, uses a src attribute to know what SVG element to inline. Now that src attribute feels like it could be natural dom language, but it's not an official attribute of the svg element. So someone removing umb-inlinesvg may not know that they also need to remove the src attribute.

How much of a problem this will be, I don't really know. It's just at least by using C# in your razor file, you explicitly know if it's server side vs client side, where as with these helpers, it just feels like it's going to become a whole load murkier.

[rjsmith2]

I just wrote a similar comment to here too! It seems we're on the same boat here :)

[hfloyd]

This is the same sort of feeling I was having when reading about these "tag-helpers"... I work on a lot of projects with non-Umbraco experts - particularly front-end devs, and already I know they are often squeamish about the obvious C# inside Razor files... but at least that is clearly "back-end stuff" which they can work around. I think it's fine if these things are added as options to Core code, but I can't see myself using them much - just to keep out of the way of the front-end devs I work with.

Additionally, though it is more verbose, I think "@if" code blocks are a bit easier to understand, and do allow for multiple HTML elements to be rendered (or not) in each conditional block...

[ronaldbarendse]

Correctly naming things will be very important indeed, especially if they aren't prefixed with something like umb-. Tag helpers can also be prefixed to make their usage explicit, you can only add the tag helper in the view you require it (although it's common to put them in the Views/_ViewImports.cshtml), out-out individual elements, etc.

[rjsmith2]

Good point on prefixing- asp-umb-if would be more clear that its ASP, which would imply server-side rendering.

[warrenbuckley]

Yes I agree it could be problematic Matt, but I think as long as we are clear that we use a well defined prefix such as umb- or whatever we can all collectively decide on.

However this is not really an Umbraco issue but more a .NETCore issue where it could be confusing the mix of ServerSide TagHelpers and Custom Elements and attributes with WebComponents. Again this is all snytax sugar and won't be mandatory to use. So if you and your team would find it more confusing then I suggest to carry on working how you are comfrtable today. This will all be in addition to as opposed to replacing what can be currently done.

Visual Studio gives great tooling to really highlight when you are using a taghelper, note in the screenshot, the change of text color and bold (default in Visual Studio).

In regards to the Inline SVG demo above, I could improve my hack/example so that the svg element only uses the filepath in the custom attribute. This is where the power of the community and the shared hive knowledge is better than my very rusty knowledge of mark-up that is a little on the rustier side since I have done full blown implementations for customers.

[rjsmith2]

I do like the idea, but... one small problem with "umb-if", I could see some potential issue with this in the long run. Wouldn't the tag helper directive name collide with a front-end framework directive? What if there is a yet another new frontend javascript (or even blazor WASM) framework package called Umbo, and it too has directive called umb-if? Umbo's directive umb-if and razor tag helper umb-if` would then collide each other- how would developers resolve this then? This feels like a pit-trap in the making if this is not caught early on.

Also, considering about code clarity, if we do combine this with JavaScript framework like AngularJS, KnockoutJS, VueJs, WebComponents, etc that have their own directive, I could see this confusing our readers that would be digesting our codes in future:

<a umb-if="Model.ContentPickerThing != null" ng-if="!isClicked" href="@Model.ContentPickerThing?.Url()" class="btn btn-action">

Now we have two directive with "...-if". I would imagine that readers digesting this piece of code would then ask themselves this question, "is umb-if part of javascript framework or is this part of razor taghelper- how do I know which one?" - they may have harder time differentiating server-side view logic apart from client-side logic. To me, I would know umb-if is doing server-side rendering, and ng-if (angularjs's equivalent) is doing client-side view rendering, but how many developers would actually know this?

For this reason, I think I'd rather favor using @if razor syntax over this taghelper to help keep each DOM element clean and not muddying up things.

[warrenbuckley]

I can see the potential concern or worry and as mentioned to Matt this will all be syntax sugar if you prefer the way you write your views today then you are free to carry on as you would like to.

In regards to the name clash umb-if I kind of like @ronaldbarendse suggestion of it being asp-umb-if to help align with the ones that Microsoft ship and a littler clearer its doing something server side.

With Visual Studio giving better tooling to highlight this I am not sure if or how we could combat confusion between the two and I am curious how Microsoft team themselves have combatted this.

[greystate]

I'll say right away that I didn't know what "tag helpers" was, and that I didn't get that they were the point of the discussion when I replied to the original tweet from Warren. I am very happy that you're opening this for discussion Warren, and I'm sure there'll be lots of opinions - so here are my 2 cents:

For some of the same reasons as raised by @​mattbrailsford and @​rjsmith2 above, I am not a fan of mixing frontend and backend like this (especially don't recommend replacing an <img> tag with the <svg> for any reason) - what I was referring to (as stuff that would be helpful) was a way to help render the combination of <picture>, <source> and <img> tags necessary when a design calls for say "a 1920×1080 banner here" - whenever I see a template or partial making multiple calls to GetCropUrl() inside the various attributes, I feel there's some missing communication somewhere - I've always tried to reduce my implementation in such cases to something almost equivalent of MediaHelper.RenderPicture(media) — in every version of templating (XSLT, ASP, Razor)...

Rendering media has always been problematic (check the forums) and the very first thing we get questions about when helping someone implement an Umbraco site; they look up how to render media, and there's various (too many) ways to get "a URL" for an image, and every forum answer has yet another version of doing it. If this could be reduced to something akin to GetGridHtml() for the very basics, I think it would be a huge help for many. Especially when you think about the way that you could customize that using your own partials. (I don't use the Grid myself, but I've always thought that the way it's possible to tweak the output from partials of your own, gave it a big advantage).