Form rendering

WARNING

This documentation describes asperationally how aeppic 4.x renders forms.

In the preceding version 3.x this implementation of ae-form is only enabled as an opt-in feature for forms that opt-into rendering with this method. It is still experimental and the internals might change until release

TIP

Opt-In

The new rendering behavior as documented below is activated with [feature flag](/reference/aeppic/Modules/features.md) named 'aeppic.forms.rendering.experimental'

Forms also need to contain the tag experimental-rendering.

Components

Displaying a form in the UI is done via the ae-form component.

<ae-form :document="locals.documentToDisplay" ...></ae-form>

There a a number of parameters that can be passed into ae-form these are more fully documented in [ae-form](/reference/aeppic/forms/ae-form.md)

When called to display a document ae-form looks up any information related to the form of the document passed in.

When a form definition gets parsed it outputs the following hierarchy:

Form / Root Section / Header + Paragraph + Sub Sections

Conceptual DOM tree

flowchart LR__NEWLINE__ subgraph ae-form__NEWLINE__ ae-form-section__NEWLINE__ end__NEWLINE__ subgraph ae-form-section__NEWLINE__ ae-header__NEWLINE__ ae-form-paragraph__NEWLINE__ ae-form-section_SubSection__NEWLINE__ end__NEWLINE__ subgraph ae-form-paragraph["ae-form-paragraph"]__NEWLINE__ text__NEWLINE__ field__NEWLINE__ control__NEWLINE__ end__NEWLINE__ subgraph ae-form-section_SubSection["ae-form-section"]__NEWLINE__ end

Full Component Tree

The full tree is a little more complex as the actual html is user configurable on multiple levels.

• The components ae-form, ae-form-section, and ae-field use a configurable layout and can be changed via a Theme.
• ae-control is a dynamic component itself. When used standalone and as used by ae-field.
• ae-form-parapgraph is a helper component to be used inside of section layouts to render the paragraphs. It provides slots for customization.
• ae-header is a simple component which is also used by section layouts to help with rendering a sections title header.

flowchart TB__NEWLINE__ subgraph ae-form__NEWLINE__ ae-layout_Form__NEWLINE__ end__NEWLINE__ subgraph ae-layout_Form["ae-layout"]__NEWLINE__ ae-form-section__NEWLINE__ end__NEWLINE__ subgraph ae-form-section__NEWLINE__ ae-layout_Section__NEWLINE__ end__NEWLINE__ subgraph ae-layout_Section["ae-layout"]__NEWLINE__ ae-header__NEWLINE__ ae-form-paragraph__NEWLINE__ ae-form-section_SubSection__NEWLINE__ end__NEWLINE__ subgraph ae-form-section_SubSection["ae-form-section"]__NEWLINE__ end

flowchart TB__NEWLINE__ subgraph ae-form-paragraph __NEWLINE__ html__NEWLINE__ ae-field__NEWLINE__ ae-control_Standalone__NEWLINE__ end__NEWLINE__ subgraph ae-field__NEWLINE__ ae-layout_Field __NEWLINE__ end__NEWLINE__ subgraph ae-layout_Field["ae-layout"]__NEWLINE__ ae-control__NEWLINE__ end__NEWLINE__ subgraph ae-control_Standalone["ae-control (Standalone)"]__NEWLINE__ end

Standalone controls not associated with a field in the document would be on the level of the ae-field and not wrapped.

The layout components are defined at runtime as aeppic documents and thus extremely flexible. A form layout could thus forgoe all rendering as outlined above and just display <h1>Hello World</h1> and be done. This wouldn't render any fields, but allowed.

Responsibilites

Each component has a specific responsibility

Component
ae-form	Lookup up form information, including which layout to use and render with those parameters starting at the root section
ae-layout (inside the form)	Use the form information to setup the main style scope (CSS) and render the chosen root section (pass along any required parameters)
ae-form-section	Lookup the parts of the section (fields,sub-sections) and pass it to the section layout
ae-layout (inside the section)	Layout the parts according their type, order, and designated styles
ae-field	Lookup the layout for the field and control component to render the field with and render it.
ae-layout (inside the field)	Layout the field surroundings (label,help,validation,etc) if the control cannot do it then position the control
ae-control	Render the actual user interactive html to let the user change a field in the editable docuemnt (unless it's set as readonly)

ae-form

1. Look up the document's form information Aeppic.Forms.getRenderInfoForDocument
2. Lookup the form's theme to be used.
3. Ensure the editable document is registed in an existing outer edit context
4. Figure out which section to render. Each form consists of a tree of sections, thus the root section is normally the one being rendered, but this could have been overriden.
5. Instantiate the layout based on that information and render the section <ae-layout :layout-id="..." :params="..."></ae-layout>

ae-layout (inside the form)

A layout is dynamic content, thus this description only shows what a form layout needs to do for normal rendering to occur.

There is often no need to override the form layout as it makes more sense to override the section styles and/or respective layouts.

1. Render the root section to fill the entire area

<ae-form-section :section="params.section"
            :param-sections-params="params.sectionParams"
            :class="params.sectionClass"
            :style="params.sectionStyle"
            >
</ae-form-section>

ae-form-section

1. Lookup the parts in the form making up the section
2. Lookup the layout to use for the section
3. Render the layout and pass in the inherited parameters and the parts/styles discovered

<ae-layout :layout-id="layoutId"
           :params="layoutParams"
           :class="layoutClass"
           :style="layoutStyle"
           >
</ae-layout>

ae-layout (inside the section)

1. Define the layout of the different parts to be rendered in the section

Example:

ae-form-paragraph

Each part making up the section requires some basic layouting logic. This is embedded with a default rendering rule. Each rule is overridable using slots from the section layout.

Part Types

Name	Description
HTML	Pure HTML/Markdown
SECTIONS	A list of sibling sections
FIELD	A single field
LINE_OF_FIELDS	A horizontal list of fields
FIELDS_WITH_TEXT	A block of markdown with embedded fields with
STANDALONE_CONTROL	A standalone control
LINE_OF_CONTROLS	A horizontal list of standalone controls
STANDALONE_CONTROLS_WITH_TEXT	A horizontal list of standalone controls with text/html around or between them

ae-field

A field is responsible for allowing read/write access to a documents field.

A field currently has access to the entire document, but this will become an opt-in behavior in an upcoming release

ae-layout (inside the section)

1. Define the layout of the different parts to be rendered in the section

ae-control