Main entity of a web page¶
Target group: Developers
Table of Contents
Introduction¶
A WebPage
type provides a property mainEntity
, which indicates the
primary content of a page. Every type is allowed - although some types does not
make sense (for example, a breadcrumb cannot be the primary content).
Note
Technically, there can be more than one main entity at a time. For example,
if you have a FAQPage
you will usually assign more than one question
as mainEntity
.
Using the API¶
The main entity of a web page can be defined with the API. Let's start with an example that specifies a product as the primary content:
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Controller;
use Brotkrueml\Schema\Manager\SchemaManager;
use Brotkrueml\Schema\Type\TypeFactory;
final class MyController
{
public function __construct(
private readonly SchemaManager $schemaManager,
private readonly TypeFactory $typeFactory,
) {}
public function addMainEntity(): void
{
// ...
$aggregateRating = $this->typeFactory->create('AggregateRating')
->setProperty('ratingValue', '4')
->setProperty('reviewCount', '126');
$product = $this->typeFactory->create('Product')
->setProperties([
'name' => 'Some fancy product',
'color' => 'blue',
'material' => 'wood',
'image' => 'https://example.org/some-fancy-product.jpg',
'aggregateRating' => $aggregateRating,
]);
$this->schemaManager->addMainEntityOfWebPage($product);
// ...
}
}
The above example is rendered as JSON-LD. Let's assume the WebPage
type is
set to ItemPage
- either in the page properties or via the API or a view
helper.
{
"@context": "https://schema.org/",
"@type": "ItemPage",
"mainEntity": {
"@type": "Product",
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "4",
"reviewCount": "126"
},
"color": "blue",
"image": "https://example.org/some-fancy-product.jpg",
"material": "wood",
"name": "Some fancy product"
}
}
Note
If the WebPage
type is not defined because the
appropriate setting
is disabled in the extension configuration, the main entity is rendered as
a root type.
Using the view helpers¶
You can define the main entity also in a view helper:
<schema:type.product
-as="mainEntity"
-isMainEntityOfWebPage="1"
name="Some fancy product"
color="blue"
material="wood"
image="https://example.org/some-fancy-product.jpg"
>
<schema:type.aggregateRating
-as="aggregateRating"
ratingValue="4"
reviewCount="126"
/>
</schema:type.product>
Remark¶
You can set the view helper argument -isMainEntityOfWebPage
only in the
main type view helper, not in a child type view helper.
Prioritisation¶
Main entities can be prioritised. This is sometimes necessary when different main entities are defined in different places (for example in a controller, a Fluid page template or in a content element).
Let's look at an example: In a page template for a blog post, the main entity
is defined as type BlogPosting
. There are content elements on the page that
display questions and answers for a FAQ. The content element sets the web page
type to 'FAQPage' and also defines the questions as the main entities (to
display as rich snippets on the search results page). However, Google Search
Console shows an error because BlogPosting
is not allowed as the main entity
of a FAQPage
.
With the API¶
The main entity of the API example above can be prioritised by setting the
second argument to true
:
$schemaManager->addMainEntityOfWebPage($product, true);
With view helpers¶
Let's look at the example described in the introduction. In a page template, a
BlogPosting
type is defined as the main entity of the page:
<!-- This is defined in a page template -->
<schema:type.blogPosting
-isMainEntityOfWebPage="1"
name="A blog post"
/>
And the FAQ is rendered in the template of a content element. To prioritise
these types, -isMainEntityOfWebPage
is set to 2
:
<!-- This is defined in a content element template -->
<schema:type.fAQPage/>
<f:for each="{questions}" as="question">
<schema:type.question
-isMainEntityOfWebPage="2"
name="{question.title}"
/>
</f:for>
This results in the following output:
{
"@context": "https://schema.org/",
"@graph": [{
"@type": "FAQPage",
"mainEntity":[{
"@type": "Question",
"name": "Question #1"
}, {
"@type": "Question",
"name": "Question #2"
}]
}, {
"@type": "BlogPosting",
"name": "A blog post"
}]
}