Custom Locode Apps

Locode also lets you create rich custom user experiences by going beyond the declarative C# dev model to create custom HTML & JS Components loaded directly in your Locode Apps.

This lets us provide an enhanced UX beyond Locode's default UI to create Custom Forms for some of our tables or override Locode's own components to create a custom home page or customize your App's branding components or make use of custom format functions to change how results are rendered.

To facilitate custom HTML/JS UI development we've packaged type definitions for all Locode's functionality in the
@servicestack/ui npm package below to enable its productive typed development UX whose changes load instantly without App restarts when run in development mode:

dotnet watch

Getting Started​

When customizing any ServiceStack UI App you can enable static typing and intelli-sense by installing the @servicestack/ui npm package (containing their TypeScript .d.ts definitions) in your host project, where you'll be able to use the standard ES6 import syntax to enable static analysis on any built-in functionality you want to use.

Install​

Add TypeScript definitions for ServiceStack UI's to your Host project with:

npm install -D @servicestack/ui

Update​

Update your local Type definitions to the latest version with:

npm install @servicestack/ui@latest

API Reference​

Type definitions for functionality available in ServiceStack UI's

Library Reference​

Namespace Description
shared Type Definitions for all Types and shared functionality used in all UI's
client Type Definitions for the @servicestack/client library

UIs​

UI Description
locode Global App and Type instances available in Locode Apps
explorer Global App and Type instances available in API Explorer
admin Global App and Type instances available in ServiceStack's Admin UI

Custom UI​

Whilst @servicestack/ui isn't used at runtime and therefore not strictly required, it contains the type definitions for all built-in ServiceStack Apps to enable superior Developer UX by enabling static analysis, rich-intellisense and type safety feedback to provide a helpful guide ensuring correct usage of discoverable built-in functionality.

All built-in ServiceStack Apps can be customized the same way where each of their HTML components can be replaced by adding a local file at their same path in your AppHost Project's /wwwroot/modules folder:

/wwwroot/modules​

To make it easy to customize each App, purpose-specific custom.* placeholders can be overridden to include additional CSS, JS and HTML in each App. Whilst any of their existing components can be replaced by adding a local modified copy in its /components/*.html folder.

We'll go through each App's folder to better visualize their extension placeholders that's available:

/locode​

Lets you customize Locode Apps where Custom Forms can either be registered in custom.html or added to /components/*.mjs where you can also override any of Locode's components by including a locally modified copy from /components/*.mjs

    /components
        *.mjs
    custom.js
    custom.css
    custom.html

/ui​

Is where to customize your Services API Explorer UI where each API can be documented by adding Custom API Docs to /docs/*.mjs, whilst existing components can be overridden in /components/*.html and custom UI added to custom.*

    /docs
        *.mjs
    /components
        *.mjs
    custom.js
    custom.css
    custom.html

/admin-ui​

Is where to add any customizations to Admin UI by overriding existing components in /components/*.mjs or adding custom UI to custom.*

    /components
        *.mjs
    custom.js
    custom.css
    custom.html

/shared​

The shared folder is where you can customize all Apps by overriding generic components in shared/*.html whilst custom HTML can be added to the <head/>, at the start and end of the <body/> of each App by including the custom-*.html placeholders below:

    custom-head.html
    custom-body.html
    custom-end.html

Custom App Example​

The Blazor WASM template includes example App customizations with Custom API Docs for its CreateBooking and Todos APIs:

Whilst replacing the existing shared Brand Component changes the top-left App Branding UI in each App:

Next we'll see how we to create Custom Forms to replace the Auto Form UI in Locode Apps.

Edit this page on GitHub