A panel primer

Various panels are available to enable you to build complex application layouts with ease. We’ll run through each of these and explain how to declare them and the kind of layout they’ll achieve.

A word on dimensions

In order to visualise exactly how panels lay out their content, we’ll need to quickly run through how a view’s dimensions (width and height) are calculated.

There’s two ways in which this can occur:

  • If the view renders content whose dimensions can be calculated automatically, like a label or an image, its intrinsic size is used by default. With these views, you don’t need to specify any width or height.
  • Otherwise, its width and height by default are 0, unless overridden by the user

If you want a fixed width or height for a view, either can be specified in a layout, for example:

<layout>
  <relative-panel>
    <label width="50" height="50">Some content...</label>
  </relative-panel>
</layout>

Also, you can specify a minimum and maximum width and height for any view, to allow for some flexibility on a view’s size.

For example, with the demonstration below the label’s intrinsic width based on its content is used, but only up to a maximum of 100 points. This allows it to shrink if necessary, but not take up an unexpected amount of horizontal screen space if it for example has a lot of content, or a large font:

<layout>
  <relative-panel>
    <label max-width="100" height="50">Some content...</label>
  </relative-panel>
</layout>

In addition to views, panels can also have their dimensions specified. Whilst panels never display content, they are capable of being sized and positioned. We’ll see how this works in pratice later in this guide.

Relative Panel

A Relative Panel allows for views and panels to be pinned to its edges, as well as providing the ability to vertically or horizontally center a view within its bounds.

For example, in the layout below the label is horizontally centred, and pinned to the top edge with a 50 point margin:

<layout>
  <relative-panel>
    <label top="50" center-x="true">Some content...</label>
  </relative-panel>
</layout>

The following attributes are specific to children of a Relative Panel:

  • top: specifies that the view should be pinned to the top edge by a number of points
  • left: specifies that the view should be pinned to the left edge by a number of points
  • bottom: specifies that the view should be pinned to the bottom edge by a number of points
  • right: specifies that the view should be pinned to the right edge by a number of points
  • center-x: specifies that the view should be horizontally centred, this takes priority over left and right attributes
  • center-y: specifies that the view should be vertically centred, this takes priority over top and bottom attributes

Percent Panel

A Relative Panel allows for views and panels to be stacked together horizontally. This panel will stretch each child view or panel vertically to fill its bounds, and set child views and panels widths to a percentage of its overall width.

Each child view or panel must have a width specified, intrinsic widths are not taken into account. Unlike in other panels, widths are interpreted as percentages of the Relative Panel’s overall width rather than points.

For example, in the layout below we’ve specified that the first label takes up 30% of the panel’s width, and that the second label takes up the remaining 70%:

<layout>
  <percent-panel>
    <label width="30">Some content...</label>
    <label width="70">Some more content...</label>
  </percent-panel>
</layout>

We can also achieve this more naturally by making use of stretching. Stretching allows for the panel to scale a child view or panel to fill the remaining space available, for example:

<layout>
  <percent-panel>
    <label width="30">Some content...</label>
    <label stretch="true">Some more content...</label>
  </percent-panel>
</layout>

There are no restrictions on how many stretched views you have or what order these are in, allowing for some very flexible and dynamic layouts to be achieved, for example:

<layout>
  <percent-panel>
    <label width="20">Some content...</label>
    <label stretch="true">Some stretched content...</label>
    <label width="20">Some content...</label>
    <label stretch="true">Some stretched content...</label>
    <label width="20">Some content...</label>
  </percent-panel>
</layout>

In the above layout, we’re telling Prism that 60% of the panel width should be taken up by three of the labels, with the other two labels sharing the remaining space equally between them.

The following attributes are specific to children of a Percent Panel:

  • width: specifies that the view take up a percentage of its overall width
  • stretch: specifies that the view should take up a proportional share of the remaining width after laying out child views and panels that have a fixed percentage

Summing up

In this guide we’ve learnt about all of the panels that are available to use in Prism, how to declare them, how they lay out their content and all of the attributes you can make use of to customise their behaviour.

In the next guide, we’ll run through all of the available views you can use, and how to interact with them from JavaScript.