Guides and Sample Code

Developer

Apple News Format: Design Tutorial

On This Page

Component Layout Objects

Apple News Format lets you lay out components using component layout objects, which are used together with the article’s column system.

Component Layout Objects and the Column System

The column system defines parameters for where objects in your article can be positioned; component layout objects determine the positions of individual objects within this set of parameters.

In Apple News Format, “columns” does not refer to columns of text, but rather to a grid-like set of equal-width, vertical segments that are used for layout. Apple News Format refers to these columns by number, from left to right, starting with 0.

You define an article’s column system in the article’s top-levellayout property. This column system is the number and spacing of the columns given a certain device width.

For the purposes of this tutorial, the example article has ten columns when the display width is 1024 pixels. The number of columns decreases on narrower displays but will never increase. The figure below shows the example article on three different devices. The blue areas indicate columns. In this example, there are ten columns on this iPad Pro, seven on this iPad in portrait, six on this iPhone in landscape, and three on this iPhone in portrait.

image: ../Art/columns-ten_2x.png

You’ll use component layout objects to determine where a component is horizontally aligned within the column system of the article, how wide the component is, and the vertical spacing between components.

You’ll do this by adding component layout objects within the top-level componentLayouts property of the article. Then you’ll refer to the names of the component layout objects within individual components.

To learn more about the column system, you can start with layout at the end of this tutorial. For information on customizing component layout objects, see Component Layout in the Apple News Format Reference.

Component Layout Object Properties

You’l use the following properties of component layout objects:

  • columnStart indicates which column the component's left edge is aligned with. By default, the component is aligned to the leftmost column, which is column 0. You’ll align all components to this default.

  • columnSpan indicates how many columns the object spans. By default, the component spans the entire width of its container component, if applicable, or the entire width of the document. You’ll use a width of 7, giving the article a wide right margin.

  • margin sets the spacing above and below each component, in points, either as a single integer for both top and bottom or as an object containing separate properties for top and bottom.

For example, a component using a columnStart value of zero and a columnSpan value of seven spans the leftmost seven columns of the article. If that component’s layout has a top margin of 0 and a bottom margin of 24, some space is added below the component but not above it.

For more properties of component layout objects, see Component Layout in the Apple News Format Reference.

JSON Example: References to Component Layout Objects

Add references to component layout objects inside components. You’ll define the component layout objects themselves later.

Example Code

Ellipses (...) indicate lines of code that have been omitted from this example.

  1. {
  2. ...
  3. "components": [
  4. {
  5. "role": "heading1",
  6. "layout": "heading1Layout",
  7. "text": "HEADING"
  8. },
  9. {
  10. "role": "title",
  11. "layout": "halfMarginBelowLayout",
  12. "text": "ARTICLE TITLE"
  13. },
  14. {
  15. "role": "intro",
  16. "layout": "halfMarginBelowLayout",
  17. "text": "Etiam rhoncus. Maecenas tempus, tellus eget condimentum rhoncus, sem quam semper libero, sit amet adipiscing sem neque ipsum?"
  18. },
  19. {
  20. "role": "byline",
  21. "layout": "fullMarginBelowLayout",
  22. "text": "By Urna Semper"
  23. },
  24. {
  25. "role": "body",
  26. "format": "html",
  27. "layout": "noMarginLayout",
  28. "textStyle": "bodyFirstDropCap",
  29. "text": "<p>Nam libero tempore, cum soluta nobis est eligendi optio cumque nihil impedit quo minus id quod maxime placeat facere possimus, omnis voluptas assumenda est, dolor repellendus. <a href='http://www.apple.com'>Link text</a> quibusdam et aut.</p><p>Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, adipisci velit.</p>"
  30. },
  31. {
  32. "role": "heading2",
  33. "layout": "fullMarginAboveHalfBelowLayout",
  34. "text": "LOREM IPSUM DOLOR"
  35. },
  36. {
  37. "role": "body",
  38. "format": "html",
  39. "layout": "noMarginLayout",
  40. "text": "<p>Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur? At vero eos et accusamus et iusto odio ducimus qui blanditiis.</p><p>Cras ultricies mi eu turpis hendrerit fringilla. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; In ac dui quis mi consectetuer.</p><p>Temporibus autem et aut officiis debitis aut rerum necessitatibus saepe eveniet ut et voluptates repudiandae sint et molestiae non recusandae. Itaque rerum hic tenetur.</p><p>Inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo esciunt enim ipsam voluptatem quia.</p><p>Ut aut reiciendis voluptatibus maiores alias consequatur aut perferendis <a href='http://www.apple.com'>link text</a> repellat. Sed ut perspiciatis unde omnis iste natus sit voluptatem accusantium doloremque, totam rem aperiam, eaque ipsa quae ab illo inventore.</p><p>Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni.</p>"
  41. },
  42. {
  43. "role": "heading2",
  44. "layout": "fullMarginAboveHalfBelowLayout",
  45. "text": "HEADING"
  46. },
  47. {
  48. "role": "body",
  49. "format": "html",
  50. "layout": "noMarginLayout",
  51. "text": "Sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas."
  52. },
  53. {
  54. "role": "heading2",
  55. "layout": "fullMarginAboveHalfBelowLayout",
  56. "text": "HEADING"
  57. },
  58. {
  59. "role": "body",
  60. "format": "html",
  61. "layout": "noMarginLayout",
  62. "text": "Et harum quidem rerum facilis est et expedita distinctio. Nam libero tempore, cum soluta nobis est eligendi optio cumque nihil impedit quo minus id quod maxime placeat facere possimus, omnis voluptas est, omnis dolor repellendus."
  63. },
  64. {
  65. "role": "heading2",
  66. "layout": "fullMarginAboveHalfBelowLayout",
  67. "text": "HEADING"
  68. },
  69. {
  70. "role": "body",
  71. "format": "html",
  72. "layout": "noMarginLayout",
  73. "text": "<p>Consequatur aut doloribus asperiores repellat. Sed ut perspiciatis unde omnis iste natus error sit volup tatem accusantium doloremque laudantium, totam rem, eaque ipsa quae ab illo inventore veritatis et quasi archit ecto beatae vitae.</p><p>Nemo enim ipsam volup tatem quia voluptas sit aspernatur aut odit aut fugit, sed quia conse quuntur magni. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam.</p><p>Consequatur aut perferendis doloribus asperiores repellat. Sed ut perspiciatis unde omnis iste natus error sit volup tatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi archit ecto beatae vitae dicta. Nemo enim ipsam volup tatem quia voluptas sit <a href='http://www.apple.com'>link text</a> aut odit aut fugit, sed quia conse quuntur perspiciatis doloribus magni dolores.</p><p>Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam suscipit laboriosam.</p>"
  74. },
  75. {
  76. "role": "heading2",
  77. "layout": "fullMarginAboveHalfBelowLayout",
  78. "text": "HEADING"
  79. },
  80. {
  81. "role": "body",
  82. "format": "html",
  83. "layout": "noMarginLayout",
  84. "text": "Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur? At vero eos et accusamus et iusto odio. Dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati."
  85. },
  86. ],
  87. ...
  88. }

JSON Example: Component Layout Objects

Define the noMarginLayout, heading1Layout, halfMarginBelowLayout, fullMarginBelowLayout, and fullMarginAboveHalfBelowLayout component layout objects that are referred to in the example above. Within each of these component layout objects, specify that the component begins in the leftmost column and spans seven of the article’s ten columns. This will create readable line lengths and asymmetrical whitespace.

The names of these component layout objects are not specified by Apple News Format; when you create your own articles, you can create names for your component layout objects. For the purposes of this tutorial, a “full” margin was considered to be a 24-point space above a or below a component, a “half” margin to be a 12-point space, and a “quarter” margin to be a 6-point space. See also: JSON Naming Requirements and Conventions.

Example Code

Ellipses (...) indicate lines of code that have been omitted from this example.

  1. {
  2. ...
  3. "componentLayouts": {
  4. "noMarginLayout": {
  5. "columnStart": 0,
  6. "columnSpan": 7
  7. },
  8. "heading1Layout": {
  9. "columnStart": 0,
  10. "columnSpan": 7,
  11. "margin": {
  12. "top": 24,
  13. "bottom": 3
  14. }
  15. },
  16. "halfMarginBelowLayout": {
  17. "columnStart": 0,
  18. "columnSpan": 7,
  19. "margin": {
  20. "bottom": 12
  21. }
  22. },
  23. "fullMarginBelowLayout": {
  24. "columnStart": 0,
  25. "columnSpan": 7,
  26. "margin": {
  27. "bottom": 24
  28. }
  29. },
  30. "fullMarginAboveHalfBelowLayout": {
  31. "columnStart": 0,
  32. "columnSpan": 7,
  33. "margin": {
  34. "top": 24,
  35. "bottom": 12
  36. }
  37. }
  38. },
  39. ...
  40. }

Further Exploration

Apple News Format: Advanced Design Tutorial covers some more complex uses of component layout objects and the column system, including laying out components next to the article body or inset within the article body.