Section Template Library for ApostropheCMS

Accelerate content creation and maintain design consistency by turning your best widgets into reusable section templates. Content teams can instantly insert professionally designed components without recreating layouts from scratch.

Why Section Template Library?

• ⚡ Speed Up Content Creation: Transform hours of widget configuration into one-click insertions
• 🎨 Maintain Brand Consistency: Ensure design standards across all pages and team members
• 👥 Empower Content Teams: Non-technical editors can use complex layouts with confidence
• 📈 Scale Content Operations: Build once, reuse everywhere across your entire site
• 🔧 Developer Friendly: Configure exactly which widgets should be available as templates

Prerequisites

Node.js Requirements:

• Node.js >= v20.19.0, >= v22.12.0, or any 24.x version
• This module is ESM-only and requires a compatible Node.js version

Compatibility

This version requires the latest ApostropheCMS. When adding this module to an existing project, run npm update to ensure all ApostropheCMS modules are up to date.

Stability Note

This is a beta release. However, we do not anticipate any incompatible changes before the final release.

Installation

Note: This module requires an ApostropheCMS Pro license. Check out our pricing page and then create an account on Apostrophe Workspaces or contact us to access Pro extensions.

npm install @apostrophecms-pro/section-template-library

Configuration

Activate the bundle and configure the widget types you want available as reusable sections:

// in app.js
import apostrophe from 'apostrophe';

apostrophe({
  root: import.meta,
  shortName: 'my-project',
  // Activate the section template library bundle
  bundles: [ '@apostrophecms-pro/section-template-library' ],
  modules: {
    // Configure your widget modules first
    'my-two-column-widget': {},
    'my-three-column-widget': {},
    'my-hero-widget': {},
    'my-hero-column-widget': {},
    //
    // Next configure the section-template-library module and the
    // widgets you want to permit to be saved as sections
    '@apostrophecms-pro/section-template-library': {
      options: {
        allowedWidgets: [
          'my-two-column-widget',
          'my-three-column-widget',
          'my-hero-widget'
        ]
      }
    },
    // Also required: enable tags for sections
    '@apostrophecms-pro/section-template-tag': {}
  }
});

Configure any content areas with your available widgets as you would normally:

// in modules/@apostrophecms-pro/section-template-library/index.js
export default {
  fields: {
    add: {
      content: {
        label: 'Content',
        type: 'area',
        widgets: {
          // These are just examples, you should configure widgets
          // that actually exist in your project and are suitable
          // to be saved as potential "starting points" when adding
          // more content to the page
          'my-two-column-widget': {},
          'my-three-column-widget': {},
          'my-hero-widget': {}
        }
      }
    },
    group: {
      // Use this group name to have content
      // displayed in the existing "Sections" tab
      aposSectionTemplate: {
        fields: [ 'content' ]
      }
    }
  }
}

⚠️ If you do not configure the content field, the module will attempt to guess, but for best results you are strongly encouraged to think about which widget types are actually good candidates for reuse. In some cases the module may not find any suitable candidates on its own. You know your project best.

Usage

Creating Section Templates

You'll note the admin bar has new entries for "Sections" and "Section Tags." However, you can't create a new reusable section directly from the Section manager dialog box. That is to be expected.

Instead, navigate to any widget on your site that would make a good template and click "Save Section":

Edit the new section to make it a reusable template:

• Give it a descriptive title for easy identification
• Edit content to be generic and widely applicable
• Add section tags for better organization

Organizing With Tags

Sections can be tagged to make them easier to find later. Use tags like hero, two-column, footer, or promo to help content editors quickly identify the right layout for their needs.

When you open the Section Tag Manager using the "Browse Section Tags"button, you’ll see all tags that have been created across your project. Editors can add new tags, rename existing ones, and apply multiple tags to a section.

If you don't have any tags in your project, the button in the upper right will allow you to create one. If you already have tags created in your project, the context menu will allow you to create a new one.

💡 Tip: Encourage your team to use a consistent tagging system (for example, “layout,” “marketing,” “navigation”) so templates are easier to filter and reuse across pages.

Inserting Sections

When adding content to any page, click "Insert Section" instead of creating widgets from scratch:

Depending on your project setup, the available sections may appear either in a drop-down menu or in a modal dialog. Both provide the same functionality for browsing and inserting templates.

Choose from your library of available sections:

You can also filter by tags in this dialog, making it easier to narrow down long lists of templates and find the exact section you want.

Once inserted, the section becomes an independent widget that you can customize for your specific needs:

💡 Important: Inserted widgets are completely independent. Editing an inserted widget won't affect the original template, and template changes won't affect previously inserted widgets.

Frequently Asked Questions

Why can't I create sections from the Manage Sections dialog?

Content areas have different rules and constraints. It's more practical to identify existing widgets that work well as templates rather than trying to accommodate all possible configurations upfront.

Why aren't all sections available everywhere?

Sections might be unavailable for insertion when:

• The widget type isn't allowed in the target content area
• Image size or aspect ratio constraints are incompatible
• Other area-specific restrictions apply

Can I update all inserted widgets by editing the original section?

No, this creates independent copies. If you need linked content across pages, consider creating a piece type with relationships instead. Keep in mind that identical content on multiple pages may impact SEO.

Advanced Configuration

Customizing the Empty State

You can customize the empty state display when no section templates exist:

// in modules/@apostrophecms-pro/section-template-library/index.js
export default {
  options: {
    emptyState: {
      title: 'No Section Templates Yet',
      message: 'Create your first section template by saving a widget from any page.',
      icon: 'layers-icon'
    }
  }
}

Available options:

• title - The headline text displayed
• message - The descriptive text below the title
• icon - Icon name from the vue-material-design-icons package included in ApostropheCMS

Using custom icons: To register a new icon not included in vue-material-design-icons, see the ApostropheCMS icon documentation.

Handling Custom Widget Constraints

💡 This is an edge case, and you probably don't need to worry about it.

The section template library already handles the common cases automatically. If a widget just isn't allowed in a content area, the library will not allow you to insert it there. And if you choose to allow the image widget as a section (which most developers won't because it makes more sense to allow layout widgets that contain them), incompatible options for the @apostrophecms/image-widget are also handled.

But if you, as a developer, have added custom widget types to your project that have issues similar to the image widget then you might want to implement your own rules to "rule out" the use of a particular section in a particular area.

For that, you can implement your own handler for the @apostrophecms-pro/section-template-library:filterForArea event:

// In your modules/hero-widget/index.js file
export default {
  handlers(self) {
    return {
      '@apostrophecms-pro/section-template-library:filterForArea': {
        sameWidth(payload) {
          if (payload.widget.type !== 'hero') {
            return; // Don't interfere with other widgets
          }
          const width = payload.options.width;
          if (width !== payload.widget.width) {
            payload.keep = false;
          }
        }
      }
    };
  }
}

This example prevents hero widgets from being inserted into areas with incompatible width requirements.

💎 Ready for More Pro Features?

Maximize your content creation workflow with additional Pro modules that complement the Section Template Library:

✨ Content Management Pro Features

• 🔐 Advanced Permissions - Control who can create and manage section templates
• 📝 Document Versions - Track changes to templates and revert when needed
• 🔍 SEO Assistant - AI-powered optimization for template-based content
• 🌍 Automatic Translations - Instantly translate section templates for global sites

Explore all Pro extensions or sign up for a Pro license to unlock the full potential of your content operations. For enterprise needs, contact our team to discuss custom workflows and training.