Building Blocks

Building Blocks

This skill guides you through implementing AEM Edge Delivery blocks following established patterns and best practices. Blocks transform authored content into rich, interactive experiences through JavaScript decoration and CSS styling.

IMPORTANT: This skill should ONLY be invoked from the content-driven-development skill during Step 5 (Implementation).

If you are not already following the CDD process, STOP and invoke the content-driven-development skill first.

Related Skills

• content-driven-development: MUST be invoked before using this skill to ensure content and content models are ready
• da-auth: Obtain a valid Adobe IMS token if test content needs to be pushed to DA before implementation can begin
• block-collection-and-party: Use to find similar blocks for patterns
• testing-blocks: Automatically invoked during Step 5 for comprehensive testing

When to Use This Skill

This skill is invoked automatically by content-driven-development during Step 5 (Implementation). It handles:

Block Development:

• Creating new block files and structure
• Implementing JavaScript decoration
• Adding CSS styling

Core Functionality:

• Scripts.js modifications (decoration, utilities, auto-blocking)
• Global styles (styles.css, lazy-styles.css)
• Delayed functionality (delayed.js)
• Configuration changes

Combined:

• Blocks with supporting core changes (utilities, global styles, etc.)

Prerequisites (verified by CDD):

• ✅ Test content exists (in CMS or local drafts)
• ✅ Content model is defined/documented (if applicable)
• ✅ Test content URL is available
• ✅ Dev server is running

Block Implementation Workflow

Track your progress:

• Step 1: Find similar blocks for patterns (if new block or major changes)
• Step 2: Create or modify block structure (files and directories)
• Step 3: Implement JavaScript decoration (skip if CSS-only)
• Step 4: Add CSS styling
• Step 5: Test implementation (invokes testing-blocks skill)

Note: If your changes require core modifications (utilities in scripts.js, global styles, etc.), make those changes first, test them, then return to this workflow. See "When Modifying Core Files" below.

Step 1: Find Similar Blocks

When to use: Creating new blocks or making major structural modifications

Skip this step when: Making minor modifications to existing blocks (CSS tweaks, small decoration changes)

Quick start:

1. Search the codebase for similar blocks:

   ls blocks/

2. Use the block-collection-and-party skill to find reference implementations

3. Review patterns from similar blocks:

   • DOM manipulation strategies
   • CSS architecture
   • Variant handling
   • Performance optimizations

Step 2: Create or Modify Block Structure

For New Blocks:

1. Create the block directory and files:

   mkdir -p blocks/{block-name}
   touch blocks/{block-name}/{block-name}.js
   touch blocks/{block-name}/{block-name}.css

2. Basic JavaScript structure:

   /**
    * decorate the block
    * @param {Element} block the block
    */
   export default async function decorate(block) {
     // Your decoration logic here
   }

3. Basic CSS structure:

   /* All selectors scoped to block */
   main .{block-name} {
     /* block styles */
   }

For Existing Blocks:

1. Locate the block directory: blocks/{block-name}/
2. Review current implementation:

   # View the initial HTML structure from the server
   curl http://localhost:3000/{test-content-path}

3. Understand existing decoration logic and styles

Step 3: Implement JavaScript Decoration

Essential pattern - re-use existing DOM elements:

export default async function decorate(block) {
  // Platform delivers images as <picture> elements with <source> tags
  const picture = block.querySelector('picture');
  const heading = block.querySelector('h2');

  // Create new structure, re-using existing elements
  const figure = document.createElement('figure');
  figure.append(picture);  // Re-uses picture element

  const wrapper = document.createElement('div');
  wrapper.className = 'content-wrapper';
  wrapper.append(heading, figure);

  block.replaceChildren(wrapper);

  // Only check variants when they affect decoration logic
  // CSS-only variants like 'dark', 'wide' don't need JS
  if (block.classList.contains('carousel')) {
    // Carousel variant needs different DOM structure/behavior
    setupCarousel(block);
  }
}

For complete JavaScript guidelines including:

• Advanced DOM manipulation patterns
• Fetching data and loading modules
• Performance optimization techniques
• Helper functions from aem.js
• Code style and linting rules

Read references/js-guidelines.md