README

A lightweight control panel companion that follows editors through their session. Puppy displays a draggable, collapsible overlay with a live trail of visited pages, edited elements, and quick links back to recently worked-on locations.

Requirements

Craft CMS 5.0 or later
PHP 8.2 or later

Installation

Open your terminal and run:

composer require justinholtweb/craft-puppy
php craft plugin/install puppy

Or install via the Craft control panel under Settings > Plugins.

Features

Session Trail

Puppy records where you go in the control panel and normalizes routes into readable labels:

/admin/dashboard → Dashboard
/admin/entries/blog → Entries: Blog
/admin/entries/blog/123-spring-launch → Spring Launch
/admin/assets/images → Assets: Images
/admin/globals/footerSettings → Global: Footer Settings

Edit Tracking

Puppy listens for element save events on the backend and records them separately from page visits. Each edit captures the element type, title, action (saved or created), and section/volume context.

Floating Panel

The overlay sits on top of the control panel and includes:

Trail tab — the last 25 pages visited, with clickable links back
Edits tab — elements you saved or created during the session
Stats tab — pages visited, items edited, and session duration

Collapse and Drag

Collapse to a small badge showing the paw icon and item count
Drag the panel anywhere on screen
Position and state are remembered across page loads via localStorage

Pause and Clear

Pause tracking at any time without hiding the panel
Clear the session trail to start fresh

How It Works

Frontend: A JavaScript module loads on every CP page. It detects the current route, normalizes it into a human-readable label, and sends it to the plugin backend. The panel polls for updates every 10 seconds to pick up backend-recorded edits.

Backend: The plugin stores trail and edit data in the PHP session. Element save events are captured via Craft's Element::EVENT_AFTER_SAVE and recorded automatically. No database tables are created.

Storage

All data is stored in the PHP session and disappears when the session ends. UI preferences (panel position, collapsed state, active tab, paused state) are stored in the browser's localStorage.

Configuration

Puppy works out of the box with no configuration. Install and go.

Plugin Structure

src/
├── Plugin.php                          # Registers asset bundle and event listeners
├── assetbundles/puppy/PuppyAsset.php   # Injects JS and CSS into the CP
├── controllers/SessionController.php   # Endpoints: get-trail, record-visit, clear
├── models/TrailItem.php                # Data model for trail and edit items
├── services/Trail.php                  # Session-based trail storage and normalization
└── resources/
    ├── js/puppy.js                     # Floating panel, drag, tabs, route parsing
    └── css/puppy.css                   # Panel styles

Roadmap

Phase 2:

Pin favorite items during a session
Search within the session trail
Filter by viewed vs. edited
Auto-group related pages

Phase 3:

Team mode for admins to see active editors
Handoff mode for sharing what you worked on
Optional daily activity digest

License

See LICENSE.md.

justinholtweb / craft-puppy

Maintainers

Package info

Statistics

Security