building-blocks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Building Blocks

Block构建

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.
本技能将指导你遵循既定模式与最佳实践实现AEM Edge Delivery Block。Block通过JavaScript装饰与CSS样式将创作内容转化为丰富的交互式体验。
重要提示:本技能仅可在content-driven-development技能的第5步(实现阶段)中调用。
如果你尚未遵循CDD(内容驱动开发)流程,请停止当前操作,先调用content-driven-development技能。

Related Skills

相关技能

  • content-driven-development: MUST be invoked before using this skill to ensure content and content models are ready
  • block-collection-and-party: Use to find similar blocks for patterns
  • testing-blocks: Automatically invoked during Step 5 for comprehensive testing
  • content-driven-development: 必须在使用本技能前调用,以确保内容及内容模型已准备就绪
  • block-collection-and-party: 用于查找具有相似模式的Block
  • testing-blocks: 在第5步中自动调用,以进行全面测试

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
本技能会在content-driven-development技能的第5步(实现阶段)自动调用。它可处理以下场景:
Block开发:
  • 新建Block文件及结构
  • 实现JavaScript装饰逻辑
  • 添加CSS样式
核心功能变更:
  • 修改scripts.js(装饰工具函数、自动Block识别逻辑、页面加载)
  • 全局样式(styles.css、lazy-styles.css)
  • 延迟加载功能(delayed.js)
  • 配置变更
组合场景:
  • 需要配套核心变更的Block(工具函数、全局样式等)
前置条件(由CDD验证):
  • ✅ 测试内容已存在(位于CMS或本地草稿中)
  • ✅ 内容模型已定义/文档化(如适用)
  • ✅ 测试内容URL已就绪
  • ✅ 开发服务器已启动

Block Implementation Workflow

Block实现工作流

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.
跟踪你的进度:
  • 步骤1:查找具有相似模式的Block(针对新建Block或重大变更)
  • 步骤2:创建或修改Block结构(文件及目录)
  • 步骤3:实现JavaScript装饰逻辑(纯CSS场景可跳过)
  • 步骤4:添加CSS样式
  • 步骤5:测试实现(调用testing-blocks技能)
**注意:**如果你的变更需要修改核心文件(scripts.js中的工具函数、全局样式等),请先完成这些修改并测试,再回到本工作流。请参阅下方的“修改核心文件时的注意事项”。

Step 1: Find Similar Blocks

步骤1:查找相似Block

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:
    bash
    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
**适用场景:**新建Block或进行重大结构变更 **可跳过场景:**对现有Block进行小幅修改(如CSS调整、装饰逻辑小改动) 快速开始:
  1. 在代码库中查找相似Block:
    bash
    ls blocks/
  2. 使用block-collection-and-party技能查找参考实现
  3. 参考相似Block的模式:
    • DOM操作策略
    • CSS架构
    • 变体处理
    • 性能优化

Step 2: Create or Modify Block Structure

步骤2:创建或修改Block结构

For New Blocks:

新建Block:

  1. Create the block directory and files:
    bash
    mkdir -p blocks/{block-name}
    touch blocks/{block-name}/{block-name}.js
    touch blocks/{block-name}/{block-name}.css
  2. Basic JavaScript structure:
    javascript
    /**
     * decorate the block
     * @param {Element} block the block
     */
    export default async function decorate(block) {
      // Your decoration logic here
    }
  3. Basic CSS structure:
    css
    /* All selectors scoped to block */
    main .{block-name} {
      /* block styles */
    }
  1. 创建Block目录及文件:
    bash
    mkdir -p blocks/{block-name}
    touch blocks/{block-name}/{block-name}.js
    touch blocks/{block-name}/{block-name}.css
  2. 基础JavaScript结构:
    javascript
    /**
     * decorate the block
     * @param {Element} block the block
     */
    export default async function decorate(block) {
      // Your decoration logic here
    }
  3. 基础CSS结构:
    css
    /* All selectors scoped to block */
    main .{block-name} {
      /* block styles */
    }

For Existing Blocks:

现有Block:

  1. Locate the block directory:
    blocks/{block-name}/
  2. Review current implementation:
    bash
    # View the initial HTML structure from the server
    curl http://localhost:3000/{test-content-path}
  3. Understand existing decoration logic and styles
  1. 定位Block目录:
    blocks/{block-name}/
  2. 查看当前实现:
    bash
    # View the initial HTML structure from the server
    curl http://localhost:3000/{test-content-path}
  3. 理解现有装饰逻辑与样式

Step 3: Implement JavaScript Decoration

步骤3:实现JavaScript装饰逻辑

Essential pattern - re-use existing DOM elements:
javascript
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
resources/js-guidelines.md
核心模式 - 复用现有DOM元素:
javascript
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);
  }
}
完整JavaScript指南包含以下内容,请参阅:
  • 高级DOM操作模式
  • 数据获取与模块加载
  • 性能优化技巧
  • aem.js中的工具函数
  • 代码风格与 linting 规则
请阅读
resources/js-guidelines.md

Step 4: Add CSS Styling

步骤4:添加CSS样式

Essential patterns - scoped, responsive, using custom properties:
css
/* All selectors MUST be scoped to block */
main .my-block {
  /* Use CSS custom properties for consistency */
  background-color: var(--background-color);
  color: var(--text-color);
  font-family: var(--body-font-family);
  max-width: var(--max-content-width);

  /* Mobile-first styles (default) */
  padding: 1rem;
  flex-direction: column;
}

main .my-block h2 {
  font-family: var(--heading-font-family);
  font-size: var(--heading-font-size-m);
}

main .my-block .item {
  display: flex;
  gap: 1rem;
}

/* Tablet and up */
@media (width >= 600px) {
  main .my-block {
    padding: 2rem;
  }
}

/* Desktop and up */
@media (width >= 900px) {
  main .my-block {
    flex-direction: row;
    padding: 4rem;
  }
}

/* Variants - most are CSS-only */
main .my-block.dark {
  background-color: var(--dark-color);
  color: var(--clr-white);
}
For complete CSS guidelines including:
  • All available CSS custom properties
  • Modern CSS features (grid, logical properties, etc.)
  • Performance optimization
  • Naming conventions
  • Common patterns and anti-patterns
Read
resources/css-guidelines.md
Note on iterative validation: While building, you can test changes in your browser as you go (load test content URL, check console, verify layout and functionality). For comprehensive testing guidance including browser testing techniques, responsive testing, and validation approaches, see the testing-blocks skill invoked in Step 5.
核心模式 - 作用域化、响应式、使用自定义属性:
css
/* All selectors MUST be scoped to block */
main .my-block {
  /* Use CSS custom properties for consistency */
  background-color: var(--background-color);
  color: var(--text-color);
  font-family: var(--body-font-family);
  max-width: var(--max-content-width);

  /* Mobile-first styles (default) */
  padding: 1rem;
  flex-direction: column;
}

main .my-block h2 {
  font-family: var(--heading-font-family);
  font-size: var(--heading-font-size-m);
}

main .my-block .item {
  display: flex;
  gap: 1rem;
}

/* Tablet and up */
@media (width >= 600px) {
  main .my-block {
    padding: 2rem;
  }
}

/* Desktop and up */
@media (width >= 900px) {
  main .my-block {
    flex-direction: row;
    padding: 4rem;
  }
}

/* Variants - most are CSS-only */
main .my-block.dark {
  background-color: var(--dark-color);
  color: var(--clr-white);
}
完整CSS指南包含以下内容,请参阅:
  • 所有可用的CSS自定义属性
  • 现代CSS特性(网格、逻辑属性等)
  • 性能优化
  • 命名规范
  • 常见模式与反模式
请阅读
resources/css-guidelines.md
**迭代验证注意事项:**在构建过程中,你可以在浏览器中实时测试变更(加载测试内容URL、检查控制台、验证布局与功能)。如需全面的测试指导(包括浏览器测试技巧、响应式测试及验证方法),请参阅步骤5中调用的testing-blocks技能。

Step 5: Test Implementation

步骤5:测试实现

After implementation is complete, invoke the testing-blocks skill.
The testing-blocks skill will guide you through:
  • Browser testing (functionality, responsive behavior across viewports)
  • Linting and fixing issues
  • Writing unit tests for logic-heavy utilities (if needed)
  • Screenshot capture for validation
  • Performance validation
Provide the testing-blocks skill with:
  • Block name being tested
  • Test content URL(s) (from step 4 of CDD process)
  • Any variants that need testing
  • Screenshots of existing implementation/design/mockup to verify against
  • Acceptance criteria to verify (from step 2 of CDD process)
After testing is complete, return to CDD workflow.

实现完成后,请调用testing-blocks技能。
testing-blocks技能将指导你完成以下内容:
  • 浏览器测试(功能、不同视口下的响应式表现)
  • 代码检查与问题修复
  • 为逻辑复杂的工具函数编写单元测试(如需要)
  • 截图用于验证
  • 性能验证
请为testing-blocks技能提供以下信息:
  • 待测试的Block名称
  • 测试内容URL(来自CDD流程的步骤4)
  • 所有需要测试的变体
  • 现有实现/设计/原型的截图(用于对比验证)
  • 待验证的验收标准(来自CDD流程的步骤2)
测试完成后,请回到CDD工作流。

When Modifying Core Files

修改核心文件时的注意事项

If your changes require modifying core files (scripts.js, styles.css, delayed.js), follow these principles:
Common core files:
  • scripts.js - Decoration utilities, auto-blocking logic, page loading
  • styles.css - Global styles (eager), CSS custom properties
  • lazy-styles.css - Global styles (lazy loaded)
  • delayed.js - Marketing, analytics, third-party integrations
Key principles:
  1. Make core changes first (before block changes that depend on them)
  2. Test core changes independently with existing content before using in blocks
  3. Consider impact - core changes can affect multiple blocks/pages
  4. Test thoroughly - verify no regressions in existing functionality
  5. Keep it minimal - only add what's necessary
  6. Document with code comments - most core changes don't need separate docs
Testing core changes:
  • Test with existing content URLs that use affected functionality
  • For auto-blocking: test pages that should/shouldn't trigger it
  • For global styles: test across multiple blocks and pages
  • Check console for errors
  • Verify responsive behavior
For detailed patterns:
  • JavaScript: See
    resources/js-guidelines.md
  • CSS: See
    resources/css-guidelines.md

如果你的变更需要修改核心文件(scripts.js、styles.css、delayed.js),请遵循以下原则:
常见核心文件:
  • scripts.js - 装饰工具函数、自动Block识别逻辑、页面加载
  • styles.css - 全局样式(预加载)、CSS自定义属性
  • lazy-styles.css - 全局样式(懒加载)
  • delayed.js - 营销、分析、第三方集成
核心原则:
  1. 先完成核心变更(在依赖这些变更的Block变更之前)
  2. 独立测试核心变更,在Block中使用前,先用现有内容测试
  3. 考虑影响范围 - 核心变更可能影响多个Block/页面
  4. 全面测试 - 确保现有功能无回归问题
  5. 保持精简 - 仅添加必要内容
  6. 用代码注释文档化 - 大多数核心变更无需单独文档
核心变更测试:
  • 使用受影响功能的现有内容URL进行测试
  • 针对自动Block识别:测试应触发/不应触发该功能的页面
  • 针对全局样式:在多个Block和页面上测试
  • 检查控制台是否有错误
  • 验证响应式表现
如需详细模式:
  • JavaScript:请参阅
    resources/js-guidelines.md
  • CSS:请参阅
    resources/css-guidelines.md

Reference Materials

  • resources/js-guidelines.md
    - Complete JavaScript patterns and best practices
  • resources/css-guidelines.md
    - Complete CSS patterns and best practices