A view review

Views enable you to display various types of content within your application. We’ll run through each of these and explain how to declare them and how to access them from JavaScript.

Common attributes

Views support a series of common attributes that can be used regardless of the kind of view:

  • id: identifies the view enabling it to be accessed from JavaScript
  • top: signals to the parent Panel that this view should be positioned from the top by the specified number of points
  • left: signals to the parent Panel that this view should be positioned from the left by the specified number of points
  • right: signals to the parent Panel that this view should be positioned from the right by the specified number of points
  • bottom: signals to the parent Panel that this view should be positioned from the bottom by the specified number of points
  • center: if “true”, signals to the parent Panel that this view should be centred horizontally and vertically
  • center-x: if “true”, signals to the parent Panel that this view should be centred horizontally
  • center-y: if “true”, signals to the parent Panel that this view should be centred vertically
  • width: signals to the parent Panel that this view should have the specified width in points
  • height: signals to the parent Panel that this view should have the specified height in points
  • min-width: signals to the parent Panel that this view should have the specified minimum width in points
  • min-height: signals to the parent Panel that this view should have the specified minimum height in points
  • max-width: signals to the parent Panel that this view should have the specified maximum width in points
  • max-height: signals to the parent Panel that this view should have the specified maximum height in points
  • stretch: if “true”, signals to the parent Panel that this view should stretch to fill remaining space

View

A View displays a solid background colour, which can be useful to visually separate areas of your user interface.

Views can be declared like so:

<view />

The following attributes are specific to a View:

  • background-colour: fills the view with the specified hex background colour e.g. #FF0000 (RGB) or #FF0000FF (RGBA)

Label

A Label displays plain text. It has built-in support for displaying text across multiple lines with text wrapping and basic styling options.

Labels can be declared like so:

<label>Some content...</label>

A Label can be accessed from JavaScript like so:

window.myLabel.value = 'New label content'

The following attributes are specific to a Label:

  • foreground-colour: sets the label’s text colour to be the specified hex colour e.g. #FF0000 (RGB) or #FF0000FF (RGBA)
  • font-name: sets the label’s font name to be the specified font, unlike in CSS you specify a single font name here
  • font-size: sets the label’s font size to be the specified size in points
  • alignment: sets the label’s text alignment as one of “left”, “right”, “center” or “justified”
  • weight: sets the label’s font weight as one of “regular” (default) or “bold”

Button

A standard system button.

Buttons can be declared like so:

<button>Tap me!</button>
  • background-colour: fills the button with the specified hex background colour e.g. #FF0000 (RGB) or #FF0000FF (RGBA)
  • foreground-colour: sets the button’s text colour to be the specified hex colour e.g. #FF0000 (RGB) or #FF0000FF (RGBA)
  • font-name: sets the button’s font name to be the specified font, unlike in CSS you specify a single font name here
  • font-size: sets the button’s font size to be the specified size in points
  • style: set the button’s style to one of:
    • “system”: renders the button with the default system style, ignoring any other styling options
    • “custom”: renders the button with the specified styling options
  • weight: sets the button’s font weight as one of “regular” (default) or “bold”

A Button can be accessed from JavaScript like so:

window.myButton.value = 'New button title'
window.myButton.on('click', () => window.alert('You clicked the button!'))

Checkbox

A standard system checkbox.

<checkbox>Check me!</checkbox>

Please note that on iOS checkboxes render without a label unlike other platforms. This is due to the fact that on iOS these controls are often displayed separately from their label as part of a list item, e.g. in settings screens. It’s recommended that you use platform-specific layout files to cater for this. This will be covered in a later guide.

A Checkbox can be accessed from JavaScript like so:

window.myCheckbox.value = 'New label title'
window.myCheckbox.checked = true
window.myCheckbox.on('click', () => window.alert('You clicked the checkbox!'))

Image

An Image displays a static image with various scaling options.

Images can be declared like so:

<image src="my-image" />

The following attributes are specific to an Image:

  • “src”: sets the image’s content to the specified image
  • “content-mode”: sets the image scaling mode for the displayed image as one of:
  • “default”: clips any part of the image outside of the bounds of the view
  • “stretch”: stretches the image to fit the bounds of the view, potentially distorting the image in one or both dimensions
  • “aspect-fit”: scales the image up or down to fit the bounds of the view taking into account its aspect ratio, parts of the view may be transparent
  • “aspect-fill”: scales the image up to fit the bounds of the view taking into account its aspect ratio, parts of the image may be clipped to ensure the image is fully within the view’s bounds

An Image can be accessed from JavaScript like so:

const imageData = new Buffer(...) // contains contents of an image file e.g. PNG/JPEG/etc.
window.myImage.data = imageData

One thing you may have noticed - in the image’s src attribute we never specify a file extension, just a name. This is for similar reasons to layouts where we never specify the .xml file extension. Prism will look up at runtime the most specific image that’s appropriate for your device. If you follow the standard iOS naming convention for images, an image with the correct scale will be chosen automatically, ensuring that an image of sufficient quality is loaded.

Here’s some examples of this naming convention:

  • my-image.png: a @1x image, for screens with a low DPI where one point = one pixel
  • my-image@2x.png: a @2x image, for screens with a high DPI where one point = four pixels
  • my-image@3x.png: a @3x image, for screens with a high DPI where one point = nine pixels

You may also wonder, if we don’t specify the file’s extension then what happens if we have a JPEG and a PNG for example with the same name? Well other than the obvious response - “don’t do that”, Prism’s decision making doesn’t change. It’ll pick the highest quality, most specific image for your device, so it’ll naturally chose the PNG over the JPEG, unless of course the JPEG has a scale factor that’s not present in PNG form.

It’s recommended to keep things simple and stick to a single file format. PNGs are recommended for most UI resources due to their lossless nature. You can massively reduce them in size by crushing them.

Input

An Input displays a text field to prompt for user input.

Inputs can be declared like so:

<input />

The following attributes are specific to an Image:

  • background-colour: fills the input with the specified hex background colour e.g. #FF0000 (RGB) or #FF0000FF (RGBA)
  • foreground-colour: sets the input’s text colour to be the specified hex colour e.g. #FF0000 (RGB) or #FF0000FF (RGBA)
  • font-name: sets the input’s font name to be the specified font, unlike in CSS you specify a single font name here
  • font-size: sets the input’s font size to be the specified size in points
  • style: set the input’s style to one of:
    • “default”: default styling, ignoring custom styling options
    • “rounded”: uses rounded borders, like search input fields on macOS (may render as “default” on some platforms)
    • “custom”: custom styling, uses custom styling options
  • border-style: set the input’s border style to one of “default” (visible) or “none” (invisible)
  • weight: sets the input’s font weight as one of “regular” (default) or “bold”
  • placeholder: set the input’s placeholder text, which is displayed when no text has been added to the field by the user (may not be visible on all platforms)

An Input can be accessed from JavaScript like so:

window.myInput.value = 'Some value'
window.myInput.on('change', () => console.log(`You changed the input's text to ${window.myInput.value}!`))

Summing up

In this guide we’ve learnt about all of the views that are available to use in Prism, how to declare them, accessing them from JavaScript, and all of the attributes you can make use of to customise their behaviour.

These aren’t the only views available to you, in a later guide we’ll run through the more advanced views that are used to build layouts with dynamic content.

In the next guide, we’ll run through how to achieve navigation within your application.