# How Templates Work

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

## Supported Template Types

| Type           | Resource         | Usage                     |
| -------------- | ---------------- | ------------------------- |
| `product`      | PRODUCT          | Individual product pages  |
| `category`     | PRODUCT_GROUP    | Category/collection pages |
| `page`         | PAGE, HOME       | Custom pages              |
| `article`      | ARTICLE          | Article/blog post pages   |
| `blog`         | BLOG             | Blog listing pages        |
| `catalog`      | PRODUCTS         | Product catalog pages     |
| `manufacturer` | MANUFACTURER     | Manufacturer pages        |
| `cart`         | CART             | Shopping cart pages       |
| `wishlist`     | ACCOUNT_WISHLIST | Wishlist pages            |

## Creating a Template

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

```tsx
// 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](./blocks) - Learn how to build blocks for templates
- [Visual Editing](./visual-editing) - Use the editor to create templates
- [Architecture](./architecture) - Understand the overall system