Global Templates Controller

Path: internal/api/v1/funnels/controllers/global.templates.controller.js
Service: funnelGlobalTemplateService
Module: Funnels

Overview

The Global Templates controller manages the funnel template marketplace. It enables administrators to publish funnels as templates and allows users to browse and clone templates to their accounts.

Key Capabilities

Template Publishing: Convert funnels to global templates
Template Marketplace: Browse available funnel templates
Template Categories: Organize templates by industry/use case
Template Cloning: Clone templates to user accounts
Template Management: Update and delete templates (admin)

Methods

`saveGlobalFunnelTemplates()`

Publishes a funnel as a global template (admin only).

Route: POST /v1/funnels/templates/global
Auth: Required (admin permissions)

Request Query Parameters

{
  funnel_id: string; // Funnel ID to convert to template
}

Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "60d5ec49f1b2c72e8c8e4b40",
    "funnel_id": "60d5ec49f1b2c72e8c8e4b1a",
    "name": "Lead Generation Landing Page",
    "description": "High-converting lead generation funnel with form",
    "thumbnail": "https://cdn.example.com/templates/lead-gen.jpg",
    "preview_url": "https://preview.dashclicks.com/lead-gen",
    "category_id": "60d5ec49f1b2c72e8c8e4b41",
    "is_global": true,
    "featured": false,
    "premium": false,
    "tags": ["lead-generation", "form", "landing-page"],
    "use_count": 0,
    "created_at": "2024-01-22T18:00:00Z"
  }
}

MongoDB Collections

Collection	Operation	Purpose
`funnels`	`findOne`	Retrieve source funnel
`funnel_global_templates`	`insertOne`	Create template record
`funnel_steps`	`find`	Copy all funnel steps

Business Logic

Creates snapshot of current funnel state
Copies all steps and components
Generates thumbnail from first step
Sets initial use_count to 0

`getGlobalFunnelTemplates()`

Retrieves global funnel templates with filtering and pagination.

Route: GET /v1/funnels/templates/global
Auth: Required

Request Query Parameters

{
  limit?: number;     // Results per page (default: 12)
  page?: number;      // Page number (1-indexed)
  search?: string;    // Search template names/descriptions
  category?: string;  // Filter by category ID
}

Response

{
  "success": true,
  "message": "SUCCESS",
  "data": [
    {
      "_id": "60d5ec49f1b2c72e8c8e4b40",
      "name": "Lead Generation Landing Page",
      "description": "High-converting lead generation funnel with form",
      "thumbnail": "https://cdn.example.com/templates/lead-gen.jpg",
      "preview_url": "https://preview.dashclicks.com/lead-gen",
      "category": {
        "_id": "60d5ec49f1b2c72e8c8e4b41",
        "name": "Lead Generation"
      },
      "is_global": true,
      "featured": false,
      "premium": false,
      "tags": ["lead-generation", "form", "landing-page"],
      "use_count": 342,
      "steps_count": 3,
      "created_at": "2024-01-22T18:00:00Z"
    },
    {
      "_id": "60d5ec49f1b2c72e8c8e4b42",
      "name": "E-commerce Product Launch",
      "description": "Complete product launch funnel with checkout",
      "thumbnail": "https://cdn.example.com/templates/ecommerce.jpg",
      "preview_url": "https://preview.dashclicks.com/ecommerce",
      "category": {
        "_id": "60d5ec49f1b2c72e8c8e4b43",
        "name": "E-commerce"
      },
      "is_global": true,
      "featured": true,
      "premium": true,
      "tags": ["ecommerce", "checkout", "product-launch"],
      "use_count": 1289,
      "steps_count": 5,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 48,
    "page": 1,
    "limit": 12,
    "pages": 4
  }
}

MongoDB Collections

Collection	Operation	Purpose
`funnel_global_templates`	`find` with pagination	Query templates
`funnel_template_categories`	`lookup`	Join category names
`funnel_steps`	`count`	Count steps per template

Sorting

Featured templates: Prioritized first
Use count: Secondary sort (most popular)
Created date: Tertiary sort (newest)

`deleteGlobalFunnelTemplates()`

Removes a funnel from the global template marketplace (admin only).

Route: DELETE /v1/funnels/templates/global
Auth: Required (admin permissions)

Request Query Parameters

{
  funnel_id: string; // Template ID to delete
}

Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "deleted": true,
    "template_id": "60d5ec49f1b2c72e8c8e4b40"
  }
}

MongoDB Collections

Collection	Operation	Purpose
`funnel_global_templates`	`deleteOne`	Remove template

Business Logic

Soft delete option available (mark as inactive)
Does NOT delete user funnels cloned from template
Decrements category template count

`useGlobalFunnelTemplates()`

Clones a global template to the user's account.

Route: POST /v1/funnels/templates/global/use
Auth: Required (account-scoped)

Request Query Parameters

{
  funnel_id: string; // Template ID to clone
}

Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "60d5ec49f1b2c72e8c8e4b44",
    "name": "Lead Generation Landing Page (Copy)",
    "account_id": "60d5ec49f1b2c72e8c8e4b19",
    "domain_id": null,
    "base_path": "/lead-gen",
    "status": "inactive",
    "cloned_from_template": "60d5ec49f1b2c72e8c8e4b40",
    "steps": [
      {
        "_id": "60d5ec49f1b2c72e8c8e4b45",
        "name": "Landing Page",
        "path": "/",
        "order": 1
      },
      {
        "_id": "60d5ec49f1b2c72e8c8e4b46",
        "name": "Thank You",
        "path": "/thank-you",
        "order": 2
      }
    ],
    "created_at": "2024-01-22T18:30:00Z"
  }
}

MongoDB Collections

Collection	Operation	Purpose
`funnel_global_templates`	`findOne`	Retrieve template
`funnels`	`insertOne`	Create user funnel
`funnel_steps`	`insertMany`	Clone all steps
`funnel_step_components`	`insertMany`	Clone components
`funnel_global_templates`	`update`	Increment use_count

Business Logic

Creates complete copy of template funnel
Assigns to user's account
Sets status to "inactive" for safety
Clears domain connection (user must configure)
Records template source in cloned_from_template field
Increments template's use_count

Premium Template Handling

// If template is premium and user doesn't have access
{
  "success": false,
  "message": "Premium template requires subscription",
  "data": {
    "template_id": "60d5ec49f1b2c72e8c8e4b42",
    "premium": true,
    "required_plan": "pro"
  },
  "statusCode": 403
}

`saveGlobalFunnelTemplatesCategories()`

Creates a new template category (admin only).

Route: POST /v1/funnels/templates/categories
Auth: Required (admin permissions)

Request Body

{
  "category": {
    "name": "Real Estate"
  }
}

Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "60d5ec49f1b2c72e8c8e4b47",
    "name": "Real Estate",
    "slug": "real-estate",
    "description": null,
    "icon": null,
    "template_count": 0,
    "order": 10,
    "created_at": "2024-01-22T19:00:00Z"
  }
}

MongoDB Collections

Collection	Operation	Purpose
`funnel_template_categories`	`insertOne`	Create category

Business Logic

Auto-generates slug from name (e.g., "Real Estate" → "real-estate")
Sets initial template_count to 0
Assigns next available order number

`getGlobalFunnelTemplatesCategories()`

Retrieves template categories with optional filtering.

Route: GET /v1/funnels/templates/categories
Auth: Required

Request Query Parameters

{
  category_id?: string;  // Optional: get specific category
}

Response (All Categories)

{
  "success": true,
  "message": "SUCCESS",
  "data": [
    {
      "_id": "60d5ec49f1b2c72e8c8e4b41",
      "name": "Lead Generation",
      "slug": "lead-generation",
      "description": "Capture leads with high-converting forms",
      "icon": "https://cdn.example.com/icons/lead-gen.svg",
      "template_count": 15,
      "order": 1
    },
    {
      "_id": "60d5ec49f1b2c72e8c8e4b43",
      "name": "E-commerce",
      "slug": "ecommerce",
      "description": "Sell products with checkout funnels",
      "icon": "https://cdn.example.com/icons/ecommerce.svg",
      "template_count": 23,
      "order": 2
    },
    {
      "_id": "60d5ec49f1b2c72e8c8e4b47",
      "name": "Real Estate",
      "slug": "real-estate",
      "description": "Real estate listing and lead capture",
      "icon": "https://cdn.example.com/icons/real-estate.svg",
      "template_count": 8,
      "order": 3
    }
  ]
}

Response (Specific Category)

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "60d5ec49f1b2c72e8c8e4b41",
    "name": "Lead Generation",
    "slug": "lead-generation",
    "description": "Capture leads with high-converting forms",
    "icon": "https://cdn.example.com/icons/lead-gen.svg",
    "template_count": 15,
    "order": 1,
    "templates": [
      {
        "_id": "60d5ec49f1b2c72e8c8e4b40",
        "name": "Lead Generation Landing Page",
        "thumbnail": "https://cdn.example.com/templates/lead-gen.jpg",
        "use_count": 342
      }
      // ... more templates
    ]
  }
}

MongoDB Collections

Collection	Operation	Purpose
`funnel_template_categories`	`find`	Query categories
`funnel_global_templates`	`lookup` (if specific)	Join templates for category

`updateGlobalFunnelTemplate()`

Updates template metadata (category, featured status, etc.) - admin only.

Route: PUT /v1/funnels/templates/global/:funnel_id
Auth: Required (admin permissions)

Request Parameters

{
  funnel_id: string; // Template ID
}

Request Body

{
  "category_id": "60d5ec49f1b2c72e8c8e4b43",
  "featured": true,
  "premium": false,
  "tags": ["ecommerce", "checkout", "updated"],
  "description": "Updated description for template"
}

Response

{
  "success": true,
  "message": "SUCCESS"
}

MongoDB Collections

Collection	Operation	Purpose
`funnel_global_templates`	`findOneAndUpdate`	Update template

Data Models

Global Template Document

{
  _id: ObjectId;
  funnel_id: ObjectId;            // Source funnel (snapshot)
  name: string;                   // Template display name
  description?: string;           // Template description
  thumbnail?: string;             // Preview image URL
  preview_url?: string;           // Live preview URL

  // Categorization
  category_id?: ObjectId;         // Template category
  tags: string[];                 // Searchable tags

  // Flags
  is_global: true;                // Always true for templates
  featured: boolean;              // Show in featured section
  premium: boolean;               // Requires premium account

  // Funnel snapshot data
  steps: Array<{
    _id: ObjectId;
    name: string;
    path: string;
    order: number;
    html?: string;
    components?: object;
  }>;

  // Metadata
  base_path?: string;             // Default base path for clones
  header_tracking_code?: string;  // Default tracking code
  footer_tracking_code?: string;  // Default tracking code

  // Analytics
  use_count: number;              // Times template used
  popularity_score?: number;      // Calculated popularity

  created_at: Date;
  updated_at: Date;
  created_by?: ObjectId;          // Admin user who created
}

Template Category Document

{
  _id: ObjectId;
  name: string;                   // Category name
  slug: string;                   // URL-friendly slug
  description?: string;           // Category description
  icon?: string;                  // Icon URL

  // Ordering
  order: number;                  // Display order

  // Metadata
  template_count: number;         // Number of templates in category

  created_at: Date;
  updated_at: Date;
}

Business Logic & Workflows

Template Publishing Flow

sequenceDiagram
    participant Admin
    participant Templates
    participant Database
    participant CDN

    Admin->>Templates: POST /templates/global (saveGlobalFunnelTemplates)
    Templates->>Database: Find source funnel
    Templates->>Database: Copy all steps + components
    Templates->>CDN: Generate thumbnail from first step
    CDN-->>Templates: Thumbnail URL
    Templates->>Database: Insert template document
    Database-->>Templates: Template created
    Templates-->>Admin: 200 OK + template

Template Cloning Flow

sequenceDiagram
    participant User
    participant Templates
    participant Database
    participant Cache

    User->>Templates: POST /templates/global/use (useGlobalFunnelTemplates)
    Templates->>Database: Find template

    alt Premium Template
        Templates->>Database: Check user subscription
        alt No Access
            Templates-->>User: 403 Forbidden
        end
    end

    Templates->>Database: Copy funnel structure
    Templates->>Database: Copy all steps
    Templates->>Database: Copy all components
    Templates->>Database: Increment template use_count
    Database-->>Templates: Funnel cloned
    Templates->>Cache: Clear user funnel cache
    Templates-->>User: 200 OK + new funnel

Category Management Flow

sequenceDiagram
    participant Admin
    participant Templates
    participant Database

    Admin->>Templates: POST /templates/categories (saveGlobalFunnelTemplatesCategories)
    Templates->>Database: Check duplicate name

    alt Name Available
        Templates->>Templates: Generate slug
        Templates->>Database: Insert category
        Database-->>Templates: Category created
        Templates-->>Admin: 200 OK + category
    else Duplicate Name
        Templates-->>Admin: 409 Conflict
    end

Integration Points

CDN/Asset Storage

Purpose: Store template thumbnails and preview images
Integration: Thumbnail URLs point to CDN
Generation: Auto-generate thumbnails from first step screenshot

Funnel Builder

Purpose: Clone templates directly into builder
Integration: Template structure → Builder components
Workflow: Browse templates → Preview → Clone → Edit

Analytics

Purpose: Track template popularity and usage
Metrics: use_count, conversion rates of cloned funnels
Reporting: Popular templates dashboard

Performance Considerations

Template Listing

Featured templates cached for 1 hour
Category counts updated asynchronously
Pagination for large template libraries

Template Cloning

Async operation for large funnels (many steps/components)
Progress tracking for long-running clones
Database transactions ensure consistency

Query Optimization

Indexed fields: category_id, featured, premium, use_count
Compound indexes: (featured, use_count), (category_id, use_count)
Full-text search on name and tags

Security

Authorization

Browse templates: Any authenticated user
Clone templates: Authenticated + subscription check (if premium)
Publish/delete templates: Admin only
Manage categories: Admin only

Premium Templates

Checked via user's account subscription level
Enforced before cloning operation
Clear error message if access denied

Admin Verification

Admin permissions checked via middleware
Service layer validates admin status
Audit log for all admin operations

Error Handling

Common Errors

// Template not found
{
  "success": false,
  "message": "Template not found",
  "statusCode": 404
}

// Premium access required
{
  "success": false,
  "message": "Premium template requires subscription",
  "data": {
    "required_plan": "pro"
  },
  "statusCode": 403
}

// Admin permission required
{
  "success": false,
  "message": "Admin permissions required",
  "statusCode": 403
}

// Duplicate category name
{
  "success": false,
  "message": "Category with this name already exists",
  "statusCode": 409
}

// Clone failed
{
  "success": false,
  "message": "Failed to clone template",
  "data": {
    "reason": "Database transaction failed"
  },
  "statusCode": 500
}

Best Practices

When to Use This Controller

✅ Building template marketplaces
✅ Providing pre-built funnel templates
✅ Enabling rapid funnel creation
✅ Monetizing premium templates

Common Patterns

Featured templates: Highlight best-performing templates
Category organization: Group templates by industry/use case
Premium tiers: Offer exclusive templates to paid plans
Usage tracking: Monitor popular templates for curation

Edge Cases

Large funnels: Async cloning for 10+ steps
Deleted source funnel: Template preserves snapshot, unaffected
Category deletion: Move templates to "Uncategorized" category
Premium downgrade: User keeps cloned templates but can't clone new ones

Funnels Controller: Core funnel management
Blocks Controller: Reusable UI components
Subscription Management: Premium access control
Admin Panel: Template curation and management

Last Updated: January 2025
API Version: v1
Maintained By: DashClicks Engineering

Overview​

Key Capabilities​

Methods​

saveGlobalFunnelTemplates()​

Request Query Parameters​

Response​

MongoDB Collections​

Business Logic​

getGlobalFunnelTemplates()​

Request Query Parameters​

Response​

MongoDB Collections​

Sorting​

deleteGlobalFunnelTemplates()​

Request Query Parameters​

Response​

MongoDB Collections​

Business Logic​

useGlobalFunnelTemplates()​

Request Query Parameters​

Response​

MongoDB Collections​

Business Logic​

Premium Template Handling​

saveGlobalFunnelTemplatesCategories()​

Request Body​

Response​

MongoDB Collections​

Business Logic​

getGlobalFunnelTemplatesCategories()​

Request Query Parameters​

Response (All Categories)​

Response (Specific Category)​

MongoDB Collections​

updateGlobalFunnelTemplate()​

Request Parameters​

Request Body​

Response​

MongoDB Collections​

Data Models​

Global Template Document​

Template Category Document​

Business Logic & Workflows​

Template Publishing Flow​

Template Cloning Flow​

Category Management Flow​

Integration Points​

CDN/Asset Storage​

Funnel Builder​

Analytics​

Performance Considerations​

Template Listing​

Template Cloning​

Query Optimization​

Security​

Authorization​

Premium Templates​

Admin Verification​

Error Handling​

Common Errors​

Best Practices​

When to Use This Controller​

Common Patterns​

Edge Cases​

Related Documentation​

Documentation Assistant

Overview

Key Capabilities

Methods

`saveGlobalFunnelTemplates()`

Request Query Parameters

Response

MongoDB Collections

Business Logic

`getGlobalFunnelTemplates()`

Request Query Parameters

Response

MongoDB Collections

Sorting

`deleteGlobalFunnelTemplates()`

Request Query Parameters

Response

MongoDB Collections

Business Logic

`useGlobalFunnelTemplates()`

Request Query Parameters

Response

MongoDB Collections

Business Logic

Premium Template Handling

`saveGlobalFunnelTemplatesCategories()`

Request Body

Response

MongoDB Collections

Business Logic

`getGlobalFunnelTemplatesCategories()`

Request Query Parameters

Response (All Categories)

Response (Specific Category)

MongoDB Collections

`updateGlobalFunnelTemplate()`

Request Parameters

Request Body

Response

MongoDB Collections

Data Models

Global Template Document

Template Category Document

Business Logic & Workflows

Template Publishing Flow

Template Cloning Flow

Category Management Flow

Integration Points

CDN/Asset Storage

Funnel Builder

Analytics

Performance Considerations

Template Listing

Template Cloning

Query Optimization

Security

Authorization

Premium Templates

Admin Verification

Error Handling

Common Errors

Best Practices

When to Use This Controller

Common Patterns

Edge Cases

Related Documentation