# SW Blog Cards — AI Agent Documentation

**Module path:** `smithworks-2025/sw-modules/SW Blog Cards.module`  
**Last updated:** 2026-02-12

---

## 1. Overview

SW Blog Cards displays blog posts in a grid or slider layout. It is used on **blog listing pages** and **website or landing pages** only. For **related posts on blog post pages**, use **SW Blog Related Posts** instead.

SW Blog Cards adapts its behavior based on **where it is placed**:

- **Blog listing page:** Uses the listing's posts; supports HubSpot pagination (Posts to show = 0) or manual slice.
- **Website or landing page:** Fetches posts from the selected Blog; supports infinite scroll or grid.

**Critical:** Slider and infinite scroll are **mutually exclusive**. To use the slider, **turn off** Use infinite scroll. If the user wants the slider but doesn't see it, they must disable infinite scroll first.

### Related Modules

| Module | Relationship |
|--------|--------------|
| **SW Blog Related Posts** | For related posts on **blog post pages**. SW Blog Cards is for listing/website only. |
| **SW Cards** | Generic card repeater for non-blog content. SW Blog Cards is for blog posts only. |

---

## 2. Context-Specific Behavior

### 2.1 Blog Listing Page

When the module is on a **blog listing template** (e.g. main blog index):

- **Post source:** Uses `contents` — the posts HubSpot provides for the listing.
- **Tag Filter:** Optional. If set, filters the listing's posts to those with the selected tag.
- **Posts to show = 0:** Uses HubSpot's built-in pagination (shows all posts with HubSpot pagination controls).
- **Posts to show > 0:** Slices the listing to show that many posts (respects Post start).
- **Infinite scroll:** **Ignored** on blog listing pages. The module does not support infinite scroll on listing pages.
- **Slider:** Available when Use as slider is ON and posts exceed Cards per row (XL). Requires infinite scroll OFF.

**Posts-per-page limitation (blog setup):** HubSpot's `contents` variable only contains the number of posts set in **Marketing → Website → Blog → [Your Blog] → Templates → Number of posts per listing page**. The effective max posts displayed = that setting. When using **Post start** (offset), the displayed count = posts per page − (post start − 1). **When setting up blog templates:** Set HubSpot "Number of posts per listing page" = **Posts to show + (Post start − 1)**. Example: 12 cards + 1 hero offset → set 13 posts per page.

**Post start first page only:** When ON (default), the offset applies only on page 1. Use when SW Blog Listing Hero shows on first page—avoids incorrectly skipping a post on page 2+ where the hero is not present. When OFF, the offset applies on every page.

### 2.2 Website or Landing Page

When the module is on a **website page** or **landing page**:

- **Post source:** Fetches from the **Blog** field (Content tab). Select the blog to pull from.
- **Tag Filter blank:** Shows all recent posts from the selected blog.
- **Tag Filter set:** Shows only posts with the selected tag.
- **Infinite scroll:** Supported. Use infinite scroll ON for On scroll or Load more button.
- **Slider:** Available when Use as slider is ON and posts exceed Cards per row (XL). **Requires infinite scroll OFF.**

---

## 3. Slider vs. Grid vs. Infinite Scroll

### 3.1 Display Modes

| Mode | When it applies | Notes |
|------|-----------------|-------|
| **Grid** | Default. Posts wrap into rows. | Always available. |
| **Slider** | Use as slider = ON **and** infinite scroll = OFF **and** posts > Cards per row (XL). | **Slider settings are hidden when infinite scroll is ON.** User must turn off infinite scroll to see/use slider. |
| **Infinite scroll** | Use infinite scroll = ON (website/landing only). | Load trigger: On scroll or Load more button. Chunks revealed progressively. |

### 3.2 Slider Requirements (Important for Troubleshooting)

**If the user wants the slider but doesn't see it:**

1. **Turn off Use infinite scroll.** Content tab → Post Display Settings → Use infinite scroll = OFF.
2. Ensure **Use as slider** = ON. Style tab → Slider settings → Use as slider.
3. Ensure there are **more posts than Cards per row (XL)**. Slider only activates when posts exceed the visible cards per row.

**Slider settings group** is **hidden** when Use infinite scroll is ON. The user cannot configure arrows, dots, autoplay, or bounce until infinite scroll is disabled.

### 3.3 Infinite Scroll

- **Load trigger:** On scroll (Intersection Observer) or Load more button.
- **Load more button:** Text, style (all Sprocket Rocket options including Outline Primary, etc.), size, Add icon, Icon (picker, position, purpose). Default: "Load More Posts", Outline Primary, Chevron Circle Down icon.
- **Chunk size:** Same as Posts to show (e.g. 6 posts per chunk).
- **Max posts:** Limits total posts loaded (default 24).

---

## 4. Tag Filter

**Field:** Content tab → Tag Filter.

- **Blank:** On blog listing: All listing posts. On website/landing: All recent posts from selected blog.
- **Tag selected:** Filters posts by that tag.

---

## 5. Empty State (No Matches)

When a tag filter returns **no posts** (e.g. tag with zero posts):

- A centered message box appears: **"Check back later for our latest content."**
- Box styling: Same background, text color, and border as cards. Max-width 500px, padding 25px, margin 50px 25px, text centered. Border radius uses global theme when card border override is OFF.

---

## 6. Content Tab (Order)

1. **Custom ID** / **Custom Classes**
2. **Headings** (repeater) — Heading, Size, Display Size, Color, Align; Override Text Alignment (Tablet/Mobile); Override Tablet/Mobile Display Size; Override Padding, Padding Top/Bottom (px); CSS Class
3. **Content Area** — Rich text between headings and cards
4. **Content style** — Typography for Content Area: Default, Large (text balanced), Large (text full-width), Small, Blockquote
5. **Button Alignment** — Left, Center, Right
6. **Buttons** (repeater) — Button Text, Link, Style, Size, Add Icon, Icon
7. **Blog** — Select blog (website/landing only; ignored on blog listing)
8. **Tag Filter** — Optional. Blank = related posts (blog post) or all posts (else). Select tag to filter.
9. **Post Display Settings** — Posts to show, Post start, Use infinite scroll, Max posts, Load trigger, Load more button (when Load trigger = Load more button)
10. **Post Card** — Featured image, Tags, Summary, Author, Date, Read More (text, style, size, icon)

---

## 7. Style Tab (Order)

1. **Module Settings** — Spacing, Max Module Width, XL/Desktop/Tablet/Mobile height cascade
2. **Module Background Settings** — Background Option (Theme Color, Custom Color, Gradient, Image, Video)
3. **Content Colors** — Card content text (Theme defaults, Primary, Dark, Light, Custom), Custom Text Color when Custom, Card content links (Theme defaults, Dark, Light). **Card content links applies only when Read More = simple link.** Content Area text and Content Area links (for rich text below cards) with same options.
4. **Content Area Settings** — Text align, Override Tablet/Mobile align; Spacing, Override Tablet/Mobile spacing
5. **Cards Layout** — Cards per row (XL, Desktop, Tablet, Mobile), Card Spacing (padding, gutter), Card Colors (Card Background only), Card Border Settings, Tags Settings, Text Box Spacing, Enable Hover Effect, Enable Card as Link. When Enable Card as Link is ON, the entire card is a link; title, summary, and meta stay plain text; Read More (simple link) uses link color.
6. **Slider settings** — **Visible only when Use infinite scroll = OFF.** Use as slider, Show slider arrows, Custom arrows, Show slider dots, Auto advance, Slide bounce, Seconds between slides

---

## 8. Configuration Reference (Key Fields)

### Post Display Settings (Content tab)

| Field | Purpose |
|-------|---------|
| Posts to show | Number to display. On blog listing with 0: use HubSpot pagination. With infinite scroll: chunk size. **Blog listing:** Max = HubSpot "posts per listing page" − (Post start − 1). Set HubSpot posts per page = Posts to show + offset. |
| Post start | Skip first N posts (e.g. 2 = skip first post). On blog listing with "Post start first page only" ON: only applies on page 1. |
| Post start first page only | When ON (default): offset applies only on page 1. Use when hero shows on first page only. When OFF: offset on every page. |
| Use infinite scroll | ON = progressive load (On scroll or Load more). **OFF required for slider.** Ignored on blog listing. |
| Max posts | Max posts when infinite scroll ON (default 24). |
| Load trigger | On scroll or Load more button. Required when infinite scroll ON. |
| Load more button | Text, style, size, Add icon, Icon. Visible when Load trigger = Load more button. |

### Slider Settings (Style tab) — Visible when infinite scroll OFF

| Field | Purpose |
|-------|---------|
| Use as slider | When ON and posts > cards per row: show slider instead of grid. |
| Show slider arrows | Left/right arrows. |
| Custom arrows | Arrow size, left/right type (Font Awesome or image), colors. |
| Show slider dots | Pagination dots. |
| Auto advance slides | Autoplay. |
| Slide bounce | Subtle bounce when autoplay OFF. |
| Seconds between slides | Autoplay interval; bounce frequency. |

### Content Colors (Style tab)

| Field | Purpose |
|-------|---------|
| Text Color | Card content text (Theme defaults, Primary, Dark, Light, Custom). |
| Custom Text Color | When Text Color = Custom. |
| Link Colors | Card content links (Theme defaults, Dark, Light). **Applies only when Read More = simple link.** |
| Content Area text | Text color for rich text below cards. |
| Content Area links | Link color for links in Content Area. |

### Content Area Settings (Style tab)

| Field | Purpose |
|-------|---------|
| Text align | Left, Center, Right for Content Area. |
| Override Tablet/Mobile align | Per-breakpoint alignment. |
| Spacing | Padding and margin for Content Area. |

### Cards Layout (Style tab)

| Field | Purpose |
|-------|---------|
| Cards per row (XL/Desktop/Tablet/Mobile) | Grid columns; also slides visible in slider. |
| Card Spacing | Padding and margin on cards; Card Gutter (horizontal space). |
| Card Colors | Card Background only. Text and link colors are in Content Colors. |
| Card Border Settings | Override Card Border, Card Border, Border Radius; Image border overrides. |
| Text Box Spacing | Use custom text box spacing; padding inside card content area. |
| Enable Card as Link | When ON, entire card is link; title/summary/meta stay plain text; Read More uses link color. |

---

## 9. When to Use Custom CSS

Use custom CSS when you need to:

- Change card layout or spacing beyond the Cards Layout fields (e.g. custom grid gaps, card aspect ratios).
- Style the empty-state message beyond the card-like styling (colors, typography).
- Override Blaze Slider appearance (arrows, dots, track) beyond the Slider settings.
- Target specific breakpoints for cards per row or spacing when the built-in overrides are insufficient.
- Add hover effects or transitions beyond Enable Hover Effect.

Place overrides in the theme's `custom-styles.css` (or equivalent). Use the CSS classes in the Appendix.

---

## 10. Common Tasks ("How Do I…")

- **Show related posts on a blog post** → Use **SW Blog Related Posts** on the blog post template instead of SW Blog Cards.
- **Use the slider** → Content → Post Display Settings → Use infinite scroll = **OFF**. Style → Slider settings → Use as slider = ON. Ensure more posts than Cards per row (XL).
- **Slider not showing / Slider settings missing** → Turn **off** Use infinite scroll. Slider settings are hidden when infinite scroll is ON.
- **Load more posts on scroll** → Content → Post Display Settings → Use infinite scroll = ON, Load trigger = On scroll.
- **Load more button instead of scroll** → Content → Post Display Settings → Use infinite scroll = ON, Load trigger = Load more button. Configure Load more button (text, style, icon).
- **Filter by tag** → Content → Tag Filter → Select tag.
- **Change cards per row** → Style → Cards Layout → Cards per row (XL, Desktop, Tablet, Mobile). Also affects slider slides.
- **Change Read More button** → Content → Post Card → Read More (text, style, size, icon).
- **Change card text or link colors** → Style → Content Colors → Text Color, Custom Text Color, Link Colors (Theme defaults, Dark, Light). Link Colors applies only when Read More = simple link.
- **Change content area (below cards) text or links** → Style → Content Colors → Content Area text, Content Area links.
- **Make entire card clickable** → Style → Cards Layout → Enable Card as Link = ON. Title, summary, meta stay plain text; Read More uses link color.
- **Empty state when no posts match** → Automatic. Message: "Check back later for our latest content."
- **Use HubSpot pagination on blog listing** → Content → Post Display Settings → Posts to show = 0.
- **Skip hero on page 1 only** → Content → Post Display Settings → Post start = 2 (or N), Post start first page only = ON. Set HubSpot "Number of posts per listing page" = Posts to show + 1 (e.g. 13 for 12 cards + 1 hero).

---

## 11. Appendix: CSS Classes and Selectors

| Element | Class(es) | Notes |
|---------|-----------|-------|
| Module wrapper | `.sw-blog-cards` | Plus `data-instance`, custom_classes, Custom ID. Modifiers: `.sw-blog-cards--has-bg-video` |
| Inner | `.sw-blog-cards__inner` | Content wrapper |
| Headings | `.sw-blog-cards__headings`, `.sw-blog-cards__heading-wrap`, `.sw-blog-cards__heading` | |
| Grid | `.sw-blog-cards__grid` | Row with `row g-0`; `row-gap` for vertical spacing |
| Slider | `.sw-blog-cards__slider`, `.blaze-slider`, `.blaze-track`, `.blaze-arrow`, `.blaze-pagination` | Blaze Slider library |
| Infinite scroll | `.sw-blog-cards__infinite-scroll`, `.sw-blog-cards__chunk`, `.sw-blog-cards__chunk--hidden`, `.sw-blog-cards__sentinel` | |
| Load more | `.sw-blog-cards__load-more-wrap`, `.sw-blog-cards__load-more` | Button or simple-link |
| Card column | `.sw-blog-cards__col` | Per-card column |
| Card | `.sw-blog-cards__card` | Article wrapper |
| Card image | `.sw-blog-cards__card-image` | |
| Card content | `.sw-blog-cards__card-content` | |
| Card tags | `.sw-blog-cards__card-tags`, `.sw-blog-cards__card-tag` | |
| Card heading | `.sw-blog-cards__card-heading` | |
| Card summary | `.sw-blog-cards__card-summary` | |
| Card meta | `.sw-blog-cards__card-meta` | Author/date |
| Read more | `.sw-blog-cards__read-more` | `a.simple-link` or `span.simple-link` when card is link |
| Content area | `.sw-blog-cards__content-area` | Rich text below cards; text/link colors from Content Colors |
| Card link context | `[data-link-context="dark"]`, `[data-link-context="light"]` | On `.sw-blog-cards__card` when Link Colors = Dark or Light |
| CTA | `.sw-blog-cards__cta` | Buttons below cards |
| Empty state | `.sw-blog-cards__empty-state-wrap`, `.sw-blog-cards__empty-state`, `.sw-blog-cards__empty-state__text` | When no posts match |

---

## 12. Document Version

**Module:** SW Blog Cards (smithworks-2025).  
**Doc last updated:** 2026-02-24.

**2026-02-24:** Posts-per-page limitation (HubSpot blog setting = contents length); blog setup discussion point (posts per page = Posts to show + offset). Post start first page only (offset on page 1 only when hero present). Configuration reference and common tasks updated.  
**2026-02-12:** SW Blog Cards now listing and website only; use SW Blog Related Posts for blog post related sections. Content Colors (Card content text/link, Content Area text/link); Content Area Settings; Enable Card as Link; Card content links applies only when Read More = simple link; Read More link colors when card is link. Configuration reference and common tasks updated.  
**2026-02-06:** Initial AI documentation. Context behavior (blog listing, blog post related posts, website/landing). Slider vs infinite scroll (mutually exclusive; slider requires infinite scroll OFF). Tag filter behavior. Empty state. Load more button defaults. Full configuration reference and CSS appendix.