Spark and related events

Usually this is where I remind you to sign up to all the pre- and post-Spark events as well as what to expect on the day. But this year Spark has put together a fantastic practical guide to Spark!

Map

A map of the primary locations is included below. It also includes my recommendations for Bristol - read on for details!

Open map full screen.

Recommendations

Bristol is a lovely city - so lovely, in fact, I moved here in 2022 - so many people elect to stay in the area for the weekend afterwards. Here's some advice for those people:

Getting around

Although the city is quite sprawling, a lot of Bristol is accessible by foot (particularly if you're good with hills!)

As much as the locals complain, Bristol has a pretty good bus network (just don't compare it to London or any continental European city!) Fares on First Bus busses are £2.60 for a single with a cap at £6.80 for the day, if you stay within Bristol. Busses all support tap-on-tap-off which are automatically capped, so no cash is needed.

For bike and electric scooter hire you'll need the Dott app which you'll need your driving license (full or provisional) to sign up for, so be sure to do that ahead of time.

Food and drink

Bristol is home to fantastic independent cafes, pubs, restaurants and food stalls - as well as the birthplace of small chains like The Lounges and Boston Tea Party.

My favourite food stalls are in Wapping Wharf (Spike Island, harbourside) (St Nicholas Market is closed at the weekend!)

You can't go wrong with most cafes in Bristol, but some of my regulars are Mud Dock (harbourside), The Bristol Loaf ("The Centre"), East Village Cafe (Clifton Village) and Santiago's (particularly if you're waiting for a bus at the bus station!)

Some of my favourite pubs include The Apple (central) (don't miss having a half - too strong to sell it in pints! - of Old Bristolian cider on this cider-barge), The Cottage Inn (Spike Island, harbourside) and pretty much anywhere on King Street (central).

A touch of nature

Leigh Woods is a fantastic woodland a short walk over Clifton Suspension Bridge. You'll want some boots but it's easy to follow signposted routes.

Ashton Court is a deer park with great views over Bristol and a lovely cafe. You can stick to tarmac and gravel paths here if you want clean shoes! Also a Parkrun location.

Brandon Hill is a lovely park right next to Park Street and is home of Cabot Tower - which is worth a climb (free) for some more fantastic views.

Shopping

Cabot Circus and Bristol Shopping Quarter are mostly (although not entirely!) big chain shops you'd find in most cities.

Clifton Village (further out than Clifton but within the city, unlike it's name implies!) is where you'll find the best of Bristol's local boutique-y gift shops and cafes. Also worth visiting the iconic suspension bridge while you're there (and the cafe at the observatory is worth a stop!)

A little closer to the centre of town is Park Street and Whiteladies Road as well as Gloucester Road, less classy than Clifton but some lovely smaller shops. (Gloucester Road is the charity-shopper's heaven!)

Sightseeing

Bristol is home to some great museums. M Shed is the historic venue for Spark but also a great little free museum. You can find more information about all the Bristol Museums on their website.

This year's venue is also a museum - We The Curious is an interactive science museum that's recently reopened after a large fire. I've not been since the reopening, but have fond memories of going as a child!

Next to We The Curious is the aquarium (central) which is expensive but very good. Bristol Zoo is no longer located in Clifton, and is now outside the city.

Cabot Tower in Brandon Hill park (central) is free to climb for some epic views.

Clifton Suspension Bridge (Clifton Village) is free to walk across and Observatory Hill is nearby for some good views and a nice coffee shop. Or head into Clifton Village for endless cafes and pubs.

Bristol University has several beautiful historic buildings. The closest to the city centre are at the top of Park Street along with the Bristol Art Gallery.

Personally, I like to explore new cities using virtual audio tours. Claim a free one using my VoiceMap referral link. There are 5 highly-rated tours of Bristol to choose from.

Nearby

The cities of Bath and Cardiff, Wales are within an easy train ride (15 minutes or 1 hour respectively) if you want to spread your wings a little further.

See you there!

I'll be at the hackathon right the way through to the after party - so I'll see you there! Please come and say hi, and see my talk too if it appeals!

If you think I've missed something vital, let me know on socials!

Thanks to Tristan Thompson for his contributions to the 2024 post which have been brought forwards.

Basic setup

You'll need:

• act
• Docker (to run a Linux build) or run act from a Windows machine (to run a Windows build)
• GitHub CLI
• Azure CLI
• dotnet

Ensure your GitHub and Azure CLIs are logged in, using az login and gh auth login.

TL;DR

This PowerShell command (running on a Windows machine) will run most .NET/Azure builds:

act push -W '.github/workflows/my-workflow.yml' --var-file '.github/workflows/local/vars.env' --secret-file '.github/workflows/local/secrets.env' -s GITHUB_TOKEN="$(gh auth token)" --artifact-server-path 'C:\Windows\Temp\act-artifacts' -P windows-latest=-self-hosted -e '.github/workflows/local/payload.json'

I tend to save this PowerShell script in .github/workflows/local/act.ps1 inside the repo.

You'll also need to create the files mentioned in here.

vars.env and secrets.env are files in the .env format that must contain any variables or secrets your workflows need to run. Be sure to gitignore the secrets file!

The payload.json file should contain:

{
  "head_commit": {
      "message": "Sample commit message"
  }
}

You will also need to disable any steps that use actions/setup-dotnet or azure/login locally. e.g.

  - name: Setup .NET
    # Prevent this step from running if running locally with act
    if: ${{ !env.ACT }}
    uses: actions/setup-dotnet@v4

The rest of this article will break down why this is needed and how else you might need to modify act.

GITHUB_TOKEN

The -s GITHUB_TOKEN="$(gh auth token)" portion of our command is what provides the workflows with GitHub access. You can pass in a GitHub personal access token if you'd rather, or add the access token to your secrets.env file, but this requires less setup as the PowerShell script automatically inserts the token generated by the GitHub CLI.

Artifact Server

Providing the --artifact-server-path enables the act artifact server emulator. It's needed if you use the actions/upload-artifact and actions/download-artifact actions. This path can be viewed to help diagnose problems with artifacts.

Self-hosted Runners

Using the -P windows-latest=-self-hosted flag tells act to use the local machine as the build agent instead of a Docker container. This is not ideal, but saves complication! It's also the reason we can disable the actions/setup-dotnet or azure/login steps as we assume these are configured correctly locally. These actions are more complicated to configure.

The left hand side of the assignment should match the runs-on: declaration on your workflow and, of course, this should match your local machine. You probaly can't run a windows-latest build on a Mac.

Payload

The -e '.github/workflows/local/payload.json' parameter is a JSON file containing additional information to pass the workflow that act doesn't include by default. The azure/webapps-deploy action when using azure/login for authentication requires head_commit.messagefield to be set. Any null-reference errors in Actions (that, when the source code is viewed, use the GitHub context) can usually be fixed by addding values in this file.

Disabling steps

Act allows you to disable build steps using the if: ${{ !env.ACT }} syntax. This is helpful if you're able to use the self-hosted mode to remove configuration steps that are a pain to get working.

I'll keep this article updated as I work out better ways of working with act. Ideally a Docker container would be used for builds, but it does add an additional layer of complexity. This is the workflow I have working currently.

Scenario

You might have seen code like this, that blocks certain document types from being deleted.

/// A common use case: prevent certain document types being deleted
public class LockedDocumentContentMovingToRecycleBinNotificationHandler : INotificationHandler<ContentMovingToRecycleBinNotification>
{
    public static string[] LOCKED_ALIASES = ["home", "error"];
    public static Guid[] LOCKED_IDS = [
      Guid.Parse("a95360e8-ff04-40b1-8f46-7aa4b5983096"),
      Guid.Parse("9db112c5-c2ea-441d-8bd4-6daf522aa2b6")
    ];
    public void Handle(ContentMovingToRecycleBinNotification notification)
    {
        foreach (var item in notification.MoveInfoCollection)
        {
            if (Array.Exists(LOCKED_ALIASES, alias => alias.Equals(item.Entity.ContentType.Alias, StringComparison.OrdinalIgnoreCase)))
            {
                notification.CancelOperation(new EventMessage(
                  $"{item.Entity.Name} cannot be trashed",
                  $"The content item '{item.Entity.Name}' is of type '{item.Entity.ContentType.Name}' which cannot be trashed.",
                  EventMessageType.Error));
            }
        }
    }
}

But wouldn't it be nice to show this in the backoffice before trying to delete an item?

Flagging content items

The custom signs can be configured to show for items that have a certain "flag". This is also a new feature of Umbraco 17. (The only use I'm aware of for flags at the moment is for custom entity signs, but perhaps this will change in the future!)

using Umbraco.Cms.Core;
using Umbraco.Cms.Api.Management.Services.Flags;
using Umbraco.Cms.Api.Management.ViewModels;
using Umbraco.Cms.Api.Management.ViewModels.Document.Collection;
using Umbraco.Cms.Api.Management.ViewModels.Document.Item;
using Umbraco.Cms.Api.Management.ViewModels.Tree;
using My.UmbracoBackofficeExtensions.Notifications;

namespace My.UmbracoBackofficeExtensions
{
    // Created a C# class that implements `IFlagProvider`
    public class LockedDocumentFlagProvider : IFlagProvider
    {
        // We'll use this alias in the custom sign configuration
        private const string Alias = Constants.Conventions.Flags.Prefix + "My.Locked";

        // Indicate that this flag provider only provides flags for documents.
        public bool CanProvideFlags<TItem>()
            where TItem : IHasFlags =>
            typeof(TItem) == typeof(DocumentTreeItemResponseModel) ||
            typeof(TItem) == typeof(DocumentCollectionResponseModel) ||
            typeof(TItem) == typeof(DocumentItemResponseModel);

        // Implemented the `PopulateFlags` method which is just looping through each item and checking it in the `ShouldAddFlag` method.
        public Task PopulateFlagsAsync<TItem>(IEnumerable<TItem> itemViewModels)
            where TItem : IHasFlags
        {
            foreach (TItem item in itemViewModels)
            {
                if (ShouldAddFlag(item))
                {
                    item.AddFlag(Alias);
                }
            }

            return Task.CompletedTask;
        }

        // We just get the ID of the document type and check it against our list of IDs we don't allow being deleted
        private bool ShouldAddFlag<TItem>(TItem item)
        {
            Guid id;
            switch (item)
            {
                case DocumentTreeItemResponseModel dti:
                    id = dti.DocumentType.Id;
                    break;
                case DocumentCollectionResponseModel dc:
                    id = dc.DocumentType.Id;
                    break;
                case DocumentItemResponseModel di:
                    id = di.DocumentType.Id;
                    break;
                default:
                    return false;
            }

            return LockedDocumentContentMovingToRecycleBinNotificationHandler.LOCKED_IDS.Contains(id);
        }
    }
}

This provider also needs registering in a composer.

public class LockedDocumentComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.SignProviders()
            .Append<LockedDocumentFlagProvider>();

        // Our existing logic to disallow deleting the document deletion
        builder.AddNotificationHandler<ContentMovingToRecycleBinNotification, LockedDocumentContentMovingToRecycleBinNotificationHandler>();
    }
}

Configuring the custom entity sign

The entity sign is configured in a backoffice extension. If you're already extending the backoffice and have a manifests file already, please read on. Otherwise, I've written about extending the backoffice in my Template for Success article on 24 Days in Umbraco.

Once the flag is in place, entity signs only require a manifest to configure them, no JavaScript required:

import { UMB_DOCUMENT_ENTITY_TYPE } from '@umbraco-cms/backoffice/document';

export const manifests: Array<UmbExtensionManifest> = [
  // ...
  // Adding a new manifest of type `enitiySign` and kind `icon`
  {
    type: 'entitySign',
    kind: 'icon',
    alias: 'Umb.EntitySign.Document.My.Locked',
    name: 'Is Locked Document Entity Sign',
    // Specifying which enties can show this sign, documents
    forEntityTypes: [UMB_DOCUMENT_ENTITY_TYPE],
    // Specify what entities should be "flagged" with to make the sign show
    forEntityFlags: ['Umb.My.Locked'],
    // Can only show 2 icons at once, so the weighting matters. `-1000` means this one is really unimportant!
    weight: -1000,
    meta: {
      // Specifying what the sign looks like
      iconName: 'icon-lock',
      label: 'Locked',
      iconColorAlias: 'red',
    }
    // You'll notice we don't link to a TS file! Flagging is purely a C# concern
  }
];

The result

As you can see in the screenshot below, Home and Error are locked and have our new red padlock custom entity sign, while Features and Error have unpublished changes with the default pencil entity sign and Error has both, sorted by priority.

This is an example of what entity signs could be used for, but hopefully you can now imagine many more uses! And not just document types either!

Custom backoffice block views are now configured using an Umbraco backoffice extension.

If you're already extending the backoffice and have a manifests file already, please read on. Otherwise, I've written about extending the backoffice in my Template for Success article on 24 Days in Umbraco.

The example

In this post I'll be using the example of showing a little tag to indicate a block is hidden. I'm using the familiar pattern used by Clean Starter Kit of having ahidden setting on each block. Rather than rendering the text "[HIDDEN]" in each block template I'd like this to automatically appear for all blocks. Here's a mockup I made in Paint of what we're aiming for here.

Registering the extension

Add a manifest to your manifests file:

export const manifests: Array<UmbExtensionManifest> = [
  // ...
  {
    // extension type is `blockEditorCustomView`
    type: 'blockEditorCustomView',
    alias: 'My.HiddenBlockEditorView',
    name: 'Hidden Block Editor View',
    // referencing a TS file for the element we want to use a the block view
    element: () => import('./hidden-block.element'),
    // specifying which block editor we're replacing the view for
    forBlockEditor: 'block-list'
  }
];

Creating the custom element

That referenced hidden-block.element.ts file looks like this:

import { html, customElement, LitElement, property, css, when } from '@umbraco-cms/backoffice/external/lit';
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import type { UmbBlockDataType } from '@umbraco-cms/backoffice/block';
import type { UmbBlockEditorCustomViewElement, UmbBlockEditorCustomViewConfiguration } from '@umbraco-cms/backoffice/block-custom-view';

@customElement('hidden-block-custom-view')
// Extending the `UmbElementMixin` and implementing `UmbBlockEditorCustomViewElement`
export class HiddenBlockCustomView extends UmbElementMixin(LitElement) implements UmbBlockEditorCustomViewElement {

    // UmbRefListBlockElement is not exposed to extend it, so we have to copy a lot of it in to replace it:

    @property({ type: String, reflect: false })
    label?: string;
   // ...
   // Other properties copied from UmbRefListBlockElement
   // ...

    // This render method is largely copied from UmbRefListBlockElement, with some customisations to show hidden state
    override render() {
        const blockValue = { ...this.content, $settings: this.settings, $index: this.index };
        return html`
            <uui-ref-node standalone
        href=${(this.config?.showContentEdit ? this.config?.editContentPath : undefined) ?? ''}
        class="${this.settings?.hide ? 'hidden' : ''}">
            ${when(
                this.settings?.hide,
                () =>
                    html`<umb-icon slot="icon" name="icon-checkbox-dotted"></umb-icon>`,
                () =>
                    html`<umb-icon slot="icon" .name=${this.icon}></umb-icon>`
            )}
                <umb-ufm-render slot="name" inline .markdown=${this.label} .value=${blockValue}></umb-ufm-render>
                ${when(
                    this.unpublished,
                    () =>
                        html`<uui-tag slot="name" look="secondary" title=${this.localize.term('blockEditor_notExposedDescription')}
                                    ><umb-localize key="blockEditor_notExposedLabel"></umb-localize
                                ></uui-tag>`,
                )}
                ${when(
                    this.settings?.hide,
                    () =>
                        html`<uui-tag slot="name" look="secondary" title="Hidden"
                                >Hidden</umb-localize
                            ></uui-tag>`
                )}
            </uui-ref-node>
        `;
    }

    static override styles = [
        css`
            /* Copied styles from UmbRefListBlockElement and added custom styles /*
        `,
    ];
}
export default HiddenBlockCustomView;

declare global {
    interface HTMLElementTagNameMap {
        'hidden-block-custom-view': HiddenBlockCustomView;
    }
}

The full code sample is available on GitHub.

The new view!

With that in place, my block lists now look like this!

RTE Blocks are a new way of thinking about content (and a good replacement for macros!)

Creating block types

You can reuse your existing Block List and Block Grid blocks - they're exactly the same thing! But in most real use cases these will be different document types.

You simply need to create "element" type document types with all the properties you want on your new block, the difference comes in the data type you configure them in:

Adding blocks to the RTE

Instead of creating a Block List or Block Grid, we need to create (or modify an existing) Rich Text Editor data type.

We'll need to add the Block button to the RTE toolbar.

The RTE now has settings for configuring Blocks, just like in other Block editors:

Select your element types with optional settings and configure a label template, just as you would ordinarily as well as a setting for whether the block will render inline (think span) or as a block (think div).

Rendering RTE Blocks

This is probably where the RTE block differs most from the other block editors (and even that doesn't differ much!)

It simply needs a view matching the alias in the Views\Partials\RichText\Components folder.

Here's my example phone number view located at TemplateForSuccess.Web\Views\Partials\RichText\Components\PhoneNumberRteBlock.cshtml

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem<ContentModels.PhoneNumberRteBlock>>
@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;
@using System.Text.RegularExpressions
@{
    var contactPage = Model.Content.ContactUsPage as ContentModels.Contact;

    if(contactPage is null || string.IsNullOrWhiteSpace(contactPage.PhoneNumber))
    {
        return;
    }
}

<a href="tel:@contactPage.PhoneNumber.Replace(" ", "")">
    @Regex.Replace(contactPage.PhoneNumber, @"\+44\s*", "0")
</a>

In this example I'm rendering a phone number from the selected contact page (a property on the Block), applying all the logic I want to format the phone number and adding the tel: link.

The journey for adding this block via the backoffice looks like this:

• Click the insert block button
• Pick my phone number block
• Complete the content for the block, a content picker for the contact page in my case
• Save
• And a placeholder appears inline in the RTE

Which, when viewed on the frontend renders my view:

Further reading

Migrating Rich Text Editor Macros to Blocks using uSync Migrations

Property Descriptions: Read more

One of the features that's changed in recent versions is the "read more" functionality. In earlier versions of Umbraco, --- rendered a read more link.

Short description

---

Descriptions below a `---` were rendered behind a "Read More" link in v9-13.

This is no longer the case, --- renders a horizontal rule element (as it should!) but we can recreate the read more functionality with modern HTML.

Short description

---

Three dashes renders a horizontal rule.

<details>
<summary>Read more</summary>

We have to use the native HTML `details` element for modern Umbraco.

</details>

We can even take that a step further - in this example I’m using: markdown to render italic text, a code sample and a hyperlink; HTML to render a <details> element to recreate the read more functionality; and because UUI uses web components, which are HTML, we can bring UUI elements into the descriptions too, so I’ve got a UUI Umbraco help icon in there too to make the property description rich and intuitive without taking too much space.

Should search engines and other crawlers index this page and serve them up as search results?
<details>
<summary>
  <uui-icon name="icon-help-alt" label="More details"></uui-icon> 
</summary>

This sets the *index* aspect of the [`robots` meta tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta/name/robots)

</details>

Useful expressions

I'll keep coming back to this blog post as I create more, so it might be worth a bookmark!

The regular expressions that start with ^ (start of string/line) and end with $ (end of string/line) will ensure the whole string matches. This is useful for validating a string is in the format you expect. To find a string in the format you expect inside another string, these can be omitted.

Most of these regular expressions can be changed to the other method simply by adding/removing the ^(start of string/line) and $ (end of string/line) characters at the start and end respectively.

GUID

Validate a string is a GUID

^(?:\((?=.*\))|{(?=.*}))?[a-fA-F0-9]{8}(?:-(?=(?:.*-){3}))?(?:[a-fA-F0-9]{4}-?){3}[a-fA-F0-9]{12}(?:\)(?<=\(.*)|}(?<={.*))?$

Open in RegExr

Matches guids in most formats that .NET's Guid.Parse can handle (except 0x format), is case insensitive, dashes and brackets are optional, but brackets must match.

Replace a GUID inside a longer string

As above without leading ^ and trailing $.

Find inside a longer string

[a-fA-F0-9]{8}(?:-(?=(?:[a-fA-F0-9]+-[a-fA-F0-9]+){3}))?(?:[a-fA-F0-9]{4}-?){3}[a-fA-F0-9]{12}(?=[$\s)}])

Open in RegExr

This one is simpler as it doesn't need to worry about the brackets - we're looking for the bare minimum that constitutes a GUID.

YouTube URLs

https?:\/\/(?:www.)?(?:(?:youtube.com\/(?:v\/|embed\/|watch\?v=|\&v=))|(?:youtu.be\/))([^#\&\?\s]+)\S*

Open in RegExr

Will match many forms of YouTube URL (default, short links, embed). The first group in the match will be the video ID which can be used to construct an embed URL.

Vimeo URLs

https?:\/\/(?:(?:www\.)|(?:player\.))?(?:vimeo\.com\/(?:channels\/(?:\w+\/)?|groups\/(?:\w+\/)?videos\/|album\/(?:\d+\/)?video\/|video\/|external\/)?(\d+))\S*

Open in RegExr

With thanks to Mike Masey for the starting point of this one.

Umbraco.MultiUrlPicker

Still an array, even in single mode.

Stored in SQL textValue column.

[
  {
    "name": "Link title",
    "udi": "umb://document/bb6ca0ea21334bc6b345afd7c703b965"
  },
  {
    "name": "Link title",
    "url": "https://example.com",
    "queryString": "#with-anchor",
    "target": "_blank"
  }
]

The above is prettified for legibility. The value in Umbraco will have no spaces or new lines.

How to programmatically update a Multi Url Picker This does not work.

Umbraco.MultiNodeTreePicker

Stored in SQL textValue column.

umb://document/bb6ca0ea21334bc6b345afd7c703b965,umb://document/e3d3e3b32d484424815286d4042a80a4

How to programmatically update a "Content Picker"/Multi-node tree picker

Umbraco.ContentPicker

Stored in SQL varcharValue column.

umb://document/bb6ca0ea21334bc6b345afd7c703b965

How to programmatically update a "Document Picker"/Umbraco.ContentPicker

Umbraco.RadioButtonList

Stored in SQL varcharValue column.

One

How to programmatically update a Radio Button List

Umbraco.CheckBoxList

Stored in SQL varcharValue column.

["One","Two"]

How to programmatically update a Checkbox List

Umbraco.TrueFalse

Stored in SQL intValue column.

0

How to programmatically update a Toggle/True-False/checkbox

Umbraco.Tags

Stored in SQL varcharValue column.

["Tag1","Tag2"]

How to programmatically update tags

Umbraco.DateTime

Stored in SQL dateValue column.

2023-03-15 16:20:00

(Time value is 00:00:00 if time is excluded)

How to programmatically update a DateTime

Umbraco.MemberPicker

Stored in SQL varcharValue column.

umb://member/efe1f9fb4a1b460895e70f839ba114d6

How to programmatically update a Member picker

Umbraco.UserPicker

Stored in SQL intValue column.

-1

How to programmatically update a User picker

Umbraco.MultipleTextstring (AKA Repeatable textstrings)

Stored in SQL textValue column.

One
Two
Three

How to programmatically update repeatable textstrings

Umbraco.UploadField (AKA File upload)

Stored in SQL varcharValue column.

/media/inshb1yh/callum-au.png

How to programmatically update an Upload Field. Note: This example is inconsistent with the default behaviour. It uploads the file to the Media library, unlike how File Uploads work via the UI.

Umbraco.ImageCropper

Stored in SQL textValue column.

{"src":"/media/nojjl5no/callum-au.png"}

How to programmatically update an Image Cropper field.

Umbraco.MediaPicker3

Stored in SQL textValue column.

[
  {
    "key": "22ff8e5b-062d-43ac-8aec-fb09ac2277ba",
    "mediaKey": "c63dc11a-4825-488b-8646-36211b812f3b"
  }
]

The above is prettified for legibility. The value in Umbraco will have no spaces or new lines.

How to programmatically update a media picker This looks incorrect.

Umbraco.MediaPicker (legacy AKA v2)

Stored in SQL textValue column.

umb://media/c63dc11a4825488b864636211b812f3b

How to programmatically update a legacy media picker

Umbraco.BlockList

Stored in SQL textValue column.

{
  "layout": {
    "Umbraco.BlockList": [
      {
        "contentUdi": "umb://element/2515bbf8470c43a1bda132d643a4a418"
      },
      {
        "contentUdi": "umb://element/05c3c37d6a814f7a9ac67be3d01dd057"
      }
    ]
  },
  "contentData": [
    {
      "contentTypeKey": "ec586638-a55d-463a-b36e-62ed11e2b2df",
      "udi": "umb://element/2515bbf8470c43a1bda132d643a4a418",
      "property1": "Value"
    },
    {
      "contentTypeKey": "ec586638-a55d-463a-b36e-62ed11e2b2df",
      "udi": "umb://element/05c3c37d6a814f7a9ac67be3d01dd057",
      "property1": "Value"
    }
  ],
  "settingsData": []
}

The documentation does not currently document how to programmatically update a block list. See block grid for inspiration or read Nathaniel Nunes' 24 Days in Umbraco article on Importing Block List Items Programmatically in Umbraco 17

Umbraco.BlockList (single mode)

Exactly the same as non-single mode (but with only one item!)

Stored in SQL textValue column.

{
  "layout": {
    "Umbraco.BlockList": [
      {
        "contentUdi": "umb://element/9ae5d1abe0a84b80a4ace9ae8ab1311b"
      }
    ]
  },
  "contentData": [
    {
      "contentTypeKey": "ec586638-a55d-463a-b36e-62ed11e2b2df",
      "udi": "umb://element/9ae5d1abe0a84b80a4ace9ae8ab1311b",
      "property1": "Value"
    }
  ],
  "settingsData": []
}

The above is prettified for legibility. The value in Umbraco will have no spaces or new lines.

The documentation does not currently document how to programmatically update a block list. See block grid for inspiration.

Umbraco.BlockGrid

Stored in SQL textValue column.

{
  "layout": {
    "Umbraco.BlockGrid": [
      {
        "contentUdi": "umb://element/df08225d94af450a98500b35d4b0e3d4",
        "areas": [],
        "columnSpan": 12,
        "rowSpan": 1
      },
      {
        "contentUdi": "umb://element/e373cf3ef53447f5858941a8640db5b4",
        "areas": [
          {
            "key": "2b314d42-64f8-4608-897b-0b55b449427c",
            "items": [
              {
                "contentUdi": "umb://element/81e9a611a5c84d929d1bb8d5026fc607",
                "areas": [],
                "columnSpan": 6,
                "rowSpan": 1
              }
            ]
          },
          {
            "key": "223adcd7-7e4d-4b95-9c6b-eb2047a01607",
            "items": [
              {
                "contentUdi": "umb://element/bb441112ad794756a542ac1cd7fc4477",
                "areas": [],
                "columnSpan": 6,
                "rowSpan": 1
              }
            ]
          }
        ],
        "columnSpan": 12,
        "rowSpan": 1
      }
    ]
  },
  "contentData": [
    {
      "contentTypeKey": "df88b972-6ba5-4da8-a966-036137a935ad",
      "udi": "umb://element/df08225d94af450a98500b35d4b0e3d4",
      "headline": "Value"
    },
    {
      "contentTypeKey": "cb50a504-b8cd-4262-8344-bddfddc09282",
      "udi": "umb://element/e373cf3ef53447f5858941a8640db5b4"
    },
    {
      "contentTypeKey": "df88b972-6ba5-4da8-a966-036137a935ad",
      "udi": "umb://element/81e9a611a5c84d929d1bb8d5026fc607",
      "headline": "Column 1"
    },
    {
      "contentTypeKey": "df88b972-6ba5-4da8-a966-036137a935ad",
      "udi": "umb://element/bb441112ad794756a542ac1cd7fc4477",
      "headline": "Column 2"
    }
  ],
  "settingsData": []
}

The above is prettified for legibility. The value in Umbraco will have no spaces or new lines.

How to programmatically update a block grid

Umbraco.RichText (including RTE blocks)

Stored in SQL textValue column.

Versions before v13 stored the markup as a string. With the introduction of blocks in the RTE the structure changed to JSON, with the markup stored in the markup property. The rest of the properties relate to blocks referenced in the markup.

{
  "markup": "\u003Cp\u003E\u003Cumb-rte-block-inline data-content-key=\u0022fd41689d-5c48-47a3-91cb-a702e34f2716\u0022\u003E\u003C/umb-rte-block-inline\u003E\u003C/p\u003E",
  "blocks": {
    "contentData": [
      {
        "contentTypeKey": "6d09c413-9063-4ab2-bd6e-eea970903528",
        "udi": null,
        "key": "fd41689d-5c48-47a3-91cb-a702e34f2716",
        "values": [
          {
            "editorAlias": "Umbraco.MultiNodeTreePicker",
            "culture": null,
            "segment": null,
            "alias": "contactUsPage",
            "value": "umb://document/14e766739b714259aac3fc9507eb3bdb"
          }
        ]
      }
    ],
    "settingsData": [],
    "expose": [
      {
        "contentKey": "fd41689d-5c48-47a3-91cb-a702e34f2716",
        "culture": null,
        "segment": null
      }
    ],
    "Layout": {
      "Umbraco.RichText": [
        {
          "contentUdi": null,
          "settingsUdi": null,
          "contentKey": "fd41689d-5c48-47a3-91cb-a702e34f2716",
          "settingsKey": null
        }
      ]
    }
  }
}

The above is prettified for legibility. The value in Umbraco will have no spaces or new lines.

The docs guide on How to programmatically update a Rich Text Editor is currently out of date. Take inspiration from the Block Grid docs or my post on Migrating RTE Macros.

I'm not sure what the expose section does, but it may not be necessary?

I haven't yet worked out a way to contribute this back to the uSync Migrations project as it requires too much customisation. If anybody wants to take this and make it more generically compatible, please do.

The first step is to create element types equivalent to all your macros. Feel free to change names, as the next step is to map them.

Create a Migrator that inherits from RichTextBoxMigrator:

[SyncMigrator(UmbConstants.PropertyEditors.Aliases.TinyMce, typeof(RichTextConfiguration), IsDefaultAlias = true)]
[SyncMigrator("Umbraco.TinyMCEv3")]
[SyncMigratorVersion(7, 8)]
public class RichTextBoxMacrosToBlocksMigrator : RichTextBoxMigrator
{
    private IJsonSerializer _jsonSerializer;
    private ILogger<RichTextBoxMacrosToBlocksMigrator> _logger;

    public RichTextBoxMacrosToBlocksMigrator(ILogger<RichTextBoxMacrosToBlocksMigrator> logger, IJsonSerializer jsonSerializer)
    {
        _logger = logger;
        _jsonSerializer = jsonSerializer;
    }
}

Then create a mapping for all the macros you want to replace with blocks. My mapping class has a field for the macro alias, the alias of the new element type and a dictionary optionally mapping the macro parameter name to the new property alias (no need to include properties that are the same).

private class MacroMapping
{
    public required string MacroAlias { get; set; }
    public required string BlockTypeAlias { get; set; }
    public Dictionary<string, string>? PropertyMappings { get; set; }
}

private IEnumerable<MacroMapping> mappings = new List<MacroMapping>()
{
    new MacroMapping()
    {
        MacroAlias = "renderUmbracoForm",
        BlockTypeAlias = "RenderUmbracoFormEmbeddedBlock",
        PropertyMappings = new Dictionary<string, string>()
        {
            { "ExcludeScripts", "excludeScripts" },
            { "FormGuid", "form" },
            { "FormTheme", "theme" },
            { "RedirectToPageId", "redirectToPage" }
        }
    }
};

Then we can map these across by overriding the GetContentValue method:

public override string? GetContentValue(SyncMigrationContentProperty contentProperty, SyncMigrationContext context)
{
    var rawValue = base.GetContentValue(contentProperty, context) ?? string.Empty;

    var value = new RteValue();

    // Newer sites or RTEs within blocks will already have been converted to the new format, so attempt to parse the JSON
    if (RichTextPropertyEditorHelper.TryParseRichTextEditorValue(rawValue, _jsonSerializer, _logger, out RichTextEditorValue? existingValue))
    {
        // Migrate existing blocks
        value.Blocks!.ContentData.AddRange(existingValue.Blocks?.ContentData.Select(x => new BlockListRowValue() { ContentTypeKey = x.ContentTypeKey, RawPropertyValues = x.RawPropertyValues, Udi = x.Udi?.ToString() }) ?? Enumerable.Empty<BlockListRowValue>());
        value.Blocks!.SettingsData.AddRange(existingValue.Blocks?.SettingsData.Select(x => new BlockListRowValue() { ContentTypeKey = x.ContentTypeKey, RawPropertyValues = x.RawPropertyValues, Udi = x.Udi?.ToString() }) ?? Enumerable.Empty<BlockListRowValue>());
        value.Blocks!.Layout!.BlockOrder.AddRange(existingValue.Blocks?.Layout?["Umbraco.TinyMCE"].Select(x => new BlockUdiValue() { ContentUdi = x["contentUdi"]?.Value<string>(), SettingsUdi = x["settingsUdi"]?.Value<string>() }) ?? Enumerable.Empty<BlockUdiValue>());
    }
    else
    {
        // Existing value is plain HTML markup, we need to update it to match the new format
        existingValue = new RichTextEditorValue() { Markup = rawValue, Blocks = new Umbraco.Cms.Core.Models.Blocks.BlockValue() };
    }

    value.Markup = Regex.Replace(existingValue.Markup, @"\<\?UMBRACO_MACRO macroAlias=""(?<macro>[^""]+)""(?:\s*(?<prop>[^=]*)=""(?<propval>[^""]*)"")*? \/>", match =>
    {
        var macroAlias = match.Groups["macro"].Value;
        var mapping = mappings.FirstOrDefault(x => x.MacroAlias.InvariantEquals(macroAlias));
        if (mapping != null)
        {
            var block = new BlockListRowValue()
            {
                ContentTypeKey = context.ContentTypes.GetKeyByAlias(mapping.BlockTypeAlias),
                Udi = $"umb://element/{Guid.NewGuid():N}"
            };

            // Add block config

            var propVals = match.Groups["propval"].Captures;
            var propNames = match.Groups["prop"].Captures;

            for (int i = 0; i < propVals.Count; i++)
            {
                var propVal = HttpUtility.HtmlDecode(propVals[i].Value);
                var propName = propNames[i].Value;
                propName = mapping.PropertyMappings?[propName] ?? propName;

                block.RawPropertyValues[propName] = propVal;
            }

            value.Blocks!.ContentData.Add(block);

            // Add settings if nescessary
            // value.Blocks.SettingsData.Add(settings);

            value.Blocks!.Layout!.BlockOrder.Add(new BlockUdiValue()
            {
                ContentUdi = block.Udi,
                //SettingsUdi = settings.Udi
            });

            return $"<umb-rte-block class=\"ng-scope ng-isolate-scope\" data-content-udi=\"{block.Udi}\"><!--Umbraco-Block--></umb-rte-block>";
        }
        return match.Value;
    }, RegexOptions.IgnoreCase | RegexOptions.Multiline);

    if (value.Blocks?.Layout?.BlockOrder?.Any() != true)
    {
        // Clear this out if we have no blocks
        value.Blocks = null;
    }

    return JsonConvert.SerializeObject(value, Formatting.Indented);
}

This code sample makes use of custom strongly-typed models for the RTE value. These are included in the full code sample at the end.

You'll then need to add this migrator to your custom Migration Plan:

using System;
using System.Collections.Generic;
using uSync.Migrations.Core;
using uSync.Migrations.Core.Composing;
using uSync.Migrations.Core.Configuration.Models;
using UmbConstants = Umbraco.Cms.Core.Constants;

public class MyMigrationPlan : ISyncMigrationPlan
{
    private readonly SyncMigrationHandlerCollection _migrationHandlers;

    public MyMigrationPlan(SyncMigrationHandlerCollection migrationHandlers)
    {
        _migrationHandlers = migrationHandlers;
    }

    public int Order => 250;
    public string Name => "My Migration Plan";
    public string Icon => "icon-brick color-green";
    public string Description => "";

    public MigrationOptions Options => new MigrationOptions
    {
        Group = "Convert",
        Source = "uSync/v9",
        Target = $"{uSyncMigrations.MigrationFolder}/{DateTime.Now:yyyyMMdd_HHmmss}",
        Handlers = _migrationHandlers.SelectGroup(8, string.Empty),
        SourceVersion = 8,

        // This adds our migrator
        PreferredMigrators = new Dictionary<string, string>
        {
            { UmbConstants.PropertyEditors.Aliases.TinyMce, "RichTextBoxMacrosToBlocksMigrator" },
        }
    };
}

You'll notice I'm using the Convert ("Convert this site" via the UI) method that uSync Migrations offers rather than legacy ("Migration" via the UI) . This is for converting content already on a site. This works well if you've upgraded a site to v13 (where macros and blocks in RTEs are both supported), run the migrators and then (optionally) migrate to a newer Umbraco version.

Complete RichTextBoxMacrosToBlocksMigrator.cs file

using Newtonsoft.Json.Linq;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Extensions;
using UmbConstants = Umbraco.Cms.Core.Constants;
using uSync.Migrations.Core.Migrators;
using uSync.Migrations.Core.Migrators.Models;
using uSync.Migrations.Core.Context;
using System.Linq;
using System.Collections.Generic;
using System.Text.RegularExpressions;
using Newtonsoft.Json;
using System;
using System.Web;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Serialization;
using Microsoft.Extensions.Logging;

namespace uSync.Migrations.Migrators.Core;

[SyncMigrator(UmbConstants.PropertyEditors.Aliases.TinyMce, typeof(RichTextConfiguration), IsDefaultAlias = true)]
[SyncMigrator("Umbraco.TinyMCEv3")]
[SyncMigratorVersion(7, 8)]
public class RichTextBoxMacrosToBlocksMigrator : RichTextBoxMigrator
{
    private IJsonSerializer _jsonSerializer;
    private ILogger<RichTextBoxMacrosToBlocksMigrator> _logger;

    public RichTextBoxMacrosToBlocksMigrator(ILogger<RichTextBoxMacrosToBlocksMigrator> logger, IJsonSerializer jsonSerializer)
    {
        _logger = logger;
        _jsonSerializer = jsonSerializer;
    }


    // Map across each macro to an already created type and optionally map the properties
    private IEnumerable<MacroMapping> mappings = new List<MacroMapping>()
    {
        new MacroMapping()
        {
            MacroAlias = "renderUmbracoForm",
            BlockTypeAlias = "RenderUmbracoFormEmbeddedBlock",
            PropertyMappings = new Dictionary<string, string>()
            {
                { "ExcludeScripts", "excludeScripts" },
                { "FormGuid", "form" },
                { "FormTheme", "theme" },
                { "RedirectToPageId", "redirectToPage" }
            }
        }
    };

    public override string? GetContentValue(SyncMigrationContentProperty contentProperty, SyncMigrationContext context)
    {
        var rawValue = base.GetContentValue(contentProperty, context) ?? string.Empty;

        var value = new RteValue();

        // Newer sites or RTEs within blocks will already have been converted to the new format, so attempt to parse the JSON
        if (RichTextPropertyEditorHelper.TryParseRichTextEditorValue(rawValue, _jsonSerializer, _logger, out RichTextEditorValue? existingValue))
        {
            // Migrate existing blocks
            value.Blocks!.ContentData.AddRange(existingValue.Blocks?.ContentData.Select(x=> new BlockListRowValue() { ContentTypeKey = x.ContentTypeKey, RawPropertyValues = x.RawPropertyValues, Udi = x.Udi?.ToString() }) ?? Enumerable.Empty<BlockListRowValue>());
            value.Blocks!.SettingsData.AddRange(existingValue.Blocks?.SettingsData.Select(x => new BlockListRowValue() { ContentTypeKey = x.ContentTypeKey, RawPropertyValues = x.RawPropertyValues, Udi = x.Udi?.ToString() }) ?? Enumerable.Empty<BlockListRowValue>());
            value.Blocks!.Layout!.BlockOrder.AddRange(existingValue.Blocks?.Layout?["Umbraco.TinyMCE"].Select(x => new BlockUdiValue() { ContentUdi = x["contentUdi"]?.Value<string>(), SettingsUdi = x["settingsUdi"]?.Value<string>() }) ?? Enumerable.Empty<BlockUdiValue>());
        }
        else
        {
            // Existing value is plain HTML markup, we need to update it to match the new format
            existingValue = new RichTextEditorValue() { Markup = rawValue, Blocks = new Umbraco.Cms.Core.Models.Blocks.BlockValue() };
        }

        value.Markup = Regex.Replace(existingValue.Markup, @"\<\?UMBRACO_MACRO macroAlias=""(?<macro>[^""]+)""(?:\s*(?<prop>[^=]*)=""(?<propval>[^""]*)"")*? \/>", match =>
        {
            var macroAlias = match.Groups["macro"].Value;
            var mapping = mappings.FirstOrDefault(x => x.MacroAlias.InvariantEquals(macroAlias));
            if (mapping != null)
            {
                var block = new BlockListRowValue()
                {
                    ContentTypeKey = context.ContentTypes.GetKeyByAlias(mapping.BlockTypeAlias),
                    Udi = $"umb://element/{Guid.NewGuid():N}"
                };

                // Add block config

                var propVals = match.Groups["propval"].Captures;
                var propNames = match.Groups["prop"].Captures;

                for (int i = 0; i < propVals.Count; i++)
                {
                    var propVal = HttpUtility.HtmlDecode(propVals[i].Value);
                    var propName = propNames[i].Value;
                    propName = mapping.PropertyMappings?[propName] ?? propName;

                    block.RawPropertyValues[propName] = propVal;
                }

                value.Blocks!.ContentData.Add(block);

                // Add settings if nescessary
                // value.Blocks.SettingsData.Add(settings);

                value.Blocks!.Layout!.BlockOrder.Add(new BlockUdiValue()
                {
                    ContentUdi = block.Udi,
                    //SettingsUdi = settings.Udi
                });

                return $"<umb-rte-block class=\"ng-scope ng-isolate-scope\" data-content-udi=\"{block.Udi}\"><!--Umbraco-Block--></umb-rte-block>";
            }
            return match.Value;
        }, RegexOptions.IgnoreCase | RegexOptions.Multiline);

        if (value.Blocks?.Layout?.BlockOrder?.Any() != true)
        {
            // Clear this out if we have no blocks
            value.Blocks = null;
        }

        return JsonConvert.SerializeObject(value, Formatting.Indented);
    }

    private class MacroMapping
    {
        public required string MacroAlias { get; set; }
        public required string BlockTypeAlias { get; set; }
        public Dictionary<string, string>? PropertyMappings { get; set; }
    }

    // Strongly typed versions of RichTextEditorValue
    private class RteValue
    {
        [JsonProperty("markup")]
        public string? Markup { get; set; }
        [JsonProperty("blocks")]
        public BlockListValue? Blocks { get; set; } = new BlockListValue();
    }
    private class BlockListValue
    {
        [JsonProperty("layout")]
        public BlockListLayoutValue? Layout { get; set; } = new BlockListLayoutValue();

        [JsonProperty("contentData")]
        public List<BlockListRowValue> ContentData { get; set; } = new List<BlockListRowValue>();

        [JsonProperty("settingsData")]
        public List<BlockListRowValue> SettingsData { get; set; } = new List<BlockListRowValue>();
    }
    private class BlockListLayoutValue
    {
        [JsonProperty("Umbraco.TinyMCE")]
        public List<BlockUdiValue> BlockOrder { get; set; } = new List<BlockUdiValue>();
    }
    private class BlockUdiValue
    {
        [JsonProperty("contentUdi")]
        public string? ContentUdi { get; set; }

        [JsonProperty("settingsUdi")]
        public string? SettingsUdi { get; set; }
    }
    private class BlockListRowValue
    {
        [JsonProperty("contentTypeKey")]
        public Guid ContentTypeKey { get; set; }

        [JsonProperty("udi")]
        public string? Udi { get; set; }

        [JsonExtensionData]
        public IDictionary<string, object?> RawPropertyValues { get; set; } = new Dictionary<string, object?>();
    }
}

Clothes

Codegarden is a pretty casual affair - think jeans, tee and a hoodie. The weather is generally pretty mild, though it can get a little chilly and rainy - but we often see the sun too!

• swashbuckling pre-party outfit - the theme this year is pirates! 🏴‍☠️
• warm jacket, just in case!
• waterproof jacket
• sun hat
• hoodie/jacket/sweater, in case the venue is a little chilly or you're out late
• shorts
• tops and t-shirts (Umbraco swag, if you have them!)
• jeans/casual trousers
• dresses/skirts, but keep it casual
• comfortable shoes/trainers (Jen aggrees!)
• flip-flops (if you ask Discord, that is!)
• dancing shoes for Thursday night 💃🕺(so Steffie informs me!)
• pyjamas
• underwear

Feeling sporty?

Codegarden offers a few sporting opportunities, if you're so inclined. 🏓🚲🧗🏃🏊

• sports-wear and -gear for padel, cycling or bouldering, if you've signed up for Tuesday morning
• running kit, if you want to join the CG Runners each morning - #cgRunners
• swimming kit, sauna towel and towel (there's a cohort of people swimming in the free lido each morning - keep an eye on the socials #cgSwimmers)

Electronics

It's a tech conference after all!

• phone
• local SIM if your roaming deal sucks - $3 off an Airalo eSIM with code JOE9791* or try Firsty for free (but slow and ad-supported) data in Europe.
• power bank (planes generally restrict to <100Wh and this must be in hand luggage)
• charge cables
• USB wall charger
• laptop, for workshops, hackathons or inspired coding
• laptop charger (I'm looking at you, Jason!)
• EU adaptor, if your plug pins are an odd shape! (Denmark uses 230V, so you might need a voltage converter if your devices like voltages closer to 100V 🦅)
• headphones (vital for the journey!)

Hygiene

We like to hug and high-5!

• toothbrush
• toothpaste
• deodorant
• other toiletries and grooming kit
• medication (including antihistamines, pain killers, etc.)
• check what else you need if you're staying in an Airbnb! (Towel, shampoo, etc)

Travel

• passport (check the validity!) or ID card (if you're lucky enough!)
• visa (if required)
• health insurance card, if your country has one (e.g. EHIC, GHIC) - this still includes UK residents post-brexit
• travel insurance documentation, if not travelling with work or you don't have a health insurance card
• flight/train tickets (remember to check in!)
• hotel reservation details
• train reservation details (it can be cheaper and easier to prebook!)
• fee-free payment card (Revolut*, Monzo* and Starling* are popular options in the UK, register now to save money next time)
• (Probably no) Danish Kroner (optional, particularly with a fee-free card. Almost everywhere in Denmark accepts card - including hot dog carts! - and some places will refuse cash. I've never taken cash nor felt the need for it.)

Miscellaneous

• backpack/bag - handy for lugging your stuff around the venues
• water bottle - remember to empty before airport security, but you can usually fill it up again before the flight!
• reusable coffee cup (free coffee, but make it eco!)
• sun cream (you never know!)
• sun glasses
• wallet
• notebook & pen
• snacks for the journey
• entertainment for the journey - offline games, podcasts, movies, audiobooks and/or ebooks (or an analogue book if you're so inclined)

Presenting?

• slides (offline) and a backup
• display dongle (if your laptop doesn't have HDMI)
• clicker
• laser pointer

*referral links mean we both get something nice!

See you in Odense!

So grab your laptops, charge up your brain cells, and get ready to embark on a wild journey where coding meets camaraderie, where networking knows no bounds, and where the exchange of knowledge is only rivaled by the exchange of witty tech puns. 🤓

I'll see you there!

More tips

There's now a whole Discord channel dedicated to Codegarden, so ask any questions you have in there.

In 2024, Seb had a fantastic pre-Codegarden 2024 megathread on Discord (also available without Discord login) which is still relevant this year!

Print this page or use the checkboxes to mark off items as you pack! Checked items are saved locally in your browser.

Getting hyped up for Spark

Keep up to date with the goings on by following Spark on Mastodon or BlueSky as the details unfold and they share crucial event information. Keep an eye on the #UmbracoSpark, #Umbraco and #UmbracoCommunity hashtags in the lead up to the event to keep in touch with the communuity.

The fun before the party starts!

Although the Spark conference is only one day, the fun starts the day before with a hackathon and pre-party.

Hackathon

Umbraco and true digital are hosting a hackathon all day on Thursday 7 March!

This is a great opportunity to get stuck in with the Umbraco source code, with Umbraco HQ crew and community experts on site to help you out!

Alternatively, use the hackathon as a chance to get started on your PackageJam submission!

What is an Umbraco Hackathon?

Unlike some other hackathons you may have attended, Umbraco hackathons don't have a strict theme or overall goal. They're an excuse to get together and code together. People work on Umbraco source code bugs, Umbraco packages and community projects. You don't need to have an idea before you attend - but be sure to ask for inspiration when you get there.

The hackathon will include refreshments and lunch (usually pizza or burritos).

Convince your boss!

How do you convince your boss to let you take an extra day for Spark? Simple! Hackathons allow you to get your head into the source code and understand how the product works better. You might even be able to fix some bugs that have been niggling your business for a while! You also get the assistance of Umbraco employees and community experts - who better to help you understand the Umbraco ecosystem!? Plus the usual networking - it's a very sociable way to code!

You don't have to be there for the whole thing either - just turn up for the afternoon if that's all you can muster!

More information and sign up on Meetup. This is a separate event and requires signing up (free!) on Meetup to attend. Once signed up, keep an eye on your inbox in the weeks leading up to the event for more details.

Pre-party!

Every year umBristol, the Bristol Umbraco Meetup, host a pre-party to make friends (it's like "networking" but more fun!) and have fun. This year we're all meeting just 5 minutes from the hackathon venue at Roxy Lanes to play some duck-pin bowling, ice-free curling and other games. A few drinks and/or snacks are sometimes thrown in by the sponsor, and there's an opportunity to buy food and drink.

More information and sign up on Meetup. This is a separate event and requires signing up (free!) on Meetup to attend.

The big day - what to expect

Morning run (optional!)

Spark are hosting a morning 5km run. It should be "easy-paced" (but Frederik always claims his pre-Codegarden runs will be easy too - maybe I'm just too slow!) You'll need to register your interest in joining the run and meet outside The Bristol Hotel Prince Street, BS1 4QF.

Umbraco Spark!

Spark is hosted at the curiosity-inducing We The Curious in Millennium Square. This is an exciting new venue for Spark, but once at We The Curious expect the usual Spark signage pointing you to the venue and you can expect to be greeted by some friendly Bristolians to get your name badge and merch. Coffee and tea are usually available and it's time to mingle! The Umbraco community are very friendly (it's kinda their thing!), so don't be afraid to chat to people you've never met before (even if they're a community celebrity!) I'll be there awkwardly mingling too, so come and chat to me - "I read your blog post" is always a great conversation opener!

Spark offers one track this year which, looking at the lineup, promises to be interesting. The other option at Spark this year is to enter the PackageJam which will run alongside the talks. If you miss some talks, why not ask the speaker to repeat at your local meetup?

Lunch and snacks are provided at various points throughout the day, as well as a cheeky drink at the end before we move on to...

The after-party

No need to book this one, just turn up to Ritorno Lounge next to the harbour with your lanyard and follow signs upstairs to The Caraboo (it's privately hired). It's always nice to join folks for a drink and food before heading home - so try to plan around this if you can! There will be food and drink to buy at the after-party venue (this one's not included).

It's usually a casual affair where we sit and chat with friends new and old late into the night!

What do I need to bring/wear?

Spark is a casual conference, so a hoodie and jeans will suit for all events. Umbraco merch is always a bonus if you want to fit in! Also, remember a raincoat - we're only a stones throw from Wales after all!

You're also unlikely to need a laptop during the conference, but you might want to bring a notebook or take photos. If you elected to receive merch when buying your ticket, you'll get a branded notebook and pen on arrival as well as a t-shirt.

Don't forget your laptop and charger if you're also attending the hackathon!

Map

A map of the primary locations is included below. It also includes my recommendations for Bristol - read on for details!

Open map full screen.

The Umbracian's guide to Bristol

Bristol is a lovely city - so lovely, in fact, I moved here in 2022 - so many people elect to stay in the area for the weekend afterwards. Here's some advice for those people:

Getting around

Although the city is quite sprawling, a lot of Bristol is accessible by foot (particularly if you're good with hills!)

As much as the locals complain, Bristol has a pretty good bus network (just don't compare it to London or any continental European city!) Fares are £2.40 for a single with a cap at £6.50 for the day, if you stay within Bristol. Busses all support tap-on-tap-off which are automatically capped, so no cash is needed.

For bike and electric scooter hire you'll need the Dott app (this is a different app to last year!) which you'll need your driving license (full or provisional) to sign up for, so be sure to do that ahead of time.

Food and drink

Bristol is home to fantastic independent cafes, pubs, restaurants and food stalls - as well as the birthplace of small chains like The Lounges and Boston Tea Party.

My favourite food stalls are in Wapping Wharf (Spike Island, harbourside) (St Nicholas Market is closed at the weekend!)

You can't go wrong with most cafes in Bristol, but some of my regulars are Mud Dock (harbourside), The Bristol Loaf ("The Centre"), East Village Cafe (Clifton Village) and Santiago's (particularly if you're waiting for a bus at the bus station!)

Some of my favourite pubs include The Apple (central) (don't miss having a half - too strong to sell it in pints! - of Old Bristolian cider on this cider-barge), The Strawberry Thief (central), The Cottage Inn (Spike Island, harbourside) and pretty much anywhere on King Street (central).

A touch of nature

Leigh Woods is a fantastic woodland a short walk over Clifton Suspension Bridge. You'll want some boots but it's easy to follow signposted routes.

Ashton Court is a deer park with great views over Bristol and a lovely cafe. You can stick to tarmac and gravel paths here if you want clean shoes! Also a Parkrun location.

Brandon Hill is a lovely park right next to Park Street and is home of Cabot Tower - which is worth a climb (free) for some more fantastic views.

Shopping

Cabot Circus and Bristol Shopping Quarter are mostly (although not entirely!) big chain shops you'd find in most cities.

Clifton Village (further out than Clifton but within the city, unlike it's name implies!) is where you'll find the best of Bristol's local boutique-y gift shops and cafes. Also worth visiting the iconic suspension bridge while you're there.

A little closer to the centre of town is Park Street and Whiteladies Road as well as Gloucester Road, less classy than Clifton but some lovely smaller shops. (Gloucester Road is the charity-shopper's heaven!)

Sightseeing

Bristol is home to some great museums. M Shed is the historic venue for Spark but also a great little free museum. You can find more information about all the Bristol Museums on their website.

This year's venue is also a museum - We The Curious is an interactive science museum that's recently reopened after a large fire. I've not been since the reopening, but have fond memories of going as a child!

Next to We The Curious is the aquarium (central) which is expensive but very good. Bristol Zoo is no longer located in Clifton, and is now outside the city.

Cabot Tower in Brandon Hill park (central) is free to climb for some epic views.

Clifton Suspension Bridge (Clifton Village) is free to walk across and Observatory Hill is nearby for some good views and a nice coffee shop. Or head into Clifton Village for endless cafes and pubs.

Bristol University has several beautiful historic buildings. The closest to the city centre are at the top of Park Street along with the Bristol Art Gallery.

Personally, I like to explore new cities using virtual audio tours. Claim a free one using my VoiceMap referral link. There are 5 highly-rated tours of Bristol to choose from.

Nearby

The cities of Bath and Cardiff, Wales are within an easy train ride (15 minutes or 1 hour respectively) if you want to spread your wings a little further.

See you there!

I'll be at the hackathon right the way through to the after party - so I'll see you there! Please come and say hi, and see my talk too if it appeals!

If you think I've missed something vital, let me know on socials!

Thanks to Tristan Thompson for his contributions to the 2024 post which have been brought forwards.

This content is also available with examples as a talk recording from WeAreDevelopers 2024.

Hello there, professional googlers!

We've all heard that software developers are just "professional googlers" and the more senior you are is mostly a product of how good you are at Googling things... and it's a great joke... but have you ever tried being a developer without internet access? It doesn't feel like much of a joke then, does it?

But I don't see that as a negative, as such. When we're isolated we may feel weak and hopeless but as a team, as a community, we're quick and efficient problem solvers.

And that's where the idea for this article came from - how can we work together more effectively as a worldwide developer community without getting stung along the way?

How can I ask for help?

Before we start with how and what to copy and paste, let's first start with some places we might find answers.

Obviously, please google* your query before you start asking people!

* I'm using the term "google" as a search-engine-agnostic term. Personally, I google it on Bing these days.

Sources that you might find useful include the official documentation; YouTube demos, tutorials, talk recordings (there's even a talk I did covering this very topic on YouTube if you're not a fan of reading!); people's blog posts (hello 24 Days in Umbraco!); or even looking at the source code.

Particularly if you're looking for help around open source projects like Umbraco, existing answers to other people's questions are very prevelant. So any destination we're going to talk about with regards to getting help, there might already be solutions there for you without you even needing to ask the question.

Image source: @VishalMalvi_ on X (probably, memes are really hard to attribute!)

Where to ask for help

Now we've established we can't find the answer already on the internet, so we need to ask for help but where do go to do that?

StackOverflow is good for some more generic development questions.

Some repositories on GitHub have discussions or some developers might like you to raise issues if you're confused about a situation.

Are there any specialised communities that you're part of? (I'm looking at you, Umbraco!) Specialized communities are smaller communities who are experts in the thing you're trying to do. There are forums, Discords, Slacks for these groups of developers.

Umbraco has a thriving community with plenty of places to ask questions, and we should take advantage of that!

Social media is a another fantastic place to find people to help you - Mastodon, X, Bluesky, Reddit, whatever your social media of choice is and wherever a developer community exists.

How to ask for help

Now we have these places to ask for help, but how exactly do we do it? It feels like an odd question but perhaps more specifically, how can I ask a question in a way that's going to get an answer that's most appropriate and most helpful to me? Because although the community is generally very helpful, it's to our own benefit to ask the right questions in the first place.

I've developed a 6 item checklist for a good question (and we know this is good advice, by the way, because it's inspired by StackOverflow's "How to Ask" and if anyone is fussy about how you ask a question it's StackOverflow!)

1. Do your research first

   Although we've already searched for answers to the question it's also important that we do some background research so that we can explain ourselves correctly and be very specific about our problem. There's also very little point asking a question if we don't know what we're asking - if we don't understand what we're asking then we need to ask a different question.

2. Comprehend the problem

   I'm using the word "comprehending" here to mean "understand". But I'm using the word "comprehend" because it emphasizes the fact we don't need to know everything - we don't need to "understand" everything, just "comprehend" what we want to understand.

   Try rubber duck debugging as a helpful tool to help comprehend your problem.

3. Be polite and patient

   ...because nobody has to help you. Any prospective answerer is just on the internet looking to reach out and give you a bit of a hand. They don't have to do it. So being polite and patient goes a long way to getting the best answer to your questions.

4. Be on topic and be suitable

   This includes any tags and categories you apply to your topic. So if you're posting on a forum make sure you're posting it in the right category and use the right tags. If you're using social media, it's really, really important to ask- if you're going to be asking the right people the right questions you need to make sure you're asking these questions in the right places in places people are expecting questions on the subject you're asking questions about.

5. Summarize your problem

6. Include a reproducible example

   I’ve grouped these two together here. It's really important to get across what you're trying to say in a concise manner but with an example. It also can really help to simplify your example too, removing any code and context that's irrelevant to your question - you don't need to give everybody all the information about the project you're working on but if you can find an example that is a little bit simplified, it can make everyone's life a lot easier. (Actually, simplifying your code can help you narrow down the problem yourself!)

Rubber duck debugging can be a useful tool to help comprehend a problem. Created with DALL-E.

What about AI?

So what about AI? I've been talking a lot about community and collaboration so why am I bringing up artificial intelligence? (It's not just so I can apply the trendy "AI" tag to the article, honest!) LLMs (Large Language Models) have been scouring the internet looking at our problems and our code samples and, as I see it, they’re tools effectively built by the community and it takes a lot of the same skills to effectively use an AI-generated answer as it does to pick the right StackOverflow answer.

LLMs are the AI tools we’ve seen popping up all over the place in the past few years, be that OpenAI ChatGPT, Microsoft CoPilot, Github Copilot or Google Gemini - they’re all LLMs and largely work in the same sort of way and we have to provide the model with the same context (and treat their responses with the same level of scrutiny as) we would if we were asking a stranger on the Internet.

What can I ask AI to do?

AI is really good as a starting point - and this is quite key for most AI generated responses - for various programming tasks.

Take writing regular expressions for example. Say we ask it to "give me a regular expression for UK phone numbers", it will give you a starting point for that. But it will also give you a starting point for sort of more generic coding questions as well.

AI is also good as an autocomplete. One of the big use cases I have for GitHub Copilot is as I'm typing some very repetitive code Copilot will quite often suggest doing the same thing I've been doing to the code above to the code below. It's very good at picking up repeating patterns or spitting out very common structures.

You can also use AI, though, to explain code samples and error messages or to convert from one format to another. Perhaps "convert the following XML file into JSON" isn’t the best example, there are numerous XML to JSON converters online, but if you're trying to convert between two very niche formats or between programming languages where there wouldn't necessarily make sense to be a direct converter, AI is pretty good at that sort of thing.

Another option is to use LLMs to be your rubber duck.

As we saw earlier, not only is AI good at helping with code, AI tooling is also pretty good at generating images of rubber ducks in an office setting. But, it turns out, it's also pretty good at generating images of rubber ducks "rubber ducking" with a desktop rubber human. Created with DALL-E.

When might I want to ask elsewhere?

AI isn’t always useful, though.

LLMs can have a poor understanding of performance.

It's pretty bad at understanding versions too, particularly in the .NET world (Microsoft's not always the best at naming things!) When .NET Framework was completely rewritten as .NET Core and then renamed .NET, AI is not particularly good at understanding the difference between those two (three?) versions. In the front-end world too distinguishing between Angular and AngularJS isn’t always clear. AI is not very good at picking out on these specific weird naming conventions and giving you answers that make sense for the language you're asking them in.

It’ll often invert boolean logic (which is a problem for me because my human brain also likes to invert boolean logic!) so asking AI for a string of ands, ors and boolean operations is not always the best option because it will often get those completely the wrong way around (or should that be “way wrong around”?).

You can struggle to persuade LLMs to make modifications to previous code samples. I’ve often asked for tools to "write me a regular expression for international phone numbers", which it does, but often omitting one thing or another. Following that up with a query like “please also allow the hyphen character” (as our friends across the Pond are fond of them) has previously resulted in the model returning a US-specific expression, ignoring the “international” requirement. It’s always worth double checking both the initial response as well as any later modifications.

And, boy, does it make things up! In my experience, AI will rarely tell you that you can't do something. It will generally make up a way that you can even if those ways are not possible, using API methods that don't exist, mythical namespaces and libraries that it’s invented - it will never say no.

It will never ask questions or give options like a human would. If a human doesn't fully understand the question it will say "oh sorry, I'm not sure I quite follow - can you provide me this context?" AI doesn't do that, it will give you an answer to what it "thinks" the question is which can lead you down the wrong rabbit holes!

Assessing the suitability of an answer

All right, so we've asked questions to humans, we've asked questions to AI now we need to know how to copy and paste.

We've established AI can be wrong because AI learns from people and people are wrong too so whoever you've asked it's very important that we assess the suitability of an answer.

It’s important to reiterate how important it is to comprehend the problem we’re experiencing. We can’t assess the suitability of an answer without this initial comprehension - we can’t grade an answer without knowing the criteria we’re scoring against.

Once we’ve comprehended the problem, it’s time to comprehend the solution. As before, we don't need to understand every intricacy of the code, we don't need to understand line by line exactly what's happening but we should know roughly what each line of code is doing and why it's there - we should have an idea of how it works.

This brings us to another checklist (I really like checklists, don’t I?!), my solution suitability checklist!

• Does it answer my question?

  Does the answer that's been given make sense as a response to the question that I asked? It could have been misread or misunderstood. And if I’m reading a solution to someone else’s question, is my question the same one as is being answered? A keyword search might have brought up questions that are very subtly different, which means they could have a less subtly different solution.

• Line by line, what is this doing?

  If it's a code solution what does each line do? You don't have to understand every intricacy of the code but we should have an idea line by line what it's doing.

• Does the code match the description?

  If someone's written a description of what a code sample does (LLMs usually do this too) does that match up with what the code actually does? If it doesn't, then we've potentially got a problem!

• Does that feel right?

  This feels like a bit of a “fluffy” checklist item, but as a developer I often rely on my “gut feel” to hunt down “code smell”! We should ask how can we apply our existing knowledge to the answer to see if it makes sense.

• How can we increase our confidence in this answer?

  If we don’t have enough background knowledge to instantly know the solution is correct, what else could we ask or what else could we look up to help us reassure us that this is the way forwards? If the solution is a regular expression, for example, perhaps we could plumb it into a regular expression explainer tool to ensure it matches our expectations. We could even dry run the code as a sanity check.

(Please appreciate the visual pun here. They're running in the desert, therefore, they're dry running!) Photo by Annie Spratt on Unsplash.

Adapting code to meet our needs

The next thing we might need to do is adapt some code to meet our needs. Perhaps we simplified our question and now we need to adapt the answer to fit back into our more complex solution. This is only possible when we’ve understood the solution, but now that we have a better understanding we can tweak it to what we're expecting it to be.

And if we’ve established the answer we’ve found doesn’t quite meet our suitability criteria, through our further research we may be able to tweak an answer that’s close to correct to be the ideal solution.

How to Copy & Paste

(Hey look! That's the title of the article!)

If you thought two checklists were enough for one article, you were wrong! I've condensed the whole article into five-point checklist for how to copy and paste:

• Google it!
• Ask the best people (or robots) in the best place in the best way
• Know what and why you're asking
• Comprehend and validate the answer
• Adapt to meet your needs

With these tips, I hope we can level-up our Ctrl+V game and become better developers and a together stronger community.

Additional indexes means more storage and more places for index corruption, so I prefer to keep my indexes to a minimum. Umbraco comes with an ExternalIndex out the box - this is designed to be used for end-user site search, and doesn't contain any unpublished nodes (unlike the InternalIndex which is intended to be used by the backoffice).

Defining fields in an existing index

To add our own fields to an index or to change the type of a field, we need to create an IConfigureNamedOptions<LuceneDirectoryIndexOptions>. This class will need registering in a composer (see below). The important lines are:

options.FieldDefinitions.AddOrUpdate(new FieldDefinition("searchCategories", FieldDefinitionTypes.Raw));
options.FieldDefinitions.AddOrUpdate(new FieldDefinition("searchDate", FieldDefinitionTypes.DateMonth));

The definition name is a magic string we'll use to reference the field when setting the values or searching. It can be anything so long as it is unique (avoid calling it the same thing as one of your properties!) and is conventionally camelCased.

Select the most relevant field definition type from the Examine Value Types documentation. In this example, I've used Raw (for exact matches) and DateMonth (for storing dates as Ticks to the precision of the month).

My full class looks like this:

public class ConfigureExternalIndexOptions : IConfigureNamedOptions<LuceneDirectoryIndexOptions>
{
    private readonly IOptions<IndexCreatorSettings> _settings;

    public ConfigureExternalIndexOptions(IOptions<IndexCreatorSettings> settings)
        => _settings = settings;

    public void Configure(string? name, LuceneDirectoryIndexOptions options)
    {
        if (name?.Equals(Constants.UmbracoIndexes.ExternalIndexName) is false)
        {
            return;
        }

        options.FieldDefinitions.AddOrUpdate(new FieldDefinition("searchCategories", FieldDefinitionTypes.Raw));
        options.FieldDefinitions.AddOrUpdate(new FieldDefinition("searchDate", FieldDefinitionTypes.DateMonth));
    }

    // not used
    public void Configure(LuceneDirectoryIndexOptions options) => throw new NotImplementedException();
}

Adding or updating values in an existing index

If you only want to modify the value of a field or have created the new field, as above, we can start populating the fields in the index.

To do this, we have to copy the existing values to a dictionary, add or modify the values and save them back using the SetValues method.

Each field can have multiple values, as shown in the case of searchCategories, but this is often an array of one item, like with searchDate.

I've also commented out an example of modifying a value which is the example given in my blog post on Tag-style exact-matching with Examine. In this case, I could have done the same thing with categories, but have chosen to index the sanitized values as a new field in this example.

public class ExternalIndexValueTransformationComponent : IComponent
{
    private readonly IExamineManager _examineManager;
    private readonly IShortStringHelper _shortStringHelper;

    public ExternalIndexValueTransformationComponent(IExamineManager examineManager, IShortStringHelper shortStringHelper)
    {
        _examineManager = examineManager;
        _shortStringHelper = shortStringHelper;
    }
    public void Initialize()
    {
        if (!_examineManager.TryGetIndex(Constants.UmbracoIndexes.ExternalIndexName,
                out var index))
        {
            return;
        }

        if (!(index is BaseIndexProvider indexProvider))
        {
            return;
        }

        indexProvider.TransformingIndexValues += ExternalIndex_TransformingIndexValues;
    }


    private void ExternalIndex_TransformingIndexValues(object? sender, IndexingItemEventArgs e)
    {
        var values = e.ValueSet.Values.ToDictionary(x => x.Key, x => (IEnumerable<object>)x.Value);

        // Insert new values

        if (e.ValueSet.Values.ContainsKey("displayDate") && DateTime.TryParse(e.ValueSet.GetValue("displayDate").ToString(), out DateTime date))
        {
            var searchDate = date.ToString("MM-yyyy");
            values.Add("searchDate", new [] { searchDate });
        }

        if (e.ValueSet.Values.ContainsKey("categories"))
        {
            var categories = e.ValueSet.GetValues("categories")
                .Select(x => x.ToString()?.ToCleanString(_shortStringHelper, CleanStringType.UrlSegment))
                .WhereNotNull().ToArray();
            if (categories?.Any() ?? false)
            {
                values.Add("searchCategories", categories);
            }
        }

        // Modify existing values
        //foreach (var value in e.ValueSet.Values)
        //{
        //    if (value.Key == "myKey")
        //    {
        //        var values = value.Value.FirstOrDefault().ToString().Split(Environment.NewLine);
        //        updatedValues["myKey"] = values.Cast<object>().ToList();
        //    }
        //}

        e.SetValues(values.ToDictionary(x => x.Key, x => x.Value));

    }

    public void Terminate()
    {
        if (_examineManager.TryGetIndex(UmbracoIndexes.ExternalIndexName, out IIndex index)
            && index is BaseIndexProvider externalIndex)
        {
            externalIndex.TransformingIndexValues -= ExternalIndex_TransformingIndexValues;
        }
    }
}

Registering the configuraiton

Both of these need adding to a composer's compose method

public class Composer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.Services.ConfigureOptions<ConfigureExternalIndexOptions>();
        builder.Components().Append<ExternalIndexValueTransformationComponent>();
    }
}

Rebuild the indexes

You can debug the methods above either by saving a content node or by rebuilding the index with a breakpoint in the above code. You'll also need to rebuild the index to get the new/modified values for all content.

To rebuild the index, navigate to Settings > "Examine Management" tab > ExternalIndex > "Rebuild index" button.

Searching with the modified index

Here's an example of a blog search functionality. This could live in a controller or service. This makes use of the Search Extensions package, which I generally recommend, for some of the extension methods and path format.

if (_examineManager.TryGetIndex(UmbracoIndexes.ExternalIndexName, out IIndex index) == false)
{
    throw new Exception($"Failed to find {UmbracoIndexes.ExternalIndexName}");
}

var type = typeof(BlogPost).Name.ToLower();

var query = index.Searcher.CreateQuery("content").NodeTypeAlias(type);

query.And().Field("path", blogRoot.Id.ToString());

if (!string.IsNullOrEmpty(category))
{
    query.And().Field("searchCategories", category);
}

if (!string.IsNullOrEmpty(month))
{
    if (DateTime.TryParseExact(month, "MM-yyyy", null, DateTimeStyles.None, out var date))
    {
        query.And().Field("searchDate", date);
    }
}

if (sortAscending == true)
{
    query.OrderBy(new SortableField("searchDate", SortType.Long));
}
else
{
    query.OrderByDescending(new SortableField("searchDate", SortType.Long));
}

var searchResults = query.Execute();

return searchResults.GetResults<BlogPost>();

Further Reading

• Tag-style exact matching

Clothes

CODECABIN is a very casual affair - wear whatever you'll be comfortable in. The weather in the Peak District in September is varied. Check the weather forecast because it could be boiling hot and sunny, thunderstorms, or anything in between (perhaps even both).

• hoodie/jacket/sweater, in case the venue is a little chilly or you're out late
• shorts, if it's likely to be hot enough!
• tops and t-shirts (Umbraco swag, if you have them!)
• jeans/casual trousers/joggers
• dresses/skirts, but keep it casual
• comfortable shoes/trainers
• flip-flops or slippers
• underwear

Touching grass

The location of CODECABIN is beautiful. If you want to make the most of the area, people often go running and there's usually a walk.

• waterproof jacket, if you want to go outside whatever the weather
• sun hat, if you want to go outside whatever the weather
• running kit, if you want to join the runners
• shoes suitable for walking, if you want to join the walk
• National Trust membership card (even if you don't plan to walk, others can use it for free parking!)

Electronics

It's a tech un-conference after all!

• phone
• local SIM if your roaming deal sucks - $3 off an Airalo eSIM with code JOE9791* or try Firsty for free (but slow and ad-supported) data.
• power bank (planes generally restrict to <100Wh and this must be in hand luggage)
• charge cables
• USB wall charger
• laptop
• laptop charger (I'm looking at you, Jason!)
• UK adaptor, if your plug pins are an odd shape! (the UK uses 240V, so you might need a voltage converter if your devices like voltages closer to 100V 🦅)
• headphones (vital for the journey!)

Sleeping

You'll be sharing a room, so prepare for the worst!

• eye mask
• ear plugs (if you have nice ones, otherwise speak to Lee for some disposable ones)
• pyjamas that you don't mind being seen by a stranger future friend in!

Hygiene

We like to hug and high-5!

• toothbrush
• toothpaste
• deodorant
• shower gel/shampoo etc.
• other toiletries and grooming kit
• medication (including comforts like pain killers, etc.)

Towels are provided by the venue.

Travel

Coming to our little island from abroad? I've got you!

• passport (check the validity!)
• visa (if required)
• health insurance card, if your country has one (e.g. EHIC)
• travel insurance documentation, if not travelling with work or you don't have a health insurance card
• flight/train tickets (remember to check in!)
• hotel reservation details
• train reservation details (it can be cheaper and easier to prebook!)
• fee-free payment card (Revolut*, Monzo* and Starling* are popular options in the UK, register now to save money next time)
• (Probably no) Pounds Sterling (optional, particularly with a fee-free card I live in the UK and almost never need cash)

Miscellaneous

• reusable coffee cup (for the journey)
• wallet
• snacks for the journey
• entertainment for the journey - offline games, podcasts, movies, audiobooks and/or ebooks (or an analogue book if you're so inclined)

*referral links mean we both get something nice!

Print this page or use the checkboxes to mark off items as you pack! Checked items are saved locally in your browser.

I'll see you there!

See my Umbraco AngularJS filter cheat sheet for v13 and below.

I'm working on a modern UFM cheat sheet for v17+.

When you're configuring a block type in a block list or block grid, you're provided with a "Label" field. Similarly, custom columns in your list views have a "label template". You can just type some plain text in here, but using dynamic labels is where it really shines.

Text string properties

If your content item has a field with the alias heading, to render this in UFM we simply type {=heading}. This might render as:

Contact us

You can also wrap this with other content such as Text block: {=heading} to render

Text block: Contact us

This syntax works the same for text box, text area, email, decimal (non-zero values only), numeric (non-zero values only) but not rich text editor, slider, etc.

⚠️ Before v14.2, if the field is empty the alias of the property is returned in curly braces. So, {=heading} with no value becomes {heading}

Markdown and HTML

Since UFM is Markdown, we are able to use Markdown syntax or HTML as well.

For example, **{=heading}** - {=subheading} would render

Contact us - How to get in touch

Or, using HTML, **Quote:** <q>{=quote}</q> - {=attribution}. Might render you:

Quote: Joe, you're actually quite funny sometimes - Lotte Pitcher

Toggles (true/false or boolean)

These fields will spit out a "true" or "false". Or, if left as default, will be blank.

So, {=heading} (Disabled: {=disabled}) may become:

My block heading (Disabled: true)

My block heading (Disabled: false)

Or if left unset:

My block heading (Disabled: )

Content pickers

Not supported in 14.1, but a work-in-progress exists.

Writing your own

Much like in AngularJS, it's possible to write your own UFM components. Components follow the same pattern as the default, but the = is replaced with a custom symbol.

In this example, I use the symbol %, so {% Hello} would render as:

👋🏻 Hello!

First, I created a package manifest at ~/App_Plugins/umf-customisations/umbraco-package.json, and set my marker to %:

{
  "id": "UFM Customisations",
  "name": "Joe Glombek",
  "version": "1.0.0",
  "allowPackageTelemetry": true,
  "extensions": [
    {
      "type": "ufmComponent",
      "alias": "My.CustomComponent",
      "name": "My Custom UFM Component",
      "api": "/App_Plugins/ufm-customisations/components/my-custom.component.js",
      "meta": {
        "marker": "%"
      }
    }
  ]
}

Then, in the referenced ~/App_Plugins/ufm-customisations/components/my-custom.component.js:

export default class MyCustomComponent {
  render(token) {
    return `👋🏻 ${token.text}!`;
  }
}

For more complex scenarios, you'd likely want to use Typescript and implement UfmComponentBase:

export class MyCustomComponent implements UfmComponentBase {
    render(token: Tokens.Generic) {
        // Do something more clever here
    }
}

and make use of the @umbraco-cms/backoffice NPM package.

The return value can also be a web component, like the default {=name} component:

return `<ufm-label-value alias="${token.text}"></ufm-label-value>`;

Allowing for all complex logic to sit inside a separate web component.

A better example will follow, once I have one.

Bugs and quirks

The following have been raised on the Umbraco issue tracker, but are worth noting.

• In a collection view, the value outputted by the {=x} syntax always outputs the value of the field selected As of v14.2, in collection views the syntax is now always {=value}, much like the Angular format
• Null fields (or fields with a default value of null) render the name of the label, with no option to coalesce to something else This has a fix in v14.2, but I haven't tested it yet
• Null-like values will not render (e.g. a 0 in a numeric field) As of v14.2, falsey values render correctly
• I could not get localization ({#general_chose}) to work in the dynamic labels This was a typo but requires further testing for custom dictionary items

Further reading

• PR for the documentation of UFM
• Merged PR for this feature

The situation is this: I have some content nodes representing Meetup groups which have a repeatable text string field on them to list the organisers of the meetup. In my case, these are people's names but they could just as easily be blog categories. This content needs to be filterable using an Examine search query. In my case, I want to list out meetups which are run by "Joe Bloggs", but again, this could easily be listing out blog posts in each tag.

I'd have the same issue if these repeatable text strings were using the tags data type instead, but a slightly different issue if they were picked content (indexing the IDs or UDI makes this a lot easier!)

How an Examine search usually works

A typical search function may look like this:

// Get the index
if (!_examineManager.TryGetIndex("ExternalIndex", out var index))
{
    return (Enumerable.Empty<MeetupDetailPage>(), 0);
}

// Create a query (some extension methods are from the Search Extensions package)
IBooleanOperation query = index
    .Searcher
    .CreatePublishedQuery()
    .And().NodeTypeAlias(MeetupDetailPage.ModelTypeAlias)
    .And().ParentId(parentId)
    ;

if (organisers?.Any() == true)
{
    query.And().GroupedAnd("organisers".AsEnumerableOfOne(), organisers);
}

var res = query.Execute();
// etc.

If I run the above code, the Lucene query generated will be something along the lines of:

+__Published:y -umbracoNaviHide:1 -templateID:0 +__NodeTypeAlias:meetupdetailpage +(parentID:[1000 TO 1000]) +organisers:Joe Bloggs

This will return groups organised by "Joe Smith" and "Jane Bloggs" as well as the desired "Joe Bloggs"-organised endeavours!

Exact match

Examine gives me the option of specifying I want this to match exactly, by using the .Escape() extension method:

query.And().GroupedAnd("organisers".AsEnumerableOfOne(), organisers.Select(x=>x.ToLower().Escape()).ToArray());

Since the "terms" within the values in the index will be lower-cased, we also have to lower case the search query.

However, this also has some downsides. If I have a "Where American Politics meets Umbraco" meetup organised by "Elizabeth Warren" and "Warren Buckley", searching for "Warren Warren" (cruel parents, I know!) would return meetups run by the two former organisers as well since by default Examine strips out whitespace.

The value is stored as a series of tokens, elizabeth, warren, warren and buckley. The .Escape() extension ensures the tokens are in the specified sequence, but not that they are different names.

Examine will also split out "stop words" - filler words in a common search phrase - such as "of", "and" and "the". Meaning "The Umbraco Rabbit of Codegarden Fame" gets tokenized as umbraco rabbit, codegarden, fame which an exact query will never find!

None of that tokenisation nonsense here, thank you very much!

A cleaner way to store this value is to not allow Examine to split it into smaller tokens. Using the Raw value type, Examine will treat the name as an atomic Joe Bloggs.

To do this, we can make use of the IConfigureNamedOptions interface:

public class ConfigureExternalIndexOptions : IConfigureNamedOptions<LuceneDirectoryIndexOptions>
{
    private readonly ILoggerFactory _loggerFactory;

    public ConfigureExternalIndexOptions(ILoggerFactory loggerFactory)
    {
        _loggerFactory = loggerFactory;
    }
    public void Configure(string name, LuceneDirectoryIndexOptions options)
    {
        if (name is Constants.UmbracoIndexes.ExternalIndexName)
        {
            // Setting this value to raw saves each name as its own term e.g. "The Umbraco Rabbit of Codegarden Fame", rather than "umbraco" "rabbit" "codegarden", "fame" which is default.
            options.FieldDefinitions.AddOrUpdate(new FieldDefinition("organisers", FieldDefinitionTypes.Raw));
        }
    }

    public void Configure(LuceneDirectoryIndexOptions options)
    {
        // We don't need this bit
        throw new System.NotImplementedException();
    }
}

The downside here, is that multiple values are now atomic too. That meetup organised by Elizabeth and Warren we mentioned earlier would be indexed as Elizabeth Warren Warren Buckley and would only be returned when searching for that exact phrase.

So we need to split these values into multiple atomic values.

Splitting the value into multiple values

Examine provides a very handy event called TransformingIndexValues that allows us to manipulate values entering the index.

To access this, we need to create a component, listen to the TransformingIndexValues event on the index provider, and split the value into its multiple parts.

public class MeetupIndexingComposer : ComponentComposer<MeetupIndexingComponent>
{
}

public class MeetupIndexingComponent : IComponent
{
    private readonly IExamineManager _examineManager;

    public MeetupIndexingComponent(IExamineManager examineManager)
    {
        _examineManager = examineManager;
    }
    public void Initialize()
    {
        if (!_examineManager.TryGetIndex(Umbraco.Cms.Core.Constants.UmbracoIndexes.ExternalIndexName,
                out var index))
        {
            return;
        }

        if (!(index is BaseIndexProvider indexProvider))
        {
            return;
        }

        indexProvider.TransformingIndexValues += IndexProviderOnTransformingIndexValues;
    }

    private void IndexProviderOnTransformingIndexValues(object sender, IndexingItemEventArgs e)
    {
        if (e.ValueSet.Category == IndexTypes.Content)
        {
            foreach (var value in e.ValueSet.Values)
            {
                if (value.Key == "organisers")
                {
                    var updatedValues = e.ValueSet.Values.ToDictionary(x => x.Key, x => x.Value.ToList());

                    // Here we split by new line, to split repeatable text strings. You might need to split by something else. Comma, maybe?
                    var values = value.Value.FirstOrDefault().ToString().Split(Environment.NewLine);
                    updatedValues["organisers"] = values.Cast<object>().ToList();

                    e.SetValues(updatedValues.ToDictionary(x => x.Key, x => (IEnumerable<object>)x.Value));
                }
            }
        }
    }

    public void Terminate()
    {
    }
}

(Thanks to Marc Love for pointing out how to save these values in Umbraco 10+!)

Our tokenized values are now Joe Bloggs or Elizabeth Warren, Warren Buckley! Now, how do we search for them?

Searching against multiple values

This is now even simpler than before:

query.And().GroupedAnd("organisers".AsEnumerableOfOne(), organisers);

Which generates a query ending:

+organisers:Joe Bloggs

The Examine query parser will treat this nicely and only return meetups where the exact phrase "Joe Bloggs" is entered as the entire line of the repeatable text strings field.

Searching in the backoffice

It's worth noting that this query won't work in the handy backoffice dashboard (/umbraco/#/settings?dashboard=settingsExamine) to test Lucene queries.

This is due to the fact that the backoffice doesn't use a query analyser.

You'll need to modify your generated queries to add double-quotes around each value like so:

+organisers:"Joe Bloggs"

Further reading

If you're doing something like the above example and need to generate a filter with all the possible values of organisers (or tags or whatever), it might be worth looking into faceting (guide to faceting with Examine in Umbraco, Examine faceting documentation).

As it happens, Jesper was grappling with the same issue recently, but came up with a different solution, which he also blogged about.

The Umbraco documentation for searching is getting more comprehensive too.

Search Extensions has some useful extension methods for using with Examine searches, as well as some sensible defaults (filtering by ancestors using the path field, for one). (A little bird told me faceting may be coming to Search Extensions in a release near you.)

Luke is a useful tool for peeking inside your index. It's a Java tool that now comes bundled with the Java version of Lucene. You'll need to use the Luke version which matches the version of Lucene.Net used by Umbraco - 4.8.0 at the time of writing. You'll need the JDK to run it. Also, don't try to run this on a monitor with any scaling - 1080p at 100% works best!

This article and topic are covered on umbraCoffee's July 2024 episode.

It's got a lot simpler to reset an admin's password in modern Umbraco. You used to have to mess with hashes in the database and before that, drag a mysterious DLL into your bin folder!

But now, it's simpler than ever to initiate a password reset - via the UI! It's a simple matter of clicking the "Forgotten password?" link on the Umbraco login screen.

Unless...

No "Forgotten password?" link?

To enable password reset you'll need the following appsettings (set them in User Secrets if you only want it locally):

{
  "Umbraco": {
    "CMS": {
      "Security": {
        "AllowPasswordReset": true
      }
    }
  }
}

(Umbraco docs)

No access to the email inbox?

If you've not got access to the admin email address, you can set up a local SMTP server. I like to use smtp4dev these days.

{
  "Umbraco": {
    "CMS": {
      "Global": {
        "Smtp": {
          "From": "noreply@example.com",
          "Host": "localhost",
          "Port": 25,
          "SecureSocketOptions": "Auto",
          "PickupDirectoryLocation": "",
          "DeliveryMethod": "Network"
        }
      }
    }
  }
}

Don't know the admin email?

If you don't even know the admin email, you'll need to look in the database (sorry, not quite codeless!):

SELECT userLogin, userEmail
  FROM [umbracoUser]
  -- Optionally, this returns the original admin account. Delete the following to see all users:
  WHERE id <= 0

Other settings

You may also need to override other settings like UmbracoApplicationUrl for the reset to work completely.

A fairly standard user secrets file to accomplish a password reset might look like this:

{
  "Umbraco": {
    "CMS": {
      "Global": {
        "Smtp": {
          "From": "noreply@example.com",
          "Host": "localhost",
          "Port": 25,
          "SecureSocketOptions": "Auto",
          "PickupDirectoryLocation": "",
          "DeliveryMethod": "Network"
        }
      },
      "Security": {
        "AllowPasswordReset": true
      },
      "WebRouting": {
        "UmbracoApplicationUrl": ""
      }
    }
  }
}

Thanks to Sebastiaan Janssen for his correction.

No disrespect to the Candid Contribs team - these are common misconceptions and you tackled some of these misconceptions in the podcast too. But I felt it's important to get this out there.

Twitter's userbase disbanding has been detrimental to many online communities. The Umbraco Community has largely moved to LinkedIn, Discord and Mastodon. This means that it is fragmented, and it's highly likely that none will ever replace the critical mass Twitter had.

"Enclosed"

Let's not forget that Twitter never had the whole community. People who miss the 'whole community' being together, just happened to be at the centre of the Twitter community. I never used Twitter prior to getting involved with Umbraco and never managed to fit it into my routine - or truly feel a part of the Umbraco Community on Twitter.

A few of the Candid Contributions team feel the same way about Mastodon - and that's expected. You spent years working on your Twitter presence and curating your Twitter timeline by finding interesting people and speaking about interesting things (only for the that timeline to be polluted in the latter years, leading to the disenchantment of many). Mastodon could replace that platform. But it takes time to build a following and curate that feed. (One of the benefits of Mastodon and potentially the Fediverse is that you might not have to do this going forwards - you can take your following and followers with you!)

As for the Umbraco Community Mastodon - it's not an "enclosed space" as suggested in the podcast. The Fediverse is designed to be exactly the opposite of that. There are features such as the local feed that only show content from the server you're currently on - but this is just one view! Think of the discoverability provided by being on the same server as the "suggested follows" feature Twitter had when you created your account. Think of it as a starting place and then find people you're interested in, follow hashtags, and begin curating your experience. The most reliable way to find Umbraco content on Mastodon is to follow the #Umbraco hashtag, rather than watching a local feed.

Think of Mastodon like email or podcasting. Just because Candid Contribs uses Spreaker to distribute the podcast, it doesn't stop me listening with Pocket Casts (or Apple Podcasts or Spotify etc.). Just because I use Gmail, doesn't stop me email people on Outlook or Yahoo. Sure, Gmail has some nice features when emailing other Gmail users - like automatic profile picture population - but it's not essential to the experience. Email, podcasting and RSS are all part of the open web, just like the Fediverse and Mastodon.

Like Lotte, I was never a heavy Twitter user, using it primarily for Umbraco content. Which admittedly makes the Umbraco Community Mastodon a very easy drop-in replacement. But now, I've found myself using Mastodon outside of work - for entertainment and education. I've even replaced my use of Instragram with a fediverse alternative - Pixelfed.

"Confusing"

Mastodon is techy and confusing - but no more so than Twitter was when we all started there! Twitter had only just reached the mainstream as it began its fall back into obscurity - only with the far right being it's new niche rather than technologists. Huge swathes of people still "never really got Twitter" and that's fine - nobody needs microblogging!

Discoverability

Emma mentioned how she misses "stumbling" across things. Stumble-upon-ability is something that I'd suggest Twitter never did that well - it was a follower-lead platform. The "for you" algorithms of other platforms are actually far better at allowing you to stumble upon other people. Just like the early days of Twitter, hashtags and boosts are the best ways of spreading content to new eyes. I "stumble upon" organic content on Mastodon more than I would a corporate-backed social media platform lead more by ads - I now have a great set of people I follow, who boost me interesting content every day on a breadth of topics, from the wider .NET community to general web and tech to the environment and international politics.

In the open

Mastodon is not as closed as Twitter is and is certainly more open and discoverable than Discord. Everything is public facing and is discoverable on Google and by other Mastodon and Fediverse instances. LinkedIn is another closed community, requiring a login to see content.

If you want to join a wider community, try DotNet.Social, FOSStodon or a generic Mastodon server. You can always come to the Umbraco Community Mastodon profile listing if you need inspiration for who to follow. The call-to-action for getting new people on the Fediverse should be just that: join the Fediverse, not "join the Umbraco Community Mastodon".

In conclusion

If you don’t want to dedicate your time to Mastodon - don’t! If you’re missing microblogging in your life - and the ability to “just put a thought out into the world” - give it a go!

I previously blogged about Umbraco in the Fediverse and Gaining insights into fediverse accounts which may also be of interest.

Suggested follows

If you do feel a bit enclosed in the Umbraco-spere on Mastodon, try following some of these accounts to broaden your fedi-horizons.

Politics and news

• Washington Post Opinions @postopinions@threads.net
• Joe Biden @potus@threads.net
• Barack Obama @barackobama@threads.net
• BBC Radio 4 @BBCRadio4@social.bbc
• BBC Radio 5 Live @BBC5Live@social.bbc

Nature, science and climate

• RSPB @RSPB@mastodonapp.uk
• Scientist Rebellion @ScientistRebellion@social.rebellion.global
• Greenpeace @greenpeace@mastodon.social
• Vagina Museum @vagina_museum@masto.ai
• Prof. Alice Roberts @aliceroberts@mastodonapp.uk
• Prof. Stefan Rahmstorf @rahmstorf@fediscience.org
• Extinction Rebellion @ExtinctionR@social.rebellion.global
• Greta Thunberg @gretathunberg@mastodon.nu

Comedy & authors

• John Green @johngreenwritesbooks@threads.net
• James Veitch @veitch@mastodon.social
• NewsThump (news satire) @newsthump@mastodon.online
• J. L. Westover (web comics) @MrLovenstein@mastodon.social
• The Oatmeal (web comics) @oatmeal@mastodon.social

Non-Umbraco tech

• The Verge @verge@mastodon.social
• Technology Connections @TechConnectify@mas.to
• .NET Bot (boosts posts tagged #DotNet) @bot@dotnet.social
• ORG (campaigning for UK digital rights) @openrightsgroup@social.openrightsgroup.org
• Internet Archive @internetarchive@mastodon.archive.org
• DEV (shares articles from dev.to) @thepracticaldev@fosstodon.org
• Mekka Okereke @mekkaokereke@hachyderm.io
• Jon Skeet @jonskeet@hachyderm.io
• Dylan Beattie @dylanbeattie@hachyderm.io
• Mozilla @mozilla@mozilla.social
• Scott Hanselman @shanselman@hachyderm.io
• Layla Porter (LaylaCodesIt) @layla@dotnet.social
• Chris Coyier @chriscoyier@front-end.social

Usernames and instances

A fediverse username has two parts, the "local username" and the "instance name". For example, my current username is @joe@umbracocommunity.social. joe is my chosen username and umbracocommunity.social is the domain name (web address) of the server or instance I signed up with. This isn't always a Mastodon server, but can be any ActivityPub compliant site.

press.coop

An account ending with @press.coop are unofficial bots which scrape RSS feeds of various news sites. They reject replies to posts (but that won't stop you tagging them!) and no replies are visible to anyone at the news organisations. All accounts are marked as bots (see below) and have a meaningless gold checkmark emoji. @BBCNews@press.coop is a popular account but has nothing to do with the BBC. Although the BBC is running a trial of Mastodon, this does not yet include any official news sources.

bird.makeup (and other domains containing bird or birdsite)

Bird.Makeup is an open-source one-way bridge from Twitter/X to the Fediverse. You cannot interact with a bird.makeup user, since the bridge is one way. There can also be sizable delays in posts appearing. There's no way to opt out or redirect from an old account to a new one, so @umbristol@bird.makeup still works even though we have an active Mastodon account at @umbristol@umbracocommunity.social - so make sure if you're tagging someone, you tag the right account! These are only good for reading posts from people not on the fediverse. Think @potus or @callumbwhyte.

threads.net

This week, Instagram Threads announced they were extending their Fediverse trial to a wider audience - including all Threads accounts in the US, Canada and Japan (at time of writing). The integration must be manually enabled is currently limited to one-way (Threads to Fediverse) meaning replies can't be seen from Threads and Threads users can't yet follow other Fediverse accounts, but Fediverse likes do show up in Threads.

Interestingly verified accounts on Threads don't show up in the Mastodon interface in any way yet. But if you want, you can now follow what @zuck@threads.net has to say!

Sites that aren't a social network

We already touched on bird.makeup not being a Mastodon server. It's its own thing. But there's nothing stopping any site being on the Fediverse - you just need to implement certain API endpoints! This means that many Wordpress blogs and other non-social network sites are followable from your Mastodon feed. Replies to posts from non-social networks can be a bit of an unknown. They may be rejected, ignored or show up as comments. Who knows!

Warren's Hack Make Do blog is followable at @blog.hackmakedo.com@blog.hackmakedo.com, or you can choose to follow the human @warrenbuckley@umbracocommunity.social.

Checkmarks

You might see some accounts with checkmarks in the names of accounts. These are simply custom emoji on the instance the account lives on and means nothing special. Some instances may restrict which accounts they allow to have a certain emoji, but there's no guarantee.

Bot accounts

Mastodon has a feature to clearly show whether an account is automated (a bot) or not. This isn't a bulletproof system - it generally relies on folks being honest about it. But if a profile displays a "Bot" or "Automated" flag (depending on the client you're using), don't expect a human reply if you get a reply at all!

@umbfyi@umbracocommunity.social is a bot account.

Link verification

The best way to tell if a profile is genuine is through checking for verified links. Umbraco's official account is a great example of this. Since we already trust umbraco.com to be owned by Umbraco, the fact that @Umbraco@umbracocommunity.social has a verified link for umbraco.com in their profile shows they have editorial control over that page. You can verify multiple links using the rel="me syntax in any page you can edit (your blog, Github profile, etc).

The first verified link shows up in search results on the default Mastdon client:

and all links, verified or not, show up in the bio, although the verified links show in green with a checkmark:

How to tell a user is genuine

So, in summary, to check you're interacting with the correct account:

1. Check for validated links
2. Do you trust the server?
3. Are they a bot?
4. Check their bio (sometimes they'll state they're unofficial)

Getting hyped up for Spark

Keep up to date with the goings on by following Spark on Mastodon or Twitter as they announce speakers and share crucial event information. Keep an eye on the #UmbracoSpark, #Umbraco and #UmbracoCommunity hashtags in the lead up to the event to keep in touch with the communuity.

The fun before the party starts!

Although the Spark conference is only one day, the fun starts the day before with a hackathon and pre-party.

Hackathon

Umbraco and true digital are hosting a hackathon all day on Thursday 7 March!

This is a great opportunity to get stuck in with the Umbraco source code, with Umbraco HQ crew and community experts on site to help you out!

What is an Umbraco Hackathon?

Unlike some other hackathons you may have attended, Umbraco hackathons don't have a strict theme or overall goal. They're an excuse to get together and code together. People work on Umbraco source code bugs, Umbraco packages and community projects. You don't need to have an idea before you attend - but be sure to ask for inspiration when you get there.

This hackathon is a little different to past Umbraco Hackathons in that there's some suggested tasks to work on (or add your own). Comment on an issue to register your interest in working on it.

The hackathon will include refreshments and lunch (usually pizza).

More information is available on the Github repo.

Convince your boss!

How do you convince your boss to let you take an extra day for Spark? Simple! Hackathons allow you to get your head into the source code and understand how the product works better. You might even be able to fix some bugs that have been niggling your business for a while! You also get the assistance of Umbraco employees and community experts - who better to help you understand the Umbraco ecosystem!? Plus the usual networking - it's a very sociable way to code!

You don't have to be there for the whole thing either - just turn up for the afternoon if that's all you can muster!

More information and sign up on Meetup. This is a separate event and requires signing up (free!) on Meetup to attend. Once signed up, keep an eye on your inbox in the weeks leading up to the event and check out the Github repo for more details.

Pre-party!

Every year umBristol, the Bristol Umbraco Meetup, host a pre-party to make friends (it's like "networking" but more fun!) and have fun. This year we're all meeting just 5 minutes from the hackathon venue at Roxy Lanes to play some duck-pin bowling, ice-free curling and other games. A few drinks are sometimes thrown in by the sponsor, and there's usually an opportunity to buy food.

More information and sign up on Meetup. This is a separate event and requires signing up (free!) on Meetup to attend.

The big day - what to expect

Morning run (optional!)

Spark are hosting a morning 5km run. It should be "easy-paced" (but Frederik always claims his pre-Codegarden runs will be easy too - maybe I'm just too slow!) You'll need to register your interest in joining the run and meet outside Ibis Bristol Centre Hotel, Explore Lane, Bristol, BS1 5TY (by the We The Curious disco ball!)

Umbraco Spark!

Spark is hosted at the fantastic M Shed on the harbourside. Upon entry, follow the signage upstairs and be greeted by some friendly Bristolians to get your name badge and merch. Coffee and tea are available in the foyer and it's time to mingle! The Umbraco community are very friendly (it's kinda their thing!), so don't be afraid to chat to people you've never met before (even if they're a community celebrity!) I'll be there awkwardly mingling too, so come and chat to me - "I read your blog post" is always a great conversation opener!

Spark offers two tracks, and both are usually fantastic. So plan ahead as much as you can - you'll likely want to swap between tracks a lot! If you miss some talks, why not ask the speaker to repeat at your local meetup?

Lunch and snacks are provided at various points throughout the day, as well as a cheeky drink at the end before we move on to...

The after-party

No need to book this one, just turn up to Arnolfini across the harbour with your lanyard (it's privately hired). It's always nice to join folks for a drink and food before heading home - so try to plan around this if you can! There will be food and drink to buy at the after-party venue (this one's not included).

It's usually a casual affair where we sit and chat with friends new and old late into the night!

What do I need to bring/wear?

Spark is a casual conference, so a hoodie and jeans will suit for all events. Umbraco merch is always a bonus if you want to fit in! Also, remember a raincoat - we're only a stones throw from Wales after all!

You're also unlikely to need a laptop during the conference, but you might want to bring a notebook or take photos. If you elected to receive merch when buying your ticket, you'll get a branded notebook and pen on arrival as well as a t-shirt.

Don't forget your laptop and charger if you're also attending the hackathon!

Map

A map of the primary locations is included below. It also includes my recommendations for Bristol - read on for details!

Open map full screen.

The Umbracian's guide to Bristol

Bristol is a lovely city - so lovely, in fact, I moved here in 2022 - so many people elect to stay in the area for the weekend afterwards. Here's some advice for those people:

Getting around

Although the city is quite sprawling, a lot of Bristol is accessible by foot (particularly if you're good with hills!)

As much as the locals complain, Bristol has a pretty good bus network (just don't compare it to London or any continental European city!) Fares are £2 for a single, £3.80 for 2-trips and cap at £6 for the day, if you stay within Bristol. Busses all support tap-on-tap-off which are automatically capped, so no cash is needed.

For bike and electric scooter hire you'll need the TIER app which you'll need your driving license (full or provisional) to sign up for, so be sure to do that ahead of time.

Food and drink

Bristol is home to fantastic independent cafes, pubs, restaurants and food stalls - as well as the birthplace of small chains like The Lounges and Boston Tea Party.

My favourite food stalls are in Wapping Wharf (Spike Island, harbourside) (St Nicholas Market is closed at the weekend!)

You can't go wrong with most cafes in Bristol, but some of my regulars are Mud Dock (harbourside), The Bristol Loaf ("The Centre"), East Village Cafe (Clifton Village) and Santiago's (particularly if you're waiting for a bus at the bus station!)

Some of my favourite pubs include The Strawberry Thief (central), The Cottage Inn (Spike Island, harbourside) and pretty much anywhere on King Street (central). (The Apple is closed for refurbishment).

A touch of nature

Leigh Woods is a fantastic woodland a short walk over Clifton Suspension Bridge. You'll want some boots but it's easy to follow signposted routes.

Ashton Court is a deer park with great views over Bristol and a lovely cafe. You can stick to tarmac and gravel paths here if you want clean shoes! Also a Parkrun location.

Brandon Hill is a lovely park right next to Park Street and is home of Cabot Tower - which is worth a climb (free) for some more fantastic views.

Shopping

Cabot Circus and Bristol Shopping Quarter are mostly (although not entirely!) big chain shops you'd find in most cities.

Clifton Village (further out than Clifton but within the city, unlike it's name implies!) is where you'll find the best of Bristol's local boutique-y gift shops and cafes. Also worth visiting the iconic suspension bridge while you're there.

A little closer to the centre of town is Park Street and Whiteladies Road as well as Gloucester Road, less classy than Clifton but some lovely smaller shops. (Gloucester Road is the charity-shopper's heaven!)

Sightseeing

Bristol is home to some great museums. M Shed is the venue for Spark but also a great little free museum. You can find more information about all the Bristol Museums on their website.

The aquarium (central) is expensive but very good. Bristol Zoo is no longer located in Clifton, and is now outside the city.

Cabot Tower in Brandon Hill park (central) is free to climb for some epic views.

Clifton Suspension Bridge (Clifton Village) is free to walk across and Observatory Hill is nearby for some good views and a nice coffee shop. Or head into Clifton Village for endless cafes and pubs.

Bristol University has several beautiful historic buildings. The closest to the city centre are at the top of Park Street along with the Bristol Art Gallery.

Personally, I like to explore new cities using virtual audio tours. Claim a free one using my VoiceMap referral link. There are 5 highly-rated tours of Bristol to choose from.

Nearby

The cities of Bath and Cardiff, Wales are within an easy train ride (15 minutes or 1 hour respectively) if you want to spread your wings a little further.

See you there!

I'll be at the hackathon right the way through to the after party - so I'll see you there! Please come and say hi, and see my talk too if it appeals!

If you think I've missed something vital, let me know on socials!

Thanks to Tristan Thompson for his contributions.

If you’re reading this article, there’s a high chance you're acquainted with Umbraco, but perhaps you're not fully aware of the nuance that comes with the phrase. So what exactly do we mean when we say “Umbraco”?

The term encompasses more than just a CMS; it embodies a rich, open-source ecosystem consisting of the Umbraco CMS, the vibrant Umbraco Community, and our custodian and driving force, Umbraco HQ. Let's delve into all things “Umbraco” to uncover the multifaceted meanings and explore the intriguing interplay between these components.

“Unbrako” the contraption

Unbrako is the Danish name for an Allen key - that’s a “hex wrench” if you want the real name - and although to most of you reading this article this one is unlikely to cause any confusion Umbraco HQ say they do occasionally get Allen-key purchase requests. But that’s not really what this article is about!

Photo by Anton Savinov on Unsplash

“Umbraco” the CMS

According to Umbraco HQ (we’ll get onto that!):

“Umbraco is a CMS that’s fully extendable, highly customizable, and user-friendly.”

Umbraco CMS is the product all this “Umbraco” hangs off of. Created in 1999 by Niels Hartvig and open sourced in 2005, Umbraco has undergone significant transformations, evolving from a basic CMS to a sophisticated platform that powers websites of all sizes.

Umbraco has always (at least since I’ve been around) been pitched as “The Friendly CMS” which, as well as hinting at it’s user- and developer-friendliness and open-source nature, indicates how welcoming the community is. Community is a large part of what makes Umbraco, Umbraco. But it’s sometimes important to make the distinction between the two.

“Umbraco” the community

The first Codegarden in 2005 is our first indication of the beginnings of the Umbraco Community and it’s grown hugely from there. Communities often form around open source projects as people from across the world problem-solve and learn together to produce something that benefits themselves and other users, all with a shared philosophy for free (as in beer and as in speech) software. But I’ve heard Emma Burstow, Director of Developer Relations at Umbraco HQ, proudly state that people refer to Umbraco as “the one with the community”, which surely shows we have something special going on!

The Umbraco Community is also set apart from other software communities because of who make up our community. In a recent conversation with Carl Sargunar, he pointed out:

“Very unusually Umbraco isn’t a community of developers, it’s a community of people who use the platform”

The Umbraco Community is so much more than the occasional developer making the odd code contribution - it’s a lifestyle choice! And I only mean that partially as a joke! Codegarden, community-run conferences, unconferences, meetups, gaming sessions, social media, podcasts, a whole digital magazine, a federated social network instance, and even daily Wordle-sharing mean we’re never far away from our friends in the community.

Although largely developers, the community very actively includes agency owners, account and project managers, CMS administrators, end users and Umbraco HQ employees - the Umbraco Community is more about the lifestyle surrounding Umbraco than the code.

Repeat offenders contributors are acknowledged by Umbraco HQ through the MVP programme.

Umbraco community members call each other “Umbracians” (um-brak-ians or umb-raishe-ans).

“Umbraco” the company

Umbraco, Umbraco HQ, or just “HQ” is the name we use for the company, Umbraco A/S (and Umbraco, LLC in the US). HQ are the maintainers of the Umbraco CMS but also own the Umbraco commercial products Cloud, Heartcore, Forms, Commerce, Deploy, Workflow and UI Builder. They also monetize Umbraco through the sale of support plans.

HQ hires a developer relations team including developer advocates (also called developer avocados 🥑) whose role is to encourage and grow the community.

Members of staff at HQ are “HQers”.

Just to confuse things even more “HQ” can also refer to the physical office locations of Umbraco A/S and Umbraco, LLC.

Where paths cross

Community recognition

It surprises me how often a community-run conference, meetup or package gets attributed to Umbraco HQ or assuming organisers, speakers or community teams members are paid for their efforts.

Although I consider open-source as part of my job (and I’m lucky enough to have an employer who agrees), even I pour more emotional and time effort into community contributions than I do into the rest of my day job (it’s hard to get too emotionally invested in C#, eh?). And I’m one of the lucky ones: many community members are dedicating evenings and weekends to make their contributions.

The community can benefit itself by acknowledging non-profit community effort. Acknowledgement and appreciation go a long way to making a contribution feel worthwhile.

Not all heroes wear capes, but this one does have a shield. Photo by Umbraco HQ on Flickr.

But also, open source is work and employers who profit from the Umbraco CMS and community should do more to support their own employees’ contributions as well as sponsor open source packages and community events that directly benefit their business. Umbraco co-founder, community member and Director at Docker, Per Ploug, has written about this and his Codegarden talk is available to watch online.

Money for “nothing”

Umbraco CMS, being open source, is free to anyone who wants to download and use it. This makes things difficult for open source maintainers, like Umbraco HQ, who need to sustain a business while giving their primary product away for free.

Rumour has it people like free things. Photo by Umbraco HQ on Flickr.

Since 2021 Umbraco HQ has been owned by Monterro, a growth investor. Open source maintenance is an unusual business model, and since the Monterro investment, we’ve seen a larger push for commercial offerings from Umbraco but there remains a huge focus on open-source offering and the community.

Traditionally, open source maintainers make money by providing services and Umbraco HQ is no different. HQ sell Umbraco Cloud as a SAAS offering along with additional premium packages and support. Although Umbraco tends to avoid these situations, this business model can result in priorities misaligning with the community.

Community as a Commodity

It’s sometimes important to attach a business case to the value of a community to ensure a business like Umbraco HQ can continue to invest in their communities. And as pointed out by Emma Burstow, businesses are finally starting to see value in community because

“People are less inclined to buy things from sales people and far more likely to buy things from people like them”.

Are bats on a board a “commodity”? Photo by Umbraco HQ on Flickr.

However, the attitude of community members and their contributions being seen as commodities can be difficult for community members.

“Venture capitalists are actually using community activity as one of the metrics that they’re going to measure against before they acquire companies”

Contributions aren’t made to keep Umbraco HQ valuable and afloat, they’re made for the betterment of the open-source product, to encourage the progression of individuals within the community and to grow the community itself. But in doing so, contributors provide value to HQ. And although we all see value in Umbraco HQ doing well, a volunteer contribution benefiting a profitable company can feel uncomfortable.

It is important to comprehend that businesses understanding the value of community does mean that they can justify investing more time and money into fostering the community. And Umbraco HQ does put a lot of time and effort into fostering the Umbraco Community: Umbraco now has a dedicated developer relations team and fund community-run events. A strong community (as a commodity) can ensure their stewardship of the open source portions of the platform for many more years to come.

Accountability

“Stewardship” is an important word there. Umbraco HQ own the trademarks around the name Umbraco, but the CMS itself is in the public domain. Under the MIT License, people are free to “use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies” of Umbraco CMS. If Umbraco HQ ceased to be, or made a questionable product decision, the Umbraco CMS would likely continue to exist under a different name, possibly along with the community.

This has happened before, with the death of Umbraco 5, members of the community split off from Umbraco and created RebelCMS. The CMS was short-lived, with the last commit now almost 12 years ago, but it does show that it can be done.

This is an important thing to remember because, although it’s very unlikely to happen, it makes Umbraco HQ accountable to the community - they can’t do something strongly against what the community wants and need to listen to the community’s requests to keep their stewardship. This fact helps to ensure that community-effort, although benefiting Umbraco HQ, means that HQ’s profitability benefits the community, in a circular way.

A delicate balance

I don’t mean for this article to cause any controversy, but believe the discussion around profitability and open source is an important one and needs to be had out in the open. The Umbraco CMS can continue to provide a valuable product for both Umbraco HQ and the Umbraco Community, but it’s a delicate balance and as a community we need to acknowledge where conflicts of interest may arise.

As contributors we should know who our contribution benefits, and ensure we’re getting enough value for ourselves from that interaction to prevent feeling cheated or burning out.

It’s also vital that Umbraco HQ continue to recognise the value of the community in steering the direction of the Umbraco CMS.

Together, we’ve build something great and are continuing to build something even better.

Following on from discussions around how distributed our online communities have become since the ongoing fall of Twitter/X on Owain's blog and UmbraCoffee #292, Mastodon has been raised as one of the locations the community is slowly moving to. As an established Fediverse user, and admin of the UmbracoCommunity.social Mastodon instance, some people have been asking me Mastodon questions and I thought a blog post might be a good way to communicate these tips to a wider audience.

I've mentioned before how I hope Federation is the future of social networking and how Mastodon may well fit the needs of the Umbraco Community going forwards, and I truly believe we need something analogous to "old" Twitter, that's less instant than chat tools such as Discord, more social than the Forums and shorter form than blog posts. Mastodon can be just that.

What is the Fediverse?

This blog post is tailored to the Umbraco Community, so I won't go into all the details here, but will keep to the relevant parts.

The Fediverse is generally used to refer to a group of servers that conform to the ActivityPub standard. Each of these servers pushes content out to the Fediverse and wider internet. The content could be blog posts, microblogs, photos, comments or anything else we as people create on the internet.

These servers within the Fediverse are subcategorised by the software they run. The software is generally analogous with a "traditional" social media platform. For example, Mastodon focusses on microblogging (think Twitter), Pixelfed is all about social image sharing (think Instagram) and Lemmy hosts communities (think Reddit). You can follow a Lemmy community or Pixelfed account from your Mastodon account too - because they all use the same protocol.

What is Mastodon?

I've explained how Mastodon is the ActivityPub-compliant software running on a server., but the concept is much greater than that! Because the ActivityPub protocol allows these servers to talk to one another and because Mastodon is free and open source, you don't have to sign up to Mastodon's own server - you can join a community (server or instance) of your choice.

This can be a barrier to entry for those unsure about how Mastodon works, but in practice this architecture helps us build a more resilient and tailored social media platform.

Because Mastodon is distributed across multiple servers, usernames take the format @[local-username]@[server-domain], for example, my username is @joe@umbracocommunity.social.

Why does it fit so well with the Umbraco Community?

I've already used the phrases "open source" and "communities" when describing Mastodon, and this is a large reason I believe Mastodon could be a large part of the future Umbraco Community: our ethea align.

An Umbraco-focusses Mastodon instance allows Umbraco to be the primary focus of an instance with additional Umbraco-related content easier to discover for users. But the way that federation works, means that the common interests of Umbracian's on the Umbraco Mastodon also become discoverable by the community, such as .NET, open source and Lego.

How do I join?

So, if you want to become a part of the Fediverse, you first choose a server. It's not the be-all and end-all if you change your mind later, you can move (although your Tweets posts (or "Toots") don't come with you) your account to a different server at a later date (see below).

Which server(s)?

Mastodon instances tend to cater to interests. Although there are generic instances too.

The more generic and larger your instance, the closer to a Twitter experience you get. But that's not where the power of Mastodon lies, in my opinion you're better off joining a niche.

Personally, I find UmbracoCommunity.social a fantastic compromise - the community is niche enough to mean the public feed (see "Getting the most out of Umbrastodon") is relevant to me but not so small as to limit it, although as an admin there, I may be biased!

Popular interest-specific servers within the Umbraco Community

If a lot of what you do online is techy, these instances may work better for you:

• UmbracoCommunity.social is a Mastodon server set up specifically for the Umbraco Community and is hosted by Steve Temple
• Hachyderm, pronounced hack-a-derm (that's right, it's a mastodon/pachyderm pun!) is a hugely popular generic-tech instance
• Fosstodon is dedicated to open source software
• Infosec.exchange for you infosec folk
• front-end.social for you frontenders

You can also find your own niche by checking the Mastodon server listing where you can filter by language, hosting country and interest.

Popular generic instances

From the UmbracoCommunity.social statistics, here are the most popular generic instances used by the Umbraco Community:

• Mastodon.social is the original server operated by Mastodon, its hugely popular and a great place to start if you can't find a niche
• mstdn.social another generic instance with a shorter URL
• Mastodon.Green a paid-for server who run off renewable energy and plant trees with 20% of the monthly fee

Host your own

If none of these take your fancy, you can also host your own instance and be in full control of your own data - Seb has a server just for his account. Mastohost is a simple and affordable way to set up your own instance. Be aware, though, it can get lonely on your own - you lose a lot of discoverability by being on a single-person server.

Already a Mastodon/Fediverse user?

If you're already in the Fediverse but want more Umbraco in your feed, here are some options:

• Use your existing Mastodon account and follow whoever you want from UmbracoCommunity.social by looking at the directory to find accounts
• Create a second Mastodon account on UmbracoCommunity.social if you want to keep your Umbraco Fediverse account separate from your other account
• Migrate your account to UmbracoCommunity.social. Your old account gets redirected, but beware your old posts will stay put.
• Make use of the public feeds on UmbracoCommunity as it’s quite a good mix of Umbraco and .NET devs: the local feed (all posts on UmbracoCommunity instance) and the federated feed (all posts from people followed by anybody on the UmbracoCommunity instance). Some mastodon clients let you add these feeds into your app too!

Getting the most out of Umbrastodon!

• Follow the #Umbraco hashtag (you can follow hashtags as well as people on Mastodon!)
• As above, Seb suggests making full use of the use of the public feeds to find relevant content.
• Make use of a browser plugin (like Graze for Mastodon) to make your web browsing experience of Mastodon easier
• Find apps that works for you - I personally like Ice Cubes on iOS and Elk for desktop but the app directory has loads of options
• Follow me! I'm @joe@umbracocommunity.social on Mastodon and @joe@expl.red on Pixelfed.

See you in the Fediverse!

A summary of my experiences at CODECABIN '23.

What is CODECABIN?

According to the CODECABIN website, it's "An Umbraco Event Like No Other".

CODECABIN is the premier, invite-only weekend away for Umbraco developers, providing time to code, learn and network in a completely relaxed and open environment away from the hustle and bustle of every day life.

Which is a pretty good summary.

We hacked on Umbraco related packages; played with new Umbraco features; discussed all things Umbraco past, present and future; played games; enjoyed the scenery; and, boy, did we eat well (thank you again Lucy!)

What happened this year?

This year's programme included 4 discussion slots (which worked a little differently to previous years), dedicated hacking time, a walk to the nearby Froggatt Edge viewpoint as well as a quiz and awards night!

What did we talk about?

This year the programme included slots to discuss items from our "discussion backlog" where in the weeks leading up to CODECABIN we has contributed suggested discussion topics to and voted on our favourites. In each slot, we'd discuss the most popular topic remaining to be discussed until it came to a logical conclusion before moving onto the next most popular topic on the list. This is different to previous years but seemed to work well with Matt and Lee's guidance setting up the next topic and suggesting when may be good to move on.

Here are my takeaways from each discussion we had.

(Please note: these are my takeaways from each topic, not necessarily the "correct" takeaways or what the group as a whole took from the discussion.)

Headless is the new black

Discussion centred around static site generation and single-page JavaScript applications (SPAs) using the new headless Umbraco Content Delivery API as well as non-web applications for the API, such as mobile apps.

Some had reservations about the application of headless sites being used for SPAs unnecessarily but the performance and sustainability benefits of static sites were also highlighted.

Segments

In this session we discussed some confusion and potential UI bugs for the non-language variant variants, segment variants. The experience feels less polished than the language variant journey and lack of up-to-date guide made things challenging for some developers. Although the 2022 24 Days article was still useful to help get things started, some cheese had been moved.

We looked at a sample implementation and discussed ways of improving it.

Segmentation seemed to be on many developers radar, but it seems to be underutilised except by uMarketingSuite so far.

Front-end frameworks for websites (not web apps)

The discussion began as a search for lighter-weight frontend frameworks than Angular, Vue or React and more in line with how we might've used jQuery, jQuery UI and jQuery plugins in the past. The consensus was that these larger frameworks are more suited to "JavaScript applications" and are too much for many "lighter sprinklings" of JavaScript.

Apline.js was discussed as a lightweight framework which allows for considerably less JS to be written since a lot of Alpine is applied by adding attributes to elements.

However, general consensus seemed to be that vanilla (frameworkless) JavaScript was incredibly capable these days, particularly for selecting elements by selector (document.querySelector and document.querySelectorAll) and fetch in place of AJAX.

For interactive components, people suggested finding vanilla, single-purpose libraries (e.g. one for a carousel and another for tabs) which should be checked for accessibility and maintainability on an individual basis. The use of these components is much easier using JS modules or compiling modules using a JS bundler like WebPack or Vite.

Vue was suggested as the lighter of the "full-fat" frameworks and it was highlighted that using these larger frameworks for a single module within a larger site may be appropriate - the whole site doesn't have to be Vue, perhaps just a smaller interactive component.

Deployment basics

We talked about the lack of documentation around deployment using Azure Pipelines and Github Actions. Although it's potentially something that sits outside the realms of the Umbraco Documentation, it was agreed it'd be helpful. I believe there is some draft documentation in the works, so we look forward to seeing that in the future.

Build a better back office

Discussion mostly lead to ways of improving the default dashboard to make it more easily customisable for users and developers. The concept of customisable widgets which a user can add and remove from their own dashboard was suggested by the group where these widgets could be more easily generated by developers. The widgets may also be able to be added to content apps with extra context. Although we believed this would be a fantastic addition to Core, Markus suggested he might add some of these improvements to his The Dashboard package.

Current state of package development

Concerns were raised by package developers about the skill gap and effort involved in converting packages for the new backoffice (expected in v14). Additional support for package developers from HQ would be welcomed.

The group suggested that the community as a whole wouldn't be "expecting" developers of free, open-source packages to be ready for v14 on release date and that a pace to suit developers is the most appropriate.

After CODECABIN, Lee announced that he was no longer planning to release any version of Contentment for Umbraco 14, instead choosing to aim for v15's release.

Another concern was that package development may have slowed in newer versions. Some suggested reasons for this included:

• developers don't want to build packages only to rebuild the frontend in v14 (see Web components, below)
• duplicate/similar packages are less commonplace than they used to in earlier versions, one package has come out on top and the similar packages have died off
• we've refined the set of packages we use as a community

Web Components

Web components were a running theme throughout a few sessions. Many developers were daunted by them and they were briefly explained within the context of the backoffice and packages (with Lit) as well as other uses for them.

I suggested that it's possible to develop a new package in current Umbraco versions as a web component, with only the Angular-to-web-component layer that would need replacing in the v14 backoffice. This is a subject Jason Elkin is planning to talk about at upcoming Umbraco events. I'll update this post when more information becomes available.

I also demo'd an obscure use case of web components and the shadow DOM as an example of how web components can be used which I will also be talking about at Upcoming Umbraco events and will update this post when more information becomes available.

Grading and categorising community blog posts

(originally "How can a 'best practice' Umbraco demo site be created?")

This one went a little off-topic! Although we were aware of many existing “best practice” starter kits and demo sites, we realised it was actually quite difficult to create a best practice site for all occasions - even taking opinion out of the equation, we don't have one way of building a site even for ourselves. If performance isn't a priority but being flashy is, we'll architect and code a site completely differently to one where performance is the be all and end all.

We then started to think that perhaps marking content as "beginner" and "advanced" may help to distinguish a generic "best practice" from a "best practice for lightning performance" or "best practice for [insert niche here]".

We also thought that standardising categories and hashtags would help with this problem, as well as discovery - another issue with the existing “best practice” sites.

A common set of categories would also allow the Umbraco Community Blog Posts page to be filterable, making it much more useful.

Discussed categories were "beginner", "advanced", "content editors", "developers", "accessibility" and "performance" as well as version-specific classifications. But no documentation has been generated as of yet. I'll update this blog post if something does.

Taming AI

This discussion was mostly about utilising generative AI (OpenAI's ChatGPT and GitHub CoPilot in particular) for software development purposes. Although many had not used AI much for software questions, those that had noted how the answers were often a good starting point but often needed correction. In fact, a study was referenced where the researchers found that 52% of ChatGPT's answers to code questions were incorrect.

Developers should use AI generated code with caution and check code samples even more thoroughly than those found on forums. It was, however, agreed that developers using AI would likely be more productive and that we should be embracing this technology.

I mentioned that my talk "How to Copy & Paste" at the Umbraco US Summit may be pertinent, and I will share a recording of it when I have one.

Umbraco Builds - LTS or STS?

Deciding which version to put a client on is never a straight answer!

Some newer STS (Short Term Support) releases go into the "security phase" of support at about the same time as their most recent LTS (Long Term Support) version, so is it worth sticking to the LTS version or providing the latest and greatest? For example, v12 (STS) enters its security phase on 29 March 2024, just 2.5 months before v10 (LTS) enters its security phase on 16 June.

"Does the client even require LTS support?" is the first question. If you have a client on retainer including regular upgrades, it may prove easier to always be on the latest.

If a build is going to last a long time, we generally start the client on the current latest (or even preview) and upgrade them as the project goes on - stopping at the LTS if nescessary.

Of course, if a client needs a new feature (Content Delivery API, for example), it's rarely worth them holding back to the previous LTS. You'd probably start on the latest STS and factor the upgrade to the next LTS into the cost, if an LTS version is even required.

It was understood that upgrades from LTS to LTS are possible (without upgrading to intermediate STS versions), but it was raised that community and even official Umbraco packages may not offer the same support. It was suggested to HQ employees that for consistency this should be the case for official packages, particularly those that come with Umbraco Cloud such as Forms and Deploy.

Multi-sites and shared content

This discussion was around the Reusable Content with Global Blocks RFC (Request For Comments) and having reusable content within an Umbraco site. In particular, consensus seemed to coincide with Matt's comments on the RFC that global content could be nodes in their own right, not just blocks.

Reusable nodes could include anything that does not logically fit into the tree structure, such as office locations or team members. This repository pattern is seen in other CMS'.

You could even have blog posts as repository items to more easily replicate a WordPress-style URL structure like /blog/2022/09/14/codecabin-23, since WordPress also has a repository structure for blog posts. Where some Umbraco blog solutions require blog posts to be manually sorted into a date-based folder structure.

We discussed that having multiple library tabs (/applications) in the navigation bar may be desirable (e.g. Blocks, Blog) similar to how Konstruct works.

It was also suggested that media should be a library type as well, since it's essentially the same thing.

Other sessions

There was also shorter sessions on "Optimising and caching Umbraco websites" and "Umbraco server beyond .NET" as well as a show & tell session but I have little to comment on from these.

What was I hacking on?

Matt, Rachel and I started work on an ActivityPub integration for Umbraco to allow for blog posts created in Umbraco sites to be pushed out to ActivityPub servers (like Mastodon) as posts to aid in their sharing. WordPress has a plugin to do this, and we'd like to release an Umbraco package in the future. ActivityPub comments could also be a future enhancement. We also realised this integration could generate RSS feeds and trigger IndexNow requests in the future. I'll update this post when something becomes public.

What else did we do?

It couldn't all be Umbraco-talk now could it!?

We were kept well fed and watered (of the regular, cola, hop and juniper-flavoured varieties) too, with some great discussions over the bar and dinner table (writing the script to Bloodswarm: Revenge of the Gnats comes to mind!)

A keen crew got up for a run every morning although I decided I ought to stick to my rule of one 5km run per year (at CodeGarden), as is tradition.

But I did attend the walk with a large group. Although only a few kilometers, the walk was spectacular and allowed us to see the cabin from the scenic Froggatt Edge on the other side of the valley, as pictured.

Karl hosted us a fantastic children's birthday party pirate themed quiz, in which we came last but with a smile on our faces and a rather respectable score of 69.

Inspired by the pirate music used in the quiz, there was also an impromptu "Pirates of the Carribean" movie night (can you believe Delia has never seen it?!)

Lotte hosted the fabulous CODECABIN Awards evening, the 6 awards I earned proudly displayed on my shelves behind my desk!

Lotte also provided entertainment throughout the weekend by providing homemade Umbraco-themed boardgames - CODECABIN Who? and UmbDobble, which were both fantastic!

Next CODECABIN

CODECABIN 24 is set to be from 20-23 September 2024.

I'll certainly be applying for next year, I had a fantastic time. Not only did I learn a load about the Umbraco ecosystem, I've had my enthusiasm for contributing reignited and I had a great laugh doing it.

CODECABIN isn't like a regular conference. It requires an application process which is starting "soon" for CODECABIN 24. Keep an eye on @codecabin on X and other community social channels around that time and get your applications in (applications usually close just after CodeGarden).

How do I get my boss to pay for all this?!

Although people do pay for themselves to attend CODECABIN, I find it's always worth a shot persuading your boss! It's great fun, but honestly, it is work. Just like I'd ask for other conference tickets, CODECABIN has reignited my passion for open source and taught me many lessons pertinent to upcoming and future projects. The event gives you time to network with people you might not otherwise meet but also code with Umbraco MVPs and HQ employees like you never would at a regular conference.

Considering it's a fraction of the cost of sending someone to CodeGarden (let alone a more expensive conference!) and includes all food and accommodation and just how much more I got out of it, CODECABIN is a bargain for employers.

Read more

More blog posts by other attendees:

• Alina
• Andy
• Rachel

Hero photo by Richard Jackson

"Nerds in the Woods" as dubbed by Richard Ockerby's wife.

When you're configuring a block type in a block list or block grid, you're provided with a "Label" field. Similarly, custom columns in your list views have a "Template". You can just type some plain text in here, but using Angular templates is where it really shines.

For example, if you want to pull up the value of a field called "Heading" (alias heading) from the block list item into the name, you can do that by simply wrapping the alias of the property in double-curly braces: {{ heading }}. You can even include fixed text around it: A text block with the heading '{{heading}}' (but maybe less wordy, eh?)

As for custom list views, the only additional thing you need to know is that instead of using the property alias in the template, you use the value variable e.g. {{ value.join(", ") }}

For properties that aren't as simple as a textbox, we can do that too with the help of these filters:

Node picker / Media Picker v2

ncNodeName will pull back the name for a node selected in a node picker (although this can be a little buggy)

e.g. Call to Action: {{ page | ncNodeName }} becomes Call to Action: Contact us

Media Picker v3 (even in single mode)

For Media Picker v2, this is the same as above, the ncNodeName filter works just fine.

However, for v3 we have a couple of alternatives.

In v11+, use the mediaItemResolver to get the media object using the key:

e.g. {{(image[0].mediaKey | mediaItemResolver).name}}

Or (for older versions, or if you just like it better) we can use the ncNodeName filter if we construct our own UDI:

e.g. {{ "umb://media/" + image[0].mediaKey | ncNodeName }}

Rich Text editor

ncRichText strips out the HTML markup and just renders the inner text. This is useful for rendering text from a Rich text editor.

e.g.Text module: {{ bodyText | ncRichText }} becomes Text module: This is some text from a rich text editor.

In v13, you'll also need to reference the markup property to access the contents:

e.g. Text module: {{ bodyText.markup | ncRichText }}

Multi-Url Picker (even in single mode)

Simply navigate to the child properties like so: link[0].name

e.g. Call to Action: {{ link[0].name }} becomes Call to Action: Make an enquiry

Yes/No

Checkboxes store their value as a numeric, so we can use the value to render some text: checkboxPickerAlias == 1 ? 'Yes' : 'No'

e.g. Text with image ({{ flipped == 1 ? "Image right" : "Image left" }}) becomes Text with image (Image right)

Too long?

We've got a few options for truncating text.

Angular's default limitTo:n (where n is the number of characters) will simply cut the text short after so many characters.

If we want to get fancy, we can use Umbraco's truncate function. It takes 3 parameters: wordwise (don't truncate in the middle of a word), the number of characters to truncate and finally an optional string to append to any truncated text (e.g. …, which is the default).

e.g. Text module: {{ bodyText.markup | ncRichText | truncate:true:35 }}* becomes Text module: This is some text from a rich text…

These last two parameters are swapped in v7 (truncate:35:true).

We can also limit to a number of words using umbWordLimit, but without all the functionality of truncate.

e.g. Text module: {{ bodyText.markup | ncRichText | umbWordLimit:4 }}* becomes Text module: This is some text

* See Rich Text editor section

What about settings?

Block list settings are made available using the $settings property.

e.g. Text with image ({{ $settings.flipped == 1 ? "Image right" : "Image left" }}) becomes Text with image (Image right)

Messing with the default

By default, the block displays the name of the block type. If we want to use that in our custom templates we can use $contentTypeName.

e.g. {{$contentTypeName}} ({{ $settings.flipped == 1 ? "Image right" : "Image left" }}) becomes Text with image block (Image right)

How do I look?

In the Block Grid, we can also access the column span and row span of the block using the $layout property and it's values $layout.rowSpan and $layout.columnSpan.

e.g. {{$contentTypeName}} ({{$layout.columnSpan == 12 ? "full width" : "half width"}}) might become Heading block (full-width)

Arrays

Umbraco provides a filter for joining arrays of strings or objects.

e.g. Things: {{ myArray | umbCmsJoinArray:', ' }} becomes Things: Thing 1, Thing 2, Cat (in hat)

When applying to an array of objects, a second parameter can be provided to specify which property to used for joining.

e.g. Things: {{ repeatableTextStrings | umbCmsJoinArray:', ':'value' }} becomes Things: Thing 1, Thing 2, Cat (in hat)

Nesting block lists?

Block lists within your block can be accessed by using the name of the block list property followed by contentData.

e.g. Tab panel ({{ tabs.contentData.length }} tabs) becomes Tab panel (5 tabs)

Since this is just an array, we can also take advantage of the umbCmsJoinArray filter here!

Things: {{ things.contentData | umbCmsJoinArray:', ':'title' }} becomes Things: Thing 1, Thing 2, Cat (in hat)

$index

The $index field can be used in block lists and nested content. Perhaps confusingly, this is a 1-based index.

e.g. {{ $index }}. {{ heading }} becomes 1. Thing

Regular ol' JS

Some basic regular JS can be used too. But bear in mind you can't do complex things like writing functions (not even arrow functions, sorry!) This will require writing your own filters (see below).

e.g. Things: {{ repeatableTextStrings.join(", ") }} becomes Things: Thing 1, Thing 2, Cat (in hat)

Although this particular example would be best solved using the existing umbCmsJoinArray filter (see above).

See also "Fallbacks" and "Messing with the default".

Fallbacks

Since we can run regular JS, we can use the truthiness of a statement to fall back to another value.

e.g. {{ heading || tabs.contentData | umbCmsJoinArray:', ':'heading'}} will be the value of the optional heading field, otherwise it will list all the headings of the child tabs.

Writing your own

Writing your own is possible too. Simply create a plugin folder in App_Plugins with a JS file for the new filter.

Here's an example taking the umbCmsJoinArray even further:

angular.module("umbraco.filters").filter("blockSummary", function () {
  return function (input, fieldAlias, maxItems, showMore, separator) {
    var items = input.contentData;
    var more = "";

    if (maxItems > 0) {
      var total = items.length;
      items = items.slice(0, maxItems);
      var moreCount = total - maxItems;

      if (showMore !== false && moreCount > 0) {
        more = ` + ${moreCount} more`;
      }
    }

    return items.map(i => i[fieldAlias]).join(separator || ", ") + more;
  }
});

You'll also need to create a package.manifest file:

    {
        "name": "MyFilters",
        "version": "1.0.0",
        "allowPackageTelemetry": false,
        "javascript": [
            "/App_Plugins/MyFilters/blockSummary.filter.js"
        ]
    }

It's used as below:

Things: {{ things | blockSummary:'title' }} becomes Things: Thing 1, Thing 2, Cat (in hat)

Although this particular example would be best solved using the existing umbCmsJoinArray filter (see above), the following take better advantage of this custom method:

Tabs: {{ tabs | blockSummary:'heading':0:false:' / ' }} becomes Tabs: Umbraco development / .NET development / Front-end builds

FAQs: {{ items | blockSummary:'question':1 }} becomes FAQs: How did I get here? + 2 more

Further reading

Some of this is covered in the Block Editor Label Properties documentation (this is targeted at v9+ which may differ from functionality in older versions, docs for these are covered in: Block Editors for < v9 and Nested Content for < v9) and the source code for the Umbraco filters can be found on GitHub.

Paul Seal covers using Block List editors in his Umbraco 10 series from episode 9 onwards.

Thanks to Bjarne Fyrstenborg, Callum Whyte, Dean Leigh, Richard Jackson, Erica Quessenberry and Lee Kelleher for keeping me up to date on this one.