Event Calendar Module - Knowledge Base

Table of Contents

1. Quick Start Guide
2. Module Configuration
3. Field Reference
4. Styling & Customization
5. Advanced Features
6. Troubleshooting
7. Technical Details
8. Best Practices

Quick Start Guide

Installation

1. Upload the Event Calendar Module.module folder to your HubSpot Design Manager
2. Add the module to any page, landing page, or template
3. Configure your events in the module editor

Basic Setup (5 Minutes)

1. Add Events: In the Content tab, click "Add" under Events to create your first event
2. Required Fields:
   • Event Title
   • Event Description
   • Event Date (use the date picker)
   • Venue Name
   • Event Location
   • Event Type
3. Optional: Add an event image and "Learn More" link
4. Publish: Save and publish your changes

First Event Example

Title: Annual Company Picnic
Description: Join us for food, games, and team building activities.
Date: June 15, 2025
Venue: City Park Pavilion
Location: Portland
Type: Community
Link: https://example.com/register

Module Configuration

Content Tab

Events Repeater

The Events repeater allows you to add unlimited events. Each event contains:

Tips:

• Events automatically sort by date (earliest first)
• Use consistent capitalization for Event Types (see Gotchas)
• Leave Event Link empty if no registration is needed
• Images are optional but enhance visual appeal

Settings Tab

Search & Filters Section

Show Search

• Toggle to display/hide the search bar
• Search looks across: titles, descriptions, venues, and locations
• Real-time filtering with 150ms debounce for performance

Search Placeholder (Default: "Search events...")

• Customize the placeholder text users see in the search box

Show Location Filter

• Toggle to display/hide location dropdown
• Options auto-generate from your events' Location fields
• Sorted alphabetically

All Locations Label (Default: "All Locations")

• Customize the default "show all" option text

Show Type Filter

• Toggle to display/hide event type dropdown
• Options auto-generate from your events' Event Type fields
• Sorted alphabetically

All Types Label (Default: "All Types")

• Customize the default "show all" option text

Animations Section

Card Animation

• None: Cards appear instantly (best for accessibility)
• Fade In: Cards fade into view
• Slide Up: Cards slide up from below
• Scale In: Cards grow from 90% to 100% size

Animation Delay (Default: 100ms)

• Time between each card's animation
• Range: 0-500ms
• Lower = faster cascade, Higher = more dramatic effect
• Set to 0 for all cards to animate simultaneously

UI Messages Section

No Results Message (Default: "No events found matching your criteria.")

• Text shown when filters produce zero results
• Customize to match your brand voice

Style Tab

The Style tab contains 80+ customization options organized into logical groups:

Colors Group (15 fields)

• Card Background Color
• Card Hover Background Color
• Date Background Color
• Date Text Color
• Title Color
• Description Color
• Detail Icon Color
• Controls Background Color
• Controls Focus Background Color
• Controls Text Color
• No Results Message Color
• Button Background Color
• Button Text Color
• Button Hover Background
• Button Hover Text Color

Spacing & Padding Group

• Card Spacing (gap between cards)
• Card Content Padding (internal padding)
• Controls Margin (space below filters)

Card Styles Group

• Card Border Radius
• Card Shadow (toggle)
• Card Hover Shadow (toggle)
• Card Date Width
• Card Date Padding
• Card Image Width
• Controls Border Radius

Button Styles Group

• Button Padding Vertical
• Button Padding Horizontal
• Button Border Radius
• Button Font Weight
• Button Letter Spacing

Controls Styles Group

• Controls Gap (space between filter elements)
• Controls Input Padding

UI Messages Group

• No Results Padding

Styling & Customization

Color Scheme Presets

Corporate Professional

Card Background: #ffffff
Date Background: #012b4a
Date Text: #ffffff
Title: #1a1a1a
Description: #666666
Button Background: #012b4a
Button Text: #ffffff

Modern Vibrant

Card Background: #f8f9fa
Date Background: #6366f1
Date Text: #ffffff
Title: #1e293b
Description: #475569
Button Background: #6366f1
Button Text: #ffffff

Minimalist Dark

Card Background: #1f2937
Date Background: #3b82f6
Date Text: #ffffff
Title: #f9fafb
Description: #d1d5db
Button Background: #3b82f6
Button Text: #ffffff

Spacing Recommendations

Tight Layout (compact design):

• Card Spacing: 16px
• Card Padding: 24px
• Controls Margin: 24px

Standard Layout (balanced):

• Card Spacing: 24px
• Card Padding: 32px
• Controls Margin: 32px

Spacious Layout (airy feel):

• Card Spacing: 32px
• Card Padding: 40px
• Controls Margin: 40px

Responsive Behavior

The module automatically adapts at these breakpoints:

Desktop (>1024px)

• Cards: Date (120px) | Content (flex) | Image (customizable)
• Filters: Horizontal row

Tablet (768px - 1024px)

• Cards: Date (120px) | Content (flex) | Image (280px)
• Filters: Horizontal row

Mobile (<768px)

• Cards: Stacked vertical layout
• Filters: Stacked vertical (full width)
• Date: Overlays image (if image exists) or full-width horizontal bar (no image)

Advanced Features

Auto-Generated Filters

The module intelligently extracts unique values from your events:

How It Works:

1. Module scans all events' event_location fields
2. Creates a unique, alphabetically sorted list
3. Populates the Location dropdown dynamically

Example:

Events have locations: "Austin", "Portland", "Austin", "Chicago"
Filter shows: "Austin", "Chicago", "Portland"

Benefits:

• No manual filter configuration needed
• Automatically updates when you add/remove events
• Guaranteed accuracy (filters match actual data.

Smart Image Loading

The module optimizes image performance automatically:

First 2 Events:

• loading="eager" - Loads immediately
• fetchpriority="high" - Browser prioritizes these
• Improves Largest Contentful Paint (LCP)

Events 3+:

• loading="lazy" - Only loads when scrolling near them
• fetchpriority="low" - Browser deprioritizes
• Saves bandwidth and improves initial page load

Override: In the image field settings, you can manually set loading behavior per image.

Search Algorithm

The search function looks across multiple fields:

// Searches this combined string (lowercased):
"event title event description venue name event location"

Example: Searching "san francisco" will match:

• Events with "San Francisco" in Location
• Events at "San Francisco Convention Center" (Venue)
• Events with "san francisco" in the description

Case-Insensitive: Search automatically converts to lowercase for matching.

Animation System

Animations use Intersection Observer API for performance:

How It Works:

1. Cards start with opacity: 0 and transform applied
2. When card enters viewport (with 50px margin)
3. JavaScript adds is-visible class
4. CSS transition animates to opacity: 1 and normal transform
5. Each card gets staggered delay based on its position

Performance:

• Only observes visible cards (filtered cards excluded)
• Unobserves after animation completes
• No scroll event listeners (uses native Intersection Observer)

Filter Combination Logic

All active filters use AND logic:

Search: "workshop"
Location: "Austin"
Type: "Workshop"

Result: Events that are Workshops AND in Austin AND match "workshop" in text

Empty filters are ignored (treated as "all").

Troubleshooting

Events Not Appearing

Problem: Added events but nothing shows on page

Solutions:

1. ✅ Check that Event Date is in the future (or past, depending on your use case)
2. ✅ Verify all required fields are filled
3. ✅ Click "Publish" (not just Save draft)
4. ✅ Clear browser cache and refresh
5. ✅ Check for JavaScript errors in browser console (F12)

Filters Not Working

Problem: Selecting filters doesn't change visible events

Solutions:

1. ✅ Ensure JavaScript is enabled in browser
2. ✅ Check browser console for errors
3. ✅ Verify Event Type values match exactly (see Case-Sensitive Filtering)
4. ✅ Confirm filters are enabled in Settings tab

Images Not Loading

Problem: Event images show broken or don't appear

Solutions:

1. ✅ Verify image URL is publicly accessible
2. ✅ Check image src field is not empty string
3. ✅ Ensure image is uploaded to HubSpot Files or accessible CDN
4. ✅ Confirm image dimensions are set (width/height)
5. ✅ Check for HTTPS (mixed content issues)

Styling Not Applying

Problem: Changed colors/spacing but nothing changed on page

Solutions:

1. ✅ Hard refresh browser (Ctrl+Shift+R or Cmd+Shift+R)
2. ✅ Clear HubSpot's cache: Design Manager → Actions → Clear cache
3. ✅ Verify you're editing the correct module instance
4. ✅ Check for CSS conflicts with theme styles
5. ✅ Use browser inspector to verify CSS custom properties are set

Case-Sensitive Filtering

Problem: Filter dropdown shows duplicate types like "Conference" and "conference"

Solution: Event Type filtering is case-sensitive. Ensure consistent capitalization:

✅ Good (consistent)

Event 1: Type = "Conference"
Event 2: Type = "Conference"
Event 3: Type = "Workshop"

❌ Bad (inconsistent):

Event 1: Type = "Conference"
Event 2: Type = "conference"
Event 3: Type = "CONFERENCE"

Fix: Edit events and standardize capitalization (recommend Title Case).

Animation Performance Issues

Problem: Page feels sluggish with many events

Solutions:

1. ✅ Set Card Animation to "None"
2. ✅ Reduce Animation Delay to 0-50ms
3. ✅ Limit events per page (use pagination or separate pages)
4. ✅ Optimize image sizes (compress before uploading)

Mobile Layout Issues

Problem: Cards look broken on mobile devices

Solutions:

1. ✅ Module automatically adapts - check actual mobile device, not just browser resize
2. ✅ Clear cache on mobile device
3. ✅ Verify Card Image Width isn't too large (recommended: 320px max)
4. ✅ Check for theme CSS conflicts overriding .blk_event-card

Technical Details

CSS Custom Properties

The module uses CSS custom properties for dynamic styling:

How It Works:

<div class="blk_events-list" style="--card-bg: rgba(255,255,255,1);">
  <div class="blk_event-card">
    <!-- Card inherits --card-bg variable -->
  </div>
</div>

.blk_event-card {
  background: var(--card-bg);
}

Benefits:

• Single source of truth for colors/spacing
• Browser-optimized performance
• Easy responsive overrides
• No repeated inline styles on every element

Server-Side Rendering

The module renders all HTML server-side with HubL:

What This Means:

• HTML is generated before page reaches browser
• Content is immediately visible (no JavaScript required)
• SEO-friendly (search engines see full content)
• Better Core Web Vitals scores

JavaScript Only Used For:

• Filtering (toggling visibility)
• Scroll animations
• Search debouncing

Performance Optimizations

1. requestIdleCallback: Defers initialization until browser is idle
2. Debouncing: Search waits 150ms after typing stops
3. Intersection Observer: Efficient scroll-based animations
4. Lazy Loading: Images below fold load on-demand
5. DocumentFragment: Minimal DOM reflows when filtering
6. CSS Transitions: Hardware-accelerated animations

Browser Compatibility

Fully Supported:

• Chrome 76+
• Firefox 68+
• Safari 13+
• Edge 79+

Graceful Degradation:

• Older browsers: No animations, but full functionality
• No JavaScript: Static list of events (no filtering)
• requestIdleCallback fallback: Uses setTimeout if unavailable

Accessibility Features

• ARIA Labels: All interactive elements labeled
• Screen Reader Only Text: .blk_sr-only class for context
• Keyboard Navigation: All filters/links keyboard accessible
• Semantic HTML: Proper heading hierarchy
• Focus States: Visible focus indicators on controls
• Alt Text: Image field includes alt text option

Best Practices

Content Guidelines

Event Titles

• Keep under 60 characters
• Use title case
• Be specific: "Digital Marketing Workshop 2025" not "Workshop"

Event Descriptions

• Aim for 100-200 characters
• Front-load key information
• Include call-to-action when appropriate
• Avoid overly technical jargon

Event Types

• Use 3-7 consistent categories
• Examples: Conference, Workshop, Webinar, Community, Networking, Training
• Stick to title case
• Document your categories for content editors

Locations

• Use city name for consistency
• Avoid abbreviations: "San Francisco" not "SF"
• For online events, use "Online" or "Virtual"

Image Guidelines

Dimensions:

• Recommended: 800x600px (4:3 ratio)
• Minimum: 640x480px
• Maximum: 1920x1080px

File Size:

• Target: Under 200KB per image
• Use JPG for photos (better compression)
• Use PNG for graphics/logos

Alt Text:

• Describe what's in the image
• Keep under 125 characters
• Example: "Conference attendees networking in modern venue lobby"

Filter Configuration

When to Show Search:

• ✅ 10+ events
• ✅ Events have detailed descriptions
• ✅ Users need to find specific topics

When to Hide Search:

• ❌ Less than 5 events
• ❌ All events are similar
• ❌ Minimalist design preference

When to Show Location Filter:

• ✅ Events in 3+ different locations
• ✅ Users care about geographic proximity
• ✅ Regional audience

When to Show Type Filter:

• ✅ Events span 3+ categories
• ✅ Users have specific interests
• ✅ Mixed event types (workshops, webinars, conferences)

Animation Recommendations

None:

• Best for accessibility
• Professional/corporate sites
• Fast-paced user needs

Fade In:

• Subtle, elegant
• Works well with any design
• Safest choice for most sites

Slide Up:

• Dynamic, modern
• Good for creative agencies
• Best with longer delays (150-200ms)

Scale In:

• Most dramatic
• Use sparingly
• Best for fewer events (5-10)

Performance Best Practices

1. Limit Events Per Page: Keep under 50 for optimal performance
2. Optimize Images: Compress before uploading to HubSpot
3. Use Lazy Loading: Enable for all images except first 2
4. Minimize Animation: Consider "None" for large event lists
5. Cache Strategy: Let HubSpot handle caching (don't disable)

SEO Best Practices

1. Structured Data: Consider adding Event schema markup (requires custom code)
2. Unique Titles: Each event should have distinct title
3. Descriptive Content: Write detailed descriptions with keywords
4. Internal Links: Link event links to relevant pages on your site
5. Alt Text: Always provide alt text for images

Maintenance Checklist

Monthly:

•  Remove past events
•  Check for broken event links
•  Update event images if needed
•  Review filter categories for consistency

Quarterly:

•  Audit event types (consolidate if too many)
•  Review analytics for popular searches
•  Test module on mobile devices
•  Check load performance with tools like PageSpeed Insights

Annually:

•  Review color scheme for brand alignment
•  Update default events in fields.json
•  Consider new features/customizations
•  Archive old events to separate page

FAQ

Can I display events in a grid instead of a list?

The current module is optimized for a vertical list layout. For a grid layout, you would need to modify module.css lines 51-64 to use display: grid with multiple columns. This requires CSS knowledge.

Can I add a calendar view?

The current module only supports list view. A calendar view would require significant custom development including a JavaScript calendar library.

Can I export events to .ics calendar files?

This requires custom development. You would need to add a server-side function to generate .ics files from event data.

Can events repeat (recurring events)?

The current module doesn't support recurring events. Each instance must be added as a separate event.

Can I integrate with Google Calendar or Outlook?

This requires custom development and API integrations beyond the scope of this module.

How do I change the "Learn More" button text?

The button text is hardcoded. You can change it there, or contact A Design Link for a field-based solution.

Can I add more detail fields (e.g., price, capacity)?

Yes, but requires modifying and new fields and styling. Consider contacting A Design Link for this customization.

Can I password-protect certain events?

This would require HubSpot membership features or custom development beyond this module's scope.

Support & Customization

Getting Help

1. Check This Documentation: Most questions are answered here
2. HubSpot Community: Search for similar module questions
3. Browser Console: Check for JavaScript errors (F12 → Console tab)
4. HubSpot Support: Contact for platform-specific issues

Professional Customization

Need features not included in this module?

A Design Link offers custom development services:

• Add new fields or functionality
• Custom layouts (grid, masonry, timeline)
• API integrations (Google Calendar, Eventbrite, etc.)
• Custom filtering logic
• Advanced animations
• Multi-language support
• Schema markup for SEO

Purchase a development package and we'll modify this module to your exact specifications.

Contact: Visit A Design Link to discuss your project.

Changelog

Version 1.0 (December 2025)

• Initial release
• Dynamic filtering system (search, location, type)
• Three animation options
• Fully responsive design
• 80+ customization fields
• Server-side rendering with HubL
• Performance optimizations
• Accessibility features
• CSS namespacing with blk_ prefix

Document Version: 1.0
Last Updated: December 18, 2025
Module Version: 1.0
Maintained By: A Design Link