Introduction

Manage e-commerce products with dynamic catalogs, filtering, and search.

🎯 What does this module do?

The Products module lets you create, retrieve, filter, and manage products in your online store or catalog - from simple items to complex products with variants, images, prices, and custom attributes.

Think of it as your digital warehouse - you manage your product inventory in OneEntry, and your app fetches products dynamically with powerful search, filters, and sorting.

📖 Simple Explanation

Imagine you're building an online store selling:

👟 Sneakers - with sizes, colors, prices
📱 Electronics - with specs, images, reviews
👕 Clothing - with sizes, materials, variants
📚 Books - with authors, prices, descriptions

Instead of hardcoding each product, you:

✅ Add products in OneEntry admin panel (with all details)
✅ Fetch products dynamically using this module
✅ Filter by category, price range, availability
✅ Search products by name or description
✅ Sort by price, date, popularity
✅ Update prices/stock without redeploying

Real-world example:

Without Products Module (hardcoded):
- Add new product → Change code → Deploy ❌
- Change price → Code change → Deploy ❌
- 1000 products = massive code file ❌

With Products Module (dynamic):
- Add new product → Update in admin → Live instantly ✅
- Change price → Update in admin → Live instantly ✅
- 10,000 products = simple API calls ✅

✨ Key Concepts

What is a Product?

A product is an item you sell, containing:

Basic info - Name, description, SKU, price
Images - Product photos, gallery
Variants - Sizes, colors, options (e.g., "Red T-shirt Size M")
Inventory - Stock quantity, availability
Custom attributes - Any fields you define (brand, material, weight, etc.)
SEO - Meta title, description, keywords
Status - Active, draft, out of stock
Localization - Multi-language support

Product Structure

Products can have different structures:

Type	Description	Example
Simple Product	Single item, no variants	Book, Poster
Product with Variants	Multiple options (size, color)	T-shirt (S/M/L, Red/Blue)
Digital Product	Downloadable items	E-book, Software
Bundle	Group of products	Starter Pack, Gift Set

Product Organization

Products are organized by:

Categories - Organize into sections (e.g., Men's Clothing, Electronics)
Statuses - Active, Draft, Out of Stock
Price ranges - Budget, Mid-range, Premium
Custom filters - Brand, Size, Color, Material, etc.

Example hierarchy:

📁 Electronics
  ├─ 📱 Smartphones
  │   ├─ iPhone 15 Pro
  │   └─ Samsung Galaxy S24
  └─ 💻 Laptops
      ├─ MacBook Pro
      └─ Dell XPS

📁 Clothing
  ├─ 👕 T-Shirts
  └─ 👖 Jeans

📋 What You Need to Know

1. Three Ways to Get Products

Method	When to Use	Example
getProducts()	List products with filters/search	Shop catalog page
getProductByUrl()	User visits specific product page	`/products/sneakers`
getProductByMarker()	Reference product in code	`featured_product`
getProductById()	Internal references	Product ID: `123`

When you have 1000 products, you don't load all at once:

Offset formula: offset = (pageNumber - 1) * limit

3. Sorting Options

Sort products by different fields:

sortKey	What It Does	Example Use
price	Sort by price	Show cheapest first
date	Sort by creation date	Show newest products
title	Sort alphabetically	A-Z product list
position	Custom order (default)	Hand-picked order from admin
id	Sort by ID	Technical sorting

Sort order:

ASC (Ascending) - Low to high (A→Z, 0→9, cheap→expensive)
DESC (Descending) - High to low (Z→A, 9→0, expensive→cheap)

4. Filtering Products

Use filters to narrow down results:

Condition markers:

Marker	Meaning	Example
eq	Equal (exact match)	Price = $50
neq	Not equal	Status ≠ "sold out"
in	Contains (one of)	Color in ["red", "blue"]
nin	Not contains	Category not in ["archived"]
mth	Greater than	Price > $100
lth	Less than	Price < $50
exs	Exists (has value)	Has discount
nexs	Does not exist (empty)	No discount

5. Product Status

Products have different statuses:

const product = await Products.getProductById(123);

if (product.statusId === 1 && product.isVisible) {
  console.log("✅ Product is active and visible");
} else if (product.statusId === 0) {
  console.log("📝 Product is draft");
} else {
  console.log("🚫 Product is hidden");
}

Status values:

statusId: 1 - Active (available for purchase)
statusId: 0 - Draft (not visible to customers)
isVisible: false - Hidden (admin can see, customers can't)

📊 Quick Reference Table - Common Methods

Method	What It Does	When to Use
getProducts()	Get all products (filtered, sorted, paginated)	Product catalog page
getProductById()	Get product by ID	Internal references
getProductByUrl()	Get product by URL	Product detail page
getProductByMarker()	Get product by marker	Featured/special products
getProductsStatusesByMarker()	Get available statuses	Filter by status
getRelatedProducts()	Get related/similar products	"You may also like" section
getProductStatus()	Check product availability	Stock management

❓ Common Questions (FAQ)

Q: Can I filter by multiple criteria at once?

A: Yes! Combine multiple filters:

// Find: Red T-shirts, Size M, Price under $30
const filtered = await Products.getProducts({
  conditionValue: [
    { attributeMarker: "category", conditionMarker: "eq", value: "t-shirts" },
    { attributeMarker: "color", conditionMarker: "eq", value: "red" },
    { attributeMarker: "size", conditionMarker: "eq", value: "M" },
    { attributeMarker: "price", conditionMarker: "lth", value: 30 }
  ],
  limit: 20
});

Q: How do I handle product variants (sizes, colors)?

A: Product variants are stored in attributeValues:

const product = await Products.getProductByUrl('/products/t-shirt');

// Get available variants
const sizes = product.attributeValues.sizes?.value || [];  // ["S", "M", "L", "XL"]
const colors = product.attributeValues.colors?.value || []; // ["Red", "Blue", "Green"]

Q: How do I implement "Load More" button?

A: Use offset to load more products:

Q: Can I show products from multiple categories?

A: Yes, use in condition marker:

// Show products from Electronics OR Clothing
const products = await Products.getProducts({
  conditionValue: [{
    attributeMarker: "category",
    conditionMarker: "in",  // Match any of these
    value: ["electronics", "clothing", "accessories"]
  }],
  limit: 20
});

Q: How do I implement "New Arrivals" section?

A: Sort by creation date or use parent category for manually sorting:

async function getNewArrivals(limit = 8) {
  const result = await Products.getProducts({
    sortKey: 'date',      // Sort by creation date
    sortOrder: 'DESC',    // Newest first
    limit: limit,
    statusId: 1
  });

  return result.items;
}

// Usage
const newProducts = await getNewArrivals(8);

💡 Important Notes

Performance Optimization

Cache frequently accessed products:

const productCache = new Map();
const CACHE_DURATION = 5 * 60 * 1000; // 5 minutes

async function getCachedProduct(url) {
  const cached = productCache.get(url);

  if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
    return cached.product;
  }

  const product = await Products.getProductByUrl(url);

  productCache.set(url, {
    product: product,
    timestamp: Date.now()
  });

  return product;
}

Always Filter Active Products

In production, always show only active products

Handle Missing Images

Provide fallback for products without images

🎓 Best Practices

Do's:

✅ Always use pagination (limit + offset)
✅ Filter by statusId: 1 in production
✅ Cache product lists to reduce API calls
✅ Handle "out of stock" gracefully
✅ Provide fallback images
✅ Use markers for featured products (not IDs)
✅ Implement search with debouncing
✅ Add loading states in UI

Don'ts:

❌ Fetch all products at once (use pagination!)
❌ Show draft products to customers
❌ Hardcode product IDs in code
❌ Ignore error handling
❌ Skip caching for popular products
❌ Forget to format prices properly
❌ Load high-res images without Optimization

Definition of the Products module

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


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

This module accepts a set of user parameters called userQuery. If the parameters are not passed to the method, the default value will be applied. Some methods accept the body as a parameter for filtering. If you don't want to set up sorting, pass an empty array or don't pass anything.

Parameters:


const userQuery = {
    offset: 0,
    limit: 30,
    sortOrder: 'DESC',
    sortKey: 'id',
}

Schema

offset: number
Pagination parameter. Default 0
example: 0

limit: number
pagination parameter. Default 30
example: 30

sortKey: string
Field for sorting (default not set - sorting by position, possible values: id, title, date, price, position)
Available values: id, position, title, date, price

sortOrder: string
sorting order DESC | ASC (default DESC)
example: "DESC"

"conditionMarker" by which values are filtered (not set by default), possible values:

'in' - Contains,
'nin' - Does not contain,
'eq' - Equal,
'neq' - Not equal,
'mth' - Greater than,
'lth' - Less than,
'exs' - Exists,
'nexs' - Does not exist

Pages Module - Manage product pages
AttributesSets Module - Custom product fields
Blocks Module - Reusable product content blocks
Orders Module - Handle product orders

Introduction

🎯 What does this module do?​

📖 Simple Explanation​

✨ Key Concepts​

What is a Product?​

Product Structure​

Product Organization​

📋 What You Need to Know​

1. Three Ways to Get Products​

2. Pagination Explained Simply​

3. Sorting Options​

4. Filtering Products​

5. Product Status​

📊 Quick Reference Table - Common Methods​

❓ Common Questions (FAQ)​

Q: Can I filter by multiple criteria at once?​

Q: How do I handle product variants (sizes, colors)?​

Q: How do I implement "Load More" button?​

Q: Can I show products from multiple categories?​

Q: How do I implement "New Arrivals" section?​

💡 Important Notes​

Performance Optimization​

Always Filter Active Products​

Handle Missing Images​

🎓 Best Practices​

Definition of the Products module​

🔗 Related Documentation​