Structure & settings

The structure is the view itself: pages, elements, data sources, settings. These methods read it, swap it for another one, or change parts of it while the view stays on screen. The JSON format is described in Structure JSON.

Method	Returns	In short
getStructure()	IStructure | null	The view as plain JSON, ready to save
getStructureModel()	IStructure | null	The live models the view renders from
setStructure(structure)	void	Replace the whole view
updateStructure(updater)	boolean	Change the view in a callback
notifyStructureChanged()	void	Fire onStructureChanged yourself
getSettings()	ISettings | null	All view-wide settings
getSetting(key)	unknown	One setting, nested paths allowed
setSetting(key, value)	boolean	Change one setting
patchSettings(patch)	boolean	Change several settings
updateSettings(updater)	boolean	Change settings in a callback
replaceSettings(settings)	boolean	Swap the settings object
captureStructureSource() / clearCapturedStructureSource()	void	Low level: the copy a runtime renders from

Every change made here shows on screen straight away, lands in getStructure() and fires onStructureChanged. In the builder it also becomes an undo step.

Reading

getStructure()

getStructure(): IStructure | null

The view as plain JSON. This is what you save: no class instances, no runtime state, nothing that does not survive JSON.stringify. Properties you changed through the API are included.

const structure = api.getStructure();
await http.put(`/api/views/${id}`, structure);

Returns:

{
  "schemaVersion": 1,
  "settings": { "language": "en", "showSubmitButton": true },
  "pages": [{ "name": "page1", "rows": [{ "columns": [{ "elementRef": "firstName" }] }] }],
  "elements": {
    "page1": { "name": "page1", "type": "page", "label": "Page 1" },
    "firstName": { "name": "firstName", "type": "text", "label": "First name", "required": true }
  },
  "dataSources": []
}

null while no view exists. In the builder, the template library is not part of it: an exported structure carries only the templates its elements use (see templates).

getStructureModel()

getStructureModel(): IStructure | null

The live models instead of JSON: every element is an instance of its model class (TextInputModel, SelectInputModel and so on) with the state the view is rendering right now, such as values and hidden flags set by logic. Use it to inspect, not to save.

const model = api.getStructureModel();
model?.elements['firstName'].hidden; // false

To change an element, prefer setElementProperty: writing to a live model directly does not refresh the screen.

Replacing and changing the view

setStructure()

setStructure(structure: IStructure): void

Replaces the whole view. The structure is migrated to the current schema first, its runtime variables are applied and the view renders again. In a runtime, render listeners get onBeforeRender, onRender and onAfterRender like for a new [pageJson].

const next = await firstValueFrom(http.get<IStructure>(`/api/views/${id}`));
api.setStructure(next);

Form data is kept: values whose element still exists show up in the new view. In the builder the current template library is kept as well when the incoming structure does not define those templates.

updateStructure()

updateStructure(updater: (structure: IStructure) => void): boolean

Hands you the structure as JSON; change it in place and the view is updated. Returns false when there is no view.

api.updateStructure((s) => {
  s.elements['email'].label = 'Work e-mail';
  s.elements['email'].required = true;
  s.pages[0].rows.push({ columns: [{ elementRef: 'notes' }] });
  s.elements['notes'] = { name: 'notes', type: 'textarea', label: 'Notes' };
});
// true

Use it for changes to the layout (pages, rows, new elements). For one property of one element, setElementProperty is lighter: it does not rebuild anything.

notifyStructureChanged()

notifyStructureChanged(): void

Fires onStructureChanged (and the (structureChanged) output) on the next tick with the current structure, even when nothing changed. The methods on this page do it for you; call it after you changed a live model by hand.

Settings

Settings are the view-wide options from the builder's Form settings dialog: language, submit and validate buttons, navigation, render mode, custom CSS, variables. Keys accept dot paths.

getSettings()

getSettings(): ISettings | null

api.getSettings();
// { language: 'en', locale: 'lt-LT', showSubmitButton: true, renderMode: 'page', variables: [...] }

getSetting()

getSetting(key: string): unknown

api.getSetting('language');      // 'en'
api.getSetting('header.title');  // 'Client onboarding'
api.getSetting('missing.key');   // undefined

setSetting()

setSetting(key: string, value: unknown): boolean

Changes one setting and updates the view. Returns true (also when the value was already equal), false without a view.

api.setSetting('showSubmitButton', false);    // the Submit button disappears
api.setSetting('header.title', 'New client');

patchSettings()

patchSettings(patch: Record<string, unknown>): boolean

Several settings in one go; keys may be dot paths.

api.patchSettings({
  showValidateButton: true,
  'header.title': 'New client',
  pageNavigationMode: 'stepper',
});

updateSettings()

updateSettings(updater: (settings: ISettings) => void): boolean

api.updateSettings((settings) => {
  settings.locale = 'de-DE';
  settings.customCss = '.invoice-total { font-weight: 700; }';
});

replaceSettings()

replaceSettings(settings: ISettings | null | undefined): boolean

Swaps the whole settings object. Anything you leave out is gone, so start from getSettings():

api.replaceSettings({ ...api.getSettings(), renderMode: 'dialog', dialogTitle: 'Order {orderNo}' });

Low level

captureStructureSource() / clearCapturedStructureSource()

captureStructureSource(structure: IStructure | null | undefined): void
clearCapturedStructureSource(): void

A runtime keeps a plain copy of the structure it rendered; getStructure() returns it and the methods above write into it. <ngx-view-builder-runtime> and setStructure() capture it for you, so hosts rarely touch these. Clearing makes getStructure() serialize the live models instead.