New Locode v2

[mythz]

I wanted to give everyone early notice that Locode - the Auto UI for managing your AutoQuery APIs has been rewritten from the minimal & restrictive petite-vue to using the full Vue 3 in the latest v6.6+ on MyGet and GitHub Packages.

The new Locode Vue 3 should have complete feature parity with the old Petite Locode, but to minimize potential disruption we'll be temporarily including both UIs at the built-in routes below:

• /locode/ - New Vue3 Locode
• /locode-v1/ - Old PetiteVue Locode

Which is included in the Blazor Gallery App if you want to compare the old & new versions of Locode side-by-side:

• https://blazor-gallery.servicestack.net/locode/
• https://blazor-gallery.servicestack.net/locode-v1/

As Vue3 Locode supports all existing C# UI declarative attributes that Locode (and Blazor AutoQueryGrid) component utilizes to customize its UI, we expect the only real friction will be to port any custom PetiteVue components you might've added into Vue 3 components.

Our plan is to remove the old Petite Vue UI in the release after next (i.e. v6.8) if we don't have any outstanding reported issues, so please let us know of any issues you find with new Locode UI now in the pre-release packages or during the next 6.7 release.

Other than being able to use full Vue 3 feature to create the UI and any custom components the primary difference is that it's also able to utilize the Vue 3 component library and its new AutoQueryGrid component which unlike Locode's PetiteVue Grid is highly customizable where you'll be able to easily include your own Customizable AutoQueryGrid components to customize its columns & forms, etc.

Customizing AutoQuery Pages

Previously if you needed to go beyond the available customizations in Locode you would need to start looking transitioning to a Bespoke App, but with Vue 3 locode you can completely change what each Data Model page does by registering a component with the <DataModel>Page which Locode will render instead, and because the <AutoQueryGrid/> is highly customizable you should be able to reuse most of its functionality whilst customizing the parts you want to change.

Custom components can be registered in your project at the following location:

- /wwwroot
	- /modules/locode/components/*.mjs

Where instead of a PetiteVue HTML component you would register a Vue 3 component which should have the .mjs extension to signify it's a JavaScript Module. If you're unfamiliar with JS Modules or Vue 3 we recommend reading our Simple, Modern JavaScript blog post which describes how the vue-mjs template creates interactive Vue Apps without needing any npm build tools, which you'd typically adopt when registering custom components, (although you can register any Vue 3 component, e.g. a compiled Vue3 SFC if you prefer to configure your project with Vite+Vue3+tsc and register the output builds).

We've added a custom component in Blazor Gallery at /wwwroot/modules/locode/components/BookingPage.mjs

import { inject, ref } from "vue"
import { QueryCoupons } from "/types/mjs"

export const BookingPage = {
    template:`
      <div>
          <h1 class="py-8 text-center text-3xl text-indigo-700 font-semibold">Custom Bookings AutoQueryGrid</h1>
          <AutoQueryGrid type="Booking" selected-columns="id,name,cost,bookingStartDate,bookingEndDate,discount">
            <template #discount="{ discount }">
              <TextLink v-if="discount" class="flex items-end" @click.stop="showCoupon(discount.id)" :title="discount.id">
                <Icon class="w-5 h-5 mr-1" type="Coupon" />
                <PreviewFormat :value="discount.description" />
              </TextLink>
            </template>
          </AutoQueryGrid>
          <AutoEditForm v-if="coupon" type="UpdateCoupon" v-model="coupon" @done="close" @save="close" />
      </div>
    `,
    props:['type'],
    setup() {
        const client = inject('client')
        const coupon = ref()
        async function showCoupon(id) {
            const api = await client.api(new QueryCoupons({ id }))
            if (api.succeeded) {
                coupon.value = api.response.results[0]
            }
        }
        const close = () => coupon.value = null
        return { coupon, showCoupon, close }
    }
}
export default BookingPage //optional

What's nice about Vue 3 is that now your components are reusable where you'll be able to reuse them in any other Vue Apps or components you have, e.g:

import BookingPage from "/locode/components/BookingPage.mjs"

const MyComponent = {
    components: { BookingPage },
    template:`
        <h3>My Bookings!</h3>
        <BookingPage />
    `
}

Which changes the Bookings Locode page
https://blazor-gallery.servicestack.net/locode/QueryBookings

From the standard AutoQueryGrid displaying all standard columns:

To the custom implementation above which opens the Edit Form when clicking on the Booking Discount letting you manage both the Bookings and Coupons on the same page.

Components

Your custom components can utilize built in libraries embedded in ServiceStack.dll by importing by package name, e.g:

import { ref } from "vue"
import { useClient } from "@servicestack/vue"
import { humanify } from "@servicestack/client"

Where your components will have access to the latest Vue 3 reactive fx, @servicestack/client client library and Vue 3 Tailwind Component library.

As all package dependencies are written in TypeScript you can install them as dev dependencies to get static analysis from its TypeScript definitions at dev time:

npm install -D vue
npm install -D @servicestack/client
npm install -D @servicestack/vue

Your components can access your Apps Typed DTOs directly from the ES6 Module DTO endpoint at /types/mjs, e.g:

import { QueryCoupons } from "/types/mjs"

App functionality

Your components access to most of the App's functionality via the injected dependencies for functionality defined in app.mjs

const app = inject('app')                  // app instance
const client = inject('client')            // JsonServiceClient
const server = inject('server')            // AppMetadata (metadata for your Server App and APIs)
const store = inject('store')              // Reactive store for App
const routes = inject('routes')            // Routing and navigation
const settings = inject('settings')        // Manage & persist user settings
const breakpoints = inject('breakpoints')  // Bind to different Tailwind responsive breakpoints

app is our wrapper component around Vue's createApp which lets you register components, providers, plugins, directives, props, onStart callbacks and events defined in core.mjs

AutoQueryGrid

More documentation about the new <AutoQueryGrid> component will be available next release, it basically has all the features of Blazor's AutoQueryGrid component where you'll able to apply the same customizations as Vue's DataGrid component inside the component.

In the meantime the best place to learn about it is from its implementation in AutoQueryGrid.vue which supports the following properties:

const props = withDefaults(defineProps<{
    filterDefinitions?: AutoQueryConvention[]
    id?: string
    apis?: string|string[]
    type?: string|InstanceType<any>|Function
    prefs?: ApiPrefs
    deny?: string|GridAllowOptions|GridAllowOptions[]
    hide?: string|GridShowOptions|GridShowOptions[]    
    selectedColumns?:string[]|string
    toolbarButtonClass?: string
    tableStyle?: TableStyleOptions
    gridClass?: string
    grid2Class?: string
    grid3Class?: string
    grid4Class?: string
    tableClass?: string
    theadClass?: string
    tbodyClass?: string
    theadRowClass?: string
    theadCellClass?: string
    apiPrefs?: ApiPrefs
    canFilter?:(column:string) => boolean
    disableKeyBindings?:(column:string) => boolean
    configureField?: (field:InputProp) => void
    skip?: number
    create?: boolean
    edit?: string|number
}>(), {
    id: 'AutoQueryGrid',
    skip: 0
})

Emits the events:

const emit = defineEmits<{
    (e: "headerSelected", name:string, ev:Event): void
    (e: "rowSelected", item:any, ev:Event): void
}>()

and lets you inject custom components using available slots:

Inject custom content above form fields of Auto Create & Edit components
<template #formheader="{ form, apis, type }" />

Inject custom content below form fields of Auto Create & Edit components
<template #formfooter="{ form, apis, type }" />

Use a Custom New Form for creating new records
<template #createform="{ form, apis, type }" />

Use a Custom Edit Form for editing existing records
<template #editform="{ form, apis, type }" />

Use a custom toolbar
<template #toolbar />

Add additional toolbar buttons
<template #toolbarbuttons />

Other slots are passed down to its DataGrid component which lets you customize how each column and header is rendered.

Feel free to ask any questions about how to use or create custom Vue 3 components here.

Displaying Referential Data

AutoQuery is able to infer relationships from the POCO References of your Data Models where if your DataModel includes [Reference] data so that it's returned in your AutoQuery APIs, AutoQueryGrid uses it to render the Contacts Name and Icon instead of just the plain ContactId.

This is visible in the JobApplications page where it renders the Job and Contact name instead of their ids, based on this DataModel DTO:

[Icon(Svg = Icons.Application)]
public class JobApplication : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }

    [References(typeof(Job))]
    public int JobId { get; set; }

    [References(typeof(Contact))]
    public int ContactId { get; set; }

    [Reference]
    [Format(FormatMethods.Hidden)]
    public Job Position { get; set; }

    [Reference]
    [Format(FormatMethods.Hidden)]
    public Contact Applicant { get; set; }

    [Reference]
    public List<JobApplicationComment> Comments { get; set; }

    public DateTime AppliedDate { get; set; }

    public JobApplicationStatus ApplicationStatus { get; set; }
    //...
}

The original ids that are replaced can be seen by hovering over the Job & Contact labels.

As we're already showing the Contact & Job Info we can tell AutoQueryGrid to hide the complex data references columns using [Format(FormatMethods.Hidden)].

If not specified, AutoQuery will use the first string column for its label which can be customized with the [Ref] attribute or if you don't want the FK Ids replaced you can use [Ref(None=true}] to disable any inference.

Please let me know any feedback or questions you have about the new Locode UI in this thread.