Skip to content

API at a glance

The parts of Borm an application touches, on one page: the services it registers, the components it renders, every parameter of BormView, the members of BormState and the types between them. Each row links to the page that shows it working. Every public type is prefixed Borm and lives in the one Bit.Borm namespace.

Services

RegistrationWhat it adds
AddBorm(registry => …)The field renderer registry - required, in every container that renders a form. The callback registers custom renderers; calling it again configures the same registry.
AddBormTranslations()The library's own words in twelve languages besides English - see translating a form.
AddBormMessages<T>()An IBormMessageProvider of your own for the library's words.
AddBormSchemaLocalizer<T>()An IBormSchemaLocalizer for the schema's labels, help and options.
Bit.Borm.FluentValidationA separate package: state.UseFluentValidation() - see FluentValidation.

Components

ComponentRenders
BormViewA whole form: its fields, steps, error summary and buttons. Parameters below.
BormFieldOne field of a state, inside a layout of the page's own - State, Name, ThrowIfMissing. See custom layout.
BormErrorSummary, BormValidationMessagesThe error summary and a message list, for a layout of your own.
BormStepsView, BormReviewSteps as tabs, an accordion or sections; and a read-back of every answer. See tabs & review.
BormAutosave, BormUnsavedChangesGuardA draft saved as the user goes, and a prompt before unsaved changes are left. See drafts.
BormDesignerA form designer bound to a BormDefinition. See the designer.
BormInputBaseThe base class of every control, and of yours. See custom renderer.

BormView parameters

ParameterDescription
DefinitionThe schema to render. Required unless State is given.
ModelA typed model to bind to.
DataA dictionary to bind to when there is no model, edited in place at every level - so don't share one between forms. Keys match without regard to case; JSON-deserialized values are converted as they are reached. See every field type.
StateA BormState the page built - with a validator, an event handler, or read from code. The page disposes it.
ConfigureStateRuns against the state the view builds from Definition - set a trigger, wire a validator - without taking it over. See from a C# type.
OnValidSubmit, OnInvalidSubmitRaised after a submit that passed, or failed, validation.
OnSubmitErrorRaised with the exception when OnValidSubmit throws, which is then handled rather than escaping into the renderer. See saving.
OnFieldChangedRaised with the path of a field whose value changed.
ReadOnly, DisabledEvery field read-only (still focusable - a review), or disabled (inoperable - a save in flight). See validation modes and the repeater.
ShowSubmitButton, SubmitText, SubmittingTextThe submit button, its label, and what it says while the form validates or saves.
ShowResetButton, ResetTextA button that puts back the values the form started with.
ShowUndoUndo and Redo buttons, and the history they need. See undo & long lists.
ShowErrorSummaryEvery error above the form, each linking to its field - or its step.
FocusFirstErrorMoves focus to the first invalid field after a failed submit (on by default; the summary takes it when shown).
AllowStepNavigation, BackText, NextText, StepperLabelA wizard's clickable stepper, its button labels and the stepper's accessible name. See the wizard.
Header, Footer, ChildContentContent above the fields, below everything, and inside the form.
ActionsReplaces the button row - handed the state. See saving.
TitleLevelThe heading level of the form's title (default 2), so it fits the page's outline.
Class, any other attributeExtra classes, and anything else - a style, a data-theme - put on the <form>. See theming.
IdPrefixWhat every DOM id starts with (default borm_) - one each for two forms on a page.
ProvideEditContextCascades a Blazor EditContext mirroring the form. See Blazor's own inputs.
FormName, PostedModelNameA form that posts with no interactivity. See forms without interactivity.

Built from a Definition, the view's state is reachable through @ref: _view.Form.

BormState at a glance

MemberPurpose
GetValue, SetValue, SetValueQuietlyRead and write by path; the quiet one does not mark the field touched.
For<TModel>()The same state by expression - SetValue(x => x.Lines[i].Quantity, 3), GetFieldState(x => x.Email).
SetValues, BatchMany writes as one change: one re-render, one undo step.
IsFormDirty, DirtyFields, TouchedFields, ResetField(path)Change tracking, by comparison with the values the form opened with; one field put back.
GetFieldState(path)Touched, dirty, invalid, validating, the first error, every message, and Status in one word.
ValidateAsync, ValidateStepAsync, ValidateFieldAsync, ValidateDependentsAsyncValidation of the form, a step, a field, or what revalidates on a field.
ValidationTrigger, RevalidationTrigger, SingleErrorPerField, RunAsyncRulesOnInvalidFieldsWhen rules run and how much is shown. See validation modes.
IsValid, HasValidated, IsValidating, IsValidatingFieldWhat validation has found - check HasValidated before treating IsValid as a verdict.
MessagesFor, AllMessages, OrderedMessages, SetServerError(s), ClearMessagesThe messages, and a server's.
SubmitAsync, SubmitOutcome, SubmitError, IsSubmitSuccessful, IsSubmitting, SubmitCountThe submit and how it ended. See saving.
CancelSubmit(), SubmitCancellationToken, ReadOnlyWhileSubmittingStopping a save in flight, and holding the fields still while it runs.
Reset(), Reset(values), AcceptChanges(), Snapshot()Back to the start, onto new values, the current ones as the baseline, and every value by path. See editing a record.
NormalizeField, NormalizeAllRun the schema's normalizers - Trim(), Normalize(...), masks.
AddArrayItem, InsertArrayItem, DuplicateArrayItem, RemoveArrayItem, MoveArrayItem, SwapArrayItems, ClearArrayItemsRepeater rows; their messages and state follow them.
OptionsFor, InvalidateOptions, OptionsError, OptionsLoadFailed, SearchOptionsAsync, TrackEntryAsyncLoaded choices, a failed load, and a search or a pending entry for a control of your own.
UploadsForFiles being uploaded with UploadWith, for a control of your own.
UndoAsync, RedoAsync, CanUndo, CanRedo, NextUndoPath, HistoryLimitHistory.
NextStepAsync, PreviousStep, GoToStep, VisibleSteps, CurrentStepNumber, FurthestStepIndex, IsStepReachableWizard navigation.
ReadOnly, Disabled, Language, IdPrefixThe whole form read-only or disabled, its language, and its ids.
FocusAsync(path), Text(key, args)Focus a field's control; the library's text for a key, in the form's language.
NotifyDefinitionChanged()The schema was changed in place: new fields get defaults, computed values run again.
StateChangedRaised after anything the page might render changes - subscribe to render markup of your own from the state.
UseDataAnnotations(), UseFluentValidation()A model's IValidatableObject, and a FluentValidation validator, beside the schema's rules.

A state the page builds is the page's to dispose: BormState is IDisposable, and disposing it cancels a lookup, an async rule, an upload or a save still in flight.

Key types

TypePurpose
BormDefinitionThe schema: fields, steps, form-level rules. Clone() to tailor a shared one, Validate() to check it, FindField(path), AllFields().
BormFieldDefinition, BormFieldTypeOne field, and its kind - see every field type.
BormBuilder, BormBuilder<TModel>, BormSchemaGeneratorBuilding a schema by name or by expression, or generating one from a type.
BormJsonSchemaImporter, BormJsonSchemaExporterJSON Schema in and out.
BormModelDataAccessor, BormDictionaryDataAccessorWhat a state reads and writes: a model, or a dictionary.
BormFieldCondition, BormConditionGroup, BormConditionOperatorA comparison, a group of them, and the operators - see conditions.
BormExpression, BormExpressionFunctionsThe expression language, and functions of your own.
BormValidationMessage, BormValidationSeverity, BormMessageKeysA message (with its Source and Code), error/warning/info, and the keys of every built-in text.
BormDraft, BormDraftOptions, BormSnapshotOptionsDrafts, and what a snapshot leaves out.
BormMask, BormMarkdown, BormSignature, BormUploadContextA mask, the safe Markdown renderer (ToHtml, ToPlainText), a signature's image, and an upload in progress - see rich fields.
BormValidator, BormEditContextAdapterValidating a form on its own, as a posted one is on the server; and an EditContext over a state rendered without a view.

Renderer hints

Attr(key, value) on a field - x-attributes in JSON Schema - passes hints to the control that draws it. The built-in controls read these:

KeyOnEffect
itemNounA repeaterThe word its buttons and announcements use: "Add line", "Remove line 2".
emptyTextA repeaterWhat it says with no rows.
duplicableA repeatertrue adds a Duplicate button to each row.
reorderableA repeaterfalse takes away the up and down buttons.
columnsA groupLays the group's own fields out in that many columns.
level, dividerA static fieldThe heading level (default 3), and a rule beneath it.
tagSeparatorsTagsThe characters that commit a tag besides Enter (default a comma).
previewMarkdowntrue opens the preview to begin with.
emptyColorA colourWhat an empty picker shows (default black).
countAnnounceAtA character countHow many characters from the limit the count starts being announced (default a tenth of the limit, at least five).
alwaysRenderA custom controltrue for a renderer that reads other fields' values, so it re-renders with them.

InputAttr(name, value) (x-inputAttributes) puts an HTML attribute on the control itself - a data-testid, a title, spellcheck="false".

Checking a schema

definition.Validate() reports the mistakes that are easy to make and hard to see - duplicate names, a repeater with no item template, steps naming fields that do not exist, conditions and expressions pointing nowhere, a comparison rule that never revalidates, computed values that feed each other in a cycle, settings a control can never honour. It is a development aid, never run for you: a schema being edited has every right to be incomplete. The JSON Schema page runs it on every document you apply.

foreach (var problem in definition.Validate())
    logger.LogWarning("{Problem}", problem);   // [Error] Lines: An array field has no ItemTemplate…
An unhandled error has occurred. Reload 🗙