Custom fields in Recommender layouts

Custom fields let you render article metadata that Marfeel does not extract by default directly in your Recommender layout templates. When you configure Custom Fields to sync to Recommender, extracted values become available in the recommendations JSON payload under the customProperties key.

How it works

Custom Fields extracts metadata from your articles during crawling using XPath or JSONPath expressions. When you enable Sync to: Recommender on a custom field, the extracted value is stored with the article and included in the recommendations data.

Article HTML → Custom Fields extraction → Recommender data → Layout template

Any metadata present in your page’s server-rendered HTML can flow into your recommendation modules without code changes on your site.

Accessing custom fields in templates

Custom fields are delivered inside each recommendation object under the customProperties key. Access them with dot notation:

{{customProperties.yourFieldName}}

Extended recommendations data

With custom fields configured, the recommendations JSON expands to include a customProperties object for each article:

{
  "recommendations": [{
    "title": "Article title",
    "url": "https://domain.com/path/to/article.html",
    "img": "https://domain.com/path/to/image.jpg",
    "authors": ["Author 1"],
    "sections": ["Politics"],
    "tags": ["Tag1", "tagGroup:Tag2"],
    "publishTime": "2024-12-26 17:01:03",
    "visibility": "open",
    "customProperties": {
      "description": "The article excerpt extracted from meta description",
      "alternativeImage": "https://domain.com/path/to/alt-image.jpg",
      "secondImage": "https://domain.com/path/to/second-image.jpg",
      "metaValue": "Custom metadata value"
    }
  }]
}

The customProperties object contains every custom field synced to Recommender for that article. Field names match the names you defined in your Custom Fields configuration.

Practical examples

Display article excerpts

Extract og:description and render it below the headline. This is useful for newsletter-style recommendation modules.

Custom Field configuration:

Setting	Value
Expression	//meta[@property="og:description"]/@content
Extract	Attribute Value (content)
Save as	Custom field: description
Sync to	Recommender

Layout template:

{{#recommendations}}
<article>
  <a href="{{url}}">
    <img src="{{img}}" alt="{{title}}" />
    <h2>{{title}}</h2>
    {{#customProperties.description}}
      <p class="excerpt">{{customProperties.description}}</p>
    {{/customProperties.description}}
  </a>
</article>
{{/recommendations}}

The {{#customProperties.description}} block ensures the excerpt only renders when a value exists for that article.

Use custom thumbnail images

Replace the default {{img}} with a publisher-preferred image extracted from structured data. This is useful when the standard image crop does not suit your layout.

Custom Field configuration:

Setting	Value
Expression	$.@graph[?(@.@type=="NewsArticle")].thumbnailUrl
Save as	Custom field: thumbnailUrl
Sync to	Recommender

Layout template:

{{#recommendations}}
<article>
  <a href="{{url}}">
    {{#customProperties.thumbnailUrl}}
      <img src="{{customProperties.thumbnailUrl}}" alt="{{title}}" />
    {{/customProperties.thumbnailUrl}}
    {{^customProperties.thumbnailUrl}}
      <img src="{{img}}" alt="{{title}}" />
    {{/customProperties.thumbnailUrl}}
    <h2>{{title}}</h2>
  </a>
</article>
{{/recommendations}}

This falls back to the default {{img}} when no custom thumbnail exists.

Add proper image alt text

Extract alt attributes from article images for use in recommendations. This improves accessibility and PageSpeed scores by avoiding generic fallbacks.

Custom Field configuration:

Setting	Value
Expression	//figure/img
Extract	Attribute Value (alt)
Save as	Custom field: imageAlt
Sync to	Recommender

Layout template:

{{#recommendations}}
<article>
  <a href="{{url}}">
    <img src="{{img}}" alt="{{#customProperties.imageAlt}}{{customProperties.imageAlt}}{{/customProperties.imageAlt}}{{^customProperties.imageAlt}}{{title}}{{/customProperties.imageAlt}}" />
    <h2>{{title}}</h2>
  </a>
</article>
{{/recommendations}}

Uses the extracted alt text when available, falls back to {{title}} otherwise.

Display a premium badge

Show a visual indicator when an article belongs to a premium content tier. Combine with the built-in {{visibility}} field or use a custom field for more granular tiers.

Custom Field configuration:

Setting	Value
Expression	//meta[@name="content-tier"]/@content
Extract	Attribute Value (content)
Save as	Custom field: contentTier
Sync to	Recommender

Layout template:

{{#recommendations}}
<article>
  <a href="{{url}}">
    <img src="{{img}}" alt="{{title}}" />
    <div class="headline-wrap">
      {{#if "customProperties.contentTier eq 'premium'"}}
        <span class="premium-badge">Premium</span>
      {{/if}}
      <h2>{{title}}</h2>
    </div>
  </a>
</article>
{{/recommendations}}

Conditionally style by custom property

Apply different visual treatments based on extracted metadata. This example adds a CSS class based on a section-specific property:

{{#recommendations}}
<article class="card {{#customProperties.contentTier}}tier-{{customProperties.contentTier}}{{/customProperties.contentTier}}">
  <a href="{{url}}">
    <img src="{{img}}" alt="{{title}}" />
    <h2>{{title}}</h2>
  </a>
</article>
{{/recommendations}}

With corresponding CSS:

.tier-premium { border-left: 3px solid gold; }
.tier-free { border-left: 3px solid #ccc; }

Testing with custom fields

The Layout Editor preview uses the JSON tab’s example data. To test layouts that use custom fields:

1. Open a Recommender experience that targets articles with custom fields configured
2. Click JSON endpoint in the preview options (top right)
3. Copy the response, which includes the customProperties object with real extracted data
4. Paste into the Layout Editor’s JSON tab

You can also manually add a customProperties object to your test JSON to simulate different scenarios before real data is available.

Limits

Custom fields in Recommender layouts inherit the same restrictions as the Custom Fields configuration:

Going deeper

• Custom Fields — Configure extraction rules and sync destinations
• Recommender Layouts — Full layout structure, templating, and default layouts
• How does Marfeel extract the metadata from articles — Default metadata extraction
• Editorial Metadata API Endpoint — Submit metadata programmatically when crawlers can’t access content

How do you access custom fields in Recommender layout templates?

Custom fields are delivered inside each recommendation object under the customProperties key. Access them with dot notation in your Mustache templates, for example {{customProperties.yourFieldName}}.

How do you test Recommender layouts that use custom fields?

Open a Recommender experience targeting articles with custom fields configured, click JSON endpoint in the preview options, copy the response including the customProperties object with real extracted data, and paste it into the Layout Editor’s JSON tab.

What happens when a custom field has no value for a specific article?

Use Mustache conditional blocks to handle missing values. Wrap the custom property in a section tag like {{#customProperties.fieldName}} to render content only when the value exists, and use the inverted tag {{^customProperties.fieldName}} to provide a fallback.