Marfeel Docs

# Layout descriptor

Marfeel offers a wide range of layouts to display article lists in section pages. You can create a layout if none fit your needs.

Tenants can choose between those layouts, and use different ones.

For example, here is a screenshot of a photo layout and a photo_grid_2 layout one after the other on a section page:

photo

Layouts are declared in JSON files that are located in the layoutsDescriptor folder of the Tenant's theme. The layouts loop on the page until all the articles are displayed.

The name of these files can be:

  • default: the layout configuration in this file applies to every section page of the Tenant.
  • The name of a section: this will override the default layout configuration for a specific section page. The name of this file needs to match the one defined in the definition.json file.
  • extraLayouts: when using pre-defined content groups, the layouts they depend on must be listed in this file.

This is the directory structure they follow:

www.example.com
│
└─── themes
  └─── default
    └──── layoutsDescriptor
      ├──── default.json
      ├──── home.json
      ├──── travel.json
      └──── extraLayouts.json

Check if layout descriptor is enabled

The configuration of layouts with layoutDescriptor must be enabled in the themeDescriptor.json file of each Tenant. It is already enabled by default for newer tenants.

A layout descriptor can contain the following attributes:

  • layouts: mandatory array. It contains as many items as needed to describe the section's structure. Those items can be strings, arrays, or objects. See the layouts attributes page to learn more.
  • maxArticles: optional number. Determines how many articles can be displayed in the section and how many articles the MarfeelPressRipper extracts if used. Defaults to 200, and ignores any smaller number on rendering.
  • tailLayouts: Optional array. Its content has the same type as layouts, but is guaranteed to appear at the bottom of the section page. These layouts must have a key.

For example, the home.json file of a Tenant using photo, photo_grid_2 layouts, could look like this:

{
  "maxArticles": 20,
  "layouts": [
    {
      "name": "photo/photo",
      "attr": {
        "headlines": {
          "author" : false
        }
      }
    },
    {
      "name": "photo/photo_grid_2",
      "attr": {
        "count": 2,
        "headlines": {
          "author" : false
        }
      }
    }
  ],
  "tailLayouts": [
    {
      "name": "newspaper/pill",
      "key": "bottom-articles"
    }
  ]
}

# Layouts attributes

The characteristics of every layout are specified with attributes that can be used when defining a layout in a layout descriptor. Whenever possible, take advantage of layout shortcuts.

Content Groups specific attributes are described in the dedicated article.

# name

Path of the layout template, starting from marfeel/themes/default/layouts (opens new window). Keep the theme name, but drop the extension:

{
  "name": "newspaper/thumb_card"
}

Usages

Can be shortened to the template name only, see the shortcuts section.

# count

Optional. How many times this layout is repeated in a row. Defaults to 1.

{
  "name": "newspaper/thumb_card",
  "count": 2
}

`count` attribute position

The count attribute has a different effect if placed inside the attr object. Check the count inside attr header.

# repetition

Optional number. When the layout list has been entirely consumed, but there are still articles to display, the layout list starts from the beginning. This attribute lets you control how many loops a layout is included. Defaults to ∞.

A value of 1 means the layout should only appear in the first iteration, and never further in the page.

{
  "name": "newspaper/thumb_card",
  "repetition": 1
}

# attr and its content

Optional object. It specifies additional attributes used by special composite layouts or content groups.

# count inside attr

Optional. How many items this layout consumes. It defaults to 1: if the current template should consume more than one article (eg. a slider, a grid), you must set it to the appropriate value.

{
  "name" : "photo/photo_grid_2",
  "attr": {
    "count" : 2
  }
}

Check the content-group specific information about this attribute.

# pocket

Optional Object. See the content groups documentation.

`pocket` in whiteCollar vs. `pocket` in layoutDescriptor

Those 2 objects are unrelated. The layout descriptor's pocket is about the layout and its characteristics, while the WhiteCollar's pocket is about the article item.

# exclude_used_articles (MarfeelPress specific)

Optional boolean, defaults to true.

Place this attribute inside the pocket in order to allow articles to repeat themselves in section pages:

{
  "layouts": [{
    "name": "photo/photo",
    "pocket": {
      "exclude_used_articles": false
    }
  }]
}

# headlines

Optional. This feature specifies if we want to show the title, the author, the date and the categories in a layout and in which order we want them to appear.

{
  "layouts": [{
    "name": "photo/photo",
    "attr": {
      "headlines": {
        "date": true,
        "order": ["DATE", "TITLE", "CATEGORIES"],
        "categoryList": true
      }
    }
  }]
}
  • title inside headlines is true by default
  • date, subtitle, author. categories are all false by default.

Properties set to true but not available (eg. no author extracted for an article) are ignored.

Default order is: ["CATEGORIES", "SUBTITLE", "TITLE", "AUTHOR", "DATE"].

MarfeelPress special

The categoryList option is available for MarfeelPress Tenants only.

# showTitle

Optional boolean. Defaults to true. It is equivalent to the title boolean inside headlines, but the value inside headlines has priority over this one.

{
  "name": "balcon",
  "showTitle": false,
  "attr": {
    "balconLayout": "slider",
    "count": 10
  }
}

# Layout attributes by key - attrByKey

WARNING

Works only in combination with startswith: content group feature.

Optional. Allows specific layout configuration of a content group by key within a startswith structure.

Example of use: A group of content groups defined by startswith:default- share layouts but two of them ("default-videos" and "default-rank") require a different layout.

{
  "name": "balcon",
  "key": "startsWith:default-",
  "count": 10,
  "attr": {
    "balconLayout": "slider",
    "count": 10
  },
  "attrByKey": {
    "default-videos": {
      "balconLayout": "videoSlider"
    },
    "default-rank": {
      "balconLayout": "ranking",
      "count": 5
    }
  }
}

# Layout shortcuts

Layouts can either be defined in the long, detailed version described above or a shorter one. For example, the following layout definitions are equivalent:

# Layout name only

{
  "name": "newspaper/thumb"
}

Vs.

{
  "newspaper/thumb"
}

# Layout and count

{
  "name": "newspaper/thumb",
  "count": 2
}

vs.

{
  ["newspaper/thumb", 2]
}

# Layout with count AND repetition

{
  "name": "newspaper/thumb",
  "count": 2,
  "repetition": 1,
}

vs.

{
  ["newspaper/thumb", 2, 1]
}

# Inheritance

This file follows Marfeel's inheritance rules.

Layouts can be shadowed following the markup extensibility principles, but the CSS extension points should be sufficient for all the necessary customizations.

← Typography →