useCwaResourceModel

useCwaResourceModel binds an admin form input to one field of the selected resource. Every change is saved to the API with a debounced PATCH. Use it in admin tab components (app/app/cwa/components/*/admin/*.vue), not in display components.

import { useCwaResourceManagerTab, useCwaResourceModel } from '#imports'

const { exposeMeta, iri } = useCwaResourceManagerTab({ name: 'Content' })
const titleModel = useCwaResourceModel<string>(iri, 'title')

defineExpose(exposeMeta)

<template>
  <CwaUiFormLabelWrapper label="Title">
    <CwaUiFormInput :model="titleModel" />
  </CwaUiFormLabelWrapper>
</template>

Pass the whole return as :model, so the control can show which other admin has the field in focus and a co-editing conflict; see Field Presence and Co-Editing Conflicts.

Signature

useCwaResourceModel<T>(
  iri: Ref<string | undefined>,  // from useCwaResourceManagerTab
  property: string | string[],   // the PHP entity property name (or dot-notation path)
  options?: {
    debounceTime?: number        // default: 250ms
    longWaitThreshold?: number   // ms before isBusy is considered a "long wait"; default: 5000ms
  }
)

Parameters

Return Values

const { model, states, resetValue, remoteChange, focusedBy, focusListeners } = useCwaResourceModel<string>(iri, 'title')

model.value   // the current field value (string | null | undefined)

Pass the whole return to a kit control as :model:

<CwaUiFormInput :model="titleModel" />

<CwaUiFormInput>, <CwaUiFormToggle> and <CwaUiSelect> take :model. For any other control, bind model.value with v-model, and add field presence and remoteChange yourself, as in Your Own Field Editor. Setting model.value triggers a debounced PATCH. Multiple rapid changes are batched into one request.

Use states to render save feedback — for example a subtle spinner while isBusy, escalating to a "still saving…" message once isLongWait flips:

<CwaUiFormInput :model="titleModel" />
<span v-if="titleModel.states.isLongWait.value">Still saving…</span>

Multiple Fields

Call useCwaResourceModel once per field:

const { exposeMeta, iri } = useCwaResourceManagerTab({ name: 'Link' })
const labelModel = useCwaResourceModel<string>(iri, 'label')
const routeModel = useCwaResourceModel<string>(iri, 'route', { debounceTime: 0 })
const rawPathModel = useCwaResourceModel<string | null>(iri, 'rawPath')

Relation Fields

Set a relation by assigning an IRI string:

const categoryModel = useCwaResourceModel<string | null>(iri, 'category')
// Assign:
categoryModel.model.value = '/component/categories/uuid'
// Clear:
categoryModel.model.value = null

Setting debounceTime: 0

For fields where immediate save is preferred (e.g. a route field where you need instant validation feedback), pass debounceTime: 0.

Field Presence

While an admin has a field in focus, the other admins see it outlined in that admin's colour, with their name in a flag above it. The flag fades after 3 seconds and shows again on hover. focusedBy lists them, one entry per admin:

A field counts as one field by its top-level property: 'address.city' and 'address.street' are both address. A draft and its live version count as one resource. An idle admin (tab hidden, or no input for 5 minutes) isn't listed.

<CwaUiFormInput>, <CwaUiFormToggle> and <CwaUiSelect> given :model show the outline and report your own focus. A disabled <CwaUiFormInput> or <CwaUiFormToggle> doesn't report focus.

Your Own Field Editor

A control that isn't a kit control, such as a rich-text editor, needs three things to co-edit like the kit fields:

1. Show who's in the field. Wrap it in <CwaUiFieldPresence :model> and bind the model's focusListeners on the wrapper. Focus is also taken on a pointer press, for buttons and switches that Safari doesn't focus on click, and kept while you use the editor's own menus.
2. Show a conflict. Put <CwaUiRemoteChangeConflict v-if="remoteChange" :change="remoteChange" /> beside it. It shows the same Use theirs / Keep mine line as the kit fields.
3. Apply another admin's save without moving your caret. When model.value changes under you, replace only the part that differs, and leave the change out of undo history. The template's tiptap/co-editing.ts does this for TipTap with applyRemoteContent.

<template>
  <CwaUiFieldPresence :model="model" v-bind="model.focusListeners">    <MyEditor v-model="model.model.value" />
    <CwaUiRemoteChangeConflict v-if="model.remoteChange.value" :change="model.remoteChange.value" />  </CwaUiFieldPresence></template>

<script setup lang="ts">
import type { useCwaResourceModel } from '#imports'

defineProps<{
  model: ReturnType<typeof useCwaResourceModel<string>>
}>()
</script>

To show other admins' carets as well, send them with useCwaRealtime. Rich-Text Editor › Editing Together covers a complete editor.

Co-Editing Conflicts

When another admin saves this field while you have a change to it that isn't saved yet, the module keeps your value on screen and holds your save. remoteChange is then set, until you choose:

The same choice appears when a save of yours crosses theirs on the way to the API. Each admin save sends the version of the resource it was based on (If-Match), and the API refuses a save based on an older version with a 412 (see API › Versions & Conflicts › Saving with If-Match). The module then shows their value with Use theirs / Keep mine. If their save created a draft, the choice moves to that draft. Saves to one resource from one tab go one at a time, so a tab never trips over its own saves.

A kit control given :model shows Name changed this · Use theirs / Keep mine beside itself. With any other control, show the choice yourself, with <CwaUiRemoteChangeConflict> or your own markup:

<template>
  <MyColourPicker v-model="colourModel.model.value" />
  <p v-if="colourModel.remoteChange.value">    {{ colourModel.remoteChange.value.name }} changed this to {{ colourModel.remoteChange.value.value }}.     <button @click="colourModel.remoteChange.value.accept()">Use theirs</button>    <button @click="colourModel.remoteChange.value.keep()">Keep mine</button>  </p></template>

How co-editing works for the admin is in Real-Time Updates › Co-Editing in the Admin. To react to every change to a resource, use onRemoteChange.