The object for defining columns, gutters, and margins for your article’s designed width.
Technology
- Apple News Format 1.7+
Properties
columns
integer
The number of columns this article was designed for. You must have at least one column.
Using a 7-column design allows components to start in columns 0 to 6, and be between 1 and 7 columns wide. An article that is designed with 7 columns provides sufficient layout information to automatically resize for iPad, Mac, and iPhone sizes. An article designed with 20 columns provides more detail for the layout system and a better reading experience. Below 5 columns there may not be sufficient information for the layout system to automatically maintain your intended design when scaling down to smaller devices.
width
integer
The width
(in points) this article was designed for. This property is used to calculate down-scaling scenarios for smaller devices.
The width of the document must be sufficient to fit two margin values and the gutter values that will be needed between each of the columns.
The width
cannot be negative or 0
. As a best practice, set the width to the width of the iPad device. This helps you see the effects of positioning components in different columns.
This property is used to automatically scale down article content for smaller devices. With a 7-column design and a width of 1024
points, the design is optimal for a landscape aspect ratio on an iPad device and will scale down on iPhones.
gutter
integer
The gutter size for the article (in points). The gutter provides spacing between columns. This property should always be an even number; odd numbers are rounded up to the next even number. If this property is omitted, a default gutter size of 20 is applied. If the gutter is negative, the number is set to 0.
Note that the first column does not have a left gutter, and the last column does not have a right gutter.
The width of the document must be sufficient to fit two margin values and the gutter values that will be needed between each of the columns.
Note that when using a width of 1024, a margin of 60, and 7 columns, the gutter cannot be greater than 150.
margin
integer
The outer (left and right) margins of the article, in points. If this property is omitted, a default article margin of 60 is applied. If the margin is negative, the number is set to 0. If the margin is greater than or equal to the width/2, the article delivery will fail.
The margins is sized down slightly when the article is automatically scaled down for smaller devices.
Discussion
Use the Layou
t object to define the column-system rules for the components in your document. The column system controls the horizontal position and spacing of your components. The News app uses this information to automatically resize your article for different screen sizes. Configuring your article with 20
columns, a 60
-point margin, and a 20
-point gutter should give you a sufficiently flexible layout.
After you define your article's layout, add its components to ArticleDocument.componentLayouts and then position each component using a ComponentLayout object.
This object can be used in ArticleDocument.
Example
{
"version": "1.7",
"identifier": "SampleArticle",
"language": "en",
"title": "Apple News",
"subtitle": "A look at the features of Apple News",
"layout": {
"columns": 20,
"width": 1024,
"margin": 60,
"gutter": 20
},
…
}