# Blogs Page — Integration Notes

Short document explaining best-fit Drupal techniques per section, highlighting risks and open decisions. Companion to `docs/blogs-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 (featured-post slider) | **Views slider display** (`node--blog--hero.html.twig`) | Featured posts are content-managed via `field_promoted=true`; slider JS reuses existing `data-slider` handler |
| Search filter | **Views Exposed Form** (3 exposed filters) | Leverages Views filter framework; Twig override preserves exact `id`/`name`/`data-*` attributes |
| Category filter | **Views Exposed Form** (chip list variant) | Same chip pattern as specialities page; override `views-exposed-form.html.twig` |
| Blog grid | **Views page display** (`node--blog--card.html.twig` as row template) | One template, many places; no duplication |
| Sidebar — Reader's Favourite | **Views block display** (sort by view count) | Independent block; Statistics module or custom sort |
| Sidebar — Hindi Blogs | **Views block display** (filter `field_language=hi`) | Independent block; language-filtered variant of the blogs View |
| Pagination | **Drupal Views pager** → `pager.html.twig` override | Pill-style override; Drupal computes real page count |
| Our Story and Vision | **Paragraph** (`text_callout`) | Reusable grey text block; shared bundle with specialities, eye-specialists, centre-cluster |
| Why CFS cards | **Paragraph** (`feature_card_grid` with nested `feature_card`) | Variable card count; each card is its own paragraph entity |
| 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/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 | Drupal target |
|-----------|---------------|--------------|
| `01-breadcrumb.html` | `specialities-components/01-breadcrumb.html` | `breadcrumb.html.twig` (core block) |
| `08-our-story.html` | `specialities-components/05-our-story.html` | `text_callout` paragraph bundle |
| `09-why-cfs.html` | `specialities-components/09-why-cfs.html` | `feature_card_grid` + `feature_card` paragraph bundles |
| `10-callback-form.html` | `specialities-components/11-callback-form.html` (post-fix variant) | `callback_cta` paragraph bundle |

The two structural differences from all prior pages:

1. **Hero is a full-bleed image slider**, not a split left-panel / right-image layout. No `hero_banner_callback` paragraph bundle — use a Views slider display instead.
2. **Main content is a 2/3+1/3 grid** (blog cards + sidebar widgets), not a single full-width listing. The `<main id="blogs-grid">` element wraps this two-column split only.

---

## 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). `blogs.html` contains no inline `<script>` blocks — it loads only `js/main.js` via a single `<script src="../js/main.js">` tag.

The hero uses the existing generic `data-slider`/`data-slider-prev`/`data-slider-next` handler in `js/main.js` — the same one used by the homepage doctor-cards carousel. No new slider code is required.

| Interaction | Handler location | Status |
|-------------|-----------------|--------|
| Mobile nav toggle | `js/main.js` (`data-menu-toggle`) | Live, shared |
| Hero featured-post slider | `js/main.js` (`data-slider="featured-blog"`) | Live, shared handler — same as doctor-cards carousel |
| Sticky bar | `js/main.js` (`data-sticky-action`) | Live, shared |
| Category filter | Server-driven via `?category=<slug>` query param | No client JS needed — page reloads on chip click; Drupal Views Exposed Filter handles filtering |
| Search filter | Drupal Views Exposed Form handles submit | No custom JS needed after handoff |
| Why CFS hover | CSS `group-hover:` transitions | No JS — pure CSS. `data-why-cfs-card` is a reserved hook only |
| Callback form | `data-callback-form` — stub form, no JS handler | Stub form. Drupal Webform module wires submission post-handoff |
| Pagination | Server-driven `?page=N` links | No client JS needed — Drupal Views pager handles page navigation |

---

## Caveats / known gaps

1. **`assets/images/blog-hero-dark-circles.png` is a placeholder copy of `blog-cataracts.png`.** The hero image uses a renamed copy of the shared cataract placeholder. Real dark-circles photography has not been provided. Update `src` when the production asset arrives. The `width="1320" height="520"` dimensions match the design spec, not the placeholder.

2. **All 10 main blog-card images use the shared `blog-cataracts.png` placeholder.** In production, each blog node (`node--blog`) has its own image via `field_image`. Replace when per-blog photography is provided by the content team.

3. **Hero featured-post is a single static post; carousel arrows are decorative until Drupal expands the slider with multiple posts.** The `data-slider-prev` / `data-slider-next` buttons are wired to the shared slider handler but have no real slides to navigate in the static HTML. The handler will silently no-op on a single-slide view. Arrows become functional once multiple `field_promoted=true` blog nodes exist in Drupal.

4. **"Lorem Ipsum" is the 12th category chip — explicit placeholder for the Drupal content team to rename to a real taxonomy term.** The slug `lorem-ipsum` and label "Lorem Ipsum" are intentionally left as a visible placeholder. Do not remove the chip in static HTML — leave the replacement to the Drupal content team after taxonomy terms are finalised.

5. **Pagination shows pages 1, 2, 3, …, 12 — the "12" is hardcoded for layout demo; Drupal Views pager computes the real count.** Do not copy the literal "12" into the `pager.html.twig` override. Let Drupal's pager variables (`pager_last`, `pager_total`) supply the real last page number.

6. **Hindi Blogs widget uses placeholder Devanagari content; Drupal supplies real Hindi titles via a separate language-filtered Views block.** The sidebar widget heading "Hindi Blogs" and all thumbnail/title content are static placeholders using `blog-cataracts.png`. Real content comes from the `blog_hindi` Views block display filtered by `field_language=hi`.

7. **All search-filter fields have `id` + `name`; backend wiring is Drupal Views Exposed Form.** The `id="blog-search"` / `name="q"`, `id="blog-month"` / `name="month"`, `id="blog-year"` / `name="year"` attributes must be preserved verbatim in the `views-exposed-form.html.twig` override. Changing `name` values changes the query param and breaks URL-based filter sharing.

8. **`<main id="blogs-grid">` wraps only the grid+sidebar split (semantic for the dominant content of the page); breadcrumb, hero, search, filter, pagination, and post-grid sections are direct `<body>` children.** This is semantically valid HTML5 and mirrors the pattern used by `specialities.html` (`<main id="treatments">`). The Drupal team may expand `<main>` to wrap more sections in the Twig page template without breaking any static preview behaviour.

---

## Paragraph bundle suggestions

Most required bundles already exist from prior pages. The new entities specific to this page:

| Bundle / entity | First introduced on | Used here as |
|-----------------|-------------------|--------------|
| `text_callout` | Centre-cluster | Our Story grey block |
| `feature_card_grid` + `feature_card` | Centre-cluster | Why CFS 4-card grid |
| `callback_cta` | Cataract / Centre-cluster | Callback form section |

**New Drupal entities this page introduces:**
- `node--blog` content type with `card` view mode (`node--blog--card.html.twig`) and `hero` view mode (`node--blog--hero.html.twig`)
- `pager.html.twig` pill-style override (new override, not a new entity)
- `blog_readers_favourite` Views block display (sort variant)
- `blog_hindi` Views block display (language filter variant)
- `blog_featured_hero` Views slider display (promoted filter variant)

---

## Views suggestions

One new View with multiple displays needed:

**View: "Blogs"**
- Base: `node` (type = `blog`)
- **Display 1: Page listing** (the blogs page main grid)
  - Row template: `node--blog--card.html.twig` (view mode `card`)
  - Sort: `field_published_date` DESC
  - Filter: published = Yes
  - Exposed filters: `title` (contains), `field_published_date` month + year, `field_category` (chip variant)
  - Pager: full pager with `pager.html.twig` override (pill style)
  - Path: `/blogs`
- **Display 2: Block — Featured Hero** (`blog_featured_hero`)
  - Row template: `node--blog--hero.html.twig` (view mode `hero`)
  - Filter: `field_promoted = true` + published = Yes
  - Sort: `field_published_date` DESC
  - Limit: 5 (or unlimited; JS handler cycles through)
- **Display 3: Block — Reader's Favourite** (`blog_readers_favourite`)
  - Row template: inline teaser-thumb item (matches `06-sidebar-list.html` item)
  - Sort: view count DESC
  - Limit: 4–5 items
- **Display 4: Block — Hindi Blogs** (`blog_hindi`)
  - Row template: same as Display 3
  - Filter: `field_language = hi`
  - Sort: `field_published_date` DESC
  - Limit: 4–5 items

---

## Files shared with other pages

- `css/input.css`, `css/output.css`, `css/custom.css` — no new utility classes introduced
- `js/main.js` — nav toggle, featured-post slider, sticky bar (all shared)
- `html/components/` — utility bar, nav, footer, sticky bar (4 files verbatim)

## No deviations from design

All sections match the blogs Figma design intent as referenced in `docs/blogs-design-spec.md`. Blog card and sidebar images use `blog-cataracts.png` as a stand-in — Drupal will populate real per-blog photos via `field_image`. Hero image uses `blog-hero-dark-circles.png` as noted in caveats above.