DEV Community: Lee Kelleher

Umbraco Bellissima WIP articles

Lee Kelleher — Sun, 11 Feb 2024 16:24:18 +0000

With the release of Umbraco's new backoffice (codenamed Bellissima) drawing closer, (May 2024), I wanted to keep a list of work-in-progress (WIP) links to articles and resources for anyone future extension developers.

As a first port of call for the most up-to-date list of links and resources, please check out the Umbraco Packages Community Team page Umbraco v14 "Bellissima" Resources, much of this is based on Markus Johansson's (@markusjoha) Resources for Umbraco 14 Bellissima (new Backoffice) page, thank you to Markus! 🙏

The rest of this post is intended to compliment, not compete with, Markus's page.

Matt Brailsford (@mattbrailsford)

In the earliest stages of Bellissima, Matt put together a series of articles that explore each aspect of the frontend tech stack.

Back to the Front-end: Exploring the Future of the Umbraco UI

Kevin Jump (@kevinjump)

Kevin is actively documenting his developer journey as an early adopter of Bellissima.

Me, Lee Kelleher (@leekelleher)

I started writing a series of articles about how I am migrating my Contentment package over to Bellissima.

Contentment for Bellissima

Lee joined Umbraco HQ

Lee Kelleher — Sun, 11 Feb 2024 14:57:18 +0000

TL;DR, I joined Umbraco HQ, to work on the Bellissima team. Yes, I'm being paid to work on an open-source project. No, Umbraco did not acquire my Contentment package.

Now, the longer story, with plenty of nuance...

At the start of 2022, after 10 years I left my agency, Umbrella. I'd gotten weary with the grind of agency-land, a lack of fulfilment with the quality of work. I wanted to explore a path down a product development route. I'd been developing Umbraco packages for a long time, I enjoyed that type of work and people valued using those packages.

My initial thought was to follow the path that my peers had paved, and go down a commercial Umbraco package route; Matt with Vendr, Kevin with uSync, Richard Soeteman, et al.

Initially, I explored what I could do with my Contentment package. There didn't feel like much I could explore, it was already open-source after all. Some advised that I could close-source it and charge a nominal fee, (e.g. under $50), but looking at the stats (from my own telemetry data), this wouldn't be sustainable for me - especially when compared to a freelance Umbraco developer's day rate.

I gave myself 6 months to come up with an alternative idea (whether it'd be Umbraco related or not). I'd already planned for this when leaving Umbrella, so made sure I was financially stable during this time.

During the 6 months, I'd had many conversations with people within the community, lots of ideas, all with potential, but all suffered from a similar concern - was the Umbraco ecosystem large enough to sustain these ideas. Most of the ideas would require heavy marketing to gain any momentum... and let's face it, I'm hardly a "sales guy".

I had lots of "what ifs", envisaging what a successful commercial Umbraco package look like, and what would be the end goal. I kept come to one of two outcomes, either a decent lifestyle business or being acquired by Umbraco HQ. (Spoiler alert, Vendr was acquired by Umbraco in April 2023.)

Towards the end of my 6 month idea exploration, I'd been chatting a lot with Steve at Gibe about helping them to productise their sports portal solution. I joined Gibe on a freelance contract to build Playmaker. If you attended the Umbraco Spark conference 2023, we did a talk about it; Playmaker: Dances with Wolves.

I felt happier building a product that had long term visions.

After finishing up with Gibe, around end of the summer 2023, I went back to the drawing board, had a few ideas, but nothing I wanted to pursue. The lure of the freelancer day rate was more appealing than bootstrapping a new venture. I slowly resigned myself to going back to agency-land, it wasn't exciting, but gotta feed the kids, hey ho!

I tried to put the feelers out on LinkedIn, got a bombarded with recruitment agents, urgh, it didn't feel like the right move.

Mid-December 2023, I was chatting with a close friend (outside the tech world), who asked me what the heck I was up to and when was I going to sort my shit out. Some days you need to a mate to give you a swift kick up the arse.

Next day, I was chatting with Matt, and the topic of "would I consider working for Umbraco?" came up. Okay, subplot...

Now, I had thought about working for Umbraco HQ a couple of years ago. Andy Butland had recently joined and was looking for an Integrations Developer to join the new DXP team and build all those integration/connector packages. I'd chatted with Andy about it, it was all exciting, but then something strange happened at the same time.

This little fella popped his head over the wall...

I got a message from Ilham at Umbraco, asking me about the little character in my Contentment package. Turns out that they'd had a complaint from an Umbraco Cloud customer who thought that my Contentment package had hacked their CMS backoffice. Obviously, this wasn't the case, but Ilham wasn't sure so wanted to check with me first. I'd explained it was along the same lines as Umbraco's manifesto 6.13% crazy, "Happy Caturday" and all that nonsense.

All was fine. Except, I couldn't shake the thought that if I took a job with Umbraco, then I may have felt guilty about this and/or been encouraged to remove such tomfoolery from my package.

At the time, I felt I needed my own autonomy to do what I wanted to do, without repercussion, so I let Andy know that I wouldn't be pursuing the position. I felt a bit rubbish about that, as it would have been cool working with Andy on those packages.

Okay, back to chatting with Matt. I said that I'd drop Filip an email, just to put the feelers out there. In my mind, I was thinking I'd hear back in a few weeks, maybe chat in a few months or maybe at CodeGarden, just see where it goes.

Nope! 4 minutes later, Filip replied, saying he'll check internally. Next day Filip emailed back saying there wasn't any open positions for me, but we should have a call the following day. On the Friday, I have a call with Filip and he offers me a job on the Bellissima team... and can I start immediately, and oh, can I fly out to Denmark the following week to meet the team.

Wow, this was quite the whirlwind. I'd never had a job enquiry turnaround so quickly, it was all very exciting.

After a couple of days back and forth of contract discussions, we were all happy. For those interested, there was zero mention of Contentment being acquired or absorbed into the core CMS. The focus of my work is to help the team deliver the new backoffice for Umbraco 14. I'm sure we'll talk about Contentment (or its features) once v14 has launched.

You may be wondering what changed for me. Am I still concerned about giving up autonomy on my own work? I'm less concerned these days. What became apparent to me since leaving Umbrella is that I was looking for a way to get paid to be an open-source developer, and now that's a reality.

Lee's opinions on Umbraco + naming things

Lee Kelleher — Wed, 06 Dec 2023 17:36:45 +0000

Naming things is hard (maybe?)

Text casing styles

Note: I'll be mentioning different text casing styles in this article. In case you aren't aware of these, here's a quick primer...

Lexicon the different text casing styles

These are the different text casing styles for naming things like folders, files, URLs, variables, etc. Along with the typical UPPERCASE, lowercase, Title Case and Sentence case, there are also...

PascalCase - spaces removed, each word is capitalised, (popularized by the Pascal language).
camelCase - same as PascalCase, but starts with lowercase, (because the capitals look like camel humps).
kebab-case - spaces replaced with hyphens/dashes, generally lowercase, (named on a late Saturday night after the pub closed).
snake_case - spaces replaced with underscores, generally lowercase, (named after some slippery character).

For further explanation on these text casings, take a read of freeCodeCamp's article on What's the Difference Between Casings?.

General naming of things

For anything that is going to be a public-facing web-asset, e.g. folders, filenames, anything that'll become a URL, then I go with kebab-case (lowercase) all the way.

In the early 2000s, the GOV.UK team (Alphagov back then, now GDS), released a bunch of guidelines on file naming, the kebab-case one stuck in my mind. Unfortunately, I can't find a link to the original document.

For Visual Studio projects, the folder structure would generally correspond C# namespaces and types, so they'd be in PascalCase.

For C# variables names; camelCase, but I still underscore prefix _ for private backing fields, (old habits die hard).

Namespaces

From my early .NET and XML days I learnt about the importance of clear and decisive namespaces. To be treated like a classification system, (scoped however you need, e.g. per project, per organisation, for global usage). I'd spend a silly amount of time deliberating on the namespace taxonomy for my code libraries.
It's like creating your own mini Dewey Decimal system.

For Visual Studio/.NET projects and libraries, I follow the general .NET convention of dot-delimited, capitalised/PascalCase namespaces.

Nowadays, especially for any Umbraco extensions I develop, I try to follow Umbraco's own namespaces as closely as possible. e.g. I'd put my custom IContentFinder classes under a [Brand].Web.Routing namespace. Mostly so that it feels logical for any other developers who may be familiar with Umbraco core code.

.NET libraries

As I start planning out an ASP.NET website, I try to judge how much application code it will need. For basic brochureware websites, there may be an odd API controller, so I'll end up placing that code within the website itself, (for legacy ASP.NET, I'd put it in App_Code; for .NET Core, it'd be in the main project, pre-compiled).

When there is more application code required, I'd separate out code into additional library dependencies, which needs to be named - what do I call them?

Historically, I'd go with initially adding a [Brand].Core library, and whack everything in there. Then if needed, separate out larger features to their own libraries. But what do I call them?

As mentioned in the previous section, with my Umbraco work, I'd been following a similar namespace pattern to Umbraco CMS itself.
I'd typically start off with naming my main project as [Brand].Web, this would house the Umbraco CMS instance, the Razor views, wwwroot, and not much else.

For the public-facing, website specific code, (including Surface/API controllers, ViewComponents, extension methods, etc). I'd name that [Brand].Cms.Web.Website library (as Umbraco has a corresponding named library).

For any CMS backoffice specific code, e.g. property-editors, dashboards, notification handlers, (maybe even a custom Contentment Data List source), etc. I'd name this [Brand].Cms.Web.BackOffice.

If there is application code that needs to be shared between the Website and the BackOffice libraries, e.g. generated ModelsBuilder classes, Configuration classes; I'd go with having a shared library called [Brand].Cms.Web.Common.

For any additional features, say a 3rd-party integration, then I'd follow similar to how Umbraco have done with their Umbraco.Cms.Integrations.* packages, so for a MailChimp integration, I'd go with [Brand].Cms.Integrations.MailChimp; or a YouTube integration, [Brand].Cms.Integrations.YouTube.

For something that is more short-lived, such as a pre-launch content migration using uSync Migrations, that may require custom code, I'd have a standalone [Brand].Cms.ContentMigration library, so that it can easily be removed prior to launch/production.

NuGet packages

Most often when naming a NuGet package, you'd go with whatever the name of your Visual Studio project library is, they fall hand-in-hand. However, if you named your library something simple, say after a generic English word, or something that has no context outside of your scope/project, then it can look messy.

I try to take a worldview; think globally. 🌍

Many developers prefix their package ID with their organisation's name; this is quite common, good advertising and totally acceptable.

With open-source Umbraco community-related NuGet packages, I've seen several misnamed packages, but not to pick faults with others, I'll keep focus on my own mistakes. Let's take uComponents (circa 2010), as the name may imply, it's a bunch of components for Umbraco, (hence the u-prefix, part of a trend of packages around that time; uCommerce, uBlogsy, uCssClassNameDropdown, uSync, etc), it made sense, it was a good brand name. The Visual Studio project was named uComponents, so when we made the NuGet package, the obvious choice was, you guessed it, uComponents! 🤦

Why is this a problem? At face value, it isn't a problem. Taking a step back at a more global level, what does "uComponents" mean to the rest of the world? Many of the .NET developers who heavily use NuGet may have not even heard of Umbraco CMS, let alone a 3rd party plugin for it. What if people from the Uno Platform community are browsing NuGet for some kind of components extension library? You can see, this could get confusing outside the scope of the Umbraco community/ecosystem.
On top of this, uComponents was developed against Umbraco v4, with its last release in 2016, now it's there to be lingering on the NuGet repository until the end of time, set in stone.

After that I started to prefix my package names under something more scoped to the context of the Umbraco ecosystem, a la Our.Umbraco.*.

You can read an old post of mine about the History of "Our.Umbraco.*" package names.

More recently, Umbraco HQ allowed use of the Umbraco.Community.* prefix, which I've use for my Contentment package and I actively advocate other package developers to do the same.

GitHub repositories

Given the name of a public GitHub repository is part of its URL, I'll use kebab-case. Additionally, I'll include a prefix to set the scope/context/namespace of the repository itself, this would typically be the primary technology used, e.g. umbraco-contentment.

My reasoning behind this, is for GitHub's approach to repository forking. Let's take for example Umbraco's RFCs repo, umbraco/rfcs; the name of the organisation is umbraco and the name of the repository is rfcs, (all makes sense!). If I were to fork this repo, (which I have), then that would become leekelleher/rfcs, losing it's context of it being about Umbraco - so I'd personally rename my fork to leekelleher/umbraco-rfcs.

Does it matter? In the greater schemes probably not, but I prefer the semantics of such naming.

The majority of my GitHub repositories are Umbraco-related, so mostly have an umbraco- prefix, but if I was developing a dependency-free library in a specific language/framework, I'd used whatever prefix deemed relevant, e.g. dotnet-, php-, wordpress-, etc.

Umbraco CMS schema style guide

I wanted to briefly touch on naming things in Umbraco CMS itself, e.g. the schema: Document Types, Property Types, Templates, etc.

For Document Types and Property Types, I try to keep the names as Sentence case, (not Title Case), I used to do this, but I tried out (Sentence case) and it felt more natural and friendly to read. With the aliases, these are camelCase by default, no arguments there. As for the descriptions, I try to write simple/plain English summaries, avoiding any technical jargon.

Document Type icon colours. I try to have a consistency based on the content type, e.g. Compositions are Lime; Pages (nodes in the tree) are Indigo; Element Types/Blocks are Blue-Grey. (I dunno, it makes me happy).

Lee's opinions on Umbraco + coding standards

Lee Kelleher — Mon, 04 Dec 2023 09:05:00 +0000

When you learn a programming language, your initial coding style is dictated by the lessons; your teacher; the books you study. My first programming language was Sinclair BASIC on the ZX Spectrum 48K. I had a book on how to code simple games, that would influence how I'd name variables, etc. (mostly as single letters, which was a terrible idea).

Several years later, I'd got into developing with Visual Basic, Hungarian notation was all the rage; (TL;DR, prefixing variable names to indicate its type, e.g. iCount for an integer variable to count something with).

Even later, when I was learning C#, Hungarian notation had fallen out of favour, mostly due to Visual Studio compile-time type-checking; and that it was deemed healthier and maintainable to have semantic variable names. You adapt with the times (and your development teams) and evolve your coding style.

Tabs vs spaces

My long time personal preference for indentation is tabs. It made sense to me. A single character of variable width (configurable in your code editor/IDE). However most development teams that I've worked on have had a stronger preference for the use of spaces, so we'd end up have tiresome debates on which was better. (When I became the Lead Developer on my team, there were less debates, tabs would win out).

This all changed when I started working on open-source projects. The evilest type of indentation is mixed tabs & spaces - it's the kind of thing that'd turn my stomach! You have to pick a style and stick with it; consistency. Of course, I would pick tabs, but when I receive a pull request contribution, I'd often find there'd be either a mix of tabs & spaces, or worse, entire files re-indented from tabs to spaces... things would get tribal.

I soon came to the conclusion that I was swimming against the tide arguing for tabs, when the majority of developers would use spaces. I wanted to play nicely with others, I cared less for the bike-shed, so I adapted to use spaces and evolved my coding style. (It took me a few years to get used to this!)

Note: With the widespread adoption of the .editorconfig specification, (circa. 2017), it became simpler to enforce a consistent coding style for an entire project.

Brace! Brace!

Code readability is something that I'd become more aware of since contributing to open-source projects. Reviewing code changes on pull requests in a web browser can get a little tricky to mentally process.

For example, take a single line conditional, I'd be tempted to write...

if (input == null) throw new ArgumentNullException(nameof(input));

This is fine and acceptable. However if we were to modify this line, say with an extra condition or change the exception logic, the line gets longer; the diff looks messy; it can take a little more mental processing to understand the exact change.

I opted to take the more verbose approach of having newline-braces for all code blocks, including single line conditionals.

if (input == null)
{
    throw new ArgumentNullException(nameof(input));
}

The C# compiler doesn't care, and it's more readable to me.

Ternary conditional operator

I do like the ternary conditional operator, (?: uh huh huh), it can make simple single-line if/else statement more succinct. In a similar vein to the code blocks, I end up placing the resulting expressions on indented newlines.

public string GetResult(bool flag)
{
    return flag == true
        ? "Success"
        : "Failure";
}

Again, more verbose, but more readable in my mind and gives a structure for any future amends; understanding diff changed, etc.

Cognitive load

On the topic of code readability, you may have noticed in my previous code snippet I added == true to the condition. Many developers see this as ugly and redundant code, as the condition is implied to be true. Sure, once you understand that's happening, that's fine, you're an experienced developer, totally acceptable.

Let's take this condition...

if (!string.IsNullOrWhiteSpace(input))

When we read this condition, we think, "okay, if the string is not null or empty or whitespace then proceed". But optically, scanning the text from left to right, you have to mentally take note of the unary logical negation operator (! bang), then understand what the string.IsNullOrWhiteSpace method means; in both terms of resultant object-type (hopefully a Boolean) and the argument parameter. Your brain is keeping track of a couple of things here, the negation and the method result, then cognitively swapping them around to make a natural English sentence (in my mind).

Taking the same example, but now with the explicit Boolean operator...

if (string.IsNullOrWhiteSpace(input) == false)

For me, optically, the text scans the way I comprehend the logic, "is the string null or empty or whitespace? no? then proceed".

The C# compiler doesn't care whether you use the ! bang or == false, it all compiles down to the exact same bytecode, (trust me, try it out in LINQPad, view the generated IL code).

If you strongly disagree with me on this one, that's cool, there's a special reddit thread for experienced developers.

C# language evolutions

Much of my C# syntax keeps changing as the language itself evolved. It didn't take me too long to switch over to using var declarations and $"Hello {name}" string interpolation. But some other new language features have taken me longer, like the file-scoped namespace declaration (as opposed to have surrounding braces for the namespace), or Span<char> pattern matching (way too much cognitive load, it hurts my head).

I try to evaluate the latest C# language features, to get a feel for if they appear comprehensible to a newcomer. If so, then I'd most likely adopt it.

Lee's opinions on Umbraco + [topic]

Lee Kelleher — Mon, 04 Dec 2023 09:04:00 +0000

Strong Opinions, Weakly Held

To open with a quote by Tim Minchin...

A famous bon mot asserts that opinions are like assholes, in that everyone has one. There is great wisdom in this, but I would add that opinions differ significantly from assholes, in that yours should be constantly and thoroughly examined.

Many years ago, I read a post on Jeff Atwood's Coding Horror blog, Strong Opinions, Weakly Held, this resonated with me; over my years with Umbraco, I'd racked up numerous MVPs, to the point where some may have perceived me as an authority on all things Umbraco; I'm not, I'm always learning - and whilst I can have strong opinions from time to time, I do try to keep an open mind about them, to be challenged and evolve accordingly.

Offering an unsolicited opinion on a particular topic can be a terrible idea. I mean, who cares about Silicon Valley boardroom power struggles, right? But then sometimes people do care, and want you to share your thoughts and insights - so at the request of my good friend @lottepitcher...

@leekelleher I have always thoroughly enjoyed, and benefitted from, hearing all the opinions that you have in and around the #umbraco ecosystem. So maybe a post per opinion that you have the desire and energy to share?! Off the top of my head: naming things (classes/projects/repos/nuget); coding styles for readability; why one should work in public (I mean you share a lot, why is that?!). That’s my two cents at least ☺️
https://umbracocommunity.social/@lotte/111448500067158203

This series of articles will offer my opinions on various aspects of working with Umbraco CMS, .NET development and the community package ecosystem.

Contentment for Bellissima

Lee Kelleher — Thu, 30 Nov 2023 12:59:06 +0000

Preamble

This series is about the migration of my Umbraco package, Contentment, to the new Umbraco backoffice, codenamed Bellissima.

If you don't know what any of that means, expand this section for background reading and lexicon for this series.

Contentment is the name of my Umbraco package, it contains a bunch of useful property-editors.

If you want to see Contentment in action, I did a 30 minute presentation at CodeGarden 2023, Finding Contentment, exploring each of the editor components.

Bellissima is the project codename of the new backoffice for Umbraco CMS, (circa v14).
Bellissima web tech... e.g. Web Components, TypeScript, Lit, Vite, see @mattbrailsford's series of articles Back to the Front-end: Exploring the Future of the Umbraco UI.

Disclaimer: I am part of the Umbraco Backoffice Community Team - my opinions in these articles are my own and do not reflect the opinions of the community team nor Umbraco HQ.

The detail in these articles tries to be as accurate as possible (at the time of writing), if reading this a year or two from now, I'd expect there to be many changes with how Umbraco extension development is approached.

Where to begin?

At CodeGarden (June 2023), a preview of v14 was released, but wasn't quite ready for package development. By August 2023, 14.0.0--preview002 was released, including the Extension API, so package developers could register their extension points, e.g. dashboards, property-editors, etc. Meaning it was ready to explore.

My initial dilemma was should I attempt to make the existing Contentment codebase work with Bellissima, or start from scratch?

Note: I had a similar dilemma with the Umbraco v9 / .NET Core migration work. Ultimately, I started off from scratch, then did a complete U-turn and ended up with the .NET multi-targeting solution, supporting multiple versions of Umbraco in a single package. (Which has turned out quite well for Contentment.)

My gut feeling was to keep the existing codebase as-is, making sure that the .NET assembly library has binary compatibility (e.g. the C# server-side bits), before thinking about the backoffice-frontend/web-component bits.

Umbraco v13 and v14 would be compiled against .NET 8.0, so I got the latest .NET 8 preview installed and configured Contentment's .csproj file to target net8.0 and reference Umbraco's 14.0.0--preview002 NuGet packages. As expected, this gave me a bunch of compiler errors from breaking-changes in v13/v14 codebase.

Fixing up the breaking-changes was straight forward, nothing complicated, given my .NET multi-targeting approach, I could make use pre-processor directives for specific fixes, e.g. #if NET8_0_OR_GREATER. All time consuming, but no headaches.

Versioning dilemmas

Once the compiler errors were resolved, I was able to run Contentment against an Umbraco instance of 14.0.0--preview002. Of course, I wasn't able to do anything with it, there were no property-editors registered, but the initial hurdle was overcome.

Before I got going with the backoffice-frontend/web-components prototyping, I wondered about whether Contentment should take the RCL (Razor Class Library) approach. Meaning that the App_Plugins folder would be served from the NuGet package itself, rather than copied over at build-time. (It's what all the cool kids are doing these days!)

This presented another dilemma, RCL is a .NET Core technology, so this wouldn't work for legacy .NET Framework, meaning that I'd need to drop support for Umbraco v8. And whilst I was considering dropping support for old versions, I could drop Umbraco v9 too. I gave it all some thought and updated Contentment's ROADMAP.

In terms of Contentment's version numbers, and expecting to add support for Umbraco v13/.NET 8, I could do a Contentment v5 to drop support for v8/v9, add v13 (LTS) and do the RCL. This would be paving the way for a Contentment v6 to add support for Bellissima, (although because of the .NET multi-targeting, it'd need to be the next .NET major, so .NET 9, which would be Umbraco v15). (There's probably a lot to unpack in this paragraph, it'll make sense in a future article).

I still haven't fully decided whether to continue with the .NET multi-targeting approach after Bellissima, I may change my mind, but I do like the idea of having a single NuGet package (and codebase) that could support multiple versions of Umbraco. It'd be interesting to explore.

Next time...

Next time, I'll show my starting steps for the backoffice-frontend/web-components, installing TypeScript/Vite/Lit, et al.
In the meantime, if you want to skip ahead and see the code, here are links to areas of interest on Contentment's GitHub repository:

A polyfill for Umbraco packages

Lee Kelleher — Wed, 27 Apr 2022 14:29:20 +0000

Update: 2023-05-23. Due to the lack of interest, the Umbraco Polyfill package has now been deprecated. The source code is available on GitHub: https://github.com/leekelleher/umbraco-polyfill

If you are unfamiliar with the term polyfill in web development, here is the definition from MDN...

A polyfill is a piece of code (usually JavaScript on the Web) used to provide modern functionality on older browsers that do not natively support it.

https://developer.mozilla.org/en-US/docs/Glossary/Polyfill

Typically, polyfills are referenced in the context of front-end web development, but they could also be applied to server-side APIs.

I hear you asking: What does this have to do with Umbraco packages?

This time last year, I'd started migrating my Umbraco package, Contentment to support Umbraco 9 on ASP.NET Core 5. My initial approach was to drop support for Umbraco 8 to focus exclusively on Umbraco 9. A decision that niggled me.

During the code migration, I'd discussed with fellow Umbraco package developers about multi-targeting .NET frameworks within the same codebase, and indeed it was possible, meaning that Contentment could still support Umbraco 8. The downsize would be that there would be many #if/#else pre-processor directives littered throughout the codebase.

For more details on this approach, take a read of
the Package Migration to V9 Using Multi-Targeting post on the Umbraco blog.

#if NET
    private readonly ILogger<MyClass> _logger;

    public MyClass(ILogger<MyClass> logger) 
    {
        _logger = logger;
    }
#else
    private readonly ILogger _logger;

    public MyClass(ILogger logger) 
    {
        _logger = logger;
    }
#endif

    public void MyMethod() 
    {
        // Do some common logic and log a result
        var result = "Some value";
#if NET
        _logger.Debug(result);
#else
        _logger.Debug<MyClass>(result);
#endif
    }

Code snippet taken from @mattbrailsford's Adding ILogger<T> support to Umbraco v8 post.

Whilst I really liked the idea of multi-targeting, the amount of pre-processor directives did start to get silly. I wondered why that was and what could be done about it.

Of course, the API between Umbraco 8 and 9 were different, some changes were subtle, others breaking. All for understandable reasons.

With Contentment, one of the more common bits was that the IOHelper.ResolveUrl() was no longer a static method, and a new IIOHelper instance would need to be injected, meaning adding an extra parameter to the class constructor.

Since IIOHelper wasn't available in Umbraco 8, I ended up using conditional pre-processor directives...

#if NET472
    public DropdownListDataListEditor()
    {
    }
#else
    private readonly IIOHelper _ioHelper;
    public DropdownListDataListEditor(IIOHelper ioHelper)
    {
        _ioHelper = ioHelper;
    }
#endif

...and this happened in a lot of places!

My thinking was that I could introduce a polyfill for IIOHelper in Umbraco 8 only. (Given the v8 roadmap, I doubted that it would ever be added to v8.x patch release.) So that's what I did, here's a link to the code for the IIOHelper polyfill and how it is registered using dependency injection in a Composer.

Now my code would look like this...

    private readonly IIOHelper _ioHelper;
    public DropdownListDataListEditor(IIOHelper ioHelper)
    {
        _ioHelper = ioHelper;
    }

Removing the need for the conditional pre-processor directives, and maintaining the same functionality and logic.

Taking this approach to some of the other v9-only interfaces and services, I was able to reduce the verbosity of Contentment's codebase. You can see the other polyfill code on the GitHub repository.

Okay, now what?

This was all great for my Contentment package, happy days. Until when I started developing a new Umbraco package. I developed the code against Umbraco 9, but when I reviewed the code I could see the potential of adding support for Umbraco 8 with a few conditional pre-processor directives. So I copied the polyfill code over from Contentment... wait a minute, what am I doing?

At this point I separated out the polyfill code to its own code library, so that it could be referenced in my other (future) Umbraco packages.

https://github.com/leekelleher/umbraco-polyfill

...and released a NuGet package:
https://www.nuget.org/packages/Our.Umbraco.Community.Polyfill/

Just to note, in it's current release, this library should be considered a continued work-in-progress, and NOT feature complete. If you are a package developer and find there are missing features, I'm happy to collaborate with you on the GitHub repository.

Umbraco Image Crop Picker using Contentment Data List

Lee Kelleher — Thu, 11 Feb 2021 12:02:43 +0000

A couple of weeks ago, Marcin Zajkowski and Adrian Ochmann announced the release of their new Umbraco package, Image Crop Picker.

// Detect dark theme var iframe = document.getElementById('tweet-1354821151541710850-866'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1354821151541710850&theme=dark" }

The Image Crop Picker is a property-editor that enables a specific image crop to be selected from the configuration of a Image Cropper data-type. This can be useful for when a content-editor needs control over which crop is used for rendering an image.

The package has releases for both Umbraco v7 and v8, and has plans to extend the functionality in future releases. If it suits your needs, then please use it. 👍

Now what does this all have to do with my Contentment package? Since developing the Data List property-editor, whenever I see another package use a dropdown-list, checkbox-list or radiobutton-list, I can't shake the concept of separating the data-source from the list-editor.

So with the the Image Crop Picker package, I wondered - Could that be achieved as a custom Data Source? 🤔

It would need a way to select a pre-configured Image Cropper data-type, then get all the crop definitions from that data-type... Yeah, why not!

🕙🕚🕛 TL;DR, If you want to skip the explanation and see the code, it is available this gist: UmbracoImageCropDataListSource.cs

To do this, I needed to define the crops in my own Image Cropper data-type. I opted to copy Marcin's examples.

Next, once I had the code (from the gist) in place, I could create my custom Data List data-type.

The configuration for the data-source needs to select a pre-configured Image Cropper data-type.

For this UI, I opted to use the Item Picker editor, I thought it would be a nicer UI, in case have numerous Image Cropper data-types. This could have easily been done with a dropdown-list.

Once selected, you can configure the list-editor you would like to use. For this example, I chose a radiobutton-list.

You can then save the Data List data-type and add it to your document-type.

On your content page, it will be displayed like so...

Of course, if you prefer a different list-editor - say a dropdown-list, or enable multiple selections with a checkbox-list or Item Picker, you can do that.

Here is the Umbraco Image Crops data-source code in full...

If people think it would be interesting for me to break down and explain the code in more detail, please let me know. I'm happy to do so, just didn't want to do it unwarranted.

🔌 Plugs and begging... 🙏
If you already use the Contentment package, please remember to give it a vote-up on the Our Umbraco project page: https://our.umbraco.com/packages/backoffice-extensions/contentment/

If you use my open-source Umbraco packages on commercial projects and want to say thanks - consider becoming a sponsor: https://github.com/sponsors/leekelleher ❤

Using ClientDependency Filters to manipulate HTML

Lee Kelleher — Thu, 16 Jan 2020 10:37:00 +0000

On a recent Umbraco project, I needed to be able to manipulate the HTML contents before it was sent to the browser.

Typically, on Umbraco projects you'd do whatever you need do within Razor templating, but in my case, I had to do after the entire page markup was built. (I won't go into details, as the requirement is specific to my client project.)

My initial thought for the solution was using a Request.Filter. I'd done this previously in my ASP.NET WebForms days - even open-sourced a packaged called Safe Mail Link that utilised this approach, (it would encode/protect any email addresses found in the markup). The guts of the Request.Filter came from Rick Strahl's ResponseFilterStream blog post.

Given the original ResponseFilterStream code was originally posted over 10 years ago, (wow!) I wasn't sure whether the approach would work with latest Umbraco (v8 is ASP.NET MVC 5). Turns out, it does!

As I started to implement this approach, I recalled that the ClientDependency library (which ships with Umbraco) uses a HttpModule to manipulate the HTML output to insert references to its bundled CSS & JS assets. So, thought it best to look at the source-code.

...and as it happens, ClientDependencyModule has a lovely undocumented feature in there... its very own IFilter interface. This enables you to piggyback ClientDependency's HttpModule and manipulate the HTML with your own code!

After a small bit of reverse-engineering, (I know, I know, it's all open-source ... so I mean "researching"), I had a working prototype! Here's a reduced example (for Umbraco v8) ...

using System.Configuration;
using System.Web;
using ClientDependency.Core.Config;
using ClientDependency.Core.Module;
using Umbraco.Core;
using Umbraco.Web.Composing;

namespace Umbraco.Community.Web
{
    public class UpdateHtmlExampleComposer : IUserComposer
    {
        public void Compose(Composition composition)
        {
            ClientDependencySettings.Instance.ConfigSection.Filters
                .Add(new ProviderSettings(nameof(UpdateHtmlExampleFilter), typeof(UpdateHtmlExampleFilter).GetFullNameWithAssembly()));
        }
    }

    public class UpdateHtmlExampleFilter : IFilter
    {
        public HttpContextBase CurrentContext { get; private set; }

        public bool CanExecute()
        {
            return Current.UmbracoContext?.IsFrontEndUmbracoRequest == true;
        }

        public void SetHttpContext(HttpContextBase ctx) => CurrentContext = ctx;

        public string UpdateOutputHtml(string html)
        {
            // TODO: Do your HTML updates in here! 
            // ------------------------------------
            // o o/ o o/ o o/  
            // //| /| //| /| //| /|   
            // / \ / \ / \ / \ / \ / \  
            // ------------------------------------

            return html
                .Replace("Headless", "Heartcore");
        }

        // NOTE: If ClientDependency's MvcFilter is valid, then I'm cool with that.
        public bool ValidateCurrentHandler() => true;
    }
}

Examples of things you could do with this, could be: minify the HTML markup; inject external scripts before the closing </body> tag, (e.g. instant.page); protect/encode email address (a la Safe Mail Link); or a super-quick way to rename a product across an entire website?

History of "Our.Umbraco.*" package names

Lee Kelleher — Tue, 27 Nov 2018 10:50:00 +0000

Back in early 2017, Callum asked the question…

Can someone explain the history behind the "Our.Umbraco.X" naming convention for packages? It seems it's used by only a few now #umbraco

I replied at the time - but felt an explanation longer than a couple of tweets would be nice, (and findable for future reference). I had a draft of this post sitting around for a while now, thought best to publish it!

When I started to work with Umbraco, back in late 2007, my company was called Bodenko. When we developed any back-office features, they all ended up being bundled into a single project called "Bodenko.Umbraco" - this quickly became a dumping ground for all our extensions.

After getting more involved with the community, asking a lot of questions on the forum - and starting to answer some of them, I thought that I should really open-source the packages we'd developed at Bodenko. Our first was the Robots.txt Editor (which is surprisingly still popular today - and with very little updates to the original codebase) … I named the assembly "Bodenko.Umbraco.RobotsTxtEditor".

In 2009, I'd parted ways with Bodenko to go as a solo freelancer, we dissolved the company. Around this time, I'd attended my first CodeGarden - where they'd launched the new forum… Our Umbraco - it was a very exciting time within the community. The Robots.txt Editor project was due a patch release (roll up of bug fixes), but when I reviewed the code, I felt that my old company name held little relevance to the package itself. There wasn't much point in using the package to "advertise" our old company and services. So, I looked to change it.

My company name for my freelance work was called Vertino , I could have swapped it with that, but that didn't feel quite right either. Around the same time, I'd noticed there were a few other newly released packages that contained a name/reference to the company that developed them, and it somewhat felt a little anti-community.

Rather than trying to come up with a new base part for my code's namespaces, I did a swap of "Bodenko" with "Our". I still can't decide if that was a clever idea or I was being lazy - probably the latter.

I never envisaged this as trying to start a convention, then as I got involved with other established Umbraco packages, e.g. Config Tree and Google Maps DataType, with the agreement of their developers, we renamed the namespaces and assemblies over time.

Ironically, we never changed the uComponents namespace or assemblies - considering that at the time, that project was considered to be the de facto Umbraco community project.

The idea was that these packages were made by the Umbraco community, for the Umbraco community.

I didn't push this naming convention, but interestingly I noticed other package developers had started to use it. It had become an unspoken guideline.

More recently, the packages that I've collaborated on with Matt Brailsford have generally come from working together at my company Umbrella (where Matt has freelanced with us). However, when we started coding and setting up namespaces, if we used "Umbrella.Umbraco.*" it wouldn't feel quite right. We knew from the outset that certain back-office extensions had the potential to be released as fully-fledged Umbraco packages - we always start out with that mindset… "for the community".

So, if you ever look in your website's /bin folder and see a bunch of "Our.Umbraco.*" assemblies, then you now know they were developed with the community in mind and are a sign of thoughtful, well-crafted Umbraco packages.