Your first layout

Prism layouts function quite similar to Android layouts. They’re not like HTML, they don’t semantically describe a document, rather they describe a visual layout for an application.

Layouts contain panels and views. Panels are responsible for managing the flow and layout of views, whereas views are responsible for displaying visual content.

For this guide, we’re going to make use of a single panel, and a single view, and update the view’s content from JavaScript. We’ll be continuing with the application we built last time.

Before continuing, it may help to remove the window.alert call we added previously in order to prevent the layout being obscured when we test out our application.

Building the layout

Open up the index.xml file. You’ll notice that it’s currently empty, like the example below:

<layout>
</layout>

Let’s add our first panel. For this guide we’re going to make use of a Relative Panel. A Relative Panel allows for views to be pinned to its edges, as well as providing the ability to vertically or horizontally center a view within its bounds.

Declaring a panel or a view is as simple as adding a new child element to the root <layout> element:

<layout>
  <relative-panel>
  </relative-panel>
</layout>

If you run your application now, you’ll observe that nothing’s changed visually. That’s because panels don’t render anything themselves, rather they act as visual containers for views. Let’s change that by adding a new view.

For our view, we’re going to make use of a Label view. Labels display plain text, with basic options for styling the font, text colour, and size.

Let’s go ahead and declare our label:

<layout>
  <relative-panel>
    <label left="10" right="10" top="10" bottom="10">Hello world!</label>
  </relative-panel>
</layout>

There’s a few things to point out about this view we’ve declared. Firstly, the left, top, right and bottom attributes are used for the Relative Panel to determine how to position the Label view within itself. With these four attributes, we’re telling the Relative Panel to pin our label 10 points from each edge. This provides a nice margin for the label, and allows it to stretch to fill its container.

Secondly, you’ll observe that we don’t specify the unit type for these four attributes. In almost all cases there’s only one unit type available for view positioning and dimension attributes - points. Points are logical units corresponding to a single pixel multiplied by the scale of the current display. For example, if your screen scale is 2x, a single point corresponds to two pixels. This is all handled for you by Prism’s layout system and the operating system itself.

Finally, you’ll observe that we’ve given this label some initial content. This will be the default content displayed within this view. You don’t need to specify default content for any view, however it’s more efficient to use this means of setting a view’s content if the content will never change.

Go ahead and run the application now. You’ll observe we now have a label that stretches and shrinks to fit the application window.

Updating a view dynamically

Just like in a web browser, each view can have an id. An id is an identifier used to refer to that particular view from JavaScript. Again like in a web browser, every view within a layout that has an id set is accessible on the window object. Unlike a web browser, identifiers are case sensitive, so bear that in mind.

Let’s see how this works in practice. Firstly, let’s add our id attribute to the label we created earlier:

<layout>
  <relative-panel>
    <label id="myLabel" left="10" right="10" top="10" bottom="10">Hello world!</label>
  </relative-panel>
</layout>

Now that our label has an identifier, it’s accessible from JavaScript as soon as the layout’s loaded. Let’s try changing the content dynamically.

Update your index.js file to look like the following example:

application.on('start', () => {
  setTimeout(() => {
    window.myLabel.value = `Content changed`
  }, 3000)
})

In the above example, we’re telling Prism that after 3 seconds (achieved via the setTimeout API), update our label’s content to 'Content changed'.

Go ahead and run the application again, after 3 seconds you’ll observe that the content of the label has changed.

Try playing around with more and less text. You’ll notice that the content of the label automatically shifts as the window is resized. There’s no extra effort involved for Prism to achieve a natural layout for its views, and all Prism layouts are automatically responsive.

Summing up

In this guide we’ve learnt how to declare panels and views, customise how views are positioned within a panel, and set their content both statically and dynamically.

In the next guide, we’ll run through all of the available panels you can use, and how to combine them to achieve the more complex layouts you’d usually find within a standard application.