> For the complete documentation index, see [llms.txt](https://docs.eximee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/interfejs-uzytkownika/komponenty-rozszerzone/komponenty-zlozone.md). # Composite components ## Introduction A composite component lets you encapsulate a piece of the application screen into a coherent, reusable element.\ In the component, both the appearance of the screen area and its behavior are defined. Teams using composite components to build user interfaces save time and make it easier to maintain frontend consistency. ### **Role and use cases** The main role of composite components is **repeated reuse** of repetitive form areas across different pages. A composite component created once can be embedded: * on different form pages – which allows multiple pages to use a common, consistent section * multiple times on the same page – e.g. if one form needs two independent address sections (for registered and correspondence addresses). 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 across 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 as a composite component and reusing it multiple times instead of creating those fields from scratch every time. Composite components are often used in business applications as standard form sections (e.g. address data, contact data, sections with customer information, etc.), which ensures a uniform user experience and makes it easier to develop future forms.

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

## Creating a component To create a new composite component or edit an existing one, you need to: 1. In **Eximee Designer** go to the **Library** and select the tab **Composite Components,** 1. 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 drop-down menu (three dots) 3. view the component version history using the drop-down menu (three dots) 3. Select the option to add a new composite component 1. the artifact creation window appears, where you enter the component name and location (folder) in the project tree, similarly to creating a new form.

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

After creating the composite component artifact, the **composite component editor**, very similar to the form editor, opens. In the central part of the view, we design the layout and add the needed 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. This is how 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 (just like in a form). After configuring the content of the composite component, we save it, assigning the appropriate version (more on versioning below). Saving creates a new artifact version that can be used in forms.

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

## Parameters **input** Composite components can accept **input parameters**, which allows values from outside to be passed into them – from a form or even from another composite component. To define an input parameter, in the editing of the composite component definition you need to 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 **embedding** 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 assign an *alias* (a user-friendly name displayed during mapping) * optionally provide a default value – used if no value is assigned during embedding. It is possible to map values from fields in 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 inside it to a specific global variable, it can accept a value as a parameter, which allows it to be used in different places with different data.

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

## Embedding a component The created composite component can be embedded in any form or even inside another composite component (nesting) – the platform allows any level of nesting. To use a composite component in a form, go to edit that form, then from the component 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). From this list, select the appropriate component and add it to the form using drag and drop at 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 fields defined earlier. {% hint style="info" %} If the embedded composite component has defined input parameters, after adding it to the form **you need to configure the mapping of these parameters**, assigning them the appropriate fields or values in the context of the form or parent component. In the form editor, this is done in the section **Input parameters** in the properties of the embedded component – just select the composite component on the form and click the pencil icon next to the field *Input parameters*, to open the mapping window. {% endhint %}

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

A composite component placed on a screen becomes an integral part of it. All fields it contains 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 on the form, etc. If needed, at the form level you can also define additional **form validators** covering fields inside composite components as well (e.g. a script checking data consistency between sections). Similarly, navigation mechanisms or conditional visibility also work on nested components – a composite component can be hidden or shown depending on a condition, just like a single field. ## Versioning and propagation of changes Versioning is described in detail [here](/documentation/documentation-en/budowanie-aplikacji/aplikacja-biznesowa/wersjonowanie.md). ## 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 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 the translations of labels and hints from a composite component can be overwritten or adjusted at the level of a specific form if needed. A composite component is also treated as a constituent 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 the same way as for a standard field on 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 the form. Moreover, validators defined at the form level (e.g. checking 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 in conditional expressions with the symbol `@.` This way, the platform will distinguish the component's session variable from the parent form's session variable. Moreover, session variables cannot be used directly in components of type *Repeatable section* inside a composite component – in such situations, it is recommended to use technical fields as the value carrier. If a composite component needs to use an external service (e.g. to populate 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, be called in response to an event (e.g. a field change). However, keep in mind that services operate in the context of the entire application, so invoking a service from within a component affects the parent form. ## **Good practices** ### **Identifying opportunities for reuse** Already at the requirements analysis stage, it is worth identifying form sections that may appear multiple times or in many different forms of the application. Such sections (e.g. address data, customer's personal data, contact information section, consent sections, etc.) should be designed as separate composite components, instead of 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 artifact naming. 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`, `insVehicleData` – 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 – composite components are worth grouping into thematic or project folders. ### **Documenting the component** Each composite component can be provided with internal **documentation**. In the **Properties** "Properties" tab of the composite component editor there is a "Documentation" section, where you can describe the component's operation and purpose (it supports HTML formatting). It is recommended to complete the documentation for the 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 reuse easier and speeds up onboarding of new team members.

Figure 6. ""Properties" tab of the composite component – documentation preview"

### **Versioning and backward compatibility** When planning changes in a composite component, consider their impact on existing forms. **Avoid introducing incompatible changes** without bumping the major version (MAJOR). If a change in the component's structure or behavior is necessary that could disrupt the operation of 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. ### **Avoid excessive complexity** Although composite components can contain any logic, try to keep them as relatively uniform, clearly defined functions. 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 inside a component inside a component, etc.) can also make debugging and understanding the form more difficult – use this capability judiciously, guided by the readability of the form structure. ### **Be careful with copying components** The platform allows duplicating a composite component (with the option **Duplicate** 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** 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. You need to consider whether in the new component we still want to use those original shared subcomponents, or whether we should copy them as well (e.g. when changes in them should not affect our new component). This is important from a maintenance perspective – unknowingly editing a nested component may affect other places where it is used. ### **Using ready-made components** Check whether the composite component you need does not already exist 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, downloadable documents component, GDPR consent sections, etc.) is faster and safer than building your own from scratch. Build new composite components only when the needed functionality is truly missing from the existing assets. ### **UX consistency** Remember that a composite component is part of the user interface – design it according to the UX/UI standards applicable in your organization. Make sure 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 "stuck on" from somewhere else. 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 following illustrations show an example of a composite component named `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:

Figure 7. Designed composite component "demoAddress" (address section)

Next, the same component `demoAddress` was embedded three times in a sample form (e.g. for registered address, correspondence address, and workplace address) – thanks to reusing a single artifact, we get three sections in the form without having to create three separate sets of fields:

Figure 8. Multiple use of the composite component "demoAddress" in the form structure (embedded three times)

As a result, in the user interface the form displays three uniform address sections using the same composite component:

Figure 9. Appearance of the form with the repeatedly embedded composite component "demoAddress" (three address sections)

The example above illustrates how composite components simplify creating repetitive parts of an application – modifying the component `demoAddress` (e.g. adding the "Country" field) will automatically introduce this field in all three address sections on the form. This makes managing complex forms easier, and shared 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. Well-designed composite components pay off by reducing duplicated work, standardizing the interface, and enabling faster implementation of future changes. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/interfejs-uzytkownika/komponenty-rozszerzone/komponenty-zlozone.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.