Smart-Map & Fallbacks

The resolution order

Every time SEO NEO needs a value — title, description, or anything else in the fallback chain — it works through five steps in order and stops at the first non-empty result:

1. Per-page SEO field. The value typed directly into seoneo_title or seoneo_description on the page's SEO tab. Always wins. Returned verbatim, with no truncation applied.
2. Smart-map fallback. SEO NEO tries the fields you configure in Modules > Configure > SeoNeo > Smart field mapping, in the order listed for each role. The first non-empty value wins. Values resolved from the smart-map are HTML-stripped, collapsed to single spaces, and truncated at the nearest word boundary to the configured max length (default 180 chars).
3. Per-template default. A value from the per-template defaults config, with placeholder substitution. Useful for templates whose pages have predictable, semi-formulaic content.
4. Site default. The page title is the ultimate fallback for seoneo_title. For description there is no site default — if nothing resolves, the tag is not output.
5. Empty. The tag is omitted from the output entirely. SEO NEO never emits an empty <meta name="description" content="">.

Each step is hookable — see Hooks & Customisation for examples.

Smart-map syntax

The smart-map is configured in Modules > Configure > SeoNeo > Smart field mapping. Enter one mapping per line in key=field1,field2 format:

title=headline,title
description=summary,body,intro

Default install value:

title=headline,title
description=summary,body

Dotted paths into nested fields

description=banner.image.description,gallery.first.alt,matrix_blocks.first.body

Each dot traverses one level. Missing properties at any step are skipped silently.

Ancestor walk with *

description=*section_description,summary
title=*section_title,title

Prefix any field with * to walk ancestor pages when the current page leaves the field empty. SEO NEO tries the current page, then each parent nearest-first, and stops at the first non-empty value.

Per-template defaults

When the smart-map returns nothing, SEO NEO tries the per-template defaults. Use [template-name] sections with key=value lines:

[blog-post]
title={title}
description={summary|body}
og_type=article

[docs-version]
title={title} Documentation
description={parent.title} v{title} documentation.

Supported placeholders:

• {title} — the page title
• {site_name} — the configured site name
• {separator} — the configured title separator
• {page.fieldname} — any field on the page (e.g. {page.summary})
• {fieldname} — shorthand for {page.fieldname}
• {parent.fieldname} — any field on the parent page
• {pageNum} — blank on page 1, " — Page 2" on subsequent pages
• {pageNumber} — always numeric (1, 2, 3)
• {long_title|title} — pipe-separated fallbacks within a placeholder

Description truncation

Values resolved from the smart-map or a template default (steps 2 and 3) are stripped of HTML, collapsed to single spaces, and truncated at the nearest word boundary to Max description length in module config (default 180 chars), with an ellipsis appended.

Values typed directly into seoneo_description (step 1) are returned verbatim. Set max length to 0 to disable truncation for steps 2 and 3.

A worked example

Suppose you have this smart-map config:

description=summary,body

And this per-template default:

[blog-post]
description={title} — a post on the {site_name} blog.

For a blog post where seoneo_description is empty and summary is "Three tips for faster ProcessWire development.", SEO NEO returns the summary at step 2. The template default is never reached.

Common gotchas

• Field doesn't exist on the template. SEO NEO skips it silently. Check the field is on the template in Setup > Templates.
• Ancestor walk on the homepage. The homepage has no parents, so *fieldname behaves the same as fieldname.

See also

• Configuration — where to enter the smart-map and per-template defaults.
• Hooks & Customisation — override any step in the resolver chain.
• Template API — reading resolved values in templates.