Layout Templates and Design video

Layout Templates and Design video
Design the look and feel of the mobile app using layout templates and cards. (8 min)

Understanding layouts, cards, and browse pages

A layout template determines how a collection is displayed in a browse page. Items in a collection are displayed on the browse page layout as cards. When you create a layout template, you do the following:

  • Define layout properties such as the number of columns, margin and gutter values, and cell shape.
  • Create cards and define card appearance.
  • Set mapping rules based on metadata to determine which content is associated with cards.

The appearance of the browse page is determined by the layout design, the card designs, and the metadata settings of collections items.

Browse page 3-column layout
This browse page uses a 3-column layout. The layout includes full-width, 2x1, and 1x1 cards that represent banners, articles, and other collections.

Cards determine the appearance of content on the browse page. The thumbnail images can appear differently on cards that have different sizes, depending on the layout settings. For example, a thumbnail image that was once featured in a 3x1 card can change to a 1x1 card when metadata is updated.

Card layouts
The yellow area represents the same 2x2 card shown in a 3-column layout (left) and a 5-column layout with a different cell aspect ratio (right).

Note the following:

  • Within a layout template, you can define different layouts (sometimes called "renditions") for tablets, phones, and the web.
  • Pinning cards to a specific location on the grid is not yet supported.
  • Using mapping rules to determine the order of content is not yet supported. Mapping rules determine which content is applied to cards.

Using Layout Templates to create cards and layouts

The Browse Page Authoring Tool is a new method for creating cards and layouts. For the time being, you can use either the new Browse Page Authoring Tool or the existing Cards and Layouts tabs for designing your browse pages.

With the Browse Page Authoring Tool, you can use the same interface to create layouts, design cards, and map cards to content. During the creation process, you can specify an existing collection to view while you adjust browse page settings. You can change the target device size, turn on and off a grid, and click a card area to edit settings for that text or image area. You can even reorder items in the collection you've imported.

You can import layouts you've already created to create a new version based on the existing layout's settings.

Layout templates require an app built using release 2015.8 (December 2015) or later.


  1. Create a collection and add content.

  2. In the On-Demand Portal (, click Content & Layouts > Layout Templates.

  3. Click Create to define a layout template from scratch.

  4. Define the layout properties.

    Define the layout properties

    On the right side of the Browse Page Layout Tool, specify a layout name, and define layout properties such as the number of columns and margin and gutter spacing.

    Import Collection

    Click Import Collection, and import one of your collections so that you can see how your changes affect your target content. When you save the layout, you can choose to apply the layout to the collection. You can even rearrange items within the collections. These changes to the collection are preserved when you save the layout template.

    Preview Menu

    Use the preview menu to select landscape or portrait orientation. Select a target device size. As you make changes to your layout, select different device sizes to preview to make sure that your design works on all targeted devices.

  5. Create cards.

    Create cards

    Click the plus sign to create a card. In the right-most panel, specify a card name and change settings. The options in the right-most panel change depending on which card area is selected.

    To edit the text area, expand the card properties on the left side and select the item you want to work on, such as Image or Text Area. If you don't want card metadata to appear, click the Hide icon next to the metadata.

    You can also click in the center preview area to edit settings for that area. Experiment with settings above the preview area to change the zoom, display the layout or the card, or show/hide content.

  6. Define mapping rules for the cards.

    Define mapping rules for the cards

    Click "Mapping" and then click "Add Rule" next to the selected card.

    Define the mapping properties. For example, you can set a rule for banners with a high importance. As you set mapping rules, you can preview which content in your collection is assigned to that card.

    Drag items in the collection to change their order. When you save the layout template, these changes are applied.

  7. (Optional) Create additional layouts (called "renditions") to define different appearance settings for tablets, phones, and the web, as described later.

  8. Save and close the layout template.

    When you save the layout template, you are prompted to apply the layout template to the imported collection if the layout has not been assigned to that collection.

  9. Assign the layout template to collections.

    You can assign the layout template to a collection either when editing the layout template or when editing collection properties.

    Assign a layout to a collection

Layout settings

A layout helps determine the appearance of collection browse pages.

If you want to use different layouts for phones and tablets, define multiple layouts (called "layout renditions") within a layout template, as described later. 

Specify these layout settings.

Cell Aspect Ratio

Use this option to change the cell shape, which is expressed in a width:height ratio. For example, a 1:1 cell is square, a 4:3 cell is wider than it is tall, and a 3:4 cell is taller than it is wide. If you specify a positive number such as 3.5, you create a 3.5:1 aspect ratio.


Specify the number of columns. Note that a card cannot have more columns than the layout.

Gutter & Margins Units

Indicate whether you want to use Device Independent Pixels (DIP) or percentages to specify gutter and margin values. Gutters determine the spacing between cards. Margins determine the spacing between the outer edges of cards and the device view area.

Layout Background Color

Specify a color for the browse page background. This color appears in margins and gutters and can show through card transparency.

Background Image

If you select this option, the image specified for the collection Background Image is displayed in the browse page. If both a Background Image and Layout Background Color are specified, the Background Image takes precedence. If the Background Image includes transparency, the Background Color is revealed. The Background Image is full screen and scaled to fill. It's also static; cards scroll in front of the collection background.

Card settings

When you create a card, you specify design characteristics, define the number of layout cells it spans, and specify other properties. However, you do not specify which content is associated with the card—you do that when you set up mapping rules.

The actual card shape and size is determined by the layout to which the card is applied. For example, a 3x2 card applied to a 3-column layout will look much different than a 3x2 card applied to a 12-column layout.

When you specify settings, the preview area displays the approximate appearance of your card using content from the imported collection.

When you're specifying settings for cards, it's important to understand concepts such as how the different items on the card interact with each other.

Order or hierarchy

The card background sits on top of the layout. The card image area sits on top of the card background. The card text area sits on top of the card image area.

Card images

Images for collections, articles, banners, and collection backgrounds are centered, scaled, and cropped as needed to fill the card image area.

Cards are visible in a collection browse page. Cards can have certain properties which are semi-transparent and reveal the background color or image for the collection. Certain portions of a card may be semi-transparent and increase the legibility of text or tint a card image, but card images are opaque.

Card Format

When you specify an "Image Left" or "Image Right" card format, make sure that the layout on which the card appears leaves enough room for the image area and text area metadata to appear side by side. To prevent the text area from being cropped, you might need to change the layout's cell aspect ratio or increase the card width.  

Backgrounds, borders, and margins

A card can have a color and can have transparency. The card color serves as a background for the card image and text areas.

The card background can be covered by images, text areas, and borders. Image and text areas sit in front of the card background. Both images and text areas have margins.

Margins move the image and text areas away from the edge of the card. Specifying margins is how you can reveal the semi-transparent card background. Images can have color overlays with transparency to tint an image. Text areas can also have padding, which moves the labels (metadata) away from the edge of the text area.

Text areas also have color backgrounds that support transparency. You can use color backgrounds to add contrast or make the text more legible.

Borders are non-transparent and push everything in from the edge of the card. If you want an edge to your card that's semi-transparent and interacts with your layout background, use margins for your image or text areas. If you just want space between cards, use gutters in your layout.

Card setting options
The card image area is above the card background. The card text area is above the card image area.

Device Independent Pixels (DIP)

A device independent pixel (DIP) is an abstraction of a pixel for use by an app that an underlying system then converts to physical pixels. For example, specifying a 10-dip border will have the same relative size when displayed on a 1024x768 SD iPad and a 2048x1536 HD iPad.

Metadata fields

When you define metadata fields, you can include text and as many as two metadata items within the same field. For example, if you define a metadata field as {{title}} by {{author}}, the card will display article metadata such as "Fishing in Argentina by Jane Doe." Alternatively, you could create separate fields for {{title}} and {{author}} so that the metadata appears on different lines in the card.

If the content mapped to the card does not include metadata for the specified field, the field is ignored, unless the field includes additional text, such as the "by" in by {{author}}. By default, cards include three metadata fields. Click the "eye" icon in the left-most pane to hide or show each metadata field.

When you choose the {{Published Date (Default)}} metadata item, the device locale and language are used to determine the format. For example, the date is displayed as MM/DD/YYYY in English (US) and DD/MM/YYYY in German.

You can select any custom font that you have uploaded using the Fonts & App Customization section of the Portal. See Customizing AEM Mobile apps: Using custom fonts.

Mapping content to cards

Setting mapping rules to determine which cards are applied to content based on metadata. For example, you can create a mapping rule that applies a large card to any article that has a priority set to “High,” and you can create a second mapping rule that applies a smaller card to any article that has a priority set to “Normal.”

For each piece of content, the mapping rules are evaluated in sequence. The first mapping rule that matches the content metadata is applied. Content must comply with all specified rule settings. For example, if the mapping rule includes Type set to Banners and Importance set to High, the content must be a banner with a high importance for the rule to be applied.

For example, suppose that you have created a 3x1 card and a 1x1 card. Create the first mapping rule with Type=Articles and Importance=High settings. For the 1x1 card, create a second mapping rule with no metadata specified. In this example, the 3x1 rule should be above the 1x1 rule; otherwise, the high-importance articles will be assigned 1x1 cards.

Metadata used in rule settings is case-sensitive. Creating a rule with a "blue" internal keyword does not apply to content with a "Blue" internal keyword. If content includes multiple keywords, the mapping rule needs to match only one of the keywords to comply for that setting.

Note that card mapping does not determine the order of content on a browse page. It determines only which content is mapped to cards.

Rule Active

Use the "Rule Active" option to apply a card only to the specified number of items that match the criteria. For example, you can create a mapping rule that applies a wide card to only the first item in the collection. When editing the rule, select Rule Active > Sometimes, and then specify the number of items to which you want to apply this rule.

In this example, the rule applies the large card only to the first item in the collection.

Map Elements

Use the "Map Elements" option to apply a card for every nth card that matches the criteria. For example, if you want to create alternating cards, create a card that applies the rule to every second card, starting with the first item that matches the rule. In this example, every other item starting with the second item would then be formatted according to the next rule that matches the criteria.

This rule applies the card to every other item. The next qualifying rule is applied to the other alternating items.

Layout renditions for phones and tablets


Layout renditions offer design flexibility, allowing you to define different appearances for the same collection on tablets, phones, and the Desktop Web Viewer. With this new feature, it's now possible to provide the same content for all supported platforms and devices while maintaining design control. When you create a layout template, you can define different layout and card settings for tablets, phones, and the web. The rendition settings for each target device then determines appearance of the browse page, depending on the device.

Layout renditions are especially useful for projects with 1 top-level collection, but they can also be effective for projects with 2 top-level collections in which you use any of the same collections for both phones and tablets.

In the following example, the cards in this layout template have different appearances on tablets and phones.

When you create a layout template, only the tablet rendition is created initially. This is the default rendition that applies to tablets, phones, and the web unless a new phone or web layout is added. When you add a layout (also called a “rendition”) for the phone or web, the new rendition inherits the settings from the default tablet rendition. From then on, any change you make to the card or layout settings applies only to that rendition. (Card mapping rules apply to all renditions.)


If you create a layout early in the process and then realize you did so too early, you can delete that rendition, change the settings that apply to all renditions, and then re-create the rendition.

  1. Create a layout template. Create cards and apply mapping rules. Specify settings that apply to all target devices.

    As a best practice, we recommend that you start with the tablet layout, add the cards and mapping rules, and change the card and layout settings that apply to all devices. Then, create a phone layout and change settings that apply only to the phone (and then the web, if necessary). That way, you avoid specifying the same settings for each rendition.

  2. To create a phone rendition, click Phone > Add Layout, and then click Create Layout. With Phone selected, specify card and layout settings that are specific to the phone.

  3. To create a rendition for the Desktop Web Viewer, click Web > Add Layout, and then click Create Layout. With Web selected, specify card and layout settings that are specific to the Desktop Web Viewer.

  4. Save the layout template and apply it to collections. Test the results.

    Layout renditions require an app built using release 2015.8 (December 2015) or later.

To remove a layout, click to display the layout pulldown menu, and then click the trash icon. You cannot remove the default layout.

To change the target preview size, choose a different size from the device menu.

To change the default layout, click to display the layout pulldown menu, and then choose Make Default. The default layout is then used for any device type that is not specified. For example, if you have only phone and tablet layouts, and then make the phone the default, the phone layout is applied to the web.

Use the menu to change preview options, set a default, or remove the layout.

Order of cards

In general, the order of content in a collection determines the order of the content in a layout. However, if the arrangement of your cards leaves gaps in the layout along an edge, the order of content can change as edge gaps might be filled by smaller cards that are lower in the order. For example, suppose that the first article in a 3-column grid is a 2x1 card, the second item maps to a 3x1 card, and the third item maps a 1x1 card. In this case, the 1x1 card will appear in the gap in the top row above the second item.

Setting card order
The third item moves in front of the second item to fill a gap.

Deleting cards and layouts

In order to delete a layout or layout template, you must first remove all references to it from collections. Specifically, edit collections to assign a different layout. After you apply a different layout to the collections, you must then re-publish those collections if they were published. You can then unpublish the layout or layout template and delete it.

In order to delete a card that is not part of a layout template, you must first remove all references to it. Specifically, edit layouts to remove or edit all mapping rules that reference the card. After you remove or edit the layout mapping rules, you must then re-publish those layouts if they were published. You can then unpublish the card and delete it. (If a card is part of a layout template, you can delete it at any time.)

You cannot delete the default card or the default layout.

Copying layouts to a different project

You can copy layout templates from one project to another within the same account. If the destination project includes a layout template with the same name, you can determine whether to overwrite the existing layout or copy a new one.

  1. Select the layout templates you want to copy, and choose Copy Layout to Another Project.

  2. In the list of projects available in your account, select the project to which you want to copy the layouts.

  3. If you want the copied layout to replace the identically named layout in the target project, select Overwrite if exists.

    If you do not select this option, an error message appears if the target project has a layout with the same name as the copied layout.

  4. Click Copy to target.