Docs

Interactive Guide System

Last updatedView as Markdown

An interactive, step-by-step guide that helps users understand and utilize the animation features in Linchpin Blocks. Uses WordPress's native Guide component for consistent UI.

📚 For complete user documentation, see Animation Controls

Overview

The Animation Guide Modal provides a comprehensive walkthrough of all animation features including:

  • Animate In (entrance animations)
  • Animate Out (exit animations)
  • Pinning (sticky scroll effects)
  • Scroll Scrubbing & Triggers
  • Snap & Advanced Features

Features

Multi-Step Walkthrough

  • 7 comprehensive steps covering all animation features
  • Progress indicators showing current position in the guide
  • Next/Previous navigation for easy step traversal
  • Finish button on the last step to complete the guide

Smart Auto-Display

The guide automatically appears when users:

  1. First enable "Animate In" animation
  2. First enable "Animate Out" animation
  3. First enable "Pin" functionality

The guide will only show once per session for users who haven't dismissed it permanently.

User Controls

  • Animation Guide Panel: A separate panel that appears in Inspector Controls when animation features are enabled
  • Show Animation Guide Button: Click to open the interactive guide
  • Don't Show Again: Checkbox on the final step to permanently dismiss auto-display
  • Close Button: Available on every step to exit the guide
  • Persistent Access: Users can always reopen the guide via the Animation Guide panel, even after dismissing

Implementation

Component Structure

Follows the same pattern as the Animation Block Guide:

src/animation-controls/components/guide/
├── index.js                  # Main guide component using WordPress Guide
├── step-wrapper.js           # Consistent wrapper for all steps
└── steps/
    ├── welcome.js           # Step 1: Welcome
    ├── animate-in.js        # Step 2: Animate In
    ├── animate-out.js       # Step 3: Animate Out
    ├── pinning.js           # Step 4: Pinning
    ├── scrub-trigger.js     # Step 5: Scroll Scrubbing
    ├── advanced.js          # Step 6: Advanced Features
    └── getting-started.js   # Step 7: Getting Started

Integration

The guide is filtered into blocks with animation support via:

src/animation-controls/filters/wrapper-guide.js
src/animation-controls/components/animation-guide-control.js  # Wrapper component
src/animation-controls/components/more-menu/index.js          # Menu item

This follows the same pattern as the Animation Block Guide for visual consistency.

Guide State Management

The guide uses the existing block guides system in:

src/block-guides.js

Guide ID: linchpin-blocks/animation-features

Usage

For Users

  1. Automatic Display:
    • The guide appears automatically when you first enable any animation feature
    • It will not show again in the same session even if you close it
    • You can permanently dismiss it on the last step
  2. Manual Access:
    • Find the "Animation Guide" panel in the Inspector Controls (block settings sidebar)
    • Click "Show Animation Guide" button
    • The guide will open at step 1
    • Navigate through all steps at your own pace
  3. Permanent Dismissal:
    • Complete all steps to the final page
    • Check "Don't show this guide automatically again"
    • Click "Finish"
    • The guide won't auto-display again, but you can still access it via the Animation Guide panel

For Developers

Opening the Guide Programmatically

setIsGuideOpen(true);

Checking Guide Status

if (window.linchpinBlocksGuides?.utils?.isGuideDismissed) {
    const isDismissed = window.linchpinBlocksGuides.utils.isGuideDismissed(
        'linchpin-blocks/animation-features'
    );
}

Dismissing Permanently

if (window.linchpinBlocksGuides?.utils?.dismissGuide) {
    window.linchpinBlocksGuides.utils.dismissGuide(
        'linchpin-blocks/animation-features'
    );
}

Guide Content Structure

Step 1: Welcome

Introduction to animation controls and GSAP/ScrollTrigger

Step 2: Animate In

  • Entrance animations
  • Preset animation types
  • Duration, delay, easing
  • Child animations with stagger
  • Scroll scrubbing

Step 3: Animate Out

  • Exit animations
  • Independent configuration
  • ScrollTrigger integration
  • Combination with Animate In

Step 4: Pinning

  • Sticky scroll effects
  • Pin types (Fixed vs Transform)
  • Pin spacing and advanced options
  • Combining with scrubbing

Step 5: Scroll Scrubbing & Triggers

  • What is scrubbing
  • Start/End positions
  • Scrub smoothness
  • Traditional vs scrubbed animations

Step 6: Snap & Advanced

  • Scroll snapping (Mandatory vs Proximity)
  • Child animations
  • Copy/Paste settings
  • Preview functionality

Step 7: Getting Started

  • Quick start guide (5 steps)
  • Resources and documentation
  • Reminder about Help button access

Styling

Custom styles are defined in:

src/animation-controls/editor-styles.scss

Key style features:

  • Progress indicator bars
  • Scrollable content area with custom scrollbar
  • Properly styled lists and code blocks
  • Responsive layout
  • Clear visual hierarchy

API Integration

The guide integrates with the WordPress REST API through the block guides system:

Endpoints Used

  • GET /linchpin-blocks/v1/block-guides/status – Check guide dismissal status
  • POST /linchpin-blocks/v1/block-guides/dismiss – Permanently dismiss guide

Nonce Verification

All API calls use the WordPress nonce system:

headers: {
    'X-WP-Nonce': window.linchpinBlocksGuides.apiNonce,
}

Best Practices

For Content Updates

  • Keep each step focused on a single topic
  • Use clear, concise language
  • Include examples and tips
  • Maintain consistent formatting
  • Test all links and code examples

For Styling

  • Follow WordPress design patterns
  • Ensure readability on all screen sizes
  • Use consistent spacing and typography
  • Maintain accessibility standards

For Functionality

  • Test auto-display triggers
  • Verify dismissal persists across sessions
  • Ensure Help button always works
  • Test all navigation controls

Future Enhancements

Potential improvements:

  • Add interactive demos within steps
  • Include video tutorials
  • Add tooltips for specific UI elements
  • Create a quick reference card
  • Add search functionality for guide content
  • Track which steps users spend most time on
  • Add keyboard navigation shortcuts

Troubleshooting

Guide Doesn't Auto-Display

  1. Check if window.linchpinBlocksGuides is loaded
  2. Verify API endpoints are accessible
  3. Check browser console for errors
  4. Clear WordPress transients/cache

Dismissal Not Persisting

  1. Verify nonce is valid
  2. Check API endpoint permissions
  3. Ensure user has proper capabilities
  4. Check database for user meta storage

Styling Issues

  1. Clear asset cache
  2. Rebuild JavaScript/CSS
  3. Check for conflicting styles
  4. Verify SCSS compilation
  • Guide Component: src/animation-controls/components/guide/index.js
  • Step Wrapper: src/animation-controls/components/guide/step-wrapper.js
  • Individual Steps: src/animation-controls/components/guide/steps/*.js
  • Control Wrapper: src/animation-controls/components/animation-guide-control.js
  • Menu Item: src/animation-controls/components/more-menu/index.js
  • Filter Integration: src/animation-controls/filters/wrapper-guide.js
  • Guide System: src/block-guides.js
  • API Controller: includes/Controller/REST/Block_Guides.php (backend)

Support

For issues or questions about the animation guide:

  1. Check this documentation
  2. Review the inline code comments
  3. Test in a clean WordPress environment
  4. Check WordPress and browser console for errors

Have a question about this page?

Linchpin assistant

Was this helpful?