89 lines
4.2 KiB
Markdown
89 lines
4.2 KiB
Markdown
|
# Product Templates
|
||
|
|
|
||
|
|
## Intent
|
||
|
|
Product detail pages support customizable templates. Editors should be able to pick a template per product. The site pulls template options by enumerating the directories under `webroot/Products/`.
|
||
|
|
|
||
|
|
This lets product marketing teams build visually distinct product pages without rebuilding the platform each time, while still staying inside the brand visual system.
|
||
|
|
|
||
|
|
## Template Directory Structure
|
||
|
|
Each template lives under:
|
||
|
|
|
||
|
|
```
|
||
|
|
webroot/Products/<template-id>/
|
||
|
|
```
|
||
|
|
|
||
|
|
Each template directory must contain exactly three subdirectories:
|
||
|
|
|
||
|
|
```
|
||
|
|
webroot/Products/<template-id>/
|
||
|
|
assets/
|
||
|
|
zh/
|
||
|
|
index.html
|
||
|
|
en/
|
||
|
|
index.html
|
||
|
|
```
|
||
|
|
|
||
|
|
### Folder Roles
|
||
|
|
- `assets/` — shared static resources for this template (images, videos, stylesheets, scripts).
|
||
|
|
- `zh/index.html` — Chinese version of the rendered product page for this template.
|
||
|
|
- `en/index.html` — English version of the rendered product page for this template.
|
||
|
|
|
||
|
|
### Rules
|
||
|
|
- The three folders `assets`, `zh`, `en` are required.
|
||
|
|
- A template is considered valid only if both `zh/index.html` and `en/index.html` exist.
|
||
|
|
- Asset references inside `index.html` should use paths relative to the template root, for example `./assets/hero.jpg`.
|
||
|
|
- Template IDs are the directory names; they are used as the value stored in CMS.
|
||
|
|
- Template IDs should be URL-safe (letters, digits, dashes, underscores).
|
||
|
|
|
||
|
|
## Template Discovery Rule
|
||
|
|
The build / CMS layer must enumerate `webroot/Products/*` inside this project and produce a list of valid template IDs. Product content entries in Payload reference one of these template IDs through a `template` field.
|
||
|
|
|
||
|
|
### Validation
|
||
|
|
- If a product references a template ID that no longer exists, the build should fail loudly rather than silently fall back.
|
||
|
|
- If a template directory is missing `assets`, `zh/index.html`, or `en/index.html`, it must not be exposed as a selectable option.
|
||
|
|
|
||
|
|
## CMS Field
|
||
|
|
Each Product record in Payload has a `template` field:
|
||
|
|
- Type: select
|
||
|
|
- Source: dynamic enumeration of valid template directories under `webroot/Products/`
|
||
|
|
- Required: true
|
||
|
|
|
||
|
|
If the template list is empty, product pages fall back to the default system-rendered product layout.
|
||
|
|
|
||
|
|
## Rendering Strategy
|
||
|
|
When rendering a product detail page:
|
||
|
|
1. Look up the product entry in Payload by slug.
|
||
|
|
2. Read the `template` field.
|
||
|
|
3. If a matching template exists in `webroot/Products/<template-id>/<locale>/index.html`, inject that HTML into the central product-body region inside the Next.js product route.
|
||
|
|
4. Serve template assets from `/products-tmp/<template-id>/assets/...`.
|
||
|
|
|
||
|
|
### Chrome Rules
|
||
|
|
- Header, footer, language switch, and breadcrumb are always rendered by the main Next.js layout.
|
||
|
|
- The template only owns the middle content region of the product detail page.
|
||
|
|
- Templates do not need to include header or footer markup.
|
||
|
|
- Templates must not override global navigation, language switch, cookie banner, or footer.
|
||
|
|
|
||
|
|
### SEO
|
||
|
|
- Page metadata (title, description, OG image, canonical, hreflang) comes from Payload, not from the template HTML.
|
||
|
|
- Any `<head>` content inside the template HTML is ignored.
|
||
|
|
- `h1` tags inside the template should stay unique per product.
|
||
|
|
|
||
|
|
## Content Ownership
|
||
|
|
- Template HTML and assets: created by design / marketing team.
|
||
|
|
- Template selection: owned in CMS per product.
|
||
|
|
- Product metadata (title, slug, hero image, summary, downloads, videos, reviews, SEO, related products): always managed in CMS, never hardcoded inside the template.
|
||
|
|
- Product detail pages must continue to render CMS-managed downloads, videos, and reviews outside the template-owned middle body region.
|
||
|
|
|
||
|
|
## Naming Guidance
|
||
|
|
- `template-id` should describe the layout intent, not a specific product. Good examples: `editorial-01`, `immersive-hero`, `split-feature`. Avoid product-specific names like `a10-page`.
|
||
|
|
|
||
|
|
## Workflow
|
||
|
|
1. Designer or marketing team adds a new template directory into this project's `webroot/Products/`.
|
||
|
|
2. Build pipeline enumerates available templates and updates the CMS select options.
|
||
|
|
3. Editor picks the template on a Product entry.
|
||
|
|
4. Page publishes with the selected template.
|
||
|
|
|
||
|
|
## Open Questions
|
||
|
|
- Whether templates can depend on external CDN assets, or must be fully self-contained within `assets/`.
|
||
|
|
- Whether templates support a lightweight preview environment in CMS.
|