Skip to main content

Introduction

Reusable content blocks that can be used across multiple pages.

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

🎯 What does this module do?​

The Blocks module lets you fetch reusable content components (blocks) — sets of attributes you create once in the admin panel and reuse across pages and product pages: headers, footers, banners, testimonials, sliders, and product/recommendation widgets. Update a block once and it changes everywhere it's used.

The SDK is read-only: you fetch blocks here and create or edit them in the OneEntry admin panel.

🚀 Quickstart​

Initialize the module from defineOneEntry:


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

Fetch a single block by its marker and read its attributes:

// Fetch the "footer" block.
const block = await Blocks.getBlockByMarker("footer", "en_US");

console.log(block.identifier, block.type, block.isVisible);
// "footer" "common_block" true

// Custom fields live in attributeValues.
console.log(block.attributeValues);

✨ Key Concepts​

What is a Block?​

A block is a reusable content component containing:

  • identifier — unique marker used to reference it in code (always use the marker; it never changes)
  • localizeInfos — localized data (e.g. title), different content per language
  • type — the BlockType that determines what the block renders
  • isVisible — visibility flag
  • attributeValues — custom fields you define via AttributesSets

Block Structure​

{
  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 (marker)
  type: 'common_block', // block type
  templateIdentifier: null, // template identifier
  isVisible: true, // visibility
  attributeValues: {}, // block attributes
}

📋 What You Need to Know​

  • Reference blocks by marker (identifier) in code — markers never change.
  • Blocks are created in the admin panel. The SDK is read-only.
  • Custom fields come from AttributesSets. Examples: a footer block (copyright, social links, contact info), a hero banner (headline, CTA, background image), a testimonial (author, photo, quote, rating).
  • Blocks vs. Pages. A page is a self-contained document with a URL (e.g. /about) created in the Pages module; a block is a reusable component you insert into pages.

📊 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
getFrequentlyOrderedProducts()Frequently ordered products"Often ordered together"
getCartComplement()"Complete your cart" by cart contextCross-sell from the cart
getCartComplementByProductIds()"Complete your cart" by productIdsCross-sell for given products
getCartSimilar()"Similar to cart" by cart contextAlternatives to cart items
getCartSimilarByProductIds()"Similar to cart" by productIdsAlternatives for given products
getWishlistSimilar()"Similar to wishlist" by wishlistAlternatives to wishlist items
getWishlistSimilarByProductIds()"Similar to wishlist" by productIdsAlternatives for given products
getPersonalRecommendations()Personal recommendationsPersonalized product feed
getRecentlyViewed()Recently viewed products"Recently viewed" widget
getRepeatPurchase()Products for repeat purchase"Buy again" widget
getTrending()Trending products"Trending now" widget
getSlides()Slider block slides treeRender a slider/carousel

🧩 Block Types​

A block's type (the BlockType) determines what it renders. In addition to the base types (common_block, product_block, similar_products_block, form, and others), the following product & personalization block types are available:

Block typeMethod
frequently_ordered_blockgetFrequentlyOrderedProducts()
trending_blockgetTrending()
recently_viewed_blockgetRecentlyViewed()
repeat_purchase_blockgetRepeatPurchase()
slider_blockgetSlides()
personal_recommendations_blockgetPersonalRecommendations()
cart_complement_blockgetCartComplement() / getCartComplementByProductIds()
cart_similar_blockgetCartSimilar() / getCartSimilarByProductIds()
wishlist_similar_blockgetWishlistSimilar() / getWishlistSimilarByProductIds()

The personalization blocks (recently viewed, repeat purchase, personal recommendations, cart/wishlist) are driven by tracked user activity and work for both authorized users and guests (see Guest mode).

Fixing the price (signPrice)​

The product & recommendation block methods (getCartSimilar, getRecentlyViewed, getTrending, getPersonalRecommendations, getRepeatPurchase, getCartComplement, getFrequentlyOrderedProducts, …) accept an optional signPrice argument. It takes the marker of an order storage and asks the server to lock the returned product prices for a limited time, so the price a customer sees in a recommendation widget is the price they pay at checkout.

signPrice — type string

Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time.

  • On the recommendation methods signPrice is the last positional argument (after langCode).
  • On the …ByProductIds variants (getCartSimilarByProductIds, getCartComplementByProductIds, …) it is a field of the request body (body.signPrice).

Each returned product then carries a signedPrice token that encodes the locked price:


const products = await Blocks.getCartSimilar("cart_similar_block", "en_US", "orders");

const signedPrice = products[0].signedPrice;

➡️ Re-use that token when creating the order — see the Fixed product price (signedPrice) section of the Orders module. The same price-fixing parameter also exists on the Products module (in userQuery.signPrice).

❓ Common Questions (FAQ)​

What's the difference between Blocks and Pages?​

  • Pages/Product Pages — self-contained pages with URLs (e.g. /about) created in the Pages module, to which you add blocks and other components.
  • Blocks — reusable components inserted into pages (e.g. a footer).

Think of a page as a full document and a block as a paragraph you reuse across documents.

How do I update a block's content?​

Edit it in the OneEntry admin panel (Blocks section). All pages using that block update automatically.

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

Prefer many small, focused blocks (e.g. header_logo, footer_social_links) over one large entire_page_layout block — small blocks are easier to reuse and maintain.

How do I show/hide blocks conditionally?​

Check the isVisible field on the fetched block.

How do I handle missing blocks gracefully?​

Wrap the fetch in try/catch and render a fallback when a block isn't found.

🎓 Best Practices​

  • Create small, focused blocks (single responsibility).
  • Use descriptive markers (global_footer, not block1); lowercase with underscores.
  • Reference blocks by marker in code — markers never change.
  • Cache blocks — they change rarely.
  • Handle missing blocks gracefully (try/catch).

🔗 Related Documentation​