Skip to main content

Blocks

Read content blocks that you reuse across pages.

More information about the module's user interface https://doc.oneentry.cloud/docs/category/blocks (opens in a new tab)

A block is a set of attributes you create once in the admin panel and reuse on pages and product pages: a header, a footer, a banner, testimonials, a slider, a product or recommendation widget. When you edit a block in the Blocks section of the admin panel, every page that uses it picks up the change.

The SDK only reads blocks. To create or edit them, use the OneEntry admin panel.

A page is a standalone document with its own URL (e.g. /about), created in the Pages module. A block is a component you add to pages.

Quickstart​

Initialize the module from defineOneEntry:


const {  } = defineOneEntry(
  , {
    
  }
);

Fetch a block by its marker:

// Fetch the "footer" block.
const block = await Blocks.getBlockByMarker("footer", "en_US");
if ('statusCode' in block) throw new Error(block.message);

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

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

Reference blocks in code by marker (identifier), not by numeric id. If someone renames a marker in the admin panel, update your code too. Blocks change rarely, so they are good candidates for caching.

Block object​

{
  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
}

localizeInfos holds the block's localized data, such as title, in the language you requested with langCode; the SDK also resolves attributeValues to that language. type is the BlockType; it determines which data the block carries and which method returns its products. To show or hide a block conditionally, check isVisible. attributeValues contains the custom fields defined in AttributesSets: for example, a footer's copyright and social links, or a hero banner's headline, CTA and background image.

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 blocks by titleAutocomplete, block pickers
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

Product and recommendation blocks​

For product_block and similar_products_block, getBlockByMarker() and getBlocks() also load the products into products and similarProducts respectively, unless traficLimit: true is set in defineOneEntry. The block types below each have a dedicated method:

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()

Recently viewed and the cart and wishlist blocks work for both authenticated users and guests (see Guest mode). Repeat purchase and personal recommendations need a signed-in user: for a guest they return an empty result (items: [], total: 0, totalFound: 0) instead of an error. Recently viewed is built from tracked user activity, repeat purchase from the user's order history.

getCartComplement, getCartSimilar, getWishlistSimilar, their …ByProductIds variants, getTrending, getPersonalRecommendations, getRecentlyViewed, getRepeatPurchase and getFrequentlyOrderedProducts resolve to an IProductsResponse, not an array. Read the products from items and the counts from total and totalFound.

Fixing the price (signPrice)​

The product methods (getCartSimilar, getRecentlyViewed, getTrending, getPersonalRecommendations, getRepeatPurchase, getCartComplement, getFrequentlyOrderedProducts, …) take an optional signPrice argument (string): the marker of an order storage. When it is set, the server locks the returned prices for a limited time, so the customer pays at checkout the price they saw in the widget.

In the recommendation methods, signPrice is the positional argument after langCode. In the …ByProductIds variants (getCartSimilarByProductIds, getCartComplementByProductIds, …) it goes in the request body as body.signPrice.

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


const products = await Blocks.("cart_similar_block", "en_US", "orders");
if ('statusCode' in products) throw new Error(products.message);

const signedPrice = products.[0]?.signedPrice;

Pass the token when you create the order; see Fixed product price (signedPrice) in the Orders module. The Products module has the same parameter as userQuery.signPrice.

Limiting the number of products (limit)​

getFrequentlyOrderedProducts, getCartComplement, getCartSimilar, getWishlistSimilar, getPersonalRecommendations, getRecentlyViewed, getRepeatPurchase and getTrending take an optional limit as the last positional argument, after signPrice.

limit: type number

Maximum number of products to return. It can only lower the block's own limit from the admin panel, not raise it: a larger value is capped at that setting. If you omit it, the block setting applies.

// The block's own quantity setting decides how many products come back.
const widget = await Blocks.getTrending('trending_block');

// Ask for at most 4 - e.g. a compact carousel on mobile.
const compact = await Blocks.getTrending('trending_block', 'en_US', undefined, 4);

In the …ByProductIds variants (getCartComplementByProductIds, getCartSimilarByProductIds, getWishlistSimilarByProductIds), limit goes in the request body as body.limit, next to productIds, langCode and signPrice. body.limit accepts an integer from 1 to 50 (values outside that range are rejected with 400) and is capped by the block setting the same way.

Handling a missing block​

When a block isn't found, the SDK by default returns an error object (statusCode: 404) instead of throwing, so check the result before rendering and fall back if needed. With isShell: false the SDK throws, and try/catch applies. See Errors.