How Templates Work

Templates define the visual layout for different resource types in the Finqu catalog (products, categories, pages, etc.).

Supported Template Types

Creating a Template

Templates are stored in the templates/ directory and are responsible for rendering a specific resource type:

// templates/my-resource-template.tsx
'use client';
 
import { useProduct } from '@finqu/storefront-sdk/react';
import { Render } from '@puckeditor/core';
import { config } from '@/.storefront/puck.render.config';
 
interface MyResourceTemplateProps {
  locale: string;
  id: number;
  searchParams?: Record<string, string | string[] | undefined>;
}
 
export function MyResourceTemplate({ locale, id, searchParams }: MyResourceTemplateProps) {
  // Fetch data via SDK hook
  const { product } = useProduct({ id });
 
  if (!product) return <div>Loading...</div>;
 
  // Try to load custom template first, fall back to default
  const data = await getTemplateConfig('my-type', id, 'published');
 
  return (
    <>
      {/* Render Puck template if one exists */}
      {data && <Render config={config} data={data} />}
 
      {/* Fallback to dedicated component */}
      {!data && <DefaultMyResourceView product={product} />}
    </>
  );
}

Template Storage & Versions

Templates are stored with two versions:

• Draft (draft) - In-progress changes in the editor
• Published (published) - Live version shown to customers

Each template type has:

• Default template - Applied to all resources of that type
• Resource-specific override - Applied only to specific products/categories

Template Key Structure:
- Default:    template:{type}:default:{version}
- Override:   template:{type}:slug:{resourceId}:{version}
- Page:       page:{pageId}:{version}

Template Resolution

When a resource is requested, the template system:

1. Checks for a resource-specific template override
2. Falls back to the default template for that resource type
3. Falls back to a basic component if no template exists

This allows you to:

• Set default layouts for all products
• Override specific products with custom layouts
• Gradually migrate from components to templates

Template API

Templates are managed through API endpoints:

POST /api/puck/template/save     # Save draft
POST /api/puck/template/publish  # Publish draft
POST /api/puck/page/save         # Save page draft
POST /api/puck/page/publish      # Publish page

Best Practices

1. Start with defaults - Create default templates for each resource type
2. Use overrides sparingly - Only override when necessary for specific resources
3. Test both versions - Always test draft before publishing
4. Keep templates focused - Each template should handle one resource type well
5. Document custom templates - Note any special requirements or dependencies

Next Steps

• Blocks - Learn how to build blocks for templates
• Visual Editing - Use the editor to create templates
• Architecture - Understand the overall system