AX1466

Using panels to group and position components

You can use Panel components on the form canvas to create groups of components and control their display relative to the panel. When using a panel:

You define the overall area devoted to the panel, as well as any panel properties (such as a panel title or border).
You assign one or more "child" components to the panel, by placing these components within the panel boundaries.

Once components have been assigned to the panel, the panel and all of its child components move as a group on the form canvas. Additionally, the child components can now be sized and positioned relative to the panel instead of relative to the overall canvas.

Example Panel component with child components

This screenshot shows an example Panel component in the Form Designer. This panel has several child components such as a label, radio buttons, combo box, and a chart. As the panel is moved on the canvas, the child components move with it.

NOTE: This section discusses the behavior of Panel components and their child components when using the default Child Layout option of Positioned. Panel components also support an alternate option named Flow, which allows child components to automatically flow across and down a page based on a set order. This alternate layout behavior is intended for home pages and dashboards where the content may not need to be positioned absolutely on a page. For more information, see Auto-flow components in a panel.

Creating a panel

The first step to using a panel is to drag and drop a Panel component on the canvas, and then size the panel to match the area that you want to control. You can resize the panel later, but you want to set an initial size that is large enough to drag and drop all of the desired child components within the panel.

In some cases, you may want to size the panel so that it fills the entire page. You can use the docked-to-container style for this purpose. Assign the style to the Panel component, then click Show Advanced Settings and clear the position and size settings for the component so that they will be inherited from the style.

The Panel component does not have many component settings. One key decision to make is whether you want the panel shape to display as a design element on the form (for example, by giving the panel a border and/or a title), or whether the panel should be an "invisible" component used only for the purposes of controlling the child components. If a panel has no visible title bar, border, or background color, then the form viewer will not be aware of the presence of the panel. For more information about the panel settings, see Panel component for Axiom forms.

NOTE: The Wizard Panel component is also a Panel component, but it is specifically intended to support creation of wizard-style interfaces. By default, the Wizard Panel is sized to fill the full window and contains built-in wizard features and formatting. For more information, see Wizard Panel component for Axiom forms.

Assigning child components to a panel

The primary way to assign child components to a panel is to use the Form Designer. When you drag and drop a component in a panel, the component is automatically assigned to that panel, by writing the name of the panel to the Parent property for the component. Any component can be assigned to a panel, including another panel (nested panels).

When dragging and dropping the child component to the panel, the top left-hand corner of the child component must be within the panel. Any other part of the child component can extend outside of the panel boundaries, as long as the top left-hand corner is within the panel (though in most cases it is desired for the component to be fully enclosed within the panel). When you are moving a component, you can tell that it will become assigned to a panel (or keep its existing assignment), because the parent panel is highlighted using a dashed border.

Example Button component will be assigned to highlighted panel

To remove a child component from a panel, drag and drop the component so that the top left-hand corner of the component is outside of the panel boundaries. The parent assignment will be automatically cleared (or updated to a different panel, if applicable).

NOTE: It is not recommended to manually edit the Parent property to assign a component to a panel or to remove an existing assignment, as this manual edit does not adjust the location settings for the component. Instead, the component's current location settings are left unchanged and are now interpreted as relative to the panel (or in the case of removing a parent assignment, as relative to the overall canvas). See the following section for more information about how the location of child components is determined. This mismatch of child component location and parent assignment can also result in confusing behavior in the Form Designer.

Child component position and size within the panel

Once a component has been assigned to a panel, its position and size in the form is now determined relative to the panel area instead of the overall canvas.

For example, if a component with no panel assignment has an x-position of 30px and a y-position of 30px, this means that this component is positioned 30 pixels from the top of the canvas, and 30 pixels from the left edge of the canvas (assuming the default reference location of UpperLeft). However, if the component is assigned to a panel, then the same settings mean that the component is positioned 30 pixels from the top of the panel and 30 pixels from the left edge of the panel, wherever that panel is located on the canvas. This keeps the position of the child components fixed within the panel as the panel is moved around the canvas.

Additionally, if a child component uses a dynamic position or size option, such as percentages or dock, then the position or size of the child component is now calculated against the panel, not the page. For example, if a child component is set to 30% width, that component will be sized to 30% of the panel width, not the page width.

Child components only display in the rendered form if the panel is visible in the form. If the panel is hidden (by setting Visible to Off on the panel or on the layer it is assigned to), then the child components are also hidden, because there is no available reference to determine their position.

Make sure to consider the Overflow property when positioning and sizing panels and their child components. The overflow property determines what happens if a child component exceeds the borders of the panel component. Because only the top left-hand corner of the child component must placed within the panel boundaries in order to remain assigned to the panel, the rest of the component may extend beyond the panel boundaries. Even if the child component is fully contained within the panel when it is originally assigned, this may change due to situations such as the following:

The parent panel is dynamically sized using a percentage, but the child components have fixed sizes using pixels. In this situation it is possible that the panel may render smaller than the fixed sizes of the child components, depending on the size of the page.
You manually change the size of a child component or the parent panel, such that the child component's width or height now extends past the panel boundaries.
You manually change the position of a child component such that it now extends past the panel boundaries.

By default, Panel components are configured so that overflow is visible in the form. If desired, you can change this so that overflow is hidden, or so that the panel scrolls to provide access to the overflow.

Working with panels in the Form Designer

Note the following behavior when working with panels in the Form Designer:

When you drag and drop a panel to another location, or otherwise cause the panel to adjust location—such as by using the align or distribute options—then all child components in the panel move with it. As discussed in the previous section, this because the child components are positioned relative to the panel.
Duplicating a panel only duplicates the Panel component, it does not duplicate the child components in the panel.
Deleting a panel deletes the panel and all child components. If you do not want the child components to be deleted, you must move them out of the panel first. If you have already deleted the panel, you can use Undo to restore the panel and its child components (as long as you have not exited the Form Designer after deleting the panel).
Child components within the same panel can be aligned and distributed with each other, but not with components outside of the panel.
Child components can be moved to the front or back relative to other components within the panel, but they cannot move "underneath" the parent panel. The parent panel is always at the bottom relative to the child components in the panel. If external components overlap the panel (but do not belong to the panel), then the panel and its child components are treated as a single unit when moving the external component to the front or the back.

Using layers with panels

Panels and child components can belong to layers like any other component. Typically the panel and its children will all belong to the same layer, but they do not have to. You might use layers in this situation simply as a Form Designer tool, to control which components display in the Form Designer at any one time. You can also use layers to control visibility in the rendered form, if controlling visibility at the panel level is not sufficient.

When using layers with child components of a panel, keep in mind that child components will only be visible if the parent panel is visible. For example, imagine that the panel belongs to a layer named Panel and a child component belongs to a layer named Child. The visibility of these components based on layer visibility is as follows:

If both layers (Panel and Child) are visible, then the panel and the child are visible.
If layer Panel is visible but layer Child is hidden, then the panel shows but the child is hidden.
If layer Panel is hidden but layer Child is visible, then both the panel and the child are hidden. The child component cannot be visible if the parent panel is hidden, even if the child component's layer is visible.

While working in the Form Designer, the following layer behavior applies to panels:

When you drag and drop a new component into a panel, the child component will be automatically assigned to the same layer as the parent panel. However, if you drag and drop an existing component into a panel, the child component will retain its current layer. In this case you must manually change the layer for the child component if you want it to have the same layer as the panel.
If a panel is not currently visible in the Form Designer (due to hiding it via a layer), then you cannot drag and drop components into that panel. The hidden panel is ignored for assignment purposes. Additionally, all of the hidden panel's child components will also be hidden. This allows you to work with multiple stacked panels, by assigning each one to a layer and then showing one layer at a time.
If two visible panels overlap and the panels belong to different layers, the layer order determines which panel a component is assigned to when it is dragged and dropped on the overlapping area.
If you change the layer for a parent panel, this does not change the layer of the child components. You must change the layer for each individual component that you want to move to the same layer as the parent panel.

Using stacked panels

Panels can be used simply for the purpose of organizing and controlling groups of components, or they can also be used to create forms with several different "pages" or "views". Your form could have several "stacked" panels that you show and hide based on the user's current selection from another component, such as radio buttons or a combo box (or by using a Wizard Panel).

When using stacked panels, you must also use layers and assign the panels to layers, so that you can show and hide layers in the Form Designer and work with only the panel or panels that you want to. Otherwise you would need to continually use Send to Back / Bring to Front to move the panel you want to work with to the front. You cannot simply select the panel that you want to work with, because if that panel is actually "behind" the other stacked panels (based on rendering order), then any child components moved into or around the selected panel will actually be assigned to the panel at the front of the stack. Instead you must either move the selected panel to the front of the stack, or hide the other stacked panels in the Form Designer using layers.