Client Handoff Toolkit for WordPress

Transform client feedback into action. Your clients click on any website element to leave comments. You manage everything through a beautiful admin dashboard. No more confusing emails or vague "fix the blue thing" requests.

🚀 Quick Start

Installation

Download or clone this repository
Upload to /wp-content/plugins/analogwp-client-handoff
Activate via WordPress Admin → Plugins
Configure settings at Client Handoff → Settings
Build assets: npm install && npm run build

First Steps

For Clients:

Look for the toggle button in the WordPress admin bar
Click it to enable comment mode
Click any element on the page to add feedback
Comments are captured automatically with screenshots

For Administrators:

View all feedback at Client Handoff → Dashboard
Track tasks with status (Open, In Progress, Resolved)
Reply to comments and update priorities
Manage user access and settings

✨ Key Features

Visual Commenting ✅

One-click feedback - Click any element to comment
Automatic screenshots - Context captured with html2canvas
Smart element detection - CSS selectors and position fallback
Reply threads - Full conversation support
User avatars - WordPress Gravatar integration

Task Management ✅

Kanban board - Organize by status (Open, In Progress, Resolved)
Priority levels - High, Medium, Low classification
Category system - Custom categories for organization
Task editing - Update comments and details
Advanced filtering - Search, filter by status/category/priority

Timesheet Tracking ✅

Time logging - Track hours per task
Persistent storage - All time entries saved to database
Time reports - View total hours by task/category
Edit capabilities - Modify or delete time entries

Access Control ✅

Role-based access - Configure which roles can see the plugin
Frontend toggle - Enable/disable comments on frontend
Secure AJAX - Nonce verification on all requests
Permission checks - WordPress capability system

Modern UI/UX ✅

React 18 - Fast, interactive interface
Toast notifications - Real-time feedback with react-toastify
Responsive design - Works on all devices
WordPress integration - Matches admin theme

📖 Usage Guide

Creating Visual Comments

Enable Comment Mode
- Click the toggle button in the WordPress admin bar
- Page overlay appears with instructions
Add a Comment
- Click on any element you want to comment on
- A popup appears asking for your comment
- Type your feedback and click "Save Comment"
- Screenshot is automatically captured
View Comments
- Existing comments appear as numbered markers
- Click any marker to view details and replies
- Add replies or update status (if permitted)

Managing Tasks (Admin)

Dashboard Overview
- Access via Client Handoff → Dashboard
- View statistics: total tasks, open, in progress, resolved
- Filter by status, category, or priority
- Search across all comments
Task Actions
- Edit: Click edit icon to modify task details
- Reply: Add threaded replies with avatars
- Status: Change between Open, In Progress, Resolved
- Delete: Remove tasks (admin only)
- Log Time: Track hours spent on tasks
Timesheet
- Access via Client Handoff → Timesheet
- View all time entries across tasks
- Filter by date range, task, or user
- Export reports (coming soon)

Configuration

Access settings at Client Handoff → Settings:

General Settings

Allowed User Roles: Select which roles can access the plugin
Enable Frontend Comments: Toggle comments app on frontend

Categories & Priorities

Categories: Create custom categories (e.g., Design, Content, Bug)
Priorities: Manage priority levels (High, Medium, Low by default)

🛠️ Technical Details

Architecture & Stack

Frontend

React 18.2.0 - UI framework
WordPress Components - @wordpress/components for consistency
html2canvas - Screenshot capture
react-toastify - Toast notifications
Sass - Styling with CSS variables

Backend

WordPress 6.0+ - Core platform
PHP 7.4+ - Server-side logic
MySQL - Database storage
REST API - AJAX endpoints

Build System

@wordpress/scripts - Build tooling
Webpack 5 - Module bundling
Babel - JavaScript compilation
PostCSS - CSS processing

Database Structure

Comments Table (`wp_agwp_cht_comments`)

```sql CREATE TABLE wp_agwp_cht_comments ( id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT, post_id bigint(20) UNSIGNED NOT NULL, user_id bigint(20) UNSIGNED NOT NULL, comment_text text NOT NULL, element_selector varchar(500) DEFAULT NULL, screenshot_url longtext DEFAULT NULL, x_position int(11) DEFAULT NULL, y_position int(11) DEFAULT NULL, page_url varchar(500) DEFAULT NULL, status varchar(20) DEFAULT 'open', priority varchar(20) DEFAULT 'medium', category varchar(100) DEFAULT NULL, created_at datetime DEFAULT CURRENT_TIMESTAMP, updated_at datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY post_id (post_id), KEY user_id (user_id), KEY status (status), KEY priority (priority), KEY category (category) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; ```

Replies Table (`wp_agwp_cht_comment_replies`)

```sql CREATE TABLE wp_agwp_cht_comment_replies ( id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT, comment_id bigint(20) UNSIGNED NOT NULL, user_id bigint(20) UNSIGNED NOT NULL, reply_text text NOT NULL, created_at datetime DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY comment_id (comment_id), KEY user_id (user_id), FOREIGN KEY (comment_id) REFERENCES wp_agwp_cht_comments(id) ON DELETE CASCADE ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; ```

Timesheet Table (`wp_agwp_cht_timesheet`)

```sql CREATE TABLE wp_agwp_cht_timesheet ( id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT, comment_id bigint(20) UNSIGNED NOT NULL, user_id bigint(20) UNSIGNED NOT NULL, hours decimal(10,2) NOT NULL, description text DEFAULT NULL, logged_at datetime DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY comment_id (comment_id), KEY user_id (user_id), FOREIGN KEY (comment_id) REFERENCES wp_agwp_cht_comments(id) ON DELETE CASCADE ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; ```

Component Structure

``` src/ ├── frontend/ │ ├── components/ │ │ ├── VisualCommentsApp.js │ │ ├── CommentToggle.js │ │ ├── CommentOverlay.js │ │ ├── CommentPopup.js │ │ ├── CommentsDisplay.js │ │ └── CommentMarker.js │ ├── styles/ │ │ └── frontend.scss │ └── frontend.js │ ├── admin/ │ ├── components/ │ │ ├── Dashboard.js │ │ ├── TaskBoard.js │ │ ├── TaskCard.js │ │ ├── TaskDetail.js │ │ ├── Timesheet.js │ │ ├── Settings.js │ │ └── settings/ │ │ ├── │ │ ├── │ │ └── │ ├── styles/ │ │ └── admin.scss │ └── admin.js │ └── shared/ └── utils/ ``` # Main app container # Toggle button # Instruction overlay # New comment form # Comments manager # Individual markers # Frontend styles # Entry point # Main dashboard # Kanban board # Individual tasks # Task detail view # Timesheet view # Settings page AccessControlSettings.js CategorySettings.js PrioritySettings.js # Admin styles # Entry point # Shared utilities

Security Features

Implemented Protections

✅ Nonce Verification - All AJAX requests protected with WordPress nonces
✅ User Capability Checks - Role-based access control via `user_has_access()`
✅ Data Sanitization - All inputs cleaned with `sanitize_text_field()` and `wp_kses_post()`
✅ SQL Injection Prevention - Prepared statements via `$wpdb->prepare()`
✅ XSS Protection - Output escaping with `esc_html()`, `esc_url()`, `esc_attr()`
✅ CSRF Protection - WordPress nonces on all forms and AJAX calls

Permission System

```php // Helper method in main plugin class public static function user_has_access() { if ( ! is_user_logged_in() ) { return false; }

if ( current_user_can( 'manage_options' ) ) {
    return true; // Admin always has access
}

$settings = get_option( 'agwp_cht_settings', array() );
$allowed_roles = $settings['general']['allowed_roles'] ?? array();

$user = wp_get_current_user();
return ! empty( array_intersect( $allowed_roles, $user->roles ) );

} ```

Browser Compatibility

Browser	Version	Status
Chrome	80+	✅ Full Support
Firefox	75+	✅ Full Support
Safari	13+	✅ Full Support
Edge	80+	✅ Full Support
Mobile Safari	iOS 13+	✅ Full Support
Chrome Mobile	Android 8+	✅ Full Support

🔧 Development

Prerequisites

Node.js 14+
npm or yarn
WordPress development environment

Setup

Clone the repository ```bash git clone https://github.com/analogwp/analogwp-client-handoff.git cd analogwp-client-handoff ```
Install dependencies ```bash npm install ```
Start development ```bash npm run start ``` This will:
- Watch for file changes
- Auto-compile SCSS to CSS
- Bundle JavaScript with hot reload
Build for production ```bash npm run build ```

Available Commands

`npm run start` - Start development server with watch mode
`npm run build` - Build optimized production assets
`npm run format` - Format code with Prettier
`npm run lint:css` - Lint SCSS files
`npm run lint:js` - Lint JavaScript files
`npm run packages-update` - Update WordPress packages

File Structure

Key PHP Files:

`analogwp-client-handoff.php` - Main plugin file with hooks and helper methods
`includes/class-database.php` - Database operations
`includes/class-assets.php` - Asset enqueuing
`includes/ajax/class-ajax.php` - AJAX endpoint handlers
`includes/admin/class-admin.php` - Admin menu and pages

React Entry Points:

`src/frontend.js` - Frontend commenting app
`src/admin.js` - Admin dashboard and settings

Styles:

`src/frontend/styles/frontend.scss` - Frontend styles
`src/admin/styles/admin.scss` - Admin dashboard styles

Customization

Custom Color Scheme: ```scss // In your theme or child theme :root { --agwp-cht-primary: #your-brand-color; --agwp-cht-danger: #your-error-color; --agwp-cht-success: #your-success-color; } ```

Extend Functionality: ```php // Add custom comment meta add_filter( 'agwp_cht_comment_data', function( $data ) { $data['custom_field'] = 'custom_value'; return $data; } );

// Modify allowed roles programmatically add_filter( 'agwp_cht_allowed_roles', function( $roles ) { $roles[] = 'shop_manager'; return $roles; } ); ```

🚨 Troubleshooting

Comments Not Saving

Possible Causes:

User doesn't have proper permissions
WordPress nonces expired
Database tables missing

Solutions:

Check user has access via Settings → Allowed User Roles
Refresh the page to regenerate nonces
Deactivate and reactivate plugin to create tables
Check WordPress debug log for errors

Screenshots Not Capturing

Possible Causes:

html2canvas library not loaded
CORS issues with external resources
Browser doesn't support canvas API

Solutions:

Check browser console for JavaScript errors
Ensure all images have proper CORS headers
Try on a different browser
Disable browser extensions that might interfere

Toggle Button Missing

Possible Causes:

User not logged in
User doesn't have access permissions
Admin bar disabled
Frontend comments disabled in settings

Solutions:

Confirm user is logged in to WordPress
Check Settings → Allowed User Roles includes user's role
Enable WordPress admin bar in user profile
Enable Settings → Enable Frontend Comments
Clear browser and WordPress caches

Permission Errors in Admin

Error: "You do not have sufficient permissions to access this page"

Solutions:

Ensure user role is in Settings → Allowed User Roles
Clear WordPress object cache
Check if `user_has_access()` method is working: ```php // Add to functions.php temporarily add_action( 'admin_init', function() { if ( class_exists( 'AGWP_CHT_Client_Handoff_Toolkit' ) ) { var_dump( AGWP_CHT_Client_Handoff_Toolkit::user_has_access() ); } } ); ```

Debug Mode

Enable WordPress debug mode for detailed error logging:

```php // In wp-config.php define( 'WP_DEBUG', true ); define( 'WP_DEBUG_LOG', true ); define( 'WP_DEBUG_DISPLAY', false ); define( 'SCRIPT_DEBUG', true ); ```

Check debug log at `wp-content/debug.log`

📈 Roadmap

Version 1.1.0 ✅ CURRENT

✅ Task editing functionality
✅ Persistent timesheet tracking
✅ Modern toast notifications
✅ Enhanced UI/UX improvements
✅ Access control system
✅ User avatars in replies

Version 1.2 🔜 NEXT

⏳ Email notifications for new comments and status changes
⏳ Enhanced mobile interface with touch optimizations
⏳ CSV/PDF export for timesheet reports
⏳ Advanced filtering with saved filter presets
⏳ Bulk actions for task management
⏳ Custom fields for tasks
🎨 Custom branding options

Version 1.3 📅 PLANNED

⏳ Advanced analytics dashboard with charts
⏳ Custom branding options
⏳ REST API endpoints for third-party integrations
⏳ Progressive Web App (PWA) features
⏳ Multi-language support (WPML/Polylang)

Future Ideas 🔮

⏳ Cloud storage for screenshots (AWS S3, Google Cloud)
⏳ AI-powered resolutions
⏳ Native mobile app companion
⏳ Real-time collaboration with WebSocket
⏳ Project templates and workflows

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch: `git checkout -b feature/amazing-feature`
Make your changes with proper testing
Commit with descriptive messages: `git commit -m 'Add amazing feature'`
Push to your branch: `git push origin feature/amazing-feature`
Open a Pull Request with detailed description

Development Guidelines

Follow WordPress Coding Standards
Write descriptive commit messages
Add code comments for complex functionality
Test across multiple browsers and WordPress versions
Update documentation as needed
Include screenshots for UI changes

📄 License

This project is licensed under the GNU General Public License v2.0 or later.

You are free to use, modify, and distribute this plugin under the terms of the GPL. See the LICENSE file for full details.

🆘 Support

Get Help

📖 Documentation: This README and inline code comments
🐛 Bug Reports: Open an issue with reproduction steps
💡 Feature Requests: Suggest improvements via GitHub issues
💬 Discussions: Join conversations in the issues section

Professional Support

For priority support, custom development, or consulting services, contact the development team.

Built with ❤️ for WordPress agencies, developers, and their clients.

Making website feedback as simple as point and click.

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
assets/images		assets/images
includes		includes
src		src
.distignore		.distignore
.gitignore		.gitignore
BUILD_QUICK_REF.md		BUILD_QUICK_REF.md
BUILD_SCRIPTS_GUIDE.md		BUILD_SCRIPTS_GUIDE.md
README.md		README.md
WPORG_SOURCE_FILES.md		WPORG_SOURCE_FILES.md
analogwp-client-handoff.php		analogwp-client-handoff.php
build-package.sh		build-package.sh
build-wporg.sh		build-wporg.sh
package.json		package.json
postcss.config.js		postcss.config.js
readme.txt		readme.txt
tailwind.config.js		tailwind.config.js
uninstall.php		uninstall.php
webpack.config.js		webpack.config.js

analogwp/analogwp-client-handoff

Folders and files

Latest commit

History

Repository files navigation

Client Handoff Toolkit for WordPress

🚀 Quick Start

Installation

First Steps

✨ Key Features

Visual Commenting ✅

Task Management ✅

Timesheet Tracking ✅

Access Control ✅

Modern UI/UX ✅

📖 Usage Guide

Creating Visual Comments

Managing Tasks (Admin)

Configuration

General Settings

Categories & Priorities

🛠️ Technical Details

Frontend

Backend

Build System

Comments Table (`wp_agwp_cht_comments`)

Replies Table (`wp_agwp_cht_comment_replies`)

Timesheet Table (`wp_agwp_cht_timesheet`)

Implemented Protections

Permission System

🔧 Development

Prerequisites

Setup

Available Commands

File Structure

Customization

🚨 Troubleshooting

📈 Roadmap

Version 1.1.0 ✅ CURRENT

Version 1.2 🔜 NEXT

Version 1.3 📅 PLANNED

Future Ideas 🔮

🤝 Contributing

Development Guidelines

📄 License

🆘 Support

Get Help

Professional Support

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Languages