# Content Management System (CMS) Module Usage Instructions

> The `feat/admin-sub/content-management` branch introduces a fully functional Page Management module. Built upon the secure `feat/admin` and `base` branches, it empowers administrators to dynamically create and manage custom pages (e.g., About Us, Privacy Policy, Terms of Service) with rich text support and SEO management.

---

## Table of Contents

1. [Module Overview](#1-module-overview)
2. [What You Inherit](#2-what-you-inherit)
3. [Deep Dive: Features & Functionality](#3-deep-dive-features--functionality)
4. [File Paths & Architecture](#4-file-paths--architecture)
5. [Step-by-Step Usage Guide](#5-step-by-step-usage-guide)

---

## 1. Module Overview

This branch establishes the CMS Pages section within the Admin Portal. It provides administrators the capability to create, read, update, delete, and archive standalone application pages. The module includes support for rich HTML content creation, SEO metadata handling, live previews, and soft-deletion tracking.

---

## 2. What You Inherit

By merging with the **Base** and **Admin** branches, this feature inherits:
- **UI Components:** Reusable `<x-common.*>`, `<x-forms.*>`, and `<x-buttons.*>` Blade components, maintaining a consistent aesthetic.
- **Admin Security:** The `auth:admin` middleware ensures only logged-in administrators can access the page management features.
- **Rich Text Tooling:** Usage of the built-in `TinyMceController` for handling direct image uploads via the WYSIWYG editor.
- **AJAX Architecture:** Fast, reload-free interactions powered by Alpine.js and Server-Side Datatables (`<x-common.table-server>`).

---

## 3. Deep Dive: Features & Functionality

This branch brings specialized features for dynamic page management:

- **Complete Page CRUD Operations:** 
  Create, Read, Update, and Delete standalone pages with robust server-side validation.
- **Rich Text Integration:** 
  Integrated TinyMCE editor for comprehensive content formatting and inline media management.
- **Live Page Previews:**
  A dedicated preview layout allows administrators to view a page exactly as it will appear to users without having to publish it.
- **Interactive Status Toggles:**
  Directly toggle page statuses (e.g., Active/Inactive or Published/Draft) right from the data table using interactive Alpine.js dropdowns.
- **Soft Deletion & Archiving:**
  Deleted pages are safely moved to the "Archived" tab. They can be restored or permanently removed from the database.
- **SEO Optimization Support:** 
  Dedicated fields for Meta Title, Meta Description, and Meta Keywords on every page.
- **Table Filters & Searching:** 
  Robust filtering tools to find specific pages quickly within the management table.

---

## 4. File Paths & Architecture

Here are the key files introduced or modified in this branch:

### Controllers & Services (`app/Http/Controllers/Admin/Page/`, `app/Services/Admin/`)
- **`PageController.php`**: The central controller handling data table rendering, CRUD operations, and previews.
- **`PageService.php`**: Encapsulates business logic, including database transactions and status modifications.
- **`PageRequest.php`**: The Form Request handling input validation and messaging.

### Models, Migrations & Factories (`app/Models/`, `database/`)
- **`Page.php`**: The Eloquent model configuring mass assignable fields, soft-delete rules, and mutators.
- **`*_create_pages_table.php`**: Database migration containing standard fields plus SEO columns.
- **`PageFactory.php` & `PageSeeder.php`**: Tools to rapidly seed dummy content for testing purposes.

### Views (`resources/views/pages/admin/cms/`, `resources/views/layouts/`)
- **`index.blade.php`**: The primary view displaying the active pages table.
- **`archived.blade.php`**: The view for managing soft-deleted pages.
- **`form.blade.php`**: The unified form view used for both creating and editing pages.
- **`preview.blade.php` / `layouts/preview.blade.php`**: Templates dedicated to rendering the frontend look of a page.
- **`partials/table.blade.php`**: The server-side table partial handling asynchronous data population.

### JavaScript (`resources/js/admin/`, `resources/js/common/`)
- **`cms-management.js`**: Contains Alpine.js component logic for handling datatables, archiving, and restorations.
- **`cms-form.js`**: Handles specific interactions inside the creation and update form.
- **`table-filter.js`**: Global JS component managing advanced table filtering.

---

## 5. Step-by-Step Usage Guide

### 1. Database Setup
First, ensure your database contains the new `pages` table. Run migrations and (optionally) the seeder:
```bash
php artisan migrate
php artisan db:seed --class=PageSeeder
```

### 2. Accessing the Module
- Log into the Admin Portal (`/behindthescreen`).
- In the sidebar navigation, locate and click on **Pages** under the CMS or Content category.

### 3. Managing Pages
- **Creating a Page:** Click "Add New Page", enter a Title, fill the Content using the rich text editor, set the SEO parameters, and click Save.
- **Status Updates:** From the `index` view, use the status dropdown in the table row to immediately activate or deactivate a page.
- **Previewing:** Click the Preview action (usually an eye icon) on any record to view how the public will see the page layout.
- **Archiving/Deleting:** Use the delete action on a record to move it to the "Archived" tab.
- **Restoring Data:** Navigate to the "Archived" tab to review soft-deleted pages. Select them to restore or permanently remove them from the system.