Form

The form is not a layout exported as useXLayout(...), but it plays the same role as the root shape.

The relevant API is createForm(...).

Signature

ts

import { createForm } from "@duplojs/form/vue";

const useForm = createForm(templates);

Then:

ts

const {
	component,
	check,
	currentValue,
	reset,
	dispose,
} = useForm(rootField, params);

Parameters of createForm(...)

• templates: a Templates object containing the rendering templates to use.

Parameters of useForm(...)

ts

useForm(formField, {
	class?: string,
	template?: Templates["form"],
});

• formField: the root FormField to instantiate.
• class: CSS class added to the form template.
• template: local override of the form template.

Returned value

useForm(...) returns:

• component: the Vue component to render.
• check(): full form validation.
• currentValue: Ref holding the raw current value.
• reset(): reset from the defaultValue values.
• dispose(): destroy the internal effects of the instance.

form template contract

The form template receives:

Props

ts

{
	fieldKey: string;
	getCurrentValue(): unknown;
}

Emits

ts

{
	submit: [];
}

Slots

ts

{
	formField(): any;
	submitter(): any;
}

Small template example

vue

<script setup lang="ts">
import { type FormTemplateProperties } from "@duplojs/form/vue";

defineProps<FormTemplateProperties["props"]>();
defineSlots<FormTemplateProperties["slots"]>();
defineEmits<FormTemplateProperties["emits"]>();
</script>

<template>
	<form>
		<slot name="formField" />

		<slot name="submitter" />
	</form>
</template>

ts

import { createTemplate } from "@duplojs/form/vue";
import MyFormTemplate from "./formTemplate.vue";

export const useMyFormTemplate = createTemplate(
	"form",
	MyFormTemplate,
);

Minimal example

ts

import { useTextInput } from "@duplojs/form/vueDesignSystem";
import { useForm } from "./init";

export function useNewsletterForm() {
	const { component, check, currentValue, reset, dispose } = useForm(
		useTextInput({
			label: "Email",
			defaultValue: "",
		}),
	);

	return {
		NewsletterForm: component,
		checkNewsletterForm: check,
		currentNewsletterValue: currentValue,
		resetNewsletterForm: reset,
		disposeNewsletterForm: dispose,
	};
}

What to remember

• the form instantiates a root FormField;
• it delegates all rendering to the form template;
• it exposes the highest lifecycle API: check, currentValue, reset, dispose.