Skip to content

README.md

Latest commit

 

History

History
160 lines (130 loc) · 7.66 KB

README.md

File metadata and controls

160 lines (130 loc) · 7.66 KB

Hotel Reservation Lightning Type (Carousel Renderer)

How to build custom, interactive UI components for Salesforce Agentforce using Lightning Types. This solution showcases a custom input form and a carousel-based collection renderer that transforms list-based agent responses into an engaging, swipeable card interface.

🎨 Inspired by the William Sonoma agent implementation - This carousel pattern enables businesses to present product catalogs, recipes, and recommendations in a visually compelling format that drives user engagement and conversion.

Why Custom UI Components Matter

Traditional agent responses display data as plain lists or tables, which can be overwhelming and difficult to navigate. Custom Lightning Type components allow you to:

  • Improve User Experience: Transform dense data into visually appealing, interactive interfaces
  • Increase Engagement: Carousel components encourage users to explore multiple options through intuitive navigation
  • Drive Conversions: Prominent call-to-action buttons (e.g., "Book Now") make it easier for users to take action
  • Brand Consistency: Customize the look and feel to match your brand guidelines and design system

Key Components

🎠 Carousel Component (hotelCarouselOutput)

The centerpiece of this solution, the carousel component provides:

  • Swipeable Navigation: Users can browse through multiple items using arrow buttons or dot indicators
  • Card-Based Layout: Each item is displayed as a rich card with images, ratings, descriptions, and actions
  • Responsive Design: Adapts seamlessly to different screen sizes
  • Event Handling: Emits custom events (e.g., "Book Now") that can be wired to downstream actions

📝 Custom Input Component (hotelRequestInput)

A branded input form that replaces the default agent input UI:

  • Structured Data Collection: Organized form fields with clear labels and validation
  • User-Friendly Interface: Date pickers, dropdowns, and text inputs optimized for the use case
  • Real-Time Validation: Immediate feedback on required fields and data formats
  • Consistent Branding: Matches your organization's design system

What's Included

  • Lightning Type hotelReservation with editor/renderer overrides
  • Apex invocable action and DTOs
  • Carousel renderer component (3 LWC components working together)
  • Custom input form component (editor override)
  • Permission set for packaged deployments

Repo Layout

🎠 Carousel Components (Renderer)

lwc/
  hotelCarouselOutput/      # Main renderer: receives HotelResponse, normalizes data
  hotelCarouselWrapper/      # Carousel controller: manages slides, navigation, state
  hotelCardCarousel/         # Individual card: displays hotel image, details, actions

📝 Input Component (Editor)

lwc/
  hotelRequestInput/         # Custom input form: replaces default agent input UI

⚙️ Configuration

lightningTypes/hotelReservation/
  schema.json                # Lightning Type definition (@apexClassType/c__Hotel)
  lightningDesktopGenAi/
    editor.json              # Editor override -> c/hotelRequestInput
    renderer.json            # Collection renderer override -> c/hotelCarouselOutput

💼 Apex Classes

classes/
  HotelReservation.cls       # Invocable method: findHotels()
  HotelRequest.cls           # Input DTO with @InvocableVariable fields
  HotelResponse.cls          # Output wrapper containing List<Hotel>
  Hotel.cls                  # Hotel DTO (name, address, rooms, category, imageUrl)
  Room.cls                   # Room DTO (type, availability, price, etc.)
  HotelCategory.cls          # Star rating DTO

🔐 Security

permissionsets/
  HotelCarousel.permissionset-meta.xml  # Grants access to all Apex classes

Architecture at a glance

Carousel Component Hierarchy

  1. hotelCarouselOutput: Receives HotelResponse data from Agentforce, normalizes hotel data, passes to wrapper
  2. hotelCarouselWrapper: Manages carousel state (current slide index), navigation controls (prev/next buttons, dot indicators), slide transitions
  3. hotelCardCarousel: Renders individual hotel cards with image, name, address, star rating, room summary, and "Book Now" button

Event Handling

  • hotelCardCarousel fires book event when user clicks "Book Now"
  • Event bubbles through hotelCarouselWrapper → hotelCarouselOutput
  • Agentforce can consume the event for downstream booking workflows

Prerequisites

  • Enhanced Chat v2 enabled (Lightning Type custom renderers are only available on Enhanced Chat v2)
  • Salesforce org with Agentforce enabled
  • API version 64.0 or later
  • Salesforce CLI installed and authorized to the target org

Deploy

# authorize once if needed
sfdx force:auth:web:login -a myOrg

# deploy all metadata in this package
sfdx force:source:deploy -p force-app/main/default -u myOrg

# assign the permission set to your user
sfdx force:user:permset:assign -n HotelCarousel -u myOrg

Configure the Agent Action

  1. In Agentforce, create or edit an action.
  2. Select method HotelReservation.findHotels.
  3. Inputs map to HotelRequest fields (check-in, check-out, city, number of guests, etc.).
  4. Output is a list of Hotel via HotelResponse.
  5. Set Output Rendering to Lightning Type hotelReservation.
  6. The editor override applies c/hotelRequestInput; the renderer override applies c/hotelCarouselOutput.
  7. Save and reload the agent page.

Test the Experience

Testing the Custom Input Component

  1. Invoke the agent action in Enhanced Chat v2
  2. Observe the custom input form (hotelRequestInput) appears instead of default fields
  3. Fill in city, check-in date, check-out date, and number of guests
  4. Verify form validation and real-time updates

Testing the Carousel Component

  1. Submit the search form and wait for results
  2. Carousel should display with sample hotels (Hard Rock Orlando, Hard Rock Immokalee)
  3. Navigate the carousel:
    • Click left/right arrow buttons to move between hotels
    • Click dot indicators to jump to specific hotels
    • Verify smooth slide transitions
  4. Inspect individual cards:
    • Hotel images load (with fallback if image fails)
    • Star ratings display correctly
    • Address information is visible
    • Room summaries show available rooms
  5. Test "Book Now" button:
    • Click "Book Now" on any hotel card
    • Check browser console for book event emission
    • Wire the event in Agentforce for downstream booking workflows

Extending / hardening

  • Replace sample data in HotelReservation with a real service call.
  • Keep rooms and hotelCategory fields if the UI still shows stars/room summary; otherwise update DTOs + LWCs together.
  • Expand the permission set as needed for additional objects or field-level security.

Enhanced Chat v2 Migration Path

Important: Lightning Types with custom renderers are only available on Enhanced Chat v2. This solution is designed for organizations planning to migrate to Enhanced Chat v2 or already using it.

Current Status

  • ✅ Enhanced Chat v2: Full support for Lightning Type custom renderers and editors
  • ⚠️ Classic Chat: Lightning Type custom renderers are not supported

References