Tasks Entity

Introduction

The Tasks entity is the primary example entity included in the default theme. It demonstrates a complete entity implementation with full CRUD operations, metadata support, API access, and internationalization.

Entity Configuration

Basic Setup

{
  slug: 'tasks',
  enabled: true,
  names: {
    singular: 'task',
    plural: 'Tasks'
  },
  icon: CheckSquare
}

Access Configuration

access: {
  public: false,      // Not accessible without authentication
  api: true,          // External API access enabled
  metadata: true,     // Metadata system supported
  shared: false       // User-scoped (not shared between users)
}

Implications:

• Users must be authenticated to access tasks
• Tasks are available via API key
• Each task can have custom metadata
• Users only see their own tasks

UI Features

ui: {
  dashboard: {
    showInMenu: true,       // Appears in sidebar
    showInTopbar: true      // Quick access in topbar
  },
  public: {
    hasArchivePage: false,  // No public archive
    hasSinglePage: false    // No public detail page
  },
  features: {
    searchable: true,       // Full-text search enabled
    sortable: true,         // Column sorting
    filterable: true,       // Advanced filters
    bulkOperations: true,   // Select multiple tasks
    importExport: false     // No CSV import/export
  }
}

Permissions

permissions: {
  read: ['admin', 'colaborator', 'member'],
  create: ['admin', 'colaborator', 'member'],
  update: ['admin', 'colaborator', 'member'],
  delete: ['admin', 'colaborator', 'member']
}

All roles can perform all operations on tasks.

Fields

Standard Fields

Title:

{
  name: 'title',
  type: 'text',
  label: 'Title',
  required: true,
  searchable: true,
  sortable: true
}

Description:

{
  name: 'description',
  type: 'textarea',
  label: 'Description',
  required: false
}

Status:

{
  name: 'status',
  type: 'select',
  label: 'Status',
  options: [
    { value: 'pending', label: 'Pending' },
    { value: 'in_progress', label: 'In Progress' },
    { value: 'completed', label: 'Completed' }
  ]
}

Priority:

{
  name: 'priority',
  type: 'select',
  label: 'Priority',
  options: [
    { value: 'low', label: 'Low' },
    { value: 'medium', label: 'Medium' },
    { value: 'high', label: 'High' }
  ]
}

Database Schema

Tasks Table

CREATE TABLE tasks (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title VARCHAR(255) NOT NULL,
  description TEXT,
  status VARCHAR(50) DEFAULT 'pending',
  priority VARCHAR(50) DEFAULT 'medium',
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Tasks Metadata Table

CREATE TABLE tasks_metas (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  entity_id UUID REFERENCES tasks(id) ON DELETE CASCADE,
  meta_key VARCHAR(255) NOT NULL,
  meta_value TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

API Endpoints

List Tasks

GET /api/v1/tasks
Authorization: Bearer {API_KEY}

Query Parameters:

• search - Full-text search
• status - Filter by status
• priority - Filter by priority
• sort - Sort by field (e.g., sort=created_at:desc)
• limit - Results per page
• offset - Pagination offset

Get Single Task

GET /api/v1/tasks/{id}
Authorization: Bearer {API_KEY}

Create Task

POST /api/v1/tasks
Authorization: Bearer {API_KEY}
Content-Type: application/json

{
  "title": "New Task",
  "description": "Task description",
  "status": "pending",
  "priority": "high"
}

Update Task

PUT /api/v1/tasks/{id}
Authorization: Bearer {API_KEY}
Content-Type: application/json

{
  "title": "Updated Title",
  "status": "completed"
}

Delete Task

DELETE /api/v1/tasks/{id}
Authorization: Bearer {API_KEY}

Translations

English (messages/en.json)

{
  "tasks": {
    "title": "Tasks",
    "singular": "Task",
    "fields": {
      "title": "Title",
      "description": "Description",
      "status": "Status",
      "priority": "Priority"
    },
    "status": {
      "pending": "Pending",
      "in_progress": "In Progress",
      "completed": "Completed"
    },
    "priority": {
      "low": "Low",
      "medium": "Medium",
      "high": "High"
    }
  }
}

Spanish (messages/es.json)

{
  "tasks": {
    "title": "Tareas",
    "singular": "Tarea",
    "fields": {
      "title": "Título",
      "description": "Descripción",
      "status": "Estado",
      "priority": "Prioridad"
    },
    "status": {
      "pending": "Pendiente",
      "in_progress": "En Progreso",
      "completed": "Completada"
    },
    "priority": {
      "low": "Baja",
      "medium": "Media",
      "high": "Alta"
    }
  }
}

Usage Examples

In Components

import { useTranslations } from 'next-intl'
import { useEntityData } from '@/core/hooks/use-entity-data'

export function TasksList() {
  const t = useTranslations('tasks')
  const { data: tasks, isLoading } = useEntityData('tasks')

  if (isLoading) return <div>Loading...</div>

  return (
    <div>
      <h1>{t('title')}</h1>
      {tasks.map(task => (
        <div key={task.id}>
          <h3>{task.title}</h3>
          <p>{t(`status.${task.status}`)}</p>
        </div>
      ))}
    </div>
  )
}

With Metadata

// Add metadata to task
await addMetadata('tasks', taskId, 'custom_field', 'custom_value')

// Get metadata
const metadata = await getMetadata('tasks', taskId, 'custom_field')

// Update metadata
await updateMetadata('tasks', taskId, 'custom_field', 'new_value')

// Delete metadata
await deleteMetadata('tasks', taskId, 'custom_field')

Row Level Security (RLS)

Policy: Users see only their tasks

CREATE POLICY "Users can only see their own tasks"
ON tasks FOR SELECT
USING (auth.uid() = user_id);

CREATE POLICY "Users can only create their own tasks"
ON tasks FOR INSERT
WITH CHECK (auth.uid() = user_id);

CREATE POLICY "Users can only update their own tasks"
ON tasks FOR UPDATE
USING (auth.uid() = user_id);

CREATE POLICY "Users can only delete their own tasks"
ON tasks FOR DELETE
USING (auth.uid() = user_id);

Dashboard Integration

Navigation Menu

Tasks automatically appear in:

• Sidebar - Full navigation entry
• Topbar - Quick access button

Mobile Navigation

Configured in app.config.ts:

mobileNav: {
  items: [
    {
      id: 'tasks',
      labelKey: 'common.mobileNav.tasks',
      href: '/dashboard/tasks',
      icon: 'CheckSquare',
      enabled: true,
    }
  ]
}

Customization

Add Custom Fields

// entities/tasks/tasks.fields.ts
{
  name: 'due_date',
  type: 'date',
  label: 'Due Date',
  required: false,
  sortable: true
}

Change Permissions

// entities/tasks/tasks.config.ts
permissions: {
  read: ['admin', 'colaborator', 'member'],
  create: ['admin', 'colaborator'],        // Only admin and colaborator
  update: ['admin', 'colaborator'],
  delete: ['admin']                        // Only admin
}

Disable API Access

access: {
  public: false,
  api: false,       // Disable API access
  metadata: true,
  shared: false
}

Next Steps

• Entity System - Complete entity documentation
• API System - API reference
• Permissions - Permission system