AX1587

Embedded Form component for Axiom forms

The Embedded Form component displays the contents of an Axiom form embedded within another Axiom form.

The form that contains the Embedded Form component is known as the parent form. When you configure the Embedded Form component, you must point it to a target form that will be displayed within the component. This target form is known as the child form. When a user views the parent form, the target child form displays as embedded within the parent form. The target child form can always be the same form, or you can use the separate Menu component to allow users to dynamically switch between child forms.

The primary use of this component is to create forms where the form web page that displays to the user is sourced from multiple files instead of a single file. The parent and child forms together make up the composite form to be displayed to the user. Use of embedded forms can simplify form creation for complex forms, by separating the form contents into smaller, logical units.

The Embedded Form component can also be used to enable reuse of the same content in multiple forms. For example, imagine that you want to use the same Map View component within two different Axiom forms. Instead of creating the same map configuration within those two Axiom forms, you could instead create a separate Axiom form that contains just the Map View component. You can then embed that Axiom form within each of the Axiom forms where you want to show that map.

NOTES:

When using the Embedded Form component, the contents of the embedded form do not display in the Form Designer. Instead, the Form Designer displays information about the target form for the Embedded Form component. You must preview the form in order to see how the embedded form is rendered.
This component requires Use Web Client Container to be enabled for the form. By default, the container is enabled for new forms. For more information, see Using the Web Client Container with Axiom forms.

Component properties

You can define the following properties for an Embedded Form component.

Component properties can be configured using the Form Assistant task pane or the Form Designer unless otherwise noted. All properties can also be defined on the Form Control Sheet directly if desired. For example, if you want a property to be dynamic depending on the result of a formula, you can define that formula in the control sheet. To access the control sheet settings for the component, double-click any property name to go to that property in the Form Control Sheet.

Component behavior properties

The following properties control the display and behavior of this particular component type.

Item	Description
Title Text	The title text for the component. This text displays in the title bar for the component within the Axiom form, if the title bar is enabled. If the title bar is disabled, then this text does not display at all in the form.
Show Title Bar	Specifies whether the title bar is visible. By default this option is enabled, which means that the component will display in a bordered box with a title bar across the top. The defined title text displays within the bar. The formatting of the title bar and its border are determined by the skin specified for the form. If disabled, then the title bar and its border will not display on the component. If the title bar is enabled and the component also has a separately defined border (either via a style or by using the formatting overrides in the advanced component settings), then both borders will display on the component. In some cases this effect may be desired; in other cases one of the borders should be disabled.
Source Menu Component	Specifies the Menu component to associate with the Embedded Form component, so that the Embedded Form component will automatically display the currently selected item in the menu. You can select any Menu component that is currently defined in the form, using the component name. This is the recommended method to link a Menu component and an Embedded Form component. The data source for the Menu component must be populated with file paths to form-enabled documents, so that the defined values are valid for display within the Embedded Form component. When using this approach, the ID for each menu item is automatically added to each child form's generated instance ID. This ensures that each menu item has a unique instance ID, even if multiple menu items use the same target file as the value. This means that you can open the same target file from the menu multiple times and each instance is maintained separately, thereby enabling each instance to be in different states. When you specify a source menu component, the Form Document and Instance Identifier properties are unnecessary and become hidden in the Form Designer and Form Assistant. If any values are defined for these properties on the Form Control Sheet, they will be ignored by the form.
Form Document	The path to the form-enabled file to display within the Embedded Form component. Click the [...] button to browse to the desired form. IMPORTANT: This property only applies if you are not using the Embedded Form component with a Menu component. If you are using a Menu component, then complete the Source Menu Component property instead. Once a source menu component has been selected, the Form Document property becomes hidden in the Form Designer and Form Assistant, and any existing value is ignored by the form. Generally speaking, the Form Document setting is only for use in cases where the target embedded form is "fixed" and the component will always display that form. NOTES: Users must have security permission to the target form in order to see it rendered as an embedded form. Permission to the parent form is not sufficient. The next time you open this file after saving, the path to the form will be automatically converted into a system-managed document shortcut (you can tell the difference by the presence of a `_tid` parameter on the end of the shortcut). This is to make the file reference "repairable" in cases where the file is renamed or moved. Note that if the path is a result of a formula instead of directly within the cell, then the conversion will not occur and the file reference will not be repairable. Files created in earlier versions may be using the following syntax to automatically use the currently selected value of a Menu component: `[MenuComponentName.SelectedValue]`. Although this syntax will still work, it is strongly recommended to convert the component to use the Source Menu Component instead.
Instance Identifier	A unique ID to add to the child form's automatically generated instance ID. Generally speaking, this property should only be used if the form contains multiple Embedded Form components, and two or more of those components use the same target form document. For more information, see Using multiple Embedded Form components in a single form. NOTE: This property does not apply if you are using a Source Menu Component.
Save on Parent Submit	Specifies whether a save-to-database is executed in the embedded child form when the parent form is updated. By default, this is disabled. When the parent form is updated, the child form will not attempt to execute a save-to-database (unless the triggering component in the parent form has Save on Submit enabled). If enabled, then whenever the parent form is updated using any component, Axiom Software will attempt to execute a save-to-database in the child form. This is most often used in conjunction with a Menu component, to save data before moving from one child form to another child form using the menu. For more information, see Saving data for embedded forms.
Force Refresh	Specifies whether the embedded child form is updated when the parent form is updated. By default, this is disabled. When an update is triggered in the parent form, the embedded child form is not automatically updated. This means that the child form will not update to reflect changes made in the parent form until the child form is separately updated. If enabled, then the embedded child form will be updated whenever the parent form is updated. The parent form is updated first, followed by the child form. This allows the child form to be updated for changes made in the parent form, such as a change to a shared variable, or a change to a value saved to the database. For more information, see Form session and update behavior for embedded forms. NOTES: This option is not available if Refresh Parent Form is enabled. Since Refresh Parent Form is enabled by default, you must first disable that option in order to make Force Refresh visible in the component properties. If the Embedded Form component is being used in conjunction with a Menu component, then this option should not be used. Instead, use the `[ForceRefresh]` property of the Menu data source to indicate whether a particular child form should be updated.
Refresh Parent Form	Specifies whether the parent form is updated when the embedded child form is updated. By default, this is enabled. When an update is triggered in the child form, the parent form will also be updated. The child form is updated first, followed by the parent form. This allows the parent form to be updated for changes made in the child form, such as a change to a shared variable, or a change to a value saved to the database. If disabled, then the parent form will not be updated when the child form is updated. This means that the parent form will not update to reflect changes made in the child form until the parent form is separately updated. This should only be disabled if the parent form does not depend on values set by the child form, or if it is not important for the parent form to be immediately updated for those changed values. For more information, see Form session and update behavior for embedded forms. NOTES: This option is not available if Force Refresh is enabled. This option is not supported when the Embedded Form component is used within a Dialog Panel component. If enabled in this configuration, it will be silently ignored. This behavior should not be necessary in a Dialog Panel component, because the Dialog Panel Action of OK can be used to refresh the parent form when closing the dialog.
Overflow	Specifies the behavior if the target form is larger than the container area of the Embedded Form component. Select one of the following: Auto (default): Scroll bars are added to the Embedded Form component only if the target form extends beyond the container area. Visible: The target form is visible beyond the container area. This may cause the target form to interfere with the expected display of other components (for example, to overlap another component). Hidden: Any part of the target form that extends beyond the container area is hidden. This may cause the target form to appear "cut off." Scroll: Scroll bars are always present on the Embedded Form component, regardless of whether they are needed. If the target form extends beyond the container area, the scroll bars are active.

General properties

The following general properties are available for all components:

Item	Description
Component Name	The name of the component. This is for identification in the file; this name does not display on the Axiom form canvas. The name of the component identifies the corresponding settings for the component on the Form Control Sheet. The component names are also useful if you have multiple types of the same component within an Axiom form, so that you can tell which component you are currently editing. Component names must be unique within a file and must start with a letter. Names can only contain letters, numbers, and underscores. Names are validated when the file is saved; an invalid name will prevent the save. NOTE: Spaces are not allowed in component names and will be automatically removed by Axiom Software. For example, if you enter "My Component" as the component name, it will be automatically adjusted to "MyComponent".
Visible	Specifies whether the component is visible on the Axiom form (On/Off). By default this is set to On. This setting can be used to dynamically show or hide the component using a formula. Keep in mind that if you have multiple components that you need to dynamically show or hide based on the same condition, then it is preferable to place those components on a dedicated layer and then show or hide the entire layer instead of the individual components. NOTE: This setting is only available on the Form Control Sheet; it cannot be set in the Form Assistant or in the Form Designer.
Layer	The layer that the component belongs to on the Axiom form canvas. In the Form Assistant and the Form Designer, this displays as the layer name (for example: Layer 1). In the Form Control Sheet, this is recorded as the layer ID (for example: 1). If the canvas only has one layer, then the component is automatically assigned to that layer and cannot be changed. If the canvas has multiple layers, you can assign the component to any layer using the drop-down list. By default, the component will be assigned to whichever layer is selected in the Layers box when you initially drag the component onto the canvas. For more information on layers, see Using multiple layers on the canvas. If desired, you can jump to the applicable layer settings on the Form Control Sheet by clicking the binoculars icon next to the drop-down list.
Parent	The parent component that this component is assigned to. If blank, then the component does not have an assigned parent. Currently, only Panel components can be designated as parents. If a component has an assigned parent, then that component is positioned within the parent instead of within the canvas at large. If the parent is hidden, all "child" components of that parent are also hidden. The parent assignment is automatically completed when a component is dragged into a panel in the Form Designer, and automatically cleared when a component is dragged out of a panel. In most cases, you should not need to manually assign a parent. For more information, see Using panels to group and position components.

Style and formatting properties

To define the component formatting, you can assign one or more styles to the component. Styles can impact formatting properties such as fonts, borders, and colors.

If you do not want to apply a style to this component, or if you want to override one or more formatting properties in an assigned style, click the Show Advanced Settings link underneath the Style box to display the individual formatting properties. For more information on defining individual formatting properties for a component, see Formatting overrides for Axiom form components.

Currently, the Axiom Software platform does not provide any styles specifically designed for Embedded Form components. Only the generic styles are available. Any styles applied only affect the embedded form container; they do not affect the display of the embedded form itself.

Item	Description
Style	Optional. The styles used to determine the formatting of the component. You can assign one or more styles. Click the Select component styles button [...] to open the Choose Style dialog. Using this dialog, you can select one or more styles to apply to the component. The available styles depend on the component type and the skin assigned to the form. For more information, see Using component styles. Some components have several styles that are specifically designed for that component type, while other components may only have the "generic" styles that are available to all components. When using a generic style, keep in mind that they may not be useful for all components. You can view a description of each style and view the effective formatting applied by the selected styles within the Choose Style dialog.
Component Theme	(Deprecated.) The theme to use for the component instead of the form-level theme. If left blank, the component uses the form-level theme. This setting should be left blank unless you need to override the form theme. Generally speaking, themes should be set at the form level and only overridden at the component level when necessary. This setting is available in the advanced component properties (click Show Advanced Settings under the Style box). On the Form Control Sheet, the setting displays using the name Theme Override. NOTE: This setting only applies if your form uses a legacy skin (any skin except the default Axiom2018). The Axiom2018 skin does not use themes.

Item

Description

Style

Optional. The styles used to determine the formatting of the component. You can assign one or more styles.

Click the Select component styles button [...] to open the Choose Style dialog. Using this dialog, you can select one or more styles to apply to the component. The available styles depend on the component type and the skin assigned to the form. For more information, see Using component styles.

Some components have several styles that are specifically designed for that component type, while other components may only have the "generic" styles that are available to all components. When using a generic style, keep in mind that they may not be useful for all components. You can view a description of each style and view the effective formatting applied by the selected styles within the Choose Style dialog.

Component Theme

(Deprecated.) The theme to use for the component instead of the form-level theme. If left blank, the component uses the form-level theme.

This setting should be left blank unless you need to override the form theme. Generally speaking, themes should be set at the form level and only overridden at the component level when necessary.

This setting is available in the advanced component properties (click Show Advanced Settings under the Style box). On the Form Control Sheet, the setting displays using the name Theme Override.

NOTE: This setting only applies if your form uses a legacy skin (any skin except the default Axiom2018). The Axiom2018 skin does not use themes.

Position and size properties

You can view the position and size properties for a component by clicking the Show Advanced Settings link under the Style box. If necessary, you can edit these properties directly (instead of automatically modifying them by adjusting the component's position and size on the canvas). For more information on using these settings, see Controlling component position and size.

Item	Description
Reference Location	The reference location determines how the x-position and y-position of a component are evaluated. By default the reference location is UpperLeft. NOTE: This setting is not exposed in the advanced component settings. It can be changed on the canvas by double-clicking the corner selection handles of a component, or you can edit the setting on the Form Control Sheet directly.
X Position Y Position	The x-position determines the component's position along the horizontal axis, and the y-position determines the component's position along the vertical axis. Both are evaluated relative to the reference location. Positions can be set in pixels (default) or percentages.
Width Height	The width and height determine the size of the component. The width and height can be set in pixels (default) or percentages. Size keywords are also available to support special behavior.
Rendering Order	The order in which the component is rendered in the layer. A component with a larger order number will display above a component with a smaller order number. For components that support tab navigation (tabbing to the next editable component), the rendering order also determines the tabbing order. NOTE: On the Form Control Sheet, this setting is labeled as Z-Index.
Lock Layout	If enabled, the component size and position are locked and cannot be changed by dragging and dropping on the canvas. This optional setting is intended to protect against accidentally moving or resizing a component while working on the canvas.

Designing the embedded form

When designing a form to be used as an embedded form, you should keep in mind certain design considerations.

Sizing

The contents of the target form are displayed in actual size within the container area defined by the Embedded Form component (unless Scale to Fit is enabled for the embedded form, which is not recommended). If the target form is larger than the container area, the behavior is determined by the Overflow property.

If you want the target form to fill the Embedded Form component, then the contents of the target form should be configured to dock the width and height. The easiest way to accomplish this is to use a panel that is configured to dock, and then place all of the contents in this panel. You can use percentage sizes for components in the target form so that they adjust to the size of the panel (which is in turn adjusting to the size of the Embedded Form component).

If you use this type of configuration, keep in mind that the contents may not adjust well if the Embedded Form component is sized smaller than the minimum optimal size of the target form. Make sure that the Embedded Form container is sized appropriately to display the target form contents, and to fill the desired space in the parent form. For example, you may want to dock the Embedded Form component within the parent form as well.

NOTE: The canvas size of the target form is ignored if set.

Appearance

The following form-level settings are treated as follows for the target form:

The skin and theme of the target form are honored. This means that both may be different than the parent form. However, while it makes sense for an embedded form to use a different theme than the parent, it is recommended to use the same skin so that the styling elements in both forms match.
The Web Client Container does not display on the target form, however, it is recommended to leave it enabled for the target form in case it is required to display certain elements in the form. The container will display on the parent form or not depending on the parent form's configuration.

Content and feature limitations

Generally speaking, embedded forms can use any form feature. Some limitations apply:

Nested embedded forms are not supported. This means that the target form displayed in an Embedded Form component should not itself contain another Embedded Form component.
Generally speaking, the form-specific features in the Web Client task bar apply to the parent form only. For example, if the Message Stream is present, any comment entered is associated with the parent form, not any embedded child forms. It is not possible to add or view comments for the child forms. One exception is the Filters panel, which can be used to apply refresh variables for both the parent and child forms. For more information, see Filters panel behavior for embedded forms.
The save locking feature can be used with embedded forms, but only when defined at the parent form level. If the parent form has a defined data context, it will control saving data for the parent as well as all child embedded forms. Data contexts cannot be defined at the child form level.

Form update behavior

Some special update behaviors apply when a form is embedded within another form. For example:

By default, triggering an update in the child form does not cause the parent form to be updated, unless Refresh Parent Form is enabled for the Embedded Form component.
By default, triggering an update in the parent form does not cause the child form to be updated, unless one of the following options is used:
- If you are using the Menu component with the Embedded Form component, you can optionally force the child form to be updated by using the [ForceRefresh] property in the Menu data source.
- If you are not using the Menu component, then you can optionally force the child form to be updated by enabling the Force Refresh property for the Embedded Form component. However, you cannot enable both Force Refresh and Refresh Parent Form on the Embedded Form component itself—you must choose one or the other (or neither).
Triggering a save-to-database in the parent form (Save on Submit) will automatically trigger a save-to-database in the child form, if the child form has an enabled save-to-database process. If you do not want the child form to save when the parent form saves, then you can use formulas to disable the child save when the triggering component is $ParentForm.
If a Formatted Grid component is used within a child form, the grid must be set to Inline loading behavior. Asynchronous loading behavior is not supported with embedded forms.

You should keep these special behaviors in mind when designing interactive elements within the form, as well as other behaviors that depend on the form update cycle, such as save-to-database. For more information, see Form session and update behavior for embedded forms and Saving data for embedded forms.

Using an Embedded Form component with a Menu component

Embedded Form components are primarily intended to be used with Menu components. As the user selects items in the menu, the Embedded Form component updates to display the target child form associated with the currently selected menu item. This way, a single Embedded Form component can be used to display any number of child forms within the parent form.

Because the two components are designed to work together, each component has certain settings that only apply to this combined use case. The following is a basic summary of how to configure an Embedded Form component and a Menu component to work together.

Place both components on the canvas, and adjust the basic component details such as position, sizing, and component name.
On the Embedded Form component, set the Source Menu Component to the name of the Menu component. This "links" the Embedded Form component to the Menu component, so that the Embedded Form component will automatically use the currently selected value for the Menu component as the target embedded form.

When using this approach, the Form Document and Instance Identifier properties are hidden and no longer apply.
In the Menu data source, make sure the [Value] column is populated appropriately for use with an Embedded Form component. To be valid for display in the Embedded Form component, the menu value must be a file path to a form-enabled document. The data source can also contain URLs or form-enabled file paths that are configured to open in a new window (using the [NewWindow] column) instead of within the Embedded Form component.
In the Menu data source, use the [ForceRefresh] column to determine if the target form should be updated when it is selected in the menu and displayed in the Embedded Form component. The target form will also be updated if it is the currently visible child form and an update is triggered in the parent form. You should set this to True if the target form depends on values that can be changed in the parent form or in other child forms.
Optional. In the Menu data source, you can use the [DocumentVariables] column to pass values to the target form when it is selected in the menu and displayed in the Embedded Form component. The target form must use the GetDocumentInfo function to return these passed values and impact the form in some way. Generally speaking, document variables should be used when the values only apply to the target form opened by the Menu item. If the values need to be shared by two or more forms, then shared variables should be used instead.

For more information on the Menu component and configuring its data source, see Menu component for Axiom forms. For general information and design concepts for embedded forms, see Using embedded forms.

Using multiple Embedded Form components in a single form

If desired, you can use multiple Embedded Form components within the same form. For example, you might want to:

Display multiple child forms within a parent form concurrently. The form could be a dashboard where you want to present three distinct blocks of content within the page. Instead of defining each block using Panel components within the parent form, you can define each block using three separate files and then display those files as embedded within the parent form.
Display the same child form multiple times within a parent form concurrently. Document variables can be passed to the child form instances so that each instance displays different content.

When using multiple Embedded Form components, the child forms can display independent content, or the child forms can depend on shared variables that are set in the parent. If you are using shared variables, then you must enable Force Refresh for the Embedded Form components in order to force the child forms to update when the parent form is updated. Otherwise the child forms will not update when the variable value is changed in the parent form. Note that the child forms cannot depend on shared variables that are set within other child forms, because there is no way to force the other child forms to update when one child form is updated.

If you are using the same child form within multiple Embedded Form components, you must do the following:

Define a unique Instance Identifier for each component. The identifier values can be anything you want, as long as they are unique. The values should not contain $ or @.

This allows Axiom Software to manage each instance of the child form independently. If unique instance identifiers are not defined, then Axiom Software will render the same instance of the form within each Embedded Form component. Additionally, errors or incomplete rendering may occur.
Append document variables to the Form Document path so that the content shown in each instance of the child form is different. For example, you could have a variable Entity and then pass different entity values to the child form, so that each instance displays the data for a different entity. The child form must use the GetDocumentInfo function to return the variable value and filter the data queries by that value (or impact the form contents in some other way).

To append document variables to the path, use the following syntax:

\foldername\filename.xslx?variablename=value&variablename=value

For example:

\Axiom\SystemFolderName_ReportsLibrary\Forms\current_sales.xlsx?Entity=1

This example passes the value 1 for the variable Entity, when this target form is opened within the Embedded Form component.

NOTE: Multiple Embedded Form components should only be used when the content needs to display concurrently (side by side within the form). If the child forms can be viewed sequentially, one at a time, then a single Embedded Form component should be used with a Menu component instead. Users can select items in the menu to change which child form currently displays as embedded within the parent.