DEV Community: Matt Brailsford

Deploying TypeScript Type Definitions for Umbraco v14 Packages

Matt Brailsford — Fri, 26 Jul 2024 12:29:56 +0000

In a recent blog series I shared how to go about creating your own Umbraco v14 extensions, but the final piece of the puzzle that I left out was how to deploy your extension type definitions such that others implementing your extensions would have nice type checking.

Well, in this article we are going to look at doing exactly that.

The Challenge

The challenge for Umbraco Package developers that provide their own extension points is that we actually need to split out deployments into two.

For the actual code that makes up your package, this is likely going to be packaged up in your NuGet package.
For your extension points, we need to distribute the types for these as an NPM package.

I won't bother covering the first part as Kevin Jump has already done a great job of outlining how to setup a project for an Umbraco package.

Here then I'll focus on the second point and how to extend your project to distribute your types.

To set a baseline however, I'll assume you've used Kevin's early adopters template for your setup.

Step 1: Consolidate Your Types

We don't want to export all types in our package, rather we just we to export our extension types, such as our custom manifest types. To make this explicit, I decided to add a root level exports.js file that exports all the types I needed to make public.



export type { 
    ManifestQuickAction,
    MetaQuickAction
} from './quick-action/types.js'

For brevity here I'm just exporting the types directly in the root level exports.js file, but in actuality, I have a number of exports.js files located in my project and my root level exports.js file re-exports all the other export files like export * from './feature/exports.js

Step 2: Generate Your Type Definitions

Now we have all our types exported in one place, we next need to use the TypeScript CLI tool to generate our type definitions.

In your package.json add a new script entry as follows



{
  "script": {
    "build:api": "tsc -p tsconfig.api.json",
  }
}

Next create a tsconfig.api.json with the following contents



{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./types",
    "rootDir": "./src",
    "declaration": true,
    "declarationMap": true,
    "emitDeclarationOnly" : true
  }
}

Essentially this is telling TypeScript to use our main tsconfig.json configuration, but to only generate type definitions.

Now if you run this script



npm run build:api

We should get a new types folder with all our generate .d.ts files.

One glaring issue here though is that we've generated type definitions for our whole package and not just the ones we want to export. At best this is a whole lot of bloat, but at worse, it's now exposing all of our packages types, not just the ones we want to make public.

Unfortunately this is just how the TypeScript CLI works, but we can do some further processing of these files to get where we want to get to.

Step 3: Rollup Your Type Definitions

What we ideally want then is a single .d.ts file that contains all of our exported types and nothing else.

Thankfully we can achieve this using third party tool, API Extractor.

API Extractor is capable of a lot of cool features, but for the purposes of this article, we'll focus on it's rollup feature.

First then, install API Extractor as a dev dependency.



npm install @microsoft/api-extractor --save-dev

Next, we need to create a config for API Extractor which we can do by running the command



npx api-extractor init

This will generate a new api-extractor.json file in our root folder. By default this file contains a lot of comments to help document all the features, but for now, we can just replace it's contents with the following



{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "projectFolder": ".",
  "mainEntryPointFilePath": "<projectFolder>/types/exports.d.ts",
  "compiler": {
    "tsconfigFilePath": "<projectFolder>/tsconfig.api.json"
  },
  "apiReport": {
    "enabled": false
  },
  "docModel": {
    "enabled": false
  },
  "dtsRollup": {
    "enabled": true,
    "publicTrimmedFilePath": "<projectFolder>/types/my-package.d.ts"
  }
}

Essentially here we are telling API Extractor where to find our types entry point, which in our case is our consolidated exports.d.ts file along with the path to our tsconfig file.

We then disable the features we don't need, but enable the dtsRollup feature and give it a publicTrimmedFilePath of where we want to export our rolled up types to.

With this in place, we can now update the script in our package.json as follows



{
  "script": {
    "build:api": "tsc -p tsconfig.api.json && api-extractor run --verbose",
  }
}

Now when you execute the script, you'll find there is an extra my-package.d.ts file added to our types output folder

If we take a look inside this file, you should see something similar to the following



import { HTMLElementConstructor } from '@umbraco-cms/backoffice/extension-api';
import { LitElement } from '@umbraco-cms/backoffice/external/lit';
import { ManifestBase } from '@umbraco-cms/backoffice/extension-api';
import { ManifestElement } from '@umbraco-cms/backoffice/extension-api';
import { ManifestElementAndApi } from '@umbraco-cms/backoffice/extension-api';
import { UmbApi } from '@umbraco-cms/backoffice/extension-api';
import { UmbControllerHostElement } from '@umbraco-cms/backoffice/controller-api';
import { UmbElement } from '@umbraco-cms/backoffice/element-api';
import { UmbExtensionElementInitializer } from '@umbraco-cms/backoffice/extension-api';

export declare type DefaultManifestQuickActionKind = ManifestKind<ManifestQuickAction> & ManifestBase;

export declare interface QuickActionApi extends UmbApi {
    manifest: ManifestQuickAction;
    execute(): Promise<void>;
}

export declare interface QuickActionElement extends UmbControllerHostElement {
    manifest: ManifestQuickAction;
    api?: QuickActionApi;
}

export declare interface ManifestQuickAction extends ManifestElementAndApi<QuickActionElement, QuickActionApi> {
    type: 'quickAction';
    meta: MetaQuickAction;
}

export declare interface MetaQuickAction {
    entityType: string;
    label: string;
    look?: 'primary' | 'secondary';
}

Step 4: Package Your Type Definitions

Now that we have all our public type in a single file, we can now move on to packaging things up.

First, update your package.json adding the following types, files and peerDependencies values.



{
  "name": "my-package",
  "version": "14.0.0",
  "type": "module",
  "types": "./types/my-package.d.ts",
  "files": [
    "types/my-package.d.ts",
  ],
  "peerDependencies": {
     "@umbraco-cms/backoffice": "^14.0.0",
  }
}

Next, add an additional script as follows



{
  "script": {
    "pack:api": "npm pack",
  }
}

And finally, execute this script in your terminal



npm run pack:api

Now in the root of your project, you should see a my-package-14.0.0.tgz file, which if we look into should contain the following files/structure.



package
├─ types
│  └─ my-package.d.ts
└─ package.json

And with that, we now have an NPM package we can publish using npm publish.

Step 5: Define an Import Map

There is one final step we need to implement, and that is to define an import map for our package.

This is required in order that when anyone used your NPM package and imports a type like import { ManifestQuickAction } from 'my-package', when this runs in the browser, we need to tell it where my-package actually resolves to.

To setup an import map, update your umbraco-package.json and add the following



{
  ...
  "importmap": {
    "imports": {
      "my-plugin": "/App_Plugins/MyPlugin/my-plugin.js"
    }
  }
}

And that should be all we need to implement.

Gotchas

There is one major gotcha I hit with using API Extractor and that is that it doesn't support using custom TypeScript path shortcuts as I recently blogged about. Unfortunately API Extractor assumes all TypeScript path declarations refer to external libraries and so failures ensue.

Ultimately this resulted in me needing to strip out those shortcuts and update all paths back to being relative. That was a fun couple of hours.

Summary

I've tried to boil down the essence here of the steps that are required in order to publish your public API as NPM modules, but there is a lot more you can do with API Extractor as well as other useful scripts you might want to implement (I have some that dynamically updates the package version based on the build server output amongst other things).

But I hope this gives at least the important steps that you might want to implement to do just the same.

The Challenge of Versioning Expandable API's in Umbraco

Matt Brailsford — Thu, 02 May 2024 08:00:00 +0000

Since Umbraco v12 there has been a big push towards making all the core Umbraco products headless. A cool feature of many of these API's is the expansion functionality.

What the expansion functionality provides is an ability to selectively expand nested entity reference objects to their fully populated counterparts.

Lets take a snippet of an Order entity from the Umbraco Commerce Storefront API as an example:

// [GET] /umbraco/commerce/storefront/api/v1.0/order/599f90b3-2647-420a-b7ef-0cd88d69a50b
{
    "id": "599f90b3-2647-420a-b7ef-0cd88d69a50b",
    "orderNumber": "ORDER-01541-34602-5F73L",
    "orderLines": [],
    "currency": {
        "$type": "CurrencyRef",
        "id": "e9368f1a-dcf4-4dc6-ba1e-018dfff40f12",
        "code": "GBP"
    },
    ...
}

Here we can see an order has a connection to a Currency entity which by default will just return a reference object

{
    "$type": "CurrencyRef",
    "id": "e9368f1a-dcf4-4dc6-ba1e-018dfff40f12",
    "code": "GBP"
}

If we now made the same request but this time pass in a query parameter of expand=currency this will now expand the currency to the full entity and return the following:

// [GET] /umbraco/commerce/storefront/api/v1.0/order/599f90b3-2647-420a-b7ef-0cd88d69a50b
// -param expand=currency
{
    "id": "599f90b3-2647-420a-b7ef-0cd88d69a50b",
    "orderNumber": "ORDER-01541-34602-5F73L",
    "orderLines": [],
    "currency": {
        "$type": "Currency",
        "id": "e9368f1a-dcf4-4dc6-ba1e-018dfff40f12",
        "code": "GBP",
        "name": "GBP"
        "culture": "en-GB",
        "allowedCountries": [
            {
                "country": {
                    "$type": "CountryRef",
                    "id": "11959743-c7f9-4a23-9b93-018dfff40f3d",
                    "code": "GB"
                }
            }
        ],    
    },
    ...
}

We can go even further than this too by expanding even deeper entities:

// [GET] /umbraco/commerce/storefront/api/v1.0/order/599f90b3-2647-420a-b7ef-0cd88d69a50b
// -param currency[allowedCountries[country]]
{
    "id": "599f90b3-2647-420a-b7ef-0cd88d69a50b",
    "orderNumber": "ORDER-01541-34602-5F73L",
    "orderLines": [],
    "currency": {
        "$type": "Currency",
        "id": "e9368f1a-dcf4-4dc6-ba1e-018dfff40f12",
        "code": "GBP",
        "name": "GBP"
        "culture": "en-GB",
        "allowedCountries": [
            {
                "country": {
                    "$type": "Country",
                    "id": "11959743-c7f9-4a23-9b93-018dfff40f3d",
                    "code": "GB",
                    "name": "United Kingdom"
                    "defaultCurrency": {
                        "$type": "CurrencyRef",
                        "code": "GBP",
                        "id": "e9368f1a-dcf4-4dc6-ba1e-018dfff40f12"
                    },
                    "defaultPaymentMethod": {
                        "$type": "PaymentMethodRef",
                        "alias": "invoicing",
                        "id": "92037283-e693-4e25-8386-018dfff41062"
                    },
                    "defaultShippingMethod": {
                        "$type": "ShippingMethodRef",
                        "alias": "pickup",
                        "id": "236e5ca1-e340-4da1-8de4-018dfff41113"
                    },
              }
        ],    
    },
    ...
}

This has however recently presented a bit of a challenge that we don't yet have a solution for (which I'm aiming to try and suggest an approach in this post) and that is to do with versioning.

Versioning

When it comes to versioning REST APIs it generally boils down to two possible approaches.

Endpoint Versioning

With this strategy the version is controlled via a version number usually somewhere in the endpoints URL structure. eg /umbraco/commerce/storefront/api/v1.0/order/. When a model changes, you duplicate the old endpoint, incrementing the version number and return the new model from the new endpoint.

This is the approach Umbraco have currently chosen.

Model Versioning

With model versioning you tend to have a single endpoint but then either pass a header or a custom mime type to control which version of the model to return. This reduces the number of endpoints you have to maintain, but it's a lot less obvious.

The Problem

Both of these strategies however are problematic when you take expansion into account.

These versioning strategies are great so long as you only ever access an entity via it's own endpoint, but with the expansions API, the nested entities are retrieved within the output of another endpoint.

Lets take our original example of an Order and a Currency. Now lets say I recently made a change to the Currency entity and so now it's endpoints are all on v2.0 but the Order entity itself hasn't had any changes and so its endpoints are still on v1.0.

If I request an order from /umbraco/commerce/storefront/api/v1.0/order/599f90b3-2647-420a-b7ef-0cd88d69a50b and ask it to extend it's currency property, which version of the currency entity should it return?

Suggestion 1: Version the whole API

You could say "Why not just version the whole API so any change results in a version bump for the whole API?". Well, apart from the fact this would just create hundreds of endpoints we'd have to maintain, there is also the issue of cross product references.

In Umbraco, we have property editors such as pickers than can reference entities in other products e.g. the Umbraco Commerce Store Picker. When an Umbraco content item is returned, it can return a store entity from the Umbraco Commerce Storefront API as it's model value.

So now, if someone was accessing v1 of the Umbraco Content Delivery API, which version of the Store entity from the Storefront API should it return?

Suggestion 2: Switch to Model Versioning

So what if we switched to model versioning. Could this work?

Lets say we introduced some headers to control the versions of models to return. It might look something like this:

// [GET] /umbraco/commerce/storefront/api/order/599f90b3-2647-420a-b7ef-0cd88d69a50b
// -header Order-Version=1.0
// -header Currency-Version=2.0
{
    "id": "599f90b3-2647-420a-b7ef-0cd88d69a50b",
    "orderNumber": "ORDER-01541-34602-5F73L",
    "orderLines": [],
    "currency": {
        "$type": "Currency",
        "id": "e9368f1a-dcf4-4dc6-ba1e-018dfff40f12",
        "code": "GBP",
        "name": "GBP"
        "culture": "en-GB",
        "allowedCountries": [
            {
                "country": {
                    "$type": "CountryRef",
                    "id": "11959743-c7f9-4a23-9b93-018dfff40f3d",
                    "code": "GB"
                }
            }
        ],    
    },
    ...
}

So here, instead of having the version in the endpoint URL, we pass header parameters that dictate the exact versions of the entities we want to return.

This could work, but I think this starts to add some major overhead for implementors.

Every time a developer expands an entity, they would have to add a new header to state which version of that entity they want to support. This would again be even more cumbersome when you take the cross product scenario into account.

My Suggestion: Date Based Versioning

So, what do I suggest? Well, first of all, let me start by saying this is currently just the seed of an idea and I haven't worked out the major details. I'm really using this blog post to document my thoughts, but ultimately, I am wondering if a date based versioning strategy could work.

So my thought is, what if when people build a project using the headless APIs on every request they pass a single date based parameter which is the date their integration started?

// [GET] /umbraco/commerce/storefront/api/order/599f90b3-2647-420a-b7ef-0cd88d69a50b
// -header Integration-Date=2024-03-31 06:16:00

Each endpoint could then use that date to work out what the latest model was up to, but not later than that date and then return that version of the model.

When someone upgrades their project, they could then update their integration date header and it would start to use models released up to that integration date, but not after.

This would ensure that no matter what endpoint an entity was accessed from there was a single flag that could control the model version to return.

Further Considerations

This does introduce some other questions of it's own however.

How would we manage model changes? How do we signal the date of a model change? Could we introduce a C# attribute to decorate models with the date of when that model was introduced? then could we have something that just automatically picks the right model for us based on those attribute?

There is also the question of how this affects the Swagger docs / Open API spec generation. There is great value in having the generated Open API specifications as they allow developers to auto generate API clients. Could we make this work with the date headers? Could we pass a querystring to the Swagger endpoint and then generate the Open API spec dynamically?

Conclusion

As I said at the beginning, this is still very much open for debate and I don't yet have all the answers. The only thing I can say is the later considerations feel much more like coding challenges than fundamental API issues so maybe those would be easier to solve.

I'd love to hear peoples thoughts on this and whether anyone has seen any solutions to this? (I'm guessing API's supporting expansion aren't all that common).

Using the Command Pattern to Re-Apply Changes to an Observable Model in Umbraco Bellissima

Matt Brailsford — Tue, 30 Apr 2024 08:00:00 +0000

In Umbraco v14 one of the hot new approaches is observable models.

You can think of observables as a long lived promise that can resolve multiple times. So when you request a model from a repository, it will usually return an observable of that model. You would then subscribe to this observable to retrieve it's value and store it in a local variable to do what you need to do with it.

If the model ever changes in the repository, your observable subscription will be notified again and you can update your local reference.

Here is some pseudo code to show how this might look:

export class MyComponent extends UmbLitElement {

  // Create a local reference to my repository
  private _modelRepo: MyModelRepo = new MyModelRepo(this);

  // Create a local variable for our model
  @state()
  private _model?: MyModel;

  constructor() {
     super();

     // Fetch the model as an observable
     const model$ = this._modelRepo.getModel();

     // Observe the observable model and store it's value locally on change
     this.observe(model$, (model) => this._model = model);
  }

  render() {
    // Render your model here
  }

}

This is great for components that just render out the model in some way as this gives your component reactivity ensuring it always displays the most up to date data.

When this can be problematic however is when you have en editor interface to your model. If your model has changed due to user input, but you then receive an update from your observable, if you simply update your local model reference, all your user changes will be lost.

The way I have solved this in Umbraco Commerce is to make use of the command pattern.

The Command Pattern

With the command pattern, where you might previously have modified your model directly based on user input, you instead encapsulate that modification into a "Command" class.

So where before we might have just done the following:

this._model.billingAddress = {
  line1: "Some Street",
  city: "Some City",
  zipCode: "Some Zip Code"
};

We instead move this command into it's own class like so:

export class UdateModelBillingAddressCommand {
    address:Address;    
    constructor(address:Address) { 
        this.address = address;
    }
    execute(receiver:MyModel) {
        receiver.billingAddress = {
            ...this.address
        };
    }
}

And then we make changes to our model via the command instead:

const newAddress = {
  line1: "Some Street",
  city: "Some City",
  zipCode: "Some Zip Code"
};
const cmd = new UdateModelBillingAddressCommand(newAddress);
cmd.execute(this._model);

You might be thinking this is a lot more code for the same outcome, and yes, it is more verbose, but by encapsulating our updates in this way, we can store them and reuse them.

Command Base Class

Before we move onto the next step, we'll want to create a Command base class that defines a predictable API for our commands.

export abstract class Command<TReceiver> {
    execute(receiver:TReceiver);
}

Now we can update our previous command like so:

export class UdateModelBillingAddressCommand extends Command<MyModel> {
    address:Address;    
    constructor(address:Address) { 
        this.address = address;
    }
    execute(receiver:MyModel) {
        receiver.billingAddress = {
            ...this.address
        };
    }
}

And ensure any future commands also do the same:

export class UdateModelShippingAddressCommand extends Command<MyModel> {
    address:Address;    
    constructor(address:Address) { 
        this.address = address;
    }
    execute(receiver:MyModel) {
        receiver.shippingAddress = {
            ...this.address
        };
    }
}

Storing Commands

With our commands now implementing this base class, it allows us to easily maintain a collection of commands, and know that we can always call an execute method passing a reference to our model:

private _commands = new Array<Command<MyModel>>();

Our collection never cares what the commands are / do. All it is bothered about is that they all have an execute command it knows how to call.

With our collection defined, now when we update our model, we can also push the command to our commands collection:

// Update our model as before
const newAddress = {
  line1: "Some Street",
  city: "Some City",
  zipCode: "Some Zip Code"
};
const cmd = new UdateModelBillingAddressCommand(newAddress);
cmd.execute(this._model);

// But now also push our command to the commands collection
this._commands.push(cmd);

So now whenever an update is performed, we update our current local model, but also store a copy of the command that was executed in our list of commands.

Re-Applying Commands

With our collection of commands, we now effectively have a history of all changes that have been applied to our model, and so this is where the power of the command pattern comes into play.

We can now update our observer subscription to not just store the new model value, but also re-apply all of our commands.

this.observe(model$, (model) => {
  this._commands.forEach(command => command.execute(model));
  this._model = model;
});

And with that we have a newly updated model, with our user modifications still maintained.

The last thing you'll want to do is update your persistence method to clear the commands list once your changes are saved.

save() {
   this._modelRepo.save(this._model);
   this._commands = [];
}

Gotchas

The only real gotcha I can think of is any occasion where a change coming from the observable is such that a command is no longer able to execute. In those situations I think it would be reasonable to wrap the logic that re-applys commands in a try/catch and if this fails, raise a notification saying something along the lines of "The model you are editing has changed and we are unable to re-apply your changes. Please refresh and try again".

I hope this solution might come in handy for others too.

Enhancing Asynchronous Data Fetching in Umbraco v14 with Lit Async Directives

Matt Brailsford — Thu, 25 Apr 2024 08:00:00 +0000

In Umbraco Commerce we have a number of interconnected models which pose a bit of a problem when it comes to rendering them for display in our markup for the new backoffice.

Fetching all of these models whenever just one of them is requested would be pretty wasteful. Instead, it would be great if the UI could easily request these connected models whenever it needed them.

This is where we can leverage Lit's async directives to do just that.

The Power of Lit Async Directives

Lit async directives provide a powerful way to manage asynchronous operations within your Lit templates. They allow you to create helper functions that fetch data and pass it to a HTML template once it's loaded.

Here's an example of such a helper used in Umbraco Commerce:

${withUcPaymentMethod(this, this.order.paymentInfo.paymentMethod.id, (paymentMethod) =>
    <div>
        <div>Payment via ${ paymentMethod.name }<div>
        <div>${this.order.paymentInfo.totalPrice.formatted}<div>
    </div>
)}

In this example, withUcPaymentMethod is an async directive. It fetches a payment method based on its ID, and once the data is loaded, it passes it to a template that renders the payment information.

Setting Up Lit

To use Lit async directives, you need to have a dependency on lit. Note that the version of lit exported by Umbraco doesn't contain the directive classes, so you'll need to install it separately:

npm install -S lit

Creating an Async Directive

Now, let's take a look at how we can create our own async directive:

import { AsyncDirective } from 'lit/async-directive.js';
import { noChange } from '@umbraco-cms/backoffice/external/lit';
import { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

class WithUcPaymentMethodDirective extends AsyncDirective {

    render(host: UmbControllerHost, id: string, template:(model:any) => unknown)
    {
        new UcPaymentMethodRepository(host).get(id).then(resp => {
            this.setValue(template(resp.data));
        });

        return noChange;
    }
}

export const withUcPaymentMethod = directive(WithUcPaymentMethodDirective);

In this code, we define a new async directive called WithUcPaymentMethodDirective. This directive fetches a payment method based on its ID, and once the data is loaded, it calls this.setValue to update the template with the fetched data.

Handling Initial Render and Re-render

When the directive initially renders, it returns noChange. This means that the template won't be updated until the data is loaded. Once the fetch request promise resolves, this.setValue is called, passing in the rendered template which is in turn passed the returned model. This call triggers a re-render for this module with the updated content.

Caching Data

It's important to note that your repository should implement some kind of caching layer to ensure you aren't making a lot of requests. This will help improve the performance of your application and provide a better user experience.

In conclusion, Lit async directives provide a powerful and flexible way to manage asynchronous data fetching in your Lit applications. They allow you to keep your templates clean and easy to understand, while also ensuring that your data is loaded efficiently and effectively. Happy coding!

Reusing Umbraco Properties in Umbraco v14

Matt Brailsford — Tue, 23 Apr 2024 08:00:00 +0000

When building user interfaces in Umbraco v14, occasionally there comes a time when you need to build a form based on some dynamically defined properties. One such example in Umbraco Commerce is how Payment Providers expose the settings they need for configuration.

When it comes to capturing this configuration, we ideally don't want to have to define these forms manually. Instead, it would be much better if we could use the exposed setting definitions as a pseudo doctype and dynamically render the form reusing the built in property editors in Umbraco to allow capturing different value types.

Data

I won't in this post go into the server side configuration for the payment provider settings, but needless to say, we have a REST endpoint that returns a JSON configuration for our settings similar to the following:

[
    {
        "alias": "continueUrl",
        "label": "Continue Url",
        "description": "The URL to continue to after the provide has done processing",
        "editorUiAlias": "Umb.PropertyEditorUi.TextBox"
    },
    ...
    {
        "alias": "textMode",
        "label": "Test Mode",
        "description": "Whether to run in test mode or production mode",
        "editorUiAlias": "Umb.PropertyEditorUi.Toggle"
    }
]

In addition, our Payment Method entities which hold the configuration values have a properties collection on it similar to the following:

{
    "id": "e06f29df-74fa-4ec8-8240-acccda44e702",
    "alias" : "invoicing",
    "name": "Invoicing",
    "properties": {
        "continueUrl": "/checkout/continue",
        "cancelUrl": "/checkout/cancel",
        "maxRetries": 12,
        "testMode": true
    }
}

Component

Lets start with a basic component that will be responsible for rendering out form.

@customElement("my-component")
export class MyComponentElement extends UmbElementMixin(LitElement) {
    render() {
        return html`TODO`
    }
}

export default MyComponentElement;

declare global {
    interface HTMLElementTagNameMap {
        "my-component": MyComponentElement;
    }
}

Lets now setup a couple of stateful variables to hold our data structures in and define a constructor that is responsible for populating those properties.

@customElement("my-component")
export class MyComponentElement extends UmbElementMixin(LitElement) {

    @state() 
    _settings: Array<MySettingType> = [];

    @state() 
    _model?: MyEntityType;

    constructor(host: UmbControllerHost) {
        super(host);
        // Some code to fetch and populate the _settings + _model
    }

    render() {
        return html`TODO`
    }
}
...

I'll leave the fetching of the data up to you as it's not the important part, but we can move on with the knowledge we should now have some data in variables in the structures outlines above.

Rendering

The two components that are key to reusing umbraco properties are the umb-property-dataset and the umb-property.

Lets initially setup our rendering function as follows:

render() {
    return html`<umb-property-dataset>
        ${repeat(
            this._settings,
            (itm) => itm.key,
            (itm) => html`<umb-property
                alias=${itm.alias}
                label=${itm.label}
                description=${itm.description}
                property-editor-ui-alias=${itm.editorUiAlias}>
            </umb-property>`)}
    </umb-property-dataset>`
}

I'll get to why we need a umb-property-dataset in a second, but for now we'll just need to know that we must have one wrapped around our rendered properties.

Inside the umb-property-dataset tag, we'll then loop through our setting definitions and use the umb-property component, passing through the alias, label, description and editorUiAlias from our settings.

If we were to now look on our front end you should now see your properties rendering, complete with labels, descriptions and the reusing of umbraco property editors.

Pretty neat for relatively little code 😎

Binding

Right now however, there won't be any values in our properties, and we aren't capturing any value changes either.

This is where the umb-property-dataset comes into play. Rather than needing to set values and handle input events for all properties, we instead populate a single values collection, and listen for a single event from the umb-property-dataset instead.

The first thing we need to do is massage our property data into the expected format. The umb-property-dataset takes in a value of type Array<UmbPropertyValueData> where UmbPropertyValueData is defined as:

export type UmbPropertyValueData<ValueType = unknown> = {
    alias: string;
    value?: ValueType;
};

In our component, lets introduce another stateful variable and populate it after we populated our other settings.

@customElement("my-component")
export class MyComponentElement extends UmbElementMixin(LitElement) {

    ...

    @state() 
    _values: Array<UmbPropertyValueData> = [];

    constructor(host: UmbControllerHost) {
        super(host);
        // Some code to fetch and populate the _settings + _model
        this._values = this._settings.map(setting => ({
           alias: setting.alias,
           value: this._model?.properties[setting.alias]
        }));
    }

    ...
}
...

Here we loop through all our setting definitions, creating a new UmbPropertyValueData entry populating it's alias with the setting alias and then it's value with the value of that setting found in our entity model.

With our property values now in the format we need, we can update our render function as follows:

render() {
    return html`<umb-property-dataset
        .value=${this._values}>
        ${repeat(
            this._settings,
            (itm) => itm.key,
            (itm) => html`<umb-property
                alias=${itm.alias}
                label=${itm.label}
                description=${itm.description}
                property-editor-ui-alias=${itm.editorUiAlias}>
            </umb-property>`)}
    </umb-property-dataset>`
}

Here we have bound our _values variable to the value attribute of the umb-property-dataset component and that is all we need to do to get our store values to display.

Change Handling

The last part of the puzzle is reacting to change and persisting the updated values back.

For this we'll create a single event handler to capture all changes like so.

@customElement("my-component")
export class MyComponentElement extends UmbElementMixin(LitElement) {

    ...

    #onPropertyDataChange(e: Event) {
        // Grab the value
        const value = (e.target as UmbPropertyDatasetElement).value;
        // Convert the value back into an object
        var data = value.reduce((acc, curr)=>({...acc, [curr.alias]: curr.value}), {});
        // Update our model
        this._model.properties = data;
    }

    ...
}
...

Here we get the data set value (which contains values for all our settings) and then we convert it into the same structure of our models property collection, and then reset the value back on the model.

Again, I'll leave the persistence side of things to you here, but for this example I'm just writing back to the main entity model..

Finally, we'll update our render function again to attach our event handler.

render() {
    return html`<umb-property-dataset
        .value=${this._values}
        @change=${this.#onPropertyDataChange}>
        ${repeat(
            this._settings,
            (itm) => itm.key,
            (itm) => html`<umb-property
                alias=${itm.alias}
                label=${itm.label}
                description=${itm.description}
                property-editor-ui-alias=${itm.editorUiAlias}>
            </umb-property>`)}
    </umb-property-dataset>`
}

And that's it. We now have a dynamically generated form that reuses umbraco property editors for input collection and where we can capture and store the user input.

I hope you found this post helpful.

If you'd like to see an example implementation of using the umb-property-dataset and umb-property elements there is an example in the Umbraco BackOffice code base here.

Until next time 👋

Creating your own UI extension points in Umbraco v14 - Part 6: Filters & Conditions

Matt Brailsford — Thu, 18 Apr 2024 08:00:00 +0000

So far in this series we have looked at creating a flexible and extendable "quick actions" feature.

In this post we'll take a look at how we can control when our quick actions will display by using filtering and conditions.

It's very likely that we are going to want to display quick actions in multiple places of our application, yet not all actions are going to suitable for all areas. This is whether filters and conditions come in to play in order to control when a quick action actually displays.

Filtering

We will use filtering to control displaying items based on more static attributes, such as a property we define in our manifest.

If we assume that actions in our quick actions list will be entity specific, the simplest filtering we could perform would be to only show actions that are suitable for a given entity type.

To achieve this, lets update our MetaQuickAction to accept a new entityType property.



export interface MetaQuickAction  {
    entityType: string;
    label: string;
    look?: 'primary' | 'secondary';
}

Next, we'll update our manifest definitions to set which entity type the action is suitable for.



export const quickActionManifests: ManifestQuickAction[] = [
    {
        type: 'quickAction',
        kind: 'primary'
        alias: 'Mb.QuickAction.SendEmail',
        name: 'Send Email Quick Action',
        weight: 200,
        meta: {
            entityType: "uc:order",
            label: "Send Email"
        }
    },
    ...
]

And now in our entities workspace elements render function, we can update the umb-extension-with-api-slot to pass in a filter.



render() {
   return html`<uui-box headline="Actions">
       <umb-extension-with-api-slot
           type="quickAction"
           filter=${(ext) => ext.meta.entityType === 'uc:order'}
           default-element="quick-action-button">
       </umb-extension-with-api-slot>
   </uui-box>`
}

A filter is a defined inline as a lambda expression that takes a manifest and performs a check against it. If the lambda returns true, the manifest will be included, otherwise it will be excluded from the output.

With this, in each entities workspace we can change the entity type to that of the given workspace and be sure we'll only display actions that are suitable for our given entity.

Conditions

Where filters allow us to control the display of our actions by manifest properties, conditions allow us to control the display based on more dynamic conditions that may only be known at runtime.

We firstly enable conditions support by updating our manifest interface as follows:



export interface ManifestQuickAction extends ManifestElementAndApi<QuickActionElement, QuickActionApi>,
    ManifestWithDynamicConditions {
    type: 'quickAction';
    meta: MetaQuickAction;
}

Here we have our ManifestQuickAction extend from both the previous ManifestElementAndApi<> interface and a new ManifestWithDynamicConditions interface.

If we take a look at the ManifestWithDynamicConditions interface we can see that our manifest now supports a conditions property.



export interface ManifestWithDynamicConditions {
    conditions?: Array<ConditionTypes>;
}

Configuration

Configuring conditions is done against the manifest definitions.

To limit a quick action to only display if a user belongs to a given user group, we can configure our manifest as follows:



export const quickActionManifests: ManifestQuickAction[] = [
    {
        type: 'quickAction',
        kind: 'primary'
        alias: 'Mb.QuickAction.SendEmail',
        name: 'Send Email Quick Action',
        weight: 200,
        meta: {
            entityType: "uc:order",
            label: "Send Email"
        },
        conditions: [
            {
                alias: 'Umb.Condition.UserGroup',
                match: 'admin',
            },
        ]
    },
    ...
]

NB The Umb.Condition.UserGroup condition doesn't actually exist in core yet, but I believe it will so have demonstrated it here, but if you need this functionality now, you may need to implement your own in the meantime (see below).

Custom Conditions

We aren't just limited to the out of the box conditions either. If needed, we can actually implement our own.

As you might expect, conditions are yet another manifest type.



export const conditionManifests: Array<ManifestCondition> = [
    {
        type: 'condition',
        name: 'My Condition',
        alias: 'Mb.Condition.MyCondition',
        api: MyCondition,
    }
];

Our custom condition in turn references a custom condition API implementation MyCondition.



export class MyCondition extends UmbConditionBase<MyConditionConfig> implements UmbExtensionCondition
{
    constructor(host: UmbControllerHost, args: UmbConditionControllerArguments<MyConditionConfig>) {
        super(host, args);

        // Do your logic here and set `this.permitted`
        // to a boolean value
        // async behavior is supported
        this.permitted = args.config.match == 'ALLOWED';
    }
}

export type MyConditionConfig = UmbConditionConfigBase<'Mb.Condition.MyCondition'> & {
    match: string;
};

The API implementation can define a config object for any parameters it might need, in our case we require a single match parameter. Then, within the conditions constructor it should perform it's checks and set it's permitted field to the result of that check.

As with any manifest definitions, we must register them with the extensions registry.



export const onInit: UmbEntryPointOnInit = (host, extensionRegistry) => {

    extensionRegistry.registerMany(conditionManifests);

};

Configuration Update

We can now update our manifest definition to use our custom condition.



export const quickActionManifests: ManifestQuickAction[] = [

    {

        type: 'quickAction',

        kind: 'primary'

        alias: 'Mb.QuickAction.SendEmail',

        name: 'Send Email Quick Action',

        weight: 200,

        meta: {

            entityType: "uc:order",

            label: "Send Email"

        },

        conditions: [

            {

                alias: 'Mb.Condition.MyCondition',

                match: 'ALLOWED',

            },

        ]

    },

    ...

]

Conclusion

This is the last post in a series about creating your own UI extension points in Umbraco v14. We've covered a whole bunch of things from basic extension definitions, to swappable APIs and interchangeable elements along with reusable kinds and condition flows.

Hopefully you've found this series useful.

Until next time 👋

Creating your own UI extension points in Umbraco v14 - Part 5: Kinds

Matt Brailsford — Tue, 16 Apr 2024 08:00:00 +0000

In the last posts in this series, we've looked at ways to allow developers to swap out behaviors and UI elements for our "quick action" feature.

In this post we'll take a look at how we can reduce some repetition in our manifest definitions by using 'kinds'.

Kind Definitions

In Umbraco v14, kinds are essentially reusable, prepopulated manifest definitions, saving you from having to fill in all manifest properties for common use cases.

In our "quick actions" feature, we have two key button types, and we have a default button and API implementation so lets create two kinds that preconfigure these settings.


export type QuickActionKind = ManifestKind<ManifestQuickAction> & ManifestBase;

export const kindManifests: Array<QuickActionKind> [
    {
        type: 'kind',
        alias: 'Mb.Kind.QuickAction.Primary',
        name: 'Primary Quick Action Kind',
        matchKind: 'primary',
        matchType: 'quickAction',
        manifest: {
            type: 'quickAction',
            kind: 'primary',
            element: QuickActionDefaultElement
            api: QuickActionDefaultApi,
            meta: {
                look: 'primary'
            }
        }
    },
    {
        type: 'kind',
        alias: 'Mb.Kind.QuickAction.Default',
        name: 'Default Quick Action Kind',
        matchKind: 'default',
        matchType: 'quickAction',
        manifest: {
            type: 'quickAction',
            kind: 'default',
            element: QuickActionDefaultElement
            api: QuickActionDefaultApi,
            meta: {
                look: 'secondary'
            }
        }
    }
]

Essentially we define a QuickActionKind kind type that extends ManifestKind<ManifestQuickAction> and ManifestBase and then create an array of implementations which state the matchKind and a matchType that our manifest kind and type attribute must be set to for this kind to apply.

Then, the manifest property defines a partially implemented ManifestQuickAction manifest. The values in this definition will automatically be copied over to any matching manifests.

Registration

As with any manifest definitions, we must register them with the extensions registry.

export const onInit: UmbEntryPointOnInit = (host, extensionRegistry) => {
    extensionRegistry.registerMany(kindManifests);
};

Manifest Updates

With our kind manifests registered, we can now update our quick action manifests to use these kinds to prepopulate our properties for us.

export const quickActionManifests: ManifestQuickAction[] = [
    {
        type: 'quickAction',
        kind: 'primary',
        alias: 'Mb.QuickAction.SendEmail',
        name: 'Send Email Quick Action',
        weight: 200,
        meta: {
            label: "Send Email"
        }
    },
    {
        type: 'quickAction',
        kind: 'default',
        alias: 'Mb.QuickAction.ChangeStatus',
        name: 'Change Status Quick Action',
        weight: 100,
        meta: {
            label: "Change Status"
        }
    }
]

Here we give each of our manifests a kind property value and remove the element, api and meta.look properties as these will now come directly from our kind definition.

Optional Cleanup

Because we are now using kinds to give all our manifests some defaults, we could do a little bit of cleanup here. In the second post in this series, we defined our default element globally and set it as the default element on our umb-extension-with-api-slot.

As all our definitions now come with a element defined, we could remove these and just use the values from our manifests.

What's next?

In this post we've look at how we can use "kinds" to create reusable manifest definitions.

In the next post, we'll take a look at how we make our manifests control when an action should be displayed by using filters and conditions.

Until then 👋

Creating your own UI extension points in Umbraco v14 - Part 4: Interchangeable Elements

Matt Brailsford — Thu, 11 Apr 2024 08:00:00 +0000

In the last post we looked at how we can swap out our "quick action" button behavior whenever a button is clicked.

In this post we'll take a look at how we could allow someone to completely replace the button element with some other user control.

Element Extensions

To allow our actions to support a interchangeable elements we first need to update our manifest definition again.

export interface ManifestQuickAction extends ManifestElementAndApi<QuickActionElement, QuickActionApi> {
    type: 'quickAction';
    meta: MetaQuickAction;
}

export interface QuickActionElement extends UmbControllerHostElement {
    manifest: UcManifestEntityQuickAction;
    api?: QuickActionApi;
}

Here again we swap out the base interface and now extend from ManifestElementAndApi<>. We also define a QuickActionElement interface which lays out the required properties that any element used as a quick action must support. This interface, along with our previously defined API interface, are passed to the ManifestElementAndApi<> interface as generic arguments.

If we take a look at the ManifestElementAndApi<> interface we can see that our manifest now supports a couple of extra properties.

export interface  ManifestElementAndApi<ElementType, ApiType> extends ManifestBase {
    element?: ElementLoaderProperty<ElementType>;
    elementName?: string;
    ...
}

Default Element Updates

With our element interface defined, we can go back to our default button implementation and ensure this now implements our required interface.

@customElement("quick-action")
export class QuickActionElement extends UmbElementMixin(LitElement)
    implements QuickActionElement {

    @property({ type: Object, attribute: false })
    manifest!: ManifestQuickAction;

    @property({ type: Object, attribute: false })
    api?: QuickActionApi;

    #onClick(e: Event) {
        this.api?.execute();
    }

    render() {
        return html`<uui-button 
                look=${this.manifest.meta.look ?? 'secondary'}
                @click=${this.#onClick}>
                ${this.manifest.meta.label}
           </uui-button>`
    }
}

export default QuickActionElement;

declare global {
    interface HTMLElementTagNameMap {
        "quick-action": QuickActionElement;
    }
}

Overriding the Default Element

With everything configured developers can now override the default button element by firstly creating their own component that implements our interface.

@customElement("my-quick-action")
export class MyQuickActionElement extends UmbElementMixin(LitElement)
    implements QuickActionElement {

    @property({ type: Object, attribute: false })
    manifest!: ManifestQuickAction;

    @property({ type: Object, attribute: false })
    api?: QuickActionApi;

    #onClick(e: Event) {
        this.api?.execute();
    }

    render() {
        return html`RENDER YOUR COMPONENT HERE`
    }
}

export default MyQuickActionElement;

declare global {
    interface HTMLElementTagNameMap {
        "my-quick-action": MyQuickActionElement;
    }
}

Then updating the manifest to use this component instead.

export const quickActionManifests: ManifestQuickAction[] = [
    {
        type: 'quickAction',
        alias: 'Mb.QuickAction.SendEmail',
        name: 'Send Email Quick Action',
        weight: 200,
        element: MyQuickActionElement,
        api: SendEmailQuickActionApi,
        meta: {
            label: "Send Email",
            look: "primary"
        }
    },
    {
        type: 'quickAction',
        alias: 'Mb.QuickAction.ChangeStatus',
        name: 'Change Status Quick Action',
        weight: 100,
        element: MyQuickActionElement,
        api: ChangeStatusQuickActionApi,
        meta: {
            label: "Change Status"
        }
    }
]

What's next?

In this post we've looked out how to allow developers to override the default element of an extension.

In the next post we'll take a look at how we can reduce some repetition in our manifest definitions by creating reusable 'kinds'.

Until then 👋

Creating your own UI extension points in Umbraco v14 - Part 3: Customizable APIs

Matt Brailsford — Tue, 09 Apr 2024 08:00:00 +0000

In the last post in this series, we looked at componentizing the UI for our "quick action" elements.

In this post we'll take a look at how we can allow developers to override the default behavior of our buttons when they are clicked.

API Extensions

In Umbravo v14, the mechanism of replacing the behavior of an extension is via a custom API implementation.

To allow our actions to support a customizable API we first need to update our manifest definition.

export interface ManifestQuickAction extends ManifestApi<QuickActionApi> {
    type: 'quickAction';
    meta: MetaQuickAction;
}

export interface QuickActionApi extends UmbApi {
    manifest: ManifestQuickAction;
    execute(): void;
}

Instead of extending from ManifestBase like we did in the last post, we now extend from ManifestApi<>. We also define a QuickActionApi interface which holds a reference to our manifest and defines the signature of a supported execute behavior. This interface is passed to the ManifestApi<> interface as a generic argument so that it knows which API type to expect.

If we take a look at the ManifestApi<> interface we can see that our manifest now supports a new property.

export interface  ManifestApi<ApiType> extends ManifestBase {
    api?: ApiLoaderProperty<ApiType>;
}

We'll take a look at how to use it shortly, but we first need to update our button component to support custom APIs.

UI Updates

We'll update our component as follows:

@customElement("quick-action")
export class QuickActionElement extends UmbElementMixin(LitElement) {

    @property({ type: Object, attribute: false })
    manifest!: ManifestQuickAction;

    @property({ type: Object, attribute: false })
    api?: QuickActionApi;

    #onClick(e: Event) {
        this.api?.execute();
    }

    render() {
        return html`<uui-button 
                look=${this.manifest.meta.look ?? 'secondary'}
                @click=${this.#onClick}>
                ${this.manifest.meta.label}
           </uui-button>`
    }
}

export default QuickActionElement;

declare global {
    interface HTMLElementTagNameMap {
        "quick-action": QuickActionElement;
    }
}

Here we new have a new optional api property of type QuickActionApi. We've also also moved our click handler to a dedicated private handler function and we have that call the APIs execute() method in replace of the console.log statement.

Next, we need to update our workspaces render function as follows:

render() {
   return html`<uui-box headline="Actions">
       <umb-extension-with-api-slot
           type="quickAction"
           default-element="quick-action-button">
       </umb-extension-with-api-slot>
   </uui-box>`
}

Here we have simply switched from using a umb-extension-slot helper component, to use a umb-extension-with-api-slot helper component instead. This new component does everything the previous other does, but also instantiates and injects API instances into our button components.

API Implementations

Now that our UI is capable of executing our custom API's, lets define some API implementations for our two buttons.

// ./components/send-email.quick-action.api.ts
export default class SendEmailQuickActionApi extends UmbControllerBase implements QuickActionApi {

    manifest!: UcManifestEntityQuickAction;

    execute() {
        console.log(`You clicked ${this.manifest.meta.label}`);
    }

}

// ./components/change-status.quick-action.api.ts
export default class ChangeStatusQuickActionApi extends UmbControllerBase implements QuickActionApi {

    manifest!: UcManifestEntityQuickAction;

    execute() {
        console.log(`Now you clicked ${this.manifest.meta.label}`);
    }

}

Manifest Updates

Finally, we can now update our manifest to reference our API implementations.

export const quickActionManifests: ManifestQuickAction[] = [
    {
        type: 'quickAction',
        alias: 'Mb.QuickAction.SendEmail',
        name: 'Send Email Quick Action',
        weight: 200,
        api: SendEmailQuickActionApi,
        meta: {
            label: "Send Email",
            look: "primary"
        }
    },
    {
        type: 'quickAction',
        alias: 'Mb.QuickAction.ChangeStatus',
        name: 'Change Status Quick Action',
        weight: 100,
        api: ChangeStatusQuickActionApi,
        meta: {
            label: "Change Status"
        }
    }
]

And now when we click each of our quick actions, the defined API's will be instantiated and called allowing complete customization of the buttons behavior.

What's next?

In this post we've outlined how to allow customizable APIs for extensions. But what if you also wanted to allow swapping out the button component entirely?

In our next post we'll take a look how we can go about just that.

Until then 👋

Creating your own UI extension points in Umbraco v14 - Part 2: Extension Slots

Matt Brailsford — Thu, 04 Apr 2024 08:00:00 +0000

In our first post in this series, we looked at the basics of setting up our "quick actions" section for our UI.

In that post we manually fetched and observed the extensions registry for quick action definitions and then rendered out our button elements individually.

In this post we'll take a look at how we can do without this repetitive manual setup and make use of some other manifest extension points.

Componentization

Lets start by moving our quick action button to it's own component.

@customElement("quick-action")
export class QuickActionElement extends UmbElementMixin(LitElement) {

    @property({ type: Object, attribute: false })
    manifest!: ManifestQuickAction;

    render() {
        return html`<uui-button 
                look=${this.manifest.meta.look ?? 'secondary'}
                @click=${() => console.log(this.manifest.meta.label)}>
                ${this.manifest.meta.label}
           </uui-button>`
    }
}

export default QuickActionElement;

declare global {
    interface HTMLElementTagNameMap {
        "quick-action": QuickActionElement;
    }
}

This should be a relatively familiar setup for creating a web component. The only "special" thing here is the manifest property which accepts a copy of the manifest definition for the given quick action that this instance of the component is rendering.

Component registration

For the time being, we need to make our component definition globally accessible and so to do this we need to export it in our root level index.ts file.

export * from "./components/quick-action.element.ts";

We'll handle this better in a future blog post, but for now, this is the simplest way to make our component easily instantiatable.

Rendering

Now we can update our workspace component, removing all the code we wrote in our constructor, and getting rid of the state variable that held out quick action definitions and we can instead make use of a helper component that will take care of all of this for us.

Update your render function as follows:

render() {
   return html`<uui-box headline="Actions">
       <umb-extension-slot 
           type="quickAction"
           default-element="quick-action-button">
       </umb-extension-slot>
   </uui-box>`
}

So now, instead of us manually fetching our definitions, the umb-extension-slot will do the manifests lookup for us. It will fetch all manifests of the defined type and render each one using our quick-action-button element, as defined by the default-element attribute (this is why we needed to register our component globally for now, as it has to be referenced by name).

In addition, each instantiated element will also have the given manifest automatically injecting into its manifest property, allowing it to configure it's behavior accordingly.

What's next?

In this post we've componentized our quick actions, and made use of the umb-extension-slot to save us having to write a bunch of repetitive code.

Effectively though are buttons are still tied to a single implementation so in the next post we'll take a look at how we can make the buttons click handler customizable.

Until then 👋

Creating your own UI extension points in Umbraco v14 - Part 1: The Basics

Matt Brailsford — Tue, 02 Apr 2024 08:00:00 +0000

In this mini series I'll take a look at a progressively more advanced example of creating your own UI extensions in Umbraco v14.

I'll loosely base this on a feature in Umbraco Commerce where we display a series of "Quick Action" buttons in a few of the editor views to provide instant access to important features.

We provide a number of quick actions out of the box, but we also want to provide a means fore developers to add their own based on their customers needs.

NB As you might expect, this is considered a fairly advanced topic for Umbraco v14 and so in the name of brevity, I assume you know a lot of fundamentals of developing for v14. If you are just getting started, you might want to go do some basic learning first before tackling this subject.

In this first post we'll take a look at the most basic implementation of a UI extension point for registering our buttons.

Definition

The foundation of extending the UI in Umbraco v14 lies in defining custom manifests.

Let's start by defining a basic extension manifest interface:

export interface ManifestQuickAction extends ManifestBase {
    type: 'quickAction';
    meta: MetaQuickAction;
}

export interface MetaQuickAction  {
    label: string;
    look?: 'primary' | 'secondary';
}

A manifest consists of two parts. The manifest definition and a meta data object for defining custom properties we want to capture.

In this example we define a ManifestQuickAction manifest and give it a type of "quickAction". This will be how we identify our quick actions and will be used later to look up all manifests with this type.

We also define a meta property of type MetaQuickAction which at this point simply holds a label and optional look attribute which will control the text and style of our button.

In addition to the properties we've defined, we also get a number of standard manifest properties from the ManifestBase interface.

export interface ManifestBase {
    type: string;
    alias: string;
    kind?: unknown;
    name: string;
    weight?: number;
}

These are standard for all manifests and mostly provide a means of identifying an individual manifest definition and controlling it's position.

Implementation

With our manifest interface defined, we can now define our manifest implementations.

export const quickActionManifests: ManifestQuickAction[] = [
    {
        type: 'quickAction',
        alias: 'Mb.QuickAction.SendEmail',
        name: 'Send Email Quick Action',
        weight: 200,
        meta: {
            label: "Send Email",
            look: "primary"
        }
    },
    {
        type: 'quickAction',
        alias: 'Mb.QuickAction.ChangeStatus',
        name: 'Change Status Quick Action',
        weight: 100,
        meta: {
            label: "Change Status"
        }
    }
]

Registration

With our manifests defined we then register them with the extension registry from within our onInit entry point method.

export const onInit: UmbEntryPointOnInit = (host, extensionRegistry) => {
    extensionRegistry.registerMany(quickActionManifests);
};

Rendering

With all our manifests now registered, the next step is to render our buttons for each manifest.

Within the constructor of our workspace element we'll first lookup our manifest instances by querying the extensions registry.

constructor(host: UmbControllerHost) {
    super(host);
    const quickActionsObservable = umbExtensionsRegistry.byType<string, ManifestQuickAction>('quickAction');
}

As with most things in Umbraco v14, what we get back from our query is an observable and so we will want to observe the collection and store it's value in a local state variable.

@state() 
_quickActions: ManifestQuickAction[] = [];

constructor(host: UmbControllerHost) {
    super(host);
    const quickActionsObservable = umbExtensionsRegistry.byType<string, ManifestQuickAction>('quickAction'); 
    this.observe(quickActionsObservable, (manifests) => {
        this._quickActions = manifests
    })
}

With access to our actions, we can then output our buttons in our workspace components render method. For now we'll just output the actions label to the console when the button is clicked.

render() {
   return html`<uui-box headline="Actions">
       ${repeat(this._quickActions,
           (qa) => qa.alias,
           (qa) => html`<uui-button 
                look=${this.manifest.meta.look ?? 'secondary'}
                @click=${() => console.log(qa.meta.label)}>
                ${qa.meta.label}
           </uui-button>`
        )}
   </uui-box>`
}

What's next?

In this post I've shared the most basic example of creating a custom UI extension. If in your use case all you need is to allow developers to provide some level of configuration that you will process and handle in a predefined way, then this should cover all you need.

If as in our example however, your configuration has a 1-to-1 relation to a rendered element (ie, our quick action button) then we can actually go a little bit further, as whilst we have allowed developers to define their own quick action buttons, the implementation of what a quick action is and does is really rather restrictive.

In the next few posts in this series I'll take a look at how we can make this even more flexible by allowing developers to change the buttons behavior when clicked and also how they could swap out the button component entirely.

Until next time 👋

Simplifying Imports with TypeScript Path Aliases in Umbraco v14

Matt Brailsford — Tue, 02 Apr 2024 08:00:00 +0000

I recently attended the online Umbraco Manchester meetup where Rick Butterfield talked about Generating a TypeScript OpenAPI client from Umbraco's Content Delivery API. One really useful tip he suggested was using typescript path aliases to simplify your import paths, but on implementing his suggestion there was one tiny piece of missing information I needed so I thought I'd write this blog post to give a complete picture for any Umbraco package devs building in v14 that are using the recommended tooling (TypeScript + Vite).

Why Use Path Aliases?

In large TypeScript projects, managing imports can become a tedious task. You might find yourself navigating through multiple directories to import a single module. This is where path aliases come into play. They allow you to create shortcuts for directories, simplifying your import statements and making your code cleaner and easier to manage.

Let's take a look at a before and after example.

Before

import { Order } from '../../models/order.model.ts';
import { OrderLine } from '../../models/order-line.model.ts';
import { SomeComponent } from '../../../core/components/some-component.element.ts';

After

import { Order } from '@uc-models/order.model.ts';
import { OrderLine } from '@uc-models/order-line.model.ts';
import { SomeComponent } from '@uc-components/some-component.element.ts';

Here, @uc-models and @uc-components are path aliases that map to the directories ./src/models and ./src/core/components respectively.

Setting Up Path Aliases in TypeScript

To set up path aliases in TypeScript, you need to modify your tsconfig.json file. Here's how you can do it:

{
  "compilerOptions": {
    ...
    "baseUrl": "./src",
    "paths": {
      "@uc-models/*": ["models/*"],
      "@uc-components/*": ["core/components/*"]
    },
    ...
  }
}

In the compilerOptions object, we set the baseUrl to ./src. This is the directory that our path aliases will be relative to. Then, in the paths object, we define our path aliases. Each key is a path alias, and the corresponding value is an array of paths that the alias should map to.

Integrating Path Aliases with Vite

If you're using Vite as your build tool (which we are at Umbraco), there's one more step you need to take. You need to define the same path aliases in your vite.config.ts file. Here's how you can do it:

export default defineConfig({
    ...
    resolve: {
        alias: {
            '@uc-models': path.resolve(__dirname, './src/models'),
            '@uc-components': path.resolve(__dirname, './src/core/components'),
        },
    },
    ...
});

In the resolve object, we define an alias object. This object should have the same keys and values as the paths object in our tsconfig.json file.

UPDATE 2024-04-08
Thanks to Markus Johansson great suggestion in the comments, you can avoid having to duplicate your path declarations by installing vite-tsconfig-paths

npm install -D vite-tsconfig-paths

Then updating your vite configuration accordingly.

import { defineConfig } from 'vite'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [tsconfigPaths()],
})

And that's it! You've now set up path aliases in your TypeScript project. This will make your import statements much cleaner and easier to manage. Happy coding!