Composite components
Introduction
A composite component allows a piece of an application screen to be enclosed in 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 different form pages – so that many pages can use a shared, consistent part
multiple times on the same page – e.g. if one form needs two independent address sections (for a registered address and a mailing address).
This approach significantly speeds up application development and makes maintenance easier – a change in the definition of a composite component automatically affects all places where it has been used.
This increases application consistency (the same components look and behave identically in different forms) and reduces the risk of errors resulting from duplicated configuration. For example, if a form needs a repeating section with the same fields (like the address section mentioned above), it is worth separating it into a composite component and using it multiple times instead of recreating those fields from scratch each time.
Composite components are often used in business applications as standard form sections (e.g. address data, contact data, customer information sections, etc.), which ensures a consistent user experience and makes it easier to develop further forms.
Creating a component
To create a new composite component or edit an existing one, you should:
In Eximee Designer go to the Library and select the tab Composite components
this view displays a list of all available composite components in the repository together with management options,
From the list you can:
create a new component (button Add composite component),
copy or edit an existing artifact using the dropdown menu (three dots)
review the component version history using the dropdown menu (three dots)
Select the option to add a new composite component
the artifact creation window appears, where you provide the component name and location (folder) in the project tree, similarly to creating a new form.
After the composite component artifact is created, the composite component editoropens, very similar to the form editor. In the central part of the view we design the layout and add the necessary 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 there is a properties panel where we configure the attributes of the selected fields (as in a form).
After configuring the content of the composite component, we save it by assigning the appropriate version (more on versioning below). Saving creates a new version of the artifact, which can be used in forms.
Parameters input
Composite components can accept input parameters, which makes it possible to pass values into them from outside – from a form or even from another composite component.
To define an input parameter, in the composite component definition editor select the option 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 (that is, it will expect a specific field/variable to be assigned when the component is used). When defining a parameter:
we indicate the source of the value (form field or variable),
optionally we assign an alias (a friendly name displayed during mapping)
optionally we provide a default value – used if no value is assigned during embedding.
It is possible to map values from fields of the parent form, fields from other composite components located on the same form, as well as session variables available in the form context.
Thanks to input parameters, a composite component can be more universal – e.g. instead of referring to a specific global variable inside, it can accept a value as a parameter, which allows it to be used in different places with different data.
Embedding a component
A created composite component can be embedded in any form or even inside another composite component (nesting) – the platform allows any nesting depth.
To use a composite component in a form, go to edit that form, then from the components palette on the left select the tab Composite. A list of all available composite components in the repository will be displayed (with search by name available). From this list, choose the appropriate component and add it to the form by drag and drop to the desired place in the form structure.
After dropping, the composite component will be embedded in the form as one logical whole – in the form structure tree it will be visible as a single node containing the previously defined fields.
A composite component placed on a screen becomes its integral part. All fields contained within it inherit the behavior of standard fields – e.g. required fields must be filled in, validators attached to fields inside the composite component work the same as for fields added directly to the form, etc.
If necessary, at the form level you can also define additional form validators covering fields inside composite components as well (e.g. a script checking consistency of data between sections).
Similarly, navigation or conditional visibility mechanisms also work on nested components – a composite component can, for example, be hidden or shown depending on a condition, similarly to a single field.
Versioning and change propagation
Versioning is described in detail here.
Interactions with other artifacts
A composite component does not function in a vacuum – it interacts with various elements of the platform
Forms
The basic "relationship" is embedding in a form, which was discussed above. From the form's perspective, a composite component is simply a form element – during application runtime the end user does not see any difference between fields originating 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 a composite component can be overridden or adjusted at the level of a specific form if needed. A composite component is also treated as part of the application.
Validators
Fields within a composite component can use all validation mechanisms available for regular fields. If we assign a script validator, it will be executed in the same way as for a standard field in the form. Also visibility conditions or requiredness conditions can be defined for fields inside a composite component – they will be respected after the component is embedded in a form. Moreover, validators defined at the level of the entire form (e.g. verifying dependencies between different 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 regular form fields, which makes it easier to refer to them in scripts and configurations.
Formatted content
Composite components can also use content artifacts (TextContent), similarly to regular forms. If a section requires embedding a larger block of static text (e.g. terms, clauses, descriptions), you can add a control of type Formatted content to the composite component and bind a Content artifact containing the appropriate content (managed centrally) to it. This way, a composite component can contain not only data fields, but also informational elements or instructions for the user, 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 temporary values or service results), remember to prefix the names of these variables with the symbol @. This allows the platform to distinguish the component's session variable from the parent form's session variable.
Moreover, session variables cannot be directly used in components of type Repeatable section inside a composite component – in such situations it is recommended to use technical fields as value carriers.
If a composite component needs to use an external service (e.g. to fill its fields based on data from a database), it can call services just like a form. A service can be attached as PageService in the component logic and, for example, called in response to an event (e.g. a field change). However, it should be remembered that services operate in the context of the entire request, so invoking a service from a component affects the parent form.
Best practices
Identifying reuse opportunities
Already at the requirements analysis stage, it is worth identifying form sections that may appear repeatedly or in many different forms in the application. Such sections (e.g. address data, customer 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 makes development easier (the section is created once) and maintenance easier (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 that clearly indicates its content or purpose. It is often common to prefix component names with a convention related to the application or business module, e.g. crmCustomerAddress, insuranceVehicleData – this makes it easier to identify in the repository which area a given component belongs to. Also maintain order in the folder structure in the Library – it is worth grouping composite components into thematic or project folders.
Documenting the component
Each composite component can be provided with internal documentation. In the Properties composite component editor there is a "Documentation" section where you can describe the component's behavior and purpose (it supports HTML formatting). It is recommended to complete the documentation for a component – especially if it will be used by many developers or in many places – so that platform users know how to apply it correctly and what its possible dependencies are. Good documentation makes the component easier to reuse and speeds up onboarding of new team members.
Versioning and backward compatibility
When planning changes to a composite component, consider their impact on existing forms. Avoid introducing incompatible changes without incrementing the major version (MAJOR). If it is necessary to change the structure or behavior of a component in a way that could disrupt the forms using it, it is 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 make them perform a fairly uniform, clearly defined function. Avoid creating one huge composite component that handles many unrelated tasks – it is better to split it into smaller, more specialized sections. Excessive nesting of composite components (component within component within component, etc.) can also make debugging and understanding the form harder – use this capability wisely, guided by the readability of the form structure.
Be careful when copying components
The platform allows duplication of a composite component (using the Duplicate option in the list of composite components) – this is useful when we want to create a similar component based on an existing one. However, make sure how nested components are handled when copying. If the copied composite component contained other composite components, their duplicates will not be created – references to the original artifacts will be preserved. You need to consider whether in the new component you still want to use those original, shared subcomponents, or whether they should also be copied (e.g. when changes to them should not affect our new component). This is important from a maintenance perspective – unintentional editing of a nested component can affect other places where it is used.
Using ready-made components
Check whether the composite component you need already exists in the library – especially in larger organizations, a catalog of shared components may be created. 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 existing resources genuinely lack the needed functionality.
UX consistency
Remember that a composite component is part of the user interface – design it in accordance with the UX/UI standards applicable in your organization. Make sure that the layout of the 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 given section has been "pasted on" from somewhere else. Use the translation mechanism for static texts in the component, fill in their keys and values – this will make it easier to manage literals from the application level.
Example
The following illustrations show an example of a composite component called demoAddress and how it is used. First, a composite component containing address fields (street, city, postal code) was designed – it serves as a template for an address section:
Then the same component demoAddress was embedded three times in an example form (e.g. for a registered address, mailing address, and workplace address) – thanks to reusing a single artifact, we obtain three sections in the form without having to create three sets of fields separately:
As a result, on the user interface the form displays three uniform address sections using the same composite component:
The example above illustrates how composite components simplify the creation of repetitive parts of an application – modifying the component demoAddress (e.g. adding a "Country" field) will automatically add this field to all three address sections in the form. As a result, managing complex forms becomes easier, and common fragments of the application remain consistent everywhere they are used.
By using the above tips and best practices, Eximee composite components make it possible to efficiently create modular, easy-to-maintain business applications in which sections defined once can be used in many processes and forms. Good design of composite components pays off by reducing duplicate work, standardizing the interface, and enabling faster implementation of future changes.
Last updated
Was this helpful?