Form steps and pages

Steps and pages are the basic elements of the form structure in Eximee Designer, which allow multi-step forms to be organized. Step groups one or more pages and represents a logical stage of the form (e.g. the stage of collecting co-owner data, the borrower’s income data, or the application summary), and page is a single screen/subpage containing specific fields and components. In this way, the designer defines the user’s navigation path – it determines the order of steps, the pages contained in them, and the conditions for displaying them. In the user interface, steps can be indicated by a progress bar (the so-called step bar) – its visibility is configured in the tab Properties.

The “Steps” tab – editing the form structure

We manage the structure of steps and pages in the Steps tab of the application editor. After opening the form, this tab is displayed by default in preview mode (read-only). There you can see a list of all steps and the pages belonging to them – for each element the following is shown: business identifier (mid), title (if provided) and visibility condition (a conditional expression that determines whether a given step/page should be displayed). &#xNAN;Note: these conditions are not executed in this view, only displayed for information.

To edit the structure, switch the Steps tab to edit mode (pencil icon – Edit process) – it may be necessary to first release any working lock (draft) of the form. In edit mode, you can add and remove steps and pages, edit their basic properties, and change the order using the drag & drop mechanism. Keep in mind a few rules:

• You cannot delete all steps! – at least one step must remain in the form.

• Adding a new step automatically creates a new page inside that step (a step cannot be empty).

• Deleting a step causes all pages it contains to be deleted.

• Moving pages between steps is done by dragging with the mouse. For example, you can drag a page from one step to another.

• Deleting individual pages or steps is available from the context menu (trash icon next to the element). For a page, there is also an “Open” option, which takes you to editing the content of that page in the tab Application.

Tip: The progress bar (steps) shown to the user can be hidden if needed – use the Step bar visibility option in the Properties.

Step properties

Each step has a set of basic properties defining its role in the form. In Eximee Designer, they are visible both in the Stepstab and in the Sourcetab. In the Steps tab, these properties are available as text fields, which can be filled in according to the hints displayed in those fields. In the Source tab, the same properties appear under their technical identifiers:

• id – the unique identifier of the step (internal technical name). By default, steps receive IDs in the form Step1, Step2 etc. It can only be edited from the Source.

• titleKey – translation key for the step title. By default it takes the value StepX.title (where X is the step ID). Setting or editing the appropriate title is possible in the Steps tab, where you can quickly add or edit the title for the main language of the application, or in the Translations tab after searching for the step you are interested in, where you can add or edit the title for different languages included in the application.

• visibleCondition – the step visibility condition, written as a logical expression. If the condition is not met, the given step will be automatically skipped when presenting the application to the user. In the condition, you can refer to field values or session variables (for syntax details see the chapter Expression language in the documentation). The condition can also be configured in the Steps – field “Add condition” for the appropriate step. For example, for a step to be visible only when the user has selected the checkbox with ID GesCheckbox1, the condition may look like this:

// Step visibility condition (example)
getValue("GesCheckbox1") == "true"

This condition will return "true" if checkbox1 is checked, which will cause the step in which the condition was used to appear.

Remember that a step ID is a unique value and it is best not to change it after creating steps (it is linked, for example, to translation keys and logic). However, title and visibility condition can be modified at any time – these changes affect the behavior and appearance of the form during filling.

Page properties

Each form page has an extensive set of properties, divided in the editor into thematic sections: Basic properties, Layout, Data quality, Interactions, Styling, WCAG and Other. To edit the properties of a specific page, open that page in edit mode in the Application tab (for example, by clicking the page name in the Steps tab list or choosing the “Open” option), and then click on the empty background of the page – page properties will appear in the right panel. Note: some basic properties (identifier, title, visibility condition) can also be changed from the list in the Stepstab, but most settings are available only in page editing.

Below is a summary of the key page properties by section:

Basic page properties

• Id – unique page identifier. The Id automatically takes the next value PageX (where X corresponds to the page number) when a new page is created, and it cannot be changed in the graphical editor – this is only possible in the Source. Id it must be unique within the form and is visible in the URL address while filling out the application.

• Business identifier (mid) – optional “friendly” page identifier. By default, mid is the same as the Id page ID, but you can assign your own business name. It is also editable in the Steps tab by clicking the first column in the page row. Mid should be unique.

• Title – page title displayed to the user (e.g. Summary). You can enter static text, leave it blank, or fill it in the Translations tab if the page is to have a title in different languages.

• Title (key) – translation key for the page title. It works similarly to the titleKey step – it allows you to define the title in different languages (the default value is e.g. PageX.title where X is the page number). In the Translations tab, you can add the appropriate entries for this key.

• Page number – sequential number indicating which page of the application this screen is. This is a read-only field (the system numbers pages automatically in the order they appear in the structure).

• “Next/Submit” button label – allows you to define a custom text for the navigation button that goes to the next page or submits the application, visible on that page (e.g. “See summary” instead of “Next”). By default, the button has the label “Next” or “Submit application” on the last page.

• “Next/Submit” button label (key) – translation key for the button label. It is automatically filled in by the form with the value PageX.nextButtonLabel (where X is the page number). If the form is multilingual, appropriate values should be added in the Translations &#xNAN;Hierarchy of button label display: if no custom button label has been defined for the page, the field uses the label provided by session variables nextButtonText / submitButtonText, and subsequently the global platform keys are used (iew.navigation.next / iew.navigation.submit).

Layout

• Number of columns – this field shows the number of columns defined for the given form. The field is not editable from the Application The change in the Source tab is described in Page editing

Data quality

• Visibility condition – a formula (expression) that determines whether the page should be shown to the user. If the condition returns false, the page will be skipped when the application is displayed (the user will not see it). Conditions are written as JavaScript expressions – you can use functions such as getValue("componentId") (retrieve the value of the component with the given identifier) or isVisible("componentId") (check the visibility of the component). More examples are described in Condition definition expression language (conditions with getValue) The condition editor suggests available syntax, field identifiers, and variable names. Example condition for a page that should appear only if the selection field has a specific value:

// Page visible only when value "A" is selected in the "type" field
getValue("applicationType") == "A"

• Validators – a field that allows additional rules to be attached to check the correctness of data entered on the page. Validators are added by attaching the appropriate script validator – more information can be found in the section Complex (custom) validations

Interactions

• Listening – a mechanism responsible for dynamic refreshing of the state of the page/component/variable in response to changes in listened elements. This means that if, for example, a page visibility condition refers to the value of another component, that component should be added to the Listening. Thanks to this, a change in the value of that component will cause the condition to be recalculated/refreshed and the page to be shown/hidden if necessary. In the Listening attribute, you can indicate multiple components. Editing is done through a list window – after clicking the List button, a popup appears with a list of available components. You can search for them by entering both Id and mid. The popup also shows components already selected - the same one cannot be selected twice. &#xNAN;Example: if the page has Visibility condition field-dependent agreementCheckbox, add agreementCheckbox to Listening of this page. Similarly, for step conditions we proceed in the same way – since a step does not have its own listening attribute, the components determining its visibility are added to the listening list of the step’s first page.

Styling

• Style name – list of CSS styles assigned to the page. It allows the page (and all its elements) to be given an individual look through styling in a CSS stylesheet. The value entered in this field will be added as an HTML class to the page container. You can enter multiple classes separated by spaces. (More information can be found in the documentation in the section Form styles and component styles.)

• Sticky next button (customPositionedNavbarCondition) – condition for a specific behavior of the “Next”/“Submit” navigation button. This function is mainly used in native mobile applications – it allows, for example, the button to always be visible at the bottom of the screen (pinned) if a given condition is met. When the condition is set to true, the navigation button for the given page will change the way it is displayed. _{(Availability of this feature depends on the license and may not be available in all deployments)}

• Hide cancel button ("X") – a flag determining whether the cancel button should be visible on the page (marked with an X, usually in the form header). By default, in the mobile channel, such a button is displayed, allowing the application to be interrupted. Selecting this option will hide it on the given page. _{(Availability of this feature depends on the license and may not be available in all deployments)}

• Hide back button – a flag controlling the visibility of the back navigation button (with an arrow) in the mobile application. In some mobile templates, next to the form title, a “back” arrow to the previous screen is displayed – enabling this flag will remove that element on the given page. _{(Availability of this feature depends on the license and may not be available in all deployments)}

• Hide application title – a flag deciding whether the title of the entire application is shown at the top of the screen. In typical web deployments, the form title is displayed, for example, in the header. If the form has its own graphical title or we simply want to save space, we can hide the default title by selecting this option. _{(Availability of this feature depends on the license and may not be available in all deployments)}

WCAG

• Page contains a form – a flag determining whether the page should be treated by assistive technology as a standalone form. Setting this option will give the page container the attribute role="form", which may be required to meet WCAG accessibility standards (especially when there are many independent forms within one application). Details of this property are described in the section WCAG – page as a form. Enabling this option is usually not necessary for ordinary application pages (which are anyway inside the main form of the whole application), but it may be useful in unusual scenarios.

Other

• Curtain – a configurable message displayed at the top of the page in the form of a curtain. It can be used, for example, to block interaction with the rest of the form until the user performs some action, or simply to display a highlighted notice. Curtains can serve as information banners. This property allows you to choose a previously defined Content (TextContent) as the message or enter a text message. _{(Availability of this feature depends on the license and may not be available in all deployments)}

• Bottom bar – an additional bar at the bottom of the page (mobile applications only) used to present, for example, a collapsible section with additional information or actions. Several properties are available for configuring this bar:

  • Should the text be expandable? (expandable) – whether the bottom bar should contain expandable content (that is, an initially collapsed message with an “expand” option). By default, the option is enabled (the bar is expandable). If unchecked, the bar will be fixed (not collapsible).

  • Alternative appearance (mode) – enables an alternative way of displaying the bar. Depending on the implementation, this may mean a different color scheme or bar style.

  • Expand button text (showToggleTextKey) – translation key for the text of the link/button that expands the bar. By default, it may be e.g. “Read more”. If you enter, for example, bottom.expand, you need to add the corresponding entry in translations (e.g. bottom.expand = "Show more information"). Similarly, Collapse button text (hideToggleTextKey) – key for the text of the option to collapse the bar (e.g. “Hide details”).

  • Bar visibility condition (visibleCondition) – logical condition determining whether to show the bottom bar at all on a given page. For example, if the bar is to be visible only for new customers, you can enter an appropriate condition here.

  • Expanded content (topTextContentName) – the name of the Content (TextContent)artifact whose content will be displayed when the bottom bar is expanded. This allows the designer to create rich HTML (e.g. a list, table, links) in the Content component and embed it in the bar.

  • Collapsed content (bottomTextContentName) – similarly, the name of the Content artifact with content that is visible before the bar is expanded (i.e. a short message on the bar). After clicking “expand”, this message can be replaced or extended by the content of topTextContent.

  _{(Availability of this feature depends on the license and may not be available in all deployments)}

• Login required condition (loginRequiredCondition) – a condition that determines whether the user must be logged in before the page is displayed. If a condition is defined here (e.g. getValue("isCustomerLoggedIn") != "true"), then if it is met, the system will require the user to authenticate (log in) before the page is shown. This functionality is used in scenarios where part of the application is available only to logged-in users.

In addition, there are certain page properties available only through XML editing (Source tab). These include, among others, fixedColumns/inheritLayout – related to inheriting the column layout from the old engine version – whether migratedLayoutOn (layout migration flag). In most cases there is no need to modify them manually.

Good design practices

When designing the structure of steps and pages, it is worth following a few good practices that will make maintenance of the application easier and ensure correct logic behavior:

• Thoughtful naming: The names of artifacts (forms, components, variables) should be consistent and understandable. Decide whether you use Polish or English and stick to the convention. Id and mid for pages, it is best to name them in a way that reflects their content or role. Avoid leaving default names such as Page1 – it is better to replace them with e.g. AddressData or Summary. This makes it easier to navigate the structure, and business identifiers appearing e.g. in conditions will be more readable.

• Unique identifiers: Each step, page and component should have a unique mid (business identifier). The system does enforce uniqueness within a single form, but if you duplicate artifacts or copy form fragments, it is easy to overlook duplicated identifiers. Duplicate mid can lead to incorrect behavior of conditions or listening. When duplicating elements, always check and change mid to a unique one. Similarly, translation keys – do not use one key for two different texts.

• Readability and modularity of conditions: When creating complex conditional expressions, make sure they are readable. Use parentheses and naming conventions to clearly express the intent (e.g. getValue("netIncome") > 0 && getValue("employmentStatus") == "true" instead of an unreadable chain). Avoid repeating the same logic in multiple conditions – if several fields or pages use the same expression, consider extracting it into one session variable or a technical field. For example, you can add technical field with mid isVIPCustomer with a default expression evaluating customer data, and then in conditions for different steps refer only to getValue("isVIPCustomer"). Such centralization of expressions will simplify future changes (you modify the formula in one place) and reduce the risk of errors. In Eximee you can mark a text field as technical field, by checking the appropriate option in the Properties of the text field - in the Securitysection. Such a field is invisible to the user, but available to the logic – useful for storing auxiliary values.

• Testing visibility logic: After configuring conditions and listening, always test different application scenarios when filling out the application. Make sure that steps and pages appear and disappear as intended in response to user data. Test combinations of answers – especially edge cases – to avoid situations where, for example, a certain navigation path accidentally skips an important page. Remember the case where a condition refers to a field with a default value: if the controlling field is invisible but has a default value that satisfies the condition, then the dependent page/component will still be displayed. &#xNAN;Example: a radio field has the first option “YES” selected by default and we conditionally show another field precisely when it is “YES” – even if the radio is hidden, the default value "YES" will still cause the dependent field to appear. Such situations should be handled consciously, for example by setting no default response for the radio button.

• Order and consistency: Keep the structure tidy – do not create unnecessary empty steps, and do not place single fields on separate pages if it is not necessary (it is better to group fields thematically within one page so that the user does not have to click “Next” for every small piece of information). Try also to ensure that each step logically corresponds to one topic of the process – this will make it easier both for the user to understand the progress and for you to expand the application later.

• Translation naming: If the form is bilingual, make sure the translation keys for steps and pages are named consistently. Usually the pattern StepX.title and PageX.title is used. In the Translations tab you can easily review all keys – avoid duplicates or unnecessarily similar entries.

• Component reuse: If a certain set of fields appears in many places, consider creating a composite component instead of duplicating those fields manually in each place. This will make changes easier and keep things consistent.

• Parking the application: If your business process allows parking (saving a draft) before submission, make sure it is handled correctly in the form. By default, Eximee allows the user to park the application using the “Save and return later” button (if the implementation provides it). However, this does not apply to steps after the save point – parking the application is impossible there, so you do not need to do anything extra.

Debugging steps and pages – checklist

Despite your efforts, in complex applications there may be problems with navigation or visibility logic. Here is a checklist that will help you find the most common errors:

1. A step/page does not appear at all:

   • Check the visibility condition of the step and all parent elements. Perhaps the condition is always false (e.g. a typo in a field name in the expression causes it to always return false).

   • Make sure the identifiers used in the visibility condition exist and are correct.

   • Check whether the step has been placed as an element of another step. Eximee does not support nested steps — each step must be at the top level of the structure.

2. The visibility condition does not work dynamically:

   If the condition is based on a field changed by the user, and the page/step does not appear or disappear during interaction, then almost certainly Listeningis missing. Check whether the dependent component has Listening added to that field. If not, add the missing bindings and test again.

3. The element is displayed even though it should not be: A typical cause is a condition referring to a field with a default value, as mentioned above. If the dependency is more complex, also check whether you have mixed up operators (e.g. using == instead of !=) or data types (are you comparing text with a number?). When debugging conditions, it can help to temporarily add a text field to the form and set its text to the result of the problematic expression – then you can see “live” what the expression returns.

4. Problems with navigation between steps: If the “Next” button does not respond or the user gets stuck, make sure there is at least one visible page in the step. It may happen that all pages in the step were hidden by conditions – then after completing the previous step, the system may have nowhere to go. Solution: either ensure that at least one page always appears, or conditionally skip the whole step (condition on the step instead of on each page separately).

5. Cannot edit the form (edit icon grayed out): The form was probably locked by the draft mechanism – for example, another user edited it and did not save. The lock can be released as described in the section Draft – working draft/copy. In Eximee Designer, in the form list view, when an artifact is locked, an appropriate message and an option to take over the draft appear.

6. Checking process bindings: When using EximeeRouter2, verify the process name and business key mapping in the Save Point configuration. An incorrect process name may cause nothing to happen after submission (the application will be saved, but the process will not start). Look for messages about process start in the system logs.

7. Logs and developer mode: If problems are hard to diagnose, use the browser logs (JS console) and Eximee server logs. Verify in the Source tab whether the properties of steps and pages there match your expectations (this helps catch, for example, unintentionally overwritten identifiers or missing entries).

8. Use the FAQ: If in doubt, see the document FAQ Eximee Designer – many common problems are described there along with solutions. For example, it explains why a dependent component may appear despite the control being hidden (default value), or what to do when changes in a composite component are not visible in the application.

Applying the above checklist should help you quickly identify most errors related to the steps and pages mechanism. If the problem is unusual, it is worth analyzing it step by step, simplifying the conditions (for example, temporarily setting them to true/false in order to separate the influence of other factors) and adding diagnostic elements (technical fields, text fields, etc.).

Links to other sections of the documentation

The “Steps and pages” mechanism is closely related to other aspects of building an application in Eximee. For full understanding and correct configuration, it is also worth reading the following documentation topics:

• Processes and EximeeRouter2 – if the form is part of a larger business process, read the document Processes. It describes how to define and start processes in Eximee BPMS and how Eximee Designer communicates with EximeeRouter2 when submitting the application. Understanding this integration will help you make better use of save actions in the Save Point (e.g. passing process variables, handling exceptions).

• Translations – the Translations tab in the editor allows you to add translations for texts used in the form (including page titles, button labels, etc.). Remember that keys such as titleKey or labelForNextOrSubmitButtonKey require adding corresponding entries here, otherwise the content you are interested in will not be displayed to the user.

• Styling and UX – the steps mechanism affects the user experience, so it is worth learning the possibilities of styling the form. In the styling documentation you will find information on how to globally customize the appearance of the step bar, navigation buttons, or page layout. For example, there are platform styles and the possibility of adding your own CSS stylesheets to the application. Relevant sections (e.g. Component styling) show examples of using style properties.

• WCAG – accessibility – if the project requires WCAG compliance, be sure to read the dedicated documentation WCAG. It contains guidelines for building accessible forms, descriptions of functions such as ariaLabel/Description, accessibility audit in the editor, and tips for creating components friendly to screen readers. In the context of steps and pages, make sure, for example, that each step is announced logically (if the step bar is hidden, consider adding hidden headings on pages informing the user of the stage). The role=form flag mentioned earlier also relates to WCAG recommendations.

In conclusion, the “Steps and pages” mechanism forms the backbone of every application in Eximee Designer – mastering its principles will allow you to build extensive yet clear forms. Use the documentation and the tips above while working, and your applications will guide the user correctly from the first step to the thank-you page in a user-friendly way that meets business requirements.