SEO Fields

https://github.com/studioespresso/craft-seo-fields
Admin
SEO Fields is a Craft CMS plugin that provides fields for managing meta data, Open Graph data,...
Tokens:7,546
Snippets:64
Trust Score:8.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### schemaOptions configuration example

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/settings.md

Adds a custom schema option for the Recipe schema type. The array maps the schema class to a label.

```php
"schemaOptions" => [
    get_class(\Spatie\SchemaOrg\Schema::recipe()) => 'Recipe'
],
```

--------------------------------

### Install SEO Fields plugin

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/index.md

Install the SEO Fields plugin for Craft CMS using Composer and the Craft CLI. Run these commands from your Craft project directory.

```bash
# go to the project directory
cd /path/to/my-craft-project.dev

# tell Composer to install the plugin
composer require studioespresso/craft-seo-fields

# tell Craft to install the plugin
./craft install/plugin seo-fields
```

--------------------------------

### siteEntityOptions configuration example

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/settings.md

Adds a custom site entity type for the Sports Organization schema. The array maps the schema class to a label.

```php
"siteEntityOptions" => [
    get_class(\Spatie\SchemaOrg\Schema::sportsOrganization()) => 'Sports Organization'
],
```

--------------------------------

### Get OG image with meta.getOgImage()

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/templating.md

Gets the OG image by passing an Asset element to meta.getOgImage(). This is used for the OG and Twitter images.

```twig
{% set ogImage = meta.getOgImage(entry.overviewImage.one()) %}
```

--------------------------------

### Set custom properties with setProperty on Event

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Uses setProperty to set custom properties on a schema type when no named method exists. This example sets @id and eventAttendanceMode on an Event type.

```twig
{% do seoFields.graph.event()
    .setProperty('@id', '#my-event')
    .setProperty('eventAttendanceMode', 'https://schema.org/OfflineEventAttendanceMode')
%}
```

--------------------------------

### seoFields.graph.event().setProperty()

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Sets custom properties on a schema type using the fluent API.

```APIDOC
## seoFields.graph.event().setProperty()

### Description
Sets custom properties on a schema type using the fluent API from spatie/schema-org. Use this for properties without a named method.

### Method
Twig function call

### Endpoint
`seoFields.graph.event().setProperty()`

### Parameters
#### Fluent Methods
- **setProperty** (string, mixed) - Required - The property name and value to set.

### Request Example
```twig
{% do seoFields.graph.event()
    .setProperty('@id', '#my-event')
    .setProperty('eventAttendanceMode', 'https://schema.org/OfflineEventAttendanceMode')
%}
```

### Response
#### Success Response
No direct response; the custom properties are added to the schema node.

#### Response Example
```json
{
  "@type": "Event",
  "@id": "#my-event",
  "eventAttendanceMode": "https://schema.org/OfflineEventAttendanceMode"
}
```
```

--------------------------------

### seoFields.schema.question()

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Creates a standalone Question schema type for use as a nested object.

```APIDOC
## seoFields.schema.question()

### Description
Creates a standalone Question schema type that can be used as a nested object within other schema nodes.

### Method
Twig function call

### Endpoint
`seoFields.schema.question()`

### Parameters
#### Fluent Methods
- **name** (string) - Required - The text of the question.
- **acceptedAnswer** (Answer) - Required - The accepted answer, typically created with `seoFields.schema.answer()`.

### Request Example
```twig
{% set question = seoFields.schema.question()
    .name(faq.title)
    .acceptedAnswer(seoFields.schema.answer().text(faq.answer|striptags))
%}
```

### Response
#### Success Response
Returns a Question schema object that can be passed to other schema nodes.

#### Response Example
```json
{
  "@type": "Question",
  "name": "...",
  "acceptedAnswer": {
    "@type": "Answer",
    "text": "..."
  }
}
```
```

--------------------------------

### Add FAQ data to page node and output JSON-LD

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Adds FAQ data to the existing page node using seoFields.pageNode.mainEntity() and seoFields.addPageType('FAQPage'). The output shows the resulting JSON-LD with a single node whose @type is an array ["WebPage", "FAQPage"].

```twig
{# Add FAQ data to the existing page node #}
{% set questions = [] %}
{% for block in entry.faqBlocks.all() %}
    {% set questions = questions|merge([
        seoFields.schema.question()
            .name(block.title)
            .acceptedAnswer(seoFields.schema.answer().text(block.answer|striptags))
    ]) %}
{% endfor %}
{% do seoFields.pageNode.mainEntity(questions) %}
{% do seoFields.addPageType('FAQPage') %}
```

```json
{
  "@type": ["WebPage", "FAQPage"],
  "@id": "#page",
  "name": "...",
  "mainEntity": [
    { "@type": "Question", "name": "...", "acceptedAnswer": { "@type": "Answer", "text": "..." } }
  ]
}
```

--------------------------------

### Build schema across includes with seoFields.pageNode and addPageType

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Shows how an entry template and its include contribute to the same schema graph. The entry template adds an Event type, and the FAQ include uses seoFields.pageNode to add mainEntity to the existing page node and seoFields.addPageType('FAQPage') to merge FAQPage into the page's @type, resulting in a single node with "@type": ["WebPage", "FAQPage"].

```twig
{# _events/_entry.twig #}
{% do seoFields.graph.event()
    .name(entry.title)
    .description(entry.intro|striptags)
    .url(entry.url)
%}

{% include '_snippets/_faq' with { faqs: entry.faqBlocks } %}
```

```twig
{# _snippets/_faq.twig #}
{% if faqs|length %}
    {% set questions = [] %}
    {% for faq in faqs.all() %}
        {% set questions = questions|merge([
            seoFields.schema.question()
                .name(faq.title)
                .acceptedAnswer(
                    seoFields.schema.answer().text(faq.answer|striptags)
                )
        ]) %}
    {% endfor %}
    {% do seoFields.pageNode.mainEntity(questions) %}
    {% do seoFields.addPageType('FAQPage') %}
{% endif %}
```

--------------------------------

### Register custom element with EVENT_SEOFIELDS_REGISTER_ELEMENT

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/templating.md

Registers a custom element class with SEO Fields by listening to the EVENT_SEOFIELDS_REGISTER_ELEMENT event. This allows SEO Fields to support custom elements.

```php
Event::on(SeoFields::class, SeoFields::EVENT_SEOFIELDS_REGISTER_ELEMENT,
    function (RegisterSeoElementEvent $event) use ($elements) {
        $event->elements = array_merge($event->elements,[
            Product::class,
        ]);
    }
);
```

--------------------------------

### seoFields.pageNode.mainEntity()

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Adds properties directly to the existing page node, such as mainEntity for FAQ data.

```APIDOC
## seoFields.pageNode.mainEntity()

### Description
Adds properties directly to the existing page node (WebPage, Article, etc.) that was automatically created for the current entry or category.

### Method
Twig function call

### Endpoint
`seoFields.pageNode.mainEntity()`

### Parameters
#### Fluent Methods
- **mainEntity** (array) - Required - An array of schema objects (e.g., Question objects) to set as the mainEntity of the page node.

### Request Example
```twig
{% do seoFields.pageNode.mainEntity(questions) %}
```

### Response
#### Success Response
No direct response; the page node is updated in the JSON-LD output.

#### Response Example
```json
{
  "@type": "WebPage",
  "mainEntity": [
    { "@type": "Question", "name": "...", "acceptedAnswer": { "@type": "Answer", "text": "..." } }
  ]
}
```
```

--------------------------------

### seoFields.schema.answer()

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Creates a standalone Answer schema type for use as a nested object.

```APIDOC
## seoFields.schema.answer()

### Description
Creates a standalone Answer schema type, typically used as the `acceptedAnswer` for a Question.

### Method
Twig function call

### Endpoint
`seoFields.schema.answer()`

### Parameters
#### Fluent Methods
- **text** (string) - Required - The text of the answer.

### Request Example
```twig
{% set answer = seoFields.schema.answer().text(faq.answer|striptags) %}
```

### Response
#### Success Response
Returns an Answer schema object.

#### Response Example
```json
{
  "@type": "Answer",
  "text": "..."
}
```
```

--------------------------------

### seoFields.graph.event()

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Adds a top-level Event schema type to the shared schema graph using the fluent API.

```APIDOC
## seoFields.graph.event()

### Description
Adds a top-level Event schema type to the shared schema graph. The event is merged into the page's single `<script type="application/ld+json">` tag automatically.

### Method
Twig function call

### Endpoint
`seoFields.graph.event()`

### Parameters
#### Fluent Methods
- **name** (string) - Required - The name of the event.
- **description** (string) - Optional - A description of the event.
- **url** (string) - Optional - The URL of the event.
- **setProperty** (string, mixed) - Optional - Sets a custom property on the schema type.

### Request Example
```twig
{% do seoFields.graph.event()
    .name(entry.title)
    .description(entry.intro|striptags)
    .url(entry.url)
%}
```

### Response
#### Success Response
No direct response; the schema is added to the page's JSON-LD output.

#### Response Example
```json
{
  "@type": "Event",
  "name": "...",
  "description": "...",
  "url": "..."
}
```
```

--------------------------------

### Combine setPageType and addPageType for multi-type page node

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Combines setPageType and addPageType to produce a single #page node with "@type": ["Article", "FAQPage"].

```twig
{% do seoFields.setPageType('Article') %}
{% do seoFields.addPageType('FAQPage') %}
```

--------------------------------

### seoFields.graph.article()

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Adds a top-level Article schema type to the shared schema graph.

```APIDOC
## seoFields.graph.article()

### Description
Adds a top-level Article schema type to the shared schema graph. Typically used with `setPageType('Article')` to merge properties into the page node.

### Method
Twig function call

### Endpoint
`seoFields.graph.article()`

### Parameters
#### Fluent Methods
- **headline** (string) - Required - The headline of the article.
- **description** (string) - Optional - A description of the article.
- **url** (string) - Optional - The URL of the article.
- **datePublished** (string) - Optional - The publication date in ISO 8601 format.
- **dateModified** (string) - Optional - The modification date in ISO 8601 format.

### Request Example
```twig
{% do seoFields.graph.article()
    .headline(entry.title)
    .description(entry.intro|striptags)
    .url(entry.url)
    .datePublished(entry.postDate|atom)
    .dateModified(entry.dateUpdated|atom)
%}
```

### Response
#### Success Response
No direct response; the schema is added to the page's JSON-LD output.

#### Response Example
```json
{
  "@type": "Article",
  "headline": "...",
  "description": "...",
  "url": "...",
  "datePublished": "...",
  "dateModified": "..."
}
```
```

--------------------------------

### Add SEO Fields with template hook

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/templating.md

Adds the SEO Fields output to the HTML by placing this hook within the <head> tag of your layout.

```twig
{% hook 'seo-fields' %}
```

--------------------------------

### seoFields.setPageType()

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Replaces the default page type with a different Schema.org type for the current entry.

```APIDOC
## seoFields.setPageType()

### Description
Replaces the default page type (e.g., WebPage) with a different Schema.org type for the current entry. This prevents duplicate nodes in the output.

### Method
Twig function call

### Endpoint
`seoFields.setPageType(type)`

### Parameters
#### Path Parameters
- **type** (string) - Required - The Schema.org type to set, e.g., 'Article'.

### Request Example
```twig
{% do seoFields.setPageType('Article') %}
```

### Response
#### Success Response
No direct response; the page node's `@type` is changed in the JSON-LD output.

#### Response Example
```json
{
  "@type": "Article"
}
```
```

--------------------------------

### seoFields.addPageType()

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Registers an additional Schema.org type to merge into the existing page node.

```APIDOC
## seoFields.addPageType()

### Description
Registers an additional Schema.org type to merge into the existing page node. During rendering, the page node's `@type` becomes an array (e.g., `["WebPage", "FAQPage"]`).

### Method
Twig function call

### Endpoint
`seoFields.addPageType(type)`

### Parameters
#### Path Parameters
- **type** (string) - Required - The Schema.org type to add, e.g., 'FAQPage'.

### Request Example
```twig
{% do seoFields.addPageType('FAQPage') %}
```

### Response
#### Success Response
No direct response; the page node's `@type` is updated in the JSON-LD output.

#### Response Example
```json
{
  "@type": ["WebPage", "FAQPage"]
}
```
```

--------------------------------

### Add Event schema type with seoFields.graph.event()

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Adds a top-level Event schema type to the shared graph. The default schema (organization + section-level type) is still added automatically, and anything added from templates merges into the same graph.

```twig
{% do seoFields.graph.event()
    .name(entry.title)
    .description(entry.intro|striptags)
    .url(entry.url)
%}
```

--------------------------------

### Replace section default type with seoFields.setPageType('Article')

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Replaces the section default type (e.g., WebPage) with Article for a specific entry. Without setPageType, the output would contain both a WebPage node and a separate Article node; with setPageType('Article'), the #page node's @type is changed to Article and properties set on the article are merged into it.

```twig
{% do seoFields.setPageType('Article') %}
{% do seoFields.graph.article()
    .headline(entry.title)
    .description(entry.intro|striptags)
    .url(entry.url)
    .datePublished(entry.postDate|atom)
    .dateModified(entry.dateUpdated|atom)
%}
```

--------------------------------

### Disable schema output with setShouldRenderSchema

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/schema.md

Disables schema output for a specific entry. Note that setShouldRenderSchema is deprecated; use seoFields.graph to add schema types directly instead.

```twig
{% do entry.setShouldRenderSchema(false) %}
{% extends 'layout.twig' %}
```

--------------------------------

### Overwrite SEO field values with Twig functions

Source: https://github.com/studioespresso/craft-seo-fields/blob/develop-v5/docs/templating.md

Overwrites the SEO field values with custom text and an Asset image. Note that in version 4.0.0, methods are called on the entry directly (e.g., entry.setSocialTitle()) instead of entry.seo.setSocialTitle().

```twig
{% do entry.setSocialTitle('Facebook title') %}
{% do entry.setSocialDescription('custom description') %}


// Overwriting the image fields can be done by passing an Asset element
{% do entry.setSocialImage(entry.assetField.one()) %}
```
Tokens:
Raw