Composite components

Introduction

A composite component allows you to enclose a piece of the application's screen into a coherent, reusable element. The component defines both the appearance of the screen area and its behavior.

Teams that use composite components to build user interfaces save time and make it easier to maintain frontend consistency.

Role and applications

The main role of composite components is multiple reuse of repetitive form areas on different pages. Once created, a composite component can be embedded:

• on various form pages – so multiple pages can use a common, consistent part

• multiple times on the same page – e.g., if one form needs two independent address sections (for registered and mailing addresses).

This approach significantly speeds up application development and simplifies maintenance – a change in the composite component definition automatically affects all places where it is used.

This increases the application's consistency (the same components look and behave identically across different forms) and reduces the risk of errors resulting from duplicated configuration. For example, if a form requires a repeating section with the same fields (like the mentioned address section), it's worth extracting it as a composite component and using it multiple times instead of recreating those fields from scratch each time.

Composite components are frequently used in business applications as standard form sections (e.g., address data, contact details, customer information sections, etc.), which ensures a uniform user experience and facilitates the development of additional forms.

Illustration 1. "Composite components" in the "Library" module

Creating a component

To create a new composite component or edit an existing one, you should:

1. In Eximee Designer go to the Library module and select the Composite components

   1. tab; this view displays a list of all available composite components in the repository along with management options,

2. From the list you can:

   1. create a new component (button Add composite component),

   2. copy or edit an existing artifact using the dropdown menu (three dots)

   3. review the component's version history using the dropdown menu (three dots)

3. Select the option to add a new composite component

   1. a creation window appears in which we provide the component's name and location (folder) in the project tree, analogous to creating a new form.

Illustration 2. "Window with the list of composite components in the library"

After creating the composite component artifact, the composite component editoropens, very similar to the form editor. In the central part of the view we design the layout and add the required fields and controls – you can drag base components onto the workspace (e.g., text fields, lists, buttons, etc.) or even nest other available composite components. In this way we define the internal structure of the new composite component. On the right side there is a properties panel where we configure attributes of the selected fields (just like in a form).

After configuring the composite component's content, we save it, assigning an appropriate version (more on versioning below). Saving creates a new artifact version that can be used in forms.

Illustration 3. "Composite component editor window – designing content"

Input parameters

Composite components can accept input parameters, which allows passing values into them from the outside – from the form or even from another composite component.

To define an input parameter, in the composite component definition editor select the option in the left panel Input parameters, and then click Add input parameter. Each input parameter refers to some field or session variable from the embedding context of the component (meaning it will expect assignment of a specific field/variable when the component is used). When defining a parameter:

• we indicate the value source (form field or variable),

• optionally assign an alias (a friendly name shown during mapping)

• optionally provide a default value – used if no value is assigned during embedding.

It is possible to map values from parent form fields, fields from other composite components on the same form, as well as session variables available in the form context.

Thanks to the input parameter mechanism, a composite component can be more universal – e.g., instead of referencing a specific global variable internally, it can accept the value as a parameter, allowing it to be used in different places with different data.

Illustration 4. "Input parameter configuration panel in the composite component editor"

Embedding the component

A created composite component can be embedded in any form or even inside another composite component (nesting) – the platform allows arbitrary levels of nesting.

To use a composite component in a form, go to edit that form, then from the components palette on the left select the Compositetab. A list of all available composite components in the repository will appear (with the ability to search by name). From this list choose the appropriate component and add it to the form by drag-and-drop into the desired place in the form structure.

After dropping, the composite component will be embedded in the form as a single logical unit – in the form structure tree it will appear as a single node containing the previously defined fields.

If the embedded composite component has defined input parameters, after adding it to the form you must configure the mapping of those parameters, assigning them appropriate fields or values in the context of the form or the parent component.

In the form editor this is done in the Input parameters section of the embedded component's properties – just select the composite component on the form and click the pencil icon next to the field Input parametersto open the mapping window.

Illustration 5. "Input parameter mapping window when embedding a composite component in a form"

A composite component placed on the screen becomes an integral part of it. All fields contained within inherit the behavior of standard fields – e.g., required fields must be filled in, validators attached to fields inside the composite component operate the same as for fields added directly to the form, etc.

If necessary, you can also define additional form validators at the form level that also include fields inside composite components (e.g., a script checking data consistency between sections).

Similarly, navigation mechanisms or conditional visibility work for nested components as well – a composite component can be hidden or shown depending on a condition, analogous to a single field.

Versioning and propagation of changes

Versioning is described in detail here.

Interactions with other artifacts

A composite component does not operate in isolation – it interacts with various elements of the platform

Forms

The primary “relationship” is embedding in a form, as discussed above. From the form's perspective, a composite component is simply a form element – during application runtime the end user does not see a difference between fields coming from a composite component and other fields. In the Translations tab of the form all texts contained in embedded composite components are available for editing – this means that translations of labels and hints from the composite component can be overridden or adjusted at the level of a specific form if needed. The composite component is also treated as a constituent part of the application.

Validators

Fields within a composite component can use all validation mechanisms available to ordinary fields. If a script validatoris assigned to one of the fields inside the composite component, it will be executed the same way as for a standard field on the form. Also visibility conditions or requiredness conditions can be defined for fields inside the composite component – they will be respected after embedding the component in the form. Moreover, validators defined at the whole-form level (e.g., verifying dependencies between various fields) can refer to fields located in composite components. Such a field can be identified by its business identifier (mid) – composite components and their fields have business identifiers just like ordinary form fields, which facilitates referencing them in scripts and configurations.

Formatted content

You can also use content artifacts (TextContent) in composite components, analogous to regular forms. If a section requires embedding a larger block of static text (e.g., terms, clauses, descriptions), you can add a Formatted content control in the composite component and attach a Content artifact containing the appropriate content (managed centrally). This allows the composite component to include not only data fields but also informational elements or user instructions, making it a complete, reusable fragment of the user interface.

Services and variables

If session variables are used inside a composite component (e.g., to store transient values or service results), remember to prefix the names of those variables with the symbol in conditional expressions @. So the platform will distinguish the component's session variable from the parent form's session variable.

Additionally, session variables cannot be directly used in components of type Repeatable section inside a composite component – in such cases it is recommended to use technical fields as carriers of values.

If a composite component needs to use an external service (e.g., to populate its fields based on database data), it can call services just like a form. A service can be attached as a PageService in the component logic and, for example, invoked in response to an event (e.g., a field change). However, remember that services operate in the context of the entire request, so invoking a service from within a component affects the parent form.

Best practices

Identifying reuse opportunities

Already at the requirements analysis stage, identify form sections that may appear repeatedly or in many different application forms. Such sections (e.g., address data, client's personal data, contact information sections, consent sections, etc.) should be designed as separate composite components, rather than duplicating the same fields in many places. This facilitates development (the section is created once) and maintenance (modifying the section in one place updates it everywhere it is used).

Naming and organization

Use consistent naming for artifacts. A composite component should have a name clearly indicating its content or purpose. It is common to prefix component names with an application- or business-module-related prefix, e.g. crmClientAddress, insVehicleData – this makes it easier in the repository to identify which area a component belongs to. Also maintain order in the Library's folder structure – group composite components into thematic or project folders.

Documenting the component

Each composite component can be provided with internal documentation. In the Properties Documentation

Illustration 6. section of the composite component editor you can describe the component's operation and purpose (it supports HTML formatting). It is recommended to complete the component documentation – especially if it will be used by many developers or in many places – so platform users know how to apply it correctly and what its possible dependencies are. Good documentation facilitates reusing the component and speeds up onboarding of new team members.

"Properties" tab of the composite component – documentation preview

Versioning and backward compatibility When planning changes to a composite component, consider their impact on existing forms. Avoid introducing incompatible changes

without bumping the major version (MAJOR). If a structural or behavioral change to the component could disrupt forms using it, it's better to create a new version branch. After modifications, test the composite component in all critical scenarios – especially when the component is used in many places.

Avoiding excessive complexity

Although composite components can contain any logic, try to have them implement a reasonably uniform, clearly defined function. Avoid creating one huge composite component that handles many unrelated tasks – it's better to split it into smaller, more specialized sections. Excessive nesting of composite components (component in a component in a component, etc.) can also make debugging and understanding the form harder – use this capability judiciously, guided by the readability of the form structure.

Be careful when copying components The platform allows duplication of a composite component (the Duplicate option on the composite components list) – this is useful when you want to create a similar component based on an existing one. However, make sure how nested components are treated during copying. If the copied composite component contained other composite components, in the copy their duplicates will not be created

– references to the original artifacts will be preserved. Consider whether in the new component you still want to use those original shared subcomponents, or whether you should also copy them (e.g., when changes to them should not affect your new component). This is important for maintenance – unknowingly editing a nested component can affect other places where it is used.

Using existing components

Check whether the composite component you need already exists in the library – especially in larger organizations a catalog of shared components may exist. Using already prepared, tested components (e.g., user authorization components, document download components, GDPR consent sections, etc.) is faster and safer than creating your own from scratch. Build new composite components only when the required functionality is not available in existing resources.

UX consistency Remember that a composite component is part of the user interface – design it according to the UX/UI standards in your organization. Ensure that the layout of fields, their labels, hints, as well as validations and error messages within the component are consistent with the rest of the form. This way the user will not feel that a section has been “glued on” from another place. Use the translations

mechanism for static texts in the component, fill in their keys and values – this will make managing literals from the application level easier.

Example The illustrations below show an example of a composite component named demoAddress

Illustration 7. and how it is used. First, a composite component containing address fields (street, city, postal code) was designed – it serves as a pattern for an address section:

Designed composite component "demoAddress" (address section) The illustrations below show an example of a composite component named Then the same component

Illustration 8. was embedded three times in a sample form (e.g., for registered address, mailing address, and workplace address) – by reusing a single artifact we obtain three sections in the form without the need to create three separate sets of fields:

Multiple uses of the composite component "demoAddress" in the form structure (embedded three times)

Illustration 9. As a result, the form's user interface displays three uniform address sections using the same composite component:

Form appearance with the composite component "demoAddress" embedded multiple times (three address sections) The illustrations below show an example of a composite component named The above example illustrates how composite components simplify creating repetitive parts of an application – modifying the component (e.g., adding a "Country" field) will automatically introduce that field in all three address sections on the form. This makes managing extensive forms easier and ensures common parts of the application remain consistent everywhere they are used.

Using the above tips and best practices, Eximee composite components enable effective creation of modular, maintainable business applications where once-defined sections can be used in many processes and forms. Well-designed composite components pay off by reducing duplicated work, unifying the interface, and enabling faster deployment of changes in the future.