Skip to main content

Introduction

Create reusable content blocks that can be used across multiple pages.

🎯 What does this module do?​

The Blocks module lets you use reusable content components (blocks) that contain sets of attributes and can be used on multiple pages - like headers, footers, banners, testimonials, or any repeating content.

Think of it as LEGO bricks for your website - you create a block once, and reuse it everywhere you need it. Change the block once, and it updates everywhere automatically.

📖 Simple Explanation​

Imagine you're building a website with:

  • 🔝 Header - logo, navigation menu (same on every page)
  • 🔽 Footer - contact info, social links (same on every page)
  • 📢 Promo Banner - special offer (appears on multiple pages)
  • ⭐ Testimonials - customer reviews (reused in different places)
  • 📞 Contact Form - appears on multiple pages

Instead of copying this content to every page:

  • ✅ Create once as a Block
  • ✅ Insert the block wherever you need it
  • ✅ Update in one place → changes everywhere automatically
  • ✅ Keep your content DRY (Don't Repeat Yourself)

Real-world example:

Without Blocks (copy-paste):

  • Update footer → Edit 50 pages manually ❌
  • Add social link → Update everywhere ❌
  • Inconsistent content across pages ❌

With Blocks (reusable):

  • Update footer block → Changes on all 50 pages instantly ✅
  • Add social link → Update once ✅
  • Always consistent ✅

✨ Key Concepts​

What is a Block?​

A block is a reusable content component containing:

  • Content - Text, images, links, any data
  • Attributes - Custom fields you define
  • Marker - Unique identifier to reference it
  • Status - Active, draft, archived

Block vs Page​

FeaturePageBlock
PurposeComplete page contentReusable component
URLHas its own URL (/about)No URL (embedded)
UsageViewed directlyInserted into pages
ExampleAbout Us pageFooter, Header

Key difference: Pages are destinations, Blocks are building blocks.

Common Block Types​

Typical blocks you might create:

Block TypeExample ContentWhere Used
HeaderLogo, nav menu, searchEvery page
FooterContact, links, copyrightEvery page
Hero BannerLarge image + CTA buttonHomepage, landing pages
TestimonialsCustomer reviewsMultiple pages
Contact FormEmail formContact page, modals
Promo BannerSpecial offer alertSelected pages
Social LinksFacebook, Twitter iconsFooter, sidebar
Newsletter SignupEmail subscription boxFooter, blog

Block Reusability​

Blocks can be:

  • ✅ Used on multiple pages
  • ✅ Updated once, reflected everywhere
  • ✅ Localized (different content per language)

📋 What You Need to Know​

Block Identification​

Three ways to identify blocks:

MethodWhen to UseExample
List AllAdmin dashboard, block selectorgetBlocks()
By MarkerReference in code (best practice)footer, header, promo_banner
Search blocksInternal referencessearchBlock('foo')

Best practice: Always use markers in your code (they never change).

Block Structure​

Every block has these key fields:

{
  id: 3, // unique ID
  localizeInfos: { // block localized data
    title: 'Block', // block localized title
  },
  version: 0, // block version
  position: 1, // block position in array of blocks
  identifier: 'block', // block identifier
  type: 'common_block', // block type
  templateIdentifier: null, // template identifier
  isVisible: true, // visibility
  attributeValues: {}, // block attributes
}

Custom Attributes​

Blocks use AttributesSets for custom fields:

Examples:

  • Footer block: copyright text, social links, contact info
  • Hero banner: headline, subheading, CTA button, background image
  • Testimonial: author name, photo, quote, rating
  • Contact form: fields configuration, submit button text

Learn more: See AttributesSets Module

📊 Quick Reference Table - Common Methods​

MethodWhat It DoesWhen to Use
getBlocks()Get all blocks (paginated, filtered)List all available blocks
getBlockByMarker()Get block by markerFetch specific block in code
searchBlock()Search blocksFetch blocks

❓ Common Questions (FAQ)​

What's the difference between Blocks and Pages?​

  • Pages - Complete standalone pages with URLs (e.g., /about)
  • Blocks - Reusable components inserted into pages (e.g., footer)

Think of it like:

  • Page = Full document
  • Block = Paragraph you reuse in multiple documents

How do I update a block's content?​

Update it in OneEntry admin panel:

  1. Go to Blocks section
  2. Find your block (e.g., "Footer")
  3. Edit attributes
  4. Save

All pages using that block update automatically! ✨

Should I create many small blocks or few large blocks?​

Many small blocks is better:

✅ Good (small, focused):

- header_logo
- header_navigation
- footer_copyright
- footer_social_links

❌ Avoid (too large):

- entire_page_layout (contains everything)

Why? Small blocks are easier to reuse and maintain.

Can I use the same block multiple times on one page?​

Yes! Fetch once, render multiple times.

How do I show/hide blocks conditionally?​

Check statusId and isVisible

Can I create blocks dynamically via API?​

The SDK is read-only. To create blocks use OneEntry admin panel.

How do I handle missing blocks gracefully?​

Always use try/catch

💡 Important Notes​

Block Markers Best Practices​

✅ Good marker names:

  • Descriptive: global_footer, homepage_hero
  • Use underscores: contact_form
  • Lowercase: promo_banner
  • Indicate scope: global_header vs blog_header

❌ Bad marker names:

  • Generic: block1, content
  • Spaces: my block
  • Mixed case: MyBlock, ProMoBanner

Caching Blocks​

Blocks change rarely → cache them!

🎓 Best Practices​

  • Create small, focused blocks (single responsibility)
  • Use descriptive markers (footer, not block1)
  • Cache blocks to reduce API calls
  • Handle missing blocks gracefully (try/catch)
  • Document what each block is for
  • Keep block structure consistent
  • Test block changes before publishing
  • Use statusId to preview changes

More information about the module's user interface https://doc.oneentry.cloud/docs/blocks/introduction

Definition of the Blocks module​


const { Blocks } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 Related Documentation​