# Template Structure

How components, sections, and pages fit together in a Web Builder template


Organize the design around the parts that change together: site-wide settings, navigation, pages, and the ordered sections inside each page.

## Establish the hierarchy

The CMS hierarchy in erxes maps cleanly onto how designers already break a site into parts:

- **Site (global) elements**: stored once on the [`Web`](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/plugins/content_api/src/modules/webbuilder/graphql/schemas/web.ts) record: name, domain, copyright, logo, favicon, brand colors and fonts under `appearances`, social links under `externalLinks`, and analytics IDs under `integrations`.
- **Navigation**: [`MenuItem`](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/plugins/content_api/src/modules/cms/graphql/schemas/menu.ts) records grouped by `kind`. The Web Builder [deploy step](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/plugins/content_api/src/modules/webbuilder/utils/utils.ts#L133-L185) collects `kind` `main` and `kind` `footer` menus; nesting comes from `parentId`, order from `order`.
- **Pages**: [`Page`](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/plugins/content_api/src/modules/cms/graphql/schemas/page.ts) records. `name` is the title, `slug` is the route, `status` controls availability, and `coverImage` supplies a social/hero image.
- **Sections**: entries in `Page.pageItems`. Each item has a `type` string (which component the template renders), an `order`, a `config` JSON object for options, a `content` field, and optional `objectType`/`objectId` pointers to a linked record such as a post or category.
- **Fields**: the editable values inside `config` and `content`. Their names and types are defined by the template's section components, not by the CMS schema.

Confirm the available section `type` values and `config` keys in the selected template repository. A Figma component does not automatically create a matching section type or editable field.

## Map content to the design

Mark which values are global (on `Web`), page-specific (on `Page`), section-level (in `pageItems`), or supplied by a collection (posts, categories, menus). Distinguish labels and placeholder examples from required production content. Editors replace your placeholder copy with real text, so design for the longest realistic value.

For repeated content such as post cards or gallery images, show zero, one, and several items, plus the longest realistic title or label. Define how missing images and optional text affect spacing: `Post.excerpt`, `Post.thumbnail`, and `Page.description` can all be empty, so a missing value is a normal case, not an edge case. For dynamic content, specify loading and error states as well as the successful layout.

## Specify responsive behavior

Describe how navigation, columns, spacing, image crops, and content order change as the available width changes. Use the template's agreed breakpoints and tokens. Check reading order and keyboard access when desktop elements move on mobile, especially for the `main` menu, which collapses into a mobile menu in most templates.

Accessibility and responsiveness need implementation and testing; they are not guaranteed by installing a template. Include visible focus, readable text contrast against your `appearances` colors, meaningful labels, and alternatives for essential image content in the handoff.

## Handoff checklist

| Decision | Where it is stored | Open question for the developer |
| --- | --- | --- |
| Which elements are global vs. per-page | `Web` vs. `Page`/`pageItems` | Any element that looks global but must vary per page? |
| Section inventory | `Page.pageItems[].type` | Which `type` values does the template implement? |
| Editable options per section | `Page.pageItems[].config` | Which keys are editable, and their defaults? |
| Linked content in sections | `objectType`/`objectId` | Which object types does each section accept? |
| Collection-driven lists | `Post`, `PostCategory`, `MenuItem` | Source query, ordering, and maximum items |
| Breakpoints and tokens | Template theme (repo-specific) | Breakpoint names and token mapping |

## Review with the developer

Confirm the field mapping, component reuse, editable areas, missing-content behavior, and any new capability the design needs. Settle changes to the data shape (new `config` keys, new section types, new linked objects) before marking the design ready.