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
| Registration | What 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.FluentValidation | A separate package: state.UseFluentValidation() - see FluentValidation. |
Components
| Component | Renders |
|---|---|
BormView | A whole form: its fields, steps, error summary and buttons. Parameters below. |
BormField | One field of a state, inside a layout of the page's own - State, Name, ThrowIfMissing. See custom layout. |
BormErrorSummary, BormValidationMessages | The error summary and a message list, for a layout of your own. |
BormStepsView, BormReview | Steps as tabs, an accordion or sections; and a read-back of every answer. See tabs & review. |
BormAutosave, BormUnsavedChangesGuard | A draft saved as the user goes, and a prompt before unsaved changes are left. See drafts. |
BormDesigner | A form designer bound to a BormDefinition. See the designer. |
BormInputBase | The base class of every control, and of yours. See custom renderer. |
BormView parameters
| Parameter | Description |
|---|---|
Definition | The schema to render. Required unless State is given. |
Model | A typed model to bind to. |
Data | A 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. |
State | A BormState the page built - with a validator, an event handler, or read from code. The page disposes it. |
ConfigureState | Runs against the state the view builds from Definition - set a trigger, wire a validator - without taking it over. See from a C# type. |
OnValidSubmit, OnInvalidSubmit | Raised after a submit that passed, or failed, validation. |
OnSubmitError | Raised with the exception when OnValidSubmit throws, which is then handled rather than escaping into the renderer. See saving. |
OnFieldChanged | Raised with the path of a field whose value changed. |
ReadOnly, Disabled | Every field read-only (still focusable - a review), or disabled (inoperable - a save in flight). See validation modes and the repeater. |
ShowSubmitButton, SubmitText, SubmittingText | The submit button, its label, and what it says while the form validates or saves. |
ShowResetButton, ResetText | A button that puts back the values the form started with. |
ShowUndo | Undo and Redo buttons, and the history they need. See undo & long lists. |
ShowErrorSummary | Every error above the form, each linking to its field - or its step. |
FocusFirstError | Moves focus to the first invalid field after a failed submit (on by default; the summary takes it when shown). |
AllowStepNavigation, BackText, NextText, StepperLabel | A wizard's clickable stepper, its button labels and the stepper's accessible name. See the wizard. |
Header, Footer, ChildContent | Content above the fields, below everything, and inside the form. |
Actions | Replaces the button row - handed the state. See saving. |
TitleLevel | The heading level of the form's title (default 2), so it fits the page's outline. |
Class, any other attribute | Extra classes, and anything else - a style, a data-theme - put on the <form>. See theming. |
IdPrefix | What every DOM id starts with (default borm_) - one each for two forms on a page. |
ProvideEditContext | Cascades a Blazor EditContext mirroring the form. See Blazor's own inputs. |
FormName, PostedModelName | A 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
| Member | Purpose |
|---|---|
GetValue, SetValue, SetValueQuietly | Read 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, Batch | Many 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, ValidateDependentsAsync | Validation of the form, a step, a field, or what revalidates on a field. |
ValidationTrigger, RevalidationTrigger, SingleErrorPerField, RunAsyncRulesOnInvalidFields | When rules run and how much is shown. See validation modes. |
IsValid, HasValidated, IsValidating, IsValidatingField | What validation has found - check HasValidated before treating IsValid as a verdict. |
MessagesFor, AllMessages, OrderedMessages, SetServerError(s), ClearMessages | The messages, and a server's. |
SubmitAsync, SubmitOutcome, SubmitError, IsSubmitSuccessful, IsSubmitting, SubmitCount | The submit and how it ended. See saving. |
CancelSubmit(), SubmitCancellationToken, ReadOnlyWhileSubmitting | Stopping 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, NormalizeAll | Run the schema's normalizers - Trim(), Normalize(...), masks. |
AddArrayItem, InsertArrayItem, DuplicateArrayItem, RemoveArrayItem, MoveArrayItem, SwapArrayItems, ClearArrayItems | Repeater rows; their messages and state follow them. |
OptionsFor, InvalidateOptions, OptionsError, OptionsLoadFailed, SearchOptionsAsync, TrackEntryAsync | Loaded choices, a failed load, and a search or a pending entry for a control of your own. |
UploadsFor | Files being uploaded with UploadWith, for a control of your own. |
UndoAsync, RedoAsync, CanUndo, CanRedo, NextUndoPath, HistoryLimit | History. |
NextStepAsync, PreviousStep, GoToStep, VisibleSteps, CurrentStepNumber, FurthestStepIndex, IsStepReachable | Wizard navigation. |
ReadOnly, Disabled, Language, IdPrefix | The 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. |
StateChanged | Raised 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
| Type | Purpose |
|---|---|
BormDefinition | The schema: fields, steps, form-level rules. Clone() to tailor a shared one, Validate() to check it, FindField(path), AllFields(). |
BormFieldDefinition, BormFieldType | One field, and its kind - see every field type. |
BormBuilder, BormBuilder<TModel>, BormSchemaGenerator | Building a schema by name or by expression, or generating one from a type. |
BormJsonSchemaImporter, BormJsonSchemaExporter | JSON Schema in and out. |
BormModelDataAccessor, BormDictionaryDataAccessor | What a state reads and writes: a model, or a dictionary. |
BormFieldCondition, BormConditionGroup, BormConditionOperator | A comparison, a group of them, and the operators - see conditions. |
BormExpression, BormExpressionFunctions | The expression language, and functions of your own. |
BormValidationMessage, BormValidationSeverity, BormMessageKeys | A message (with its Source and Code), error/warning/info, and the keys of every built-in text. |
BormDraft, BormDraftOptions, BormSnapshotOptions | Drafts, and what a snapshot leaves out. |
BormMask, BormMarkdown, BormSignature, BormUploadContext | A mask, the safe Markdown renderer (ToHtml, ToPlainText), a signature's image, and an upload in progress - see rich fields. |
BormValidator, BormEditContextAdapter | Validating 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:
| Key | On | Effect |
|---|---|---|
itemNoun | A repeater | The word its buttons and announcements use: "Add line", "Remove line 2". |
emptyText | A repeater | What it says with no rows. |
duplicable | A repeater | true adds a Duplicate button to each row. |
reorderable | A repeater | false takes away the up and down buttons. |
columns | A group | Lays the group's own fields out in that many columns. |
level, divider | A static field | The heading level (default 3), and a rule beneath it. |
tagSeparators | Tags | The characters that commit a tag besides Enter (default a comma). |
preview | Markdown | true opens the preview to begin with. |
emptyColor | A colour | What an empty picker shows (default black). |
countAnnounceAt | A character count | How many characters from the limit the count starts being announced (default a tenth of the limit, at least five). |
alwaysRender | A custom control | true 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…