Feeds Package Use Cases

Getting Started

Where This Package Fits: Feeds sits in the Application layer. It depends on Tokens, Elements, and Utilities. It provides dynamic content feed components. See full architecture.

About This Guide

This guide demonstrates practical implementations of the UMD Feeds Library using web components with HTML attributes for displaying dynamic news, events, and academic content.

For Content Managers -- Feeds display dynamic UMD content like news and events. For feed configuration help and visual examples, visit designsystem.umd.edu.

Web Component Use Cases

Use Case 1: News Feed Components

Display news content using web components with various layout options and configurations.

Simple News Block

<!-- Basic 3-column news grid -->
<umd-feed-news
  data-token="your-api-token">
</umd-feed-news>

<!-- News grid with custom columns and lazy loading -->
<umd-feed-news
  data-token="your-api-token"
  data-layout-column-count="4"
  data-layout-row-count="2"
  data-lazy-load="true">
</umd-feed-news>

<!-- Filtered news with dark theme -->
<umd-feed-news
  data-token="your-api-token"
  data-filter-group-ids="145,123"
  data-theme="dark"
  data-visual-transparent>
</umd-feed-news>

Featured News Layout

<!-- Featured news with sticky positioning -->
<umd-feed-news-featured
  data-token="your-api-token">
</umd-feed-news-featured>

<!-- Featured news with filters -->
<umd-feed-news-featured
  data-token="your-api-token"
  data-filter-group-ids="101"
  data-theme="dark">
</umd-feed-news-featured>

<!-- Transparent featured news -->
<umd-feed-news-featured
  data-token="your-api-token"
  data-visual-transparent>
</umd-feed-news-featured>

Available Attributes

Attribute	Description	Values
`data-token`	API authentication token (required)	String
`data-filter-group-ids`	Filter by category IDs	Comma-separated IDs
`data-layout-column-count`	Number of columns (grid only)	1-4 (default: 3)
`data-layout-row-count`	Initial rows to display	1-2 (default: 1)
`data-theme`	Visual theme	"dark" or unset
`data-visual-transparent`	Transparent card backgrounds	Present or absent
`data-lazy-load`	Enable lazy loading	"true" or unset

Use Case 2: Events Feed Components

Display university events using web components with filtering and display options.

Events Grid Layout

<!-- Basic events grid -->
<umd-feed-events
  data-token="your-api-token">
</umd-feed-events>

<!-- Events with category filters and 4 columns -->
<umd-feed-events
  data-token="your-api-token"
  data-filter-group-ids="201,202"
  data-layout-column-count="4"
  data-layout-row-count="2"
  data-lazy-load="true">
</umd-feed-events>

<!-- Dark theme events with transparent cards -->
<umd-feed-events
  data-token="your-api-token"
  data-theme="dark"
  data-visual-transparent
  data-layout-column-count="2">
</umd-feed-events>

Events List Layout

<!-- Basic events list -->
<umd-feed-events-list
  data-token="your-api-token">
</umd-feed-events-list>

<!-- Events list with filters and dark theme -->
<umd-feed-events-list
  data-token="your-api-token"
  data-filter-group-ids="203"
  data-theme="dark">
</umd-feed-events-list>

Common Event Attributes

Required:

data-token - API authentication token

Filter Options:

data-filter-group-ids - Filter by event categories

Display Options:

data-layout-column-count - Grid columns (1-4)
data-layout-row-count - Initial rows (1-2)
data-theme - Visual theme ("dark" or unset)

Performance:

data-lazy-load - Load more on scroll

Use Case 3: Academic Feed Components

Display academic calendar events using the slider web component with the academic feed type.

Academic Calendar Slider

<!-- Basic academic calendar slider -->
<umd-element-slider-events-feed
  data-token="your-api-token"
  data-feed-type="academic">
  <div slot="headline">
    Lorem Ipsum Dolor Sit Amet
  </div>
  <umd-element-call-to-action slot="actions" data-display="secondary">
    <a href="/"><span>Learn More</span></a>
  </umd-element-call-to-action>
</umd-element-slider-events-feed>

<!-- Academic calendar with dark theme -->
<umd-element-slider-events-feed
  data-token="your-api-token"
  data-feed-type="academic"
  data-theme="dark">
  <h2 slot="headline">Academic Calendar</h2>
  <a slot="actions" href="/academic-calendar">Full Calendar</a>
</umd-element-slider-events-feed>

<!-- Academic calendar with custom styling -->
<umd-element-slider-events-feed
  data-token="your-api-token"
  data-feed-type="academic">
  <h2 slot="headline">Important Academic Dates</h2>
  <div slot="actions">
    <a href="/academic-calendar">View Full Calendar</a>
    <a href="/academic-calendar/deadlines">Key Deadlines</a>
  </div>
</umd-element-slider-events-feed>

Academic Feed Attributes

Attribute	Description	Values
`data-token`	API authentication token (required)	String
`data-feed-type`	Must be set to "academic" for academic calendar	"academic" (required)
`data-theme`	Visual theme	"dark" or unset
`resize`	Triggers size recalculation (observed)	Any value

Slots

headline - Section headline (optional)
actions - Call-to-action links (optional)

Union Feeds

Use the data-union attribute to aggregate content from multiple UMD sources into a single feed.

Usage

<!-- Aggregate news from multiple units -->
<umd-feed-news
  data-token="your-api-token"
  data-union>
</umd-feed-news>

<!-- Union events feed -->
<umd-feed-events
  data-token="your-api-token"
  data-union
  data-layout-column-count="3">
</umd-feed-events>

Union Attribute

Attribute	Description	Values
`data-union`	Aggregate content from multiple UMD sources	Present or absent (boolean attribute)

Advanced TypeScript Implementation

Use Case 4: TypeScript Integration

Use feeds programmatically in TypeScript applications with full type safety.

Basic TypeScript Usage

import { news, events, academic, experts, inTheNews } from '@universityofmaryland/web-feeds-library';

// Create news feed with configuration
const newsProps = {
  token: 'your-api-token',
  numberOfColumnsToShow: 3,
  numberOfRowsToStart: 2,
  isThemeDark: false,
  isLazyLoad: true,
  categories: ['145', '123']
};

const newsFeed = news.grid(newsProps);
// newsFeed is of type { element: HTMLElement, styles: string }

// Add the element to the DOM
document.querySelector('#news-container')?.appendChild(newsFeed.element);

// Inject the styles into the document head
const styleElement = document.createElement('style');
styleElement.textContent = newsFeed.styles;
document.head.appendChild(styleElement);

// Create experts feed
const expertsFeed = experts.grid({
  token: 'your-api-token',
  numberOfColumnsToShow: 3,
  numberOfRowsToStart: 1,
  isThemeDark: false,
  isLazyLoad: false,
});

document.querySelector('#experts-container')?.appendChild(expertsFeed.element);

// Create in-the-news feed
const inTheNewsFeed = inTheNews.grid({
  token: 'your-api-token',
  numberOfColumnsToShow: 2,
  numberOfRowsToStart: 1,
  isThemeDark: false,
  isLazyLoad: true,
});

document.querySelector('#in-the-news-container')?.appendChild(inTheNewsFeed.element);

Type Definitions

// News feed properties
interface BaseProps {
  token: string;
  numberOfRowsToStart: number;
  categories?: string[];
  isThemeDark?: boolean;
  isLazyLoad: boolean;
  isUnion: boolean;
  entriesToRemove?: string[];
}

interface BlockProps extends BaseProps {
  numberOfColumnsToShow?: number;
  isTransparent?: boolean;
  isTypeOverlay?: boolean;
}

interface FeaturedProps extends BaseProps {
  isTransparent?: boolean;
  isLayoutReversed?: boolean;
  overwriteStickyPosition?: number;
}

Available Feed Modules

Module	Import Path	Layouts
`academic`	`@universityofmaryland/web-feeds-library/academic`	slider
`events`	`@universityofmaryland/web-feeds-library/events`	grid, list, grouped, slider
`experts`	`@universityofmaryland/web-feeds-library/experts`	grid, list, bio, inTheNews
`inTheNews`	`@universityofmaryland/web-feeds-library/in-the-news`	grid, list
`news`	`@universityofmaryland/web-feeds-library/news`	grid, list, featured

Use Case 5: Event Bubbling and Style Callbacks

Feed components dispatch DOM events when content is loaded or errors occur, and provide callbacks for style injection.

Feed Events

// Listen for feed loaded event
const feedElement = document.querySelector('umd-feed-news');

feedElement.addEventListener('feed:loaded', (event) => {
  console.log('Feed loaded with', event.detail.items.length, 'items');
  // Access the loaded items
  const items = event.detail.items;
});

// Listen for feed error event
feedElement.addEventListener('feed:error', (event) => {
  console.error('Feed error:', event.detail.error);
  // Show fallback content
  feedElement.innerHTML = '<p>Unable to load feed content</p>';
});

// Event bubbling allows listening at parent levels
document.addEventListener('feed:loaded', (event) => {
  if (event.target.tagName === 'UMD-FEED-NEWS') {
    console.log('News feed loaded');
  }
});

Style Callback

// Using styleCallback with TypeScript API
import { news } from '@universityofmaryland/web-feeds-library';

const newsFeed = news.grid({
  token: 'your-api-token',
  numberOfColumnsToShow: 3,
  numberOfRowsToStart: 2,
  isThemeDark: false,
  isLazyLoad: true,

  // Style callback to handle CSS injection
  styleCallback: (cssString) => {
    // Custom style injection logic
    const styleElement = document.createElement('style');
    styleElement.textContent = cssString;
    document.head.appendChild(styleElement);
  }
});

document.querySelector('#news-container')?.appendChild(newsFeed.element);

Integration with Shadow DOM

// When feeds are inside web components with Shadow DOM
class CustomFeedWrapper extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    const feed = document.createElement('umd-feed-events');
    feed.setAttribute('data-token', 'your-api-token');

    // Events bubble from the feed to the shadow host
    feed.addEventListener('feed:loaded', (event) => {
      // Dispatch to light DOM if needed
      this.dispatchEvent(new CustomEvent('feed:loaded', {
        detail: event.detail,
        bubbles: true
      }));
    });

    this.shadowRoot.appendChild(feed);
  }
}

Available Events

feed:loaded (with items array) and feed:error (with error details). Standard DOM events (click, focus, etc.) also bubble normally through the component hierarchy.

Best Practices

Always provide a valid API token via data-token attribute
Use data-lazy-load="true" for better initial page performance
Implement error handling for network failures
Use appropriate column counts for different screen sizes
Filter content using data-filter-group-ids to reduce payload
Enable event delegation for multiple feeds on the same page
Consider caching strategies for frequently accessed feeds
Test with slow network connections and API failures

Performance Tips

Limit initial rows with data-layout-row-count="1"
Use data-entry-remove-ids to exclude unnecessary items
Enable lazy loading for below-the-fold feeds
Implement pagination for large datasets
Consider server-side rendering for SEO-critical content
Use transparent cards on image backgrounds for better performance