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.

TypeScript Definitions only used during development

Referencing types are only used to enable static analysis benefits during development and have no impact on runtime execution where they're removed in order for your code to run as-is inside the browser.

TIP

To satisfy the source transforms, each import statement should be on a single line and should contain no preceding white space.

Install

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

npm install @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

NamespaceDescription
sharedType Definitions for all Types and shared functionality used in all UI's
clientType Definitions for the @servicestack/client library

UIs

UIDescription
locodeGlobal App and Type instances available in Locode Apps
explorerGlobal App and Type instances available in API Explorer
adminGlobal 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/*.html where you can also override any of Locode's components by including a locally modified copy from /components/*.html

    /components
        *.html
    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/*.html, whilst existing components can be overridden in /components/*.html and custom UI added to custom.*

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

/admin-ui

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

    /components
        *.html
    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:

    *.html
    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 sharedBrand 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.