# Specialities Page — Integration Notes

Short document explaining best-fit Drupal techniques per section, highlighting risks and open decisions. Companion to `docs/specialities-drupal-mapping.md`.

## Section suitability

| Section | Best fit | Why |
|---------|----------|-----|
| Utility bar, main nav, footer, sticky bar | **Regions + Blocks** | Chrome/layout elements — render once per page template |
| Breadcrumb | **Core breadcrumb block** | Path-aware, already dynamic in Drupal |
| Hero banner | **Paragraph** (`hero_banner_callback`) | Page-specific content; editors customise heading, subtitle, image, CTA per landing page |
| Category filter | **Views Exposed Form** (chip list variant) | Leverages Views filter framework; chip Twig override instead of dropdown |
| Treatments grid | **Views page display** (`node--treatment--card.html.twig` as row template) | One template, many places; no duplication |
| Our Story and Vision | **Paragraph** (`text_callout`) | Reusable grey text block; shared bundle with eye-specialists and centre-cluster pages |
| All Centres | **Paragraph** (`region_card_grid` with nested `region_card`) | Variable region count; each card is its own paragraph entity |
| Contact strip | **Paragraph** (`contact_strip` with nested `contact_strip_item`) | 3-item list; phone and URL variants handled by `field_icon_type` toggle in Twig |
| Experts header | **Paragraph** (`text_callout`) | Simple heading + body block; same bundle as Our Story, different field values |
| Eye Care Experts (doctor cards) | **Views block display** (reused from homepage) | Verbatim reuse of existing doctor-card Views implementation; no new template |
| Why CFS cards | **Paragraph** (`feature_card_grid` with nested `feature_card`) | Variable card count; each card is its own paragraph entity |
| FAQ | **Paragraph** (`faq_section` with nested `faq_item`) | Editors add/edit individual Q&A entries |
| Callback form | **Webform** (shared) + **Paragraph** (`callback_cta`) | Shared form across pages; validation, submission handling, email notifications built-in |

---

## Reused shared components

These files are included verbatim from `html/components/` — the Drupal team should map them to existing Twig regions/blocks from the homepage implementation, not create new templates.

| Component file | Source page | Drupal region/block |
|----------------|------------|---------------------|
| `html/components/01-utility-bar.html` | Homepage | `region--secondary.html.twig` + menu block |
| `html/components/02-main-nav.html` | Homepage | `region--header.html.twig` + `menu.html.twig` |
| `html/components/06-doctor-cards.html` | Homepage | Existing "doctors" Views block display + `node--doctor--card.html.twig` |
| `html/components/15-footer.html` | Homepage | `region--footer.html.twig` |
| `html/components/16-sticky-bar.html` | Homepage | Custom block in `region--bottom.html.twig` |

No modifications to shared components are needed for this page.

---

## Reused cross-page patterns

These components are new files but follow the layout patterns established by earlier pages. The Drupal team should recognise the paragraph bundle names and reuse existing bundle configurations where possible.

| Component | Pattern source | Paragraph bundle |
|-----------|---------------|-----------------|
| `01-breadcrumb.html` | `eye-specialists-components/01-breadcrumb.html` | `breadcrumb.html.twig` (core block) |
| `02-hero-banner.html` | `eye-specialists-components/02-hero-banner.html` | `hero_banner_callback` |
| `05-our-story.html` | `eye-specialists-components/06-our-story.html` | `text_callout` |
| `08-experts-header.html` | Pattern from eye-specialists hero text block | `text_callout` (centered variant) |
| `09-why-cfs.html` | `eye-specialists-components/07-why-cfs.html` | `feature_card_grid` + `feature_card` |
| `10-faq.html` | `eye-specialists-components/08-faq.html` | `faq_section` + `faq_item` |
| `11-callback-form.html` | `eye-specialists-components/09-callback-form.html` (post-fix variant) | `callback_cta` |

The category filter is the one structural difference from all prior pages: it uses **chip links** (`<ul>` of `<a>` elements) rather than a `<select>` dropdown. The Twig override for `views-exposed-form.html.twig` must emit chip markup rather than a form element for this exposed filter.

---

## JS hooks needed

**No new JS files or new handler functions are required for this page.**

All interactive elements are covered by `js/main.js` (shared). `specialities.html` contains no inline `<script>` blocks — it loads only `js/main.js` via a single `<script src="../js/main.js">` tag.

| Interaction | Handler location | Status |
|-------------|-----------------|--------|
| Mobile nav toggle | `js/main.js` (`data-menu-toggle`) | Live, shared |
| Doctor cards slider | `js/main.js` (`data-slider="doctors"`) | Live, shared handler — covers mobile slider and desktop grid |
| Sticky bar | `js/main.js` (`data-sticky-action`) | Live, shared |
| FAQ accordion | `js/main.js` (`data-faq-toggle` / `data-faq-answer` / `data-faq-item`) | Live, shared handler in `js/main.js` — no Drupal-side work needed |
| Hero callback form | `data-hero-callback` — stub form, no JS handler | Stub form, no JS handler. Drupal Webform module wires submission post-handoff |
| Category filter | Server-driven via `?category=<slug>` query param | No client JS needed — page reloads on chip click; Drupal Views Exposed Filter handles filtering |
| Callback form | `data-callback-form` — stub form, no JS handler | Stub form, no JS handler. Drupal Webform module wires submission post-handoff |
| Why CFS hover | CSS `group-hover:` transitions | No JS — pure CSS. `data-why-cfs-card` is a reserved hook only |

---

## Caveats / known gaps

1. **`assets/images/specialities-family.png` is a placeholder copy of `centre-delhi.png`.** The hero right panel uses a renamed copy of an existing centre photo. The real family-with-clear-vision photography has not been provided. The `<img>` dimensions `width="663" height="672"` match the design spec (Figma frame proportions), not the placeholder image's actual dimensions. Update both the `src` and confirm dimensions match the real asset when it arrives.

2. **`assets/images/treatment-lifestyle.png` is a placeholder copy of `specialists-group.png`.** In the static markup all 12 treatment cards share this one placeholder image. In production, each treatment node (`node--treatment`) has its own image via `field_image`. Replace when per-treatment photography is provided.

3. **6th centre card (Haryana) reuses `centre-delhi.png` because only 5 distinct centre photos exist in `assets/images/`.** The Haryana-specific photography has not been provided. Replace `src="../assets/images/centre-delhi.png"` on the Haryana card when the real Haryana centre asset arrives.

4. **Contact strip phone numbers are placeholders.** `08065423777` (Delhi NCR) and `08065423666` (Rest of India) are design-time placeholder values. Drupal site configuration or the `contact_strip` paragraph `field_phone` supplies the real numbers post-handoff — do not hardcode these values in the Twig template.

5. **FAQ Q1 is marked `*PLACEHOLDER*`; Qs 2–6 are cataract-related preview content.** Questions 2–6 ("Is Cataract Surgery A Major Surgery?", "How Painful Is Cataract Surgery?", "Who Gets Affected By Cataracts?", "Is Cataract Surgery The Only Surgical Option For Treating Cataracts?", "Which Lens Is Best For Cataract?") are carried over from the cataract-page screenshot and are not appropriate for a general specialities page. The Drupal content team **must replace all 6 questions** with specialities-specific FAQ content before launch.

6. **Category filter is stub-only.** The chip `<a>` elements link to `?category=<slug>` with no backend wiring. Drupal must wire this to the Views Exposed Filter per the mapping in `docs/specialities-drupal-mapping.md`. The static slug values (e.g. `cataract`, `lasik`, `retina-uvea`) are illustrative — actual values must match the `speciality` taxonomy term URL aliases generated by pathauto.

7. **Hero `<img>` `width="663" height="672"` matches design spec, not placeholder dimensions.** The `width`/`height` attributes are intentionally set to the Figma-specified dimensions of the real asset slot. This ensures the browser reserves the correct layout space (avoiding CLS) once the real image is dropped in. Do not change these values to match the placeholder — ensure the real family photo is delivered at 663×672px (or 2× for retina: 1326×1344px).

8. **`<main>` wraps only the treatments grid (id="treatments").** The breadcrumb, hero, category filter, and all post-grid sections (Our Story through callback form) are direct `<body>` children in the static HTML — semantically valid HTML5 but narrower than typical Drupal page structure. The Drupal team may expand `<main>` to encompass more sections in the final Twig page template without breaking any static preview behaviour.

9. **Hero phone input uses `id="specialities-hero-phone"`, not the spec's `id="hero-callback-phone"`.** The id is page-scoped to prevent collisions across Drupal page templates that share partials (eye-specialists uses `id="specialist-hero-phone"` for the same reason). The `name="phone"` attribute — what Drupal Webform actually binds to — is unchanged and correct. Drupal templates should preserve the page-scoped id pattern when porting these partials.

10. **Treatment-card category coverage is sparse in the static preview.** Only 2 of the 10 filter categories have representative cards: `cataract` (4 cards) and `lasik` (8 cards). The other 8 chips (Glaucoma, Retinoblastoma, Squint Eye Treatment, Cornea Transplant, Low Vision Aids, Retina & Uvea, Oculoplasty) are filterable but have no static cards — clicking them in the static preview will appear to return zero results. This is expected stub behaviour; Drupal Views populates real treatment nodes per category at runtime.

---

## Paragraph bundle suggestions (new for this page)

Most required bundles already exist from prior pages. The one new bundle is `contact_strip_item`:

| Bundle | First introduced on | Used here as |
|--------|-------------------|--------------|
| `hero_banner_callback` | Centre-cluster | Hero with inline phone CTA |
| `text_callout` | Centre-cluster | Our Story grey block; Experts header |
| `region_card_grid` + `region_card` | Centre-cluster | All Centres 6-card grid |
| `contact_strip` + `contact_strip_item` | **This page (new)** | 3-column phone/link band |
| `feature_card_grid` + `feature_card` | Centre-cluster | Why CFS 4-card grid |
| `faq_section` + `faq_item` | Centre-cluster / Cataract | FAQ accordion |
| `callback_cta` | Cataract / Centre-cluster | Callback form section |

The **new Drupal entities** this page introduces:
- `node--treatment` content type with `card` view mode (primary implementation work)
- `contact_strip_item` paragraph bundle (nested inside existing `contact_strip`)

---

## Views suggestions

One new View needed:

**View: "Treatments"**
- Base: `node` (type = `treatment`)
- Display 1: **Page listing** (the specialities page body — the treatments grid)
  - Row template: `node--treatment--card.html.twig` (view mode `card`)
  - Sort: `field_category` (taxonomy weight), then `title` ASC
  - Filter: published = Yes
  - Exposed filter: `field_category` (taxonomy term, vocabulary `speciality`) — rendered as chip list via `views-exposed-form.html.twig` override
  - Pager: none in current static design (all 12 visible at once); optionally add load-more or infinite scroll for large treatment counts
  - Path: `/specialities` (or block on the landing page node)

---

## Files shared with other pages

- `css/input.css`, `css/output.css`, `css/custom.css` — no new utility classes introduced
- `js/main.js` — nav toggle, doctor-cards slider, sticky bar, FAQ accordion (all shared)
- `html/components/` — utility bar, nav, doctor-cards, footer, sticky bar (5 files verbatim)

## No deviations from design

All sections match the specialities Figma design intent as referenced in `docs/specialities-design-spec.md`. Treatment card image placeholders use `treatment-lifestyle.png` as a stand-in — Drupal will populate real per-treatment photos via `field_image`. Centre region card placeholder for Haryana uses `centre-delhi.png` as noted in caveats above.