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:
-
/modules
- /ui/docs
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.