APL Layout

An APL layout is a named composite component, defined in an APL document or package. The layout is a function that expands (inflates) into a collection of other named layouts and primitive components. An APL layout supports passing arguments in a parameters array. The inflation of the APL layout is conditional, as different components can be inflated based on the current data-binding context.

• Sample layout
• Properties
  • item(s)
  • parameters
• Layout inflation

Sample layout

In this example, the header layout accepts two parameters: title and logo. The title parameter is passed to a Text component, and the logo parameter is passed to an Image. The Header component inflates into a column-based Container on a round viewport and places the logo above the title. On a rectangular viewport, the logo is placed to the right of the title.

{
  "Header": {
    "description": "A basic header with a title and a logo",
    "parameters": [
      {
        "name": "title",
        "type": "string"
      },
      {
        "name": "logo",
        "type": "string",
        "default": "http://images.amazon.com/default_logo.png"
      }
    ],
    "items": [
      {
        "when": "${viewport.shape == 'round'}",
        "type": "Container",
        "direction": "column",
        "items": [
          {
            "type": "Image",
            "source": "${logo}",
            "height": 36,
            "width": 36
          },
          {
            "type": "Text",
            "text": "${title}",
            "style": "textStylePrimary2"
          }
        ]
      },
      {
        "type": "Container",
        "direction": "row",
        "paddingLeft": 20,
        "items": [
          {
            "type": "Text",
            "text": "${title}",
            "style": "textStyleSecondary2"
          },
          {
            "type": "Image",
            "source": "${logo}",
            "height": 40,
            "width": 40
          }
        ]
      }
    ]
  }
}

Properties

item(s)

The item property is either a single component or, if items, an array of components. Other layouts can also be part of the item(s), provided they have already been imported or defined earlier in the layouts object. See Data-binding evaluation.

parameters

The parameters are named values that can be passed to a layout. Each parameter is an object with the following properties:

The parameter type is a string that defines the type of the value expected in the parameter. It should be one of the following:

• any
• array
• boolean
• color
• component
• dimension
• integer
• map
• number
• object
• string

The parameter name should be a unique name starting with an upper- or lower-case letter and containing no white space.

For convenience, a simple parameter name may be used instead of the parameter object (such as "title" instead of { "name": "title", ... }. This format is not recommended, but it does allow compact layout definition for those cases where no type coercion or default values are required.

Layout inflation

Layouts are inflated with the following algorithm:

• Each parameter is evaluated and added to the data-binding context.
• The item property is evaluated using the single child algorithm.
• Properties assigned to the layout but not matching a named parameter, item, or type are passed to the item for evaluation.

Consider a sample layout definition:

"myLayout": {
  "parameters": [
    "title",
    "subtitle"
  ],
  "item": [
    {
      "when": "${viewport.width > viewport.height}",
      "type": "Text",
      "text": "<b>${title}:</b> ${subtitle}",
      "style": "textStyleHeading1"
    },
    {
      "type": "Text",
      "text": "<b>${title}</b><br>${subtitle}",
      "style": "textStyleHeading2"
    }
  ]
}

Now invoke the layout with:

{
	"type": "myLayout",
	"title": "Frankenstein",
	"subtitle": "or, The Modern Prometheus",
	"color": "green"
}

The inflation logic proceeds as follows.

First, the "title" and "subtitle" parameters are added to the data-binding context.

Next, the item property is evaluated. Assuming that this code executes on a landscape screen, the first component in the item array is selected.

Finally, the extra properties from the original invocation are passed to the component. In this case, the color property. The net result is the Text component will be created (after data-binding) with:

{
	"type": "Text",
	"text": "<b>Frankenstein</b>: or, the Modern Prometheus",
	"style": "textStyleHeading1",
	"color": "green"
}