Guides and Sample Code

Developer

Apple News Format: Design Tutorial

On This Page

Top-Level Properties

Below are descriptions of each of the top-level properties in the article in this tutorial.

Some of these properties are required in every Apple News Format article, and some are optional.

title (Required)

The top-level title property of the article is the article title or headline that appears in feeds, such as a channel feed, topic feed, or For You. Do not use HTML or Markdown for this property. For more details, see Top-Level Properties in the Apple News Format Reference.

metadata (Optional)

The top-level metadata property of the article is an object that can contain properties that describe the article.

This tutorial uses the following two child properties of the top-level metadata property:

  • thumbnailURL—The URL of an image to represent this article in feeds. For best results, provide a high-resolution image. For thumbnail image requirements, see Image Guidelines and Article Metadata in the Apple News Format Reference.

  • excerpt—A short summary of the article, which is often also a direct excerpt from the article text. This short summary appears in feeds. Although this property is optional, it’s best to define it in all of your Apple News Format documents. Do not use HTML or Markdown for this property.

The metadata property can also hold a canonical URL, a publication date, authors, and other information that is not part of the core article content. For more details, see Article Metadata in the Apple News Format Reference.

version (Required)

The top-level version property of the article indicates the version of Apple News Format that is used. The value of the version property must not be earlier than the version number of any property that is used anywhere in the article. For the version numbers of properties, see the Apple News Format Reference. For more details about the version property, see Top-Level Properties in the Apple News Format Reference.

identifier (Required)

The top-level identifier property of the article is a unique, publisher-provided article identifier. This identifier must remain constant; it must not change when the article is updated. For details, see Top-Level Properties in the Apple News Format Reference.

language (Required)

The top-level language property of the article is a string that indicates the language of the article. Use the IANA.org language subtag registry to find the appropriate string. For example, use en for English. You can also use a more specific string, such as en_UK for U.K. English, or en_US for U.S. English. For details, see Top-Level Properties in the Apple News Format Reference.

layout (Required)

The top-level layout property of the article uses four child properties—columns, width, margin, and gutter—to define the column system for the article as a whole. This column system tells News which horizontal positions are available for article components (such as images and headings). For more details, see Component Layout Objects in this tutorial, or see Layout and The Column System in the Apple News Format Reference.

The layout property has the following four child properties:

  • columns—The number of columns for the article’s column layout. Columns divide the article into equal-width, vertical segments. Apple News Format refers to these columns by number, from left to right, starting with 0. Later, you can align the left edge of any component, such as an image or a heading, to the left edge of a specific column. If this property is omitted, a default value of 7 is applied.

    When choosing a number for this property, think about how you want components arranged relative to one another horizontally. Should the entire design be symmetrical or asymmetrical? Do you want images aligned to the same horizontal position as the body, or a different horizontal position? For example, the image below shows an asymmetrical layout with both inset and marginal elements.

    image: ../Art/Overview_2_2x.png

    Once you know the general horizontal placements you need, imagine a grid that would overlay neatly on your design. Choose a number of columns that subdivides an article sufficiently to provide the horizontal alignments you need. For the layout above, 10 columns are needed. Finally, make sure to verify on some smaller devices.

  • width—The screen width that this article was designed for, in points. On screens that are narrower than this value, the number of columns will be reduced proportionately. On screens that are wider, the article contents will consume exactly this width, centered on the screen. If this property is omitted, a default width of 1024 is applied.

  • margin—The left and right margins of the article, in points. If this property is omitted, a default article margin of 60 is applied.

  • gutter—The spacing between columns, in points. If this property is omitted, a default gutter size of 20 is applied.

documentStyle (Optional)

The top-level documentStyle property of the article supports the child property backgroundColor, which sets the background color for the article. For more details, see Document Style in the Apple News Format Reference. For guidelines on using color, see Color in the iOS Human Interface Guidelines.

components (Required)

The top-level components property of the article holds the array of component objects, or components. These components hold the article content, such as article text, heading strings, and image URLs. Sometimes a component will not contain content but instead will control structural groupings like sections. For more information, see Using Components in this tutorial and Component in the Apple News Format Reference.

Each component has a role property that defines that component’s semantic function in the article. For example, a component with a role of body contains body text. For a list of all possible component roles, see Component Role Summary in the Apple News Format Reference.

Some important optional properties within a component object are layout, which can refer to a component layout object defined in componentLayouts, and textStyle, which can refer to a component text style object defined in componentTextStyles.

textStyles (Optional)

The top-level textStyles property of the article contains text style objects, or text styles, that get applied to ranges of characters. The textStyles property is not used in this tutorial.

For more information on the textStyles property, see Text Style in the Apple News Format Reference.

componentLayouts (Optional)

The top-level componentLayouts property of the article contains component layout objects. These objects determine where components, such as headings and images, are placed in the article’s column system.

In this tutorial, component layout objects are placed in this top-level componentLayouts property. You can also place component layout objects inside of components.

For more details, see Component Layout Objects in this tutorial and Component Layout in the Apple News Format Reference. For information on aligning containers, see Anchor in the Apple News Format Reference.

componentStyles (Optional)

The top-level componentStyles property of the article contains component style objects that can be applied to specific components or to all components that have a certain role. These styles affect design properties such as background and border. The componentStyles property is not used in this tutorial. For more information, see Component Style in the Apple News Format Reference.

componentTextStyles (Optional)

The top-level componentTextStyles property of the article contains component text style objects that can be applied to specific components or to all components that have a certain role.

In this tutorial, component text style objects are placed in this top-level componentTextStyles property. You can also place component text style objects inside of components.

For more details, see Component Text Style in the Apple News Format Reference.