Project Templates

Project templates allow you to package complete project structures—collections, fields, and demo data—that can be applied instantly when creating new projects. This saves time by eliminating the need to manually recreate the same collection structures across multiple projects.

What are Project Templates?

A project template is a JSON file that defines:

• Collections - Complete collection definitions with all field configurations
• Demo Data - Sample entries that populate your collections automatically
• Metadata - Template name, description, and identifier

Templates are stored in the resources/data/project_templates/ directory as individual JSON files, making them easy to version control and share.

Template Structure

Each template file should contain a complete template object with the following structure:

{
  "slug": "template-identifier",
  "name": "Template Display Name",
  "description": "What this template does",
  "has_demo_data": true,
  "collections": [
    {
      "name": "Collection Name",
      "slug": "collection-slug",
      "is_singleton": false,
      "fields": [
        {
          "type": "text",
          "label": "Field Label",
          "name": "field_name",
          "description": "Field description",
          "placeholder": "Placeholder text",
          "options": {
            "repeatable": false,
            "hiddenInAPI": false
          },
          "validations": {
            "required": {
              "status": true,
              "message": null
            }
          }
        }
      ]
    }
  ],
  "demo_data": [
    {
      "collection": "collection-slug",
      "entries": [
        {
          "id": "e1",
          "locale": "en",
          "status": "published",
          "fields": {
            "field_name": "Example value"
          }
        }
      ]
    }
  ]
}

Template Properties

• slug (required): A unique identifier for the template (e.g., landing-page-nextjs)
• name (required): The display name shown in the template dropdown
• description (optional): A brief description of what the template provides
• has_demo_data (required): Boolean indicating whether the template includes demo content
• collections (required): Array of collection definitions
• demo_data (optional): Array of demo content entries

Collection Structure

Each collection in the template includes:

• name: Display name for the collection
• slug: URL-friendly identifier
• is_singleton: Boolean indicating if this is a single-entry collection
• fields: Array of field definitions

Field Structure

Fields follow the same structure as when creating them through the UI, including:

• type: Field type (text, longtext, richtext, media, relation, group, etc.)
• label: Display label
• name: Field identifier
• description: Help text
• options: Field-specific options (repeatable, media type, relation settings, etc.)
• validations: Validation rules (required, unique, character count, etc.)

For group fields, include a children array with nested field definitions.

Creating a Template

Step 1: Create the Template File

1. Navigate to resources/data/project_templates/ in your ElmapiCMS installation
2. Create a new JSON file named after your template slug (e.g., my-template.json)
3. Follow the structure outlined above

Step 2: Define Collections

Add all collections your template needs, including their fields. You can reference existing templates in the same directory for examples.

Step 3: Add Demo Data (Optional)

If has_demo_data is true, include a demo_data array with sample entries for your collections. This helps users understand how the template works.

Step 4: Load the Template

Run the seeder to load your template into the database:

php artisan db:seed --class=ProjectTemplateSeeder

This command reads all JSON files from resources/data/project_templates/ and loads them into the database.

Note: The seeder uses updateOrCreate, so running it multiple times will update existing templates if their slugs match.

Using Templates

When creating a new project, you can select a template from the "Choose from a template" dropdown. If the template includes demo data, you can check "Include demo content" to populate your collections with sample entries.

See Creating Projects for more details on using templates when creating new projects.

Example Templates

ElmapiCMS includes several built-in templates:

• Landing Page Next.js - Complete landing page with hero, features, pricing, FAQ, and blog sections
• Blog NextJS - Blog template designed to work with the Next.js starter

You can find these templates in the resources/data/project_templates/ directory to use as references when creating your own.

Advanced: Nested Structures

Templates support complex nested structures:

Repeatable Field Groups

For features, FAQ items, or navigation links:

{
  "type": "group",
  "label": "Feature",
  "name": "features",
  "repeatable": true,
  "children": [
    {
      "type": "text",
      "label": "Title",
      "name": "title"
    },
    {
      "type": "longtext",
      "label": "Description",
      "name": "description"
    }
  ]
}

Relations Between Collections

Link collections together using relation fields:

{
  "type": "relation",
  "label": "Category",
  "name": "category",
  "options": {
    "relation": {
      "type": 1,
      "collection": "categories"
    }
  }
}

When the template is applied, relation fields are automatically updated to reference the correct collection IDs.

Alternative: Saving Projects as Templates from UI

You can also save an existing project as a template directly from the UI without creating a JSON file. This is useful for quick template creation. See Cloning Projects for details on saving projects as templates from the dashboard.

Note: Templates created from the UI are stored in the database, while templates created as JSON files are stored in resources/data/project_templates/ and can be version controlled and shared more easily.