WordPress Product Roadmap Pro - Developer Guide

Table of Contents

• Pro Architecture
• Pro Hooks Reference
• Pro REST API Extensions
• Pro JavaScript API
• Pro Database Extensions
• Pro Template System
• Pro Features Integration
• Pro Code Examples

Pro Architecture

Pro Addon Structure

roadmap-pro-addon/
├── includes/
│   ├── class-roadmap-pro-analytics.php      # Analytics engine
│   ├── class-roadmap-pro-api.php           # REST API endpoints
│   ├── class-roadmap-pro-export.php        # Import/Export functionality
│   ├── class-roadmap-pro-filters.php       # Advanced filtering
│   ├── class-roadmap-pro-license.php       # License management
│   ├── class-roadmap-pro-products.php      # Multi-product support
│   ├── class-roadmap-pro-settings.php      # Pro settings integration
│   ├── class-roadmap-pro-templates.php     # Pro templates & frontend tabs
│   └── class-roadmap-pro-timeline.php      # Timeline view
├── assets/
│   ├── js/
│   │   ├── admin.js                       # All admin JS (analytics, settings, templates)
│   │   ├── admin.min.js                   # Minified admin JS
│   │   ├── timeline.js                    # Timeline view functionality
│   │   ├── timeline.min.js                # Minified timeline JS
│   │   ├── roadmap-pro.js                 # Frontend drag-drop & export
│   │   └── roadmap-pro.min.js             # Minified frontend JS
│   └── css/
│       ├── admin.css                      # All admin styles (analytics, settings, license)
│       ├── admin.min.css                  # Minified admin CSS
│       ├── admin-rtl.css                  # RTL version of admin styles
│       ├── admin-rtl.min.css              # Minified RTL admin CSS
│       ├── roadmap-pro.css                # Frontend pro styles
│       └── roadmap-pro.min.css            # Minified frontend CSS
├── build.sh                                # Build script for minification
└── roadmap-pro-addon.php                  # Main addon file

Asset Loading Architecture

All admin styles and scripts are consolidated into single files for performance:

Admin CSS (assets/css/admin.css)

• Analytics dashboard styles
• Settings page styles
• Import/Export interface
• License management UI
• Template controls
• Loaded via wp_enqueue_style('roadmap-pro-admin')

Admin RTL CSS (assets/css/admin-rtl.css)

• RTL overrides for right-to-left languages
• Loaded conditionally with is_rtl() check
• Depends on main admin.css
• Loaded via wp_enqueue_style('roadmap-pro-admin-rtl')

Admin JavaScript (assets/js/admin.js)

• Analytics data loading and charts (Chart.js integration)
• Settings page interactions (tabs, cache clearing)
• Template analytics tab functionality
• All strings use wp_localize_script() for translation
• Loaded via wp_enqueue_script('roadmap-pro-admin')

Translation-Ready Implementation

All JavaScript strings are localized using wp_localize_script():

wp_localize_script('roadmap-pro-admin', 'roadmapProAnalytics', [
    'nonce' => wp_create_nonce('wp_rest'),
    'popularItemsUrl' => rest_url('roadmap/v1/analytics/popular-items'),
    'recentActivityUrl' => rest_url('roadmap/v1/analytics/recent-activity'),
    'chartsUrl' => rest_url('roadmap/v1/analytics/charts'),
    'exportUrl' => admin_url('admin.php?page=roadmap-analytics&export=csv'),
    'i18n' => [
        'item' => __('Item', 'roadmap-pro-addon'),
        'votes' => __('Votes', 'roadmap-pro-addon'),
        'comments' => __('Comments', 'roadmap-pro-addon'),
        'activity' => __('Activity', 'roadmap-pro-addon'),
        'date' => __('Date', 'roadmap-pro-addon'),
        'itemHash' => __('Item #', 'roadmap-pro-addon'),
        'noData' => __('No data available', 'roadmap-pro-addon'),
        'noRecentActivity' => __('No recent activity', 'roadmap-pro-addon')
    ]
]);

Build Process

The build process handles:

1. RTL CSS generation using rtlcss
2. CSS minification using cssnano
3. JavaScript minification using terser
4. Separate processing for admin and frontend assets

Run with: ./build.sh or npm run build

Pro Hooks Reference

Pro Action Hooks

Template Hooks

roadmap_pro_before_timeline

do_action('roadmap_pro_before_timeline', $items, $atts);

Fired before timeline template renders.

roadmap_pro_after_timeline

do_action('roadmap_pro_after_timeline', $items, $atts);

Fired after timeline template renders.

roadmap_pro_timeline_item

do_action('roadmap_pro_timeline_item', $item, $position);

Fired for each timeline item.

Analytics Hooks

roadmap_pro_analytics_calculated

do_action('roadmap_pro_analytics_calculated', $metrics, $period);

Fired after analytics calculation.

roadmap_pro_analytics_export

do_action('roadmap_pro_analytics_export', $data, $format);

Fired during analytics export.

Import/Export Hooks

roadmap_pro_before_import

do_action('roadmap_pro_before_import', $data, $options);

Fired before data import.

roadmap_pro_after_import

do_action('roadmap_pro_after_import', $imported_items, $results);

Fired after data import.

roadmap_pro_export_row

do_action('roadmap_pro_export_row', $row_data, $item);

Modify export data per row.

Drag & Drop Hooks

roadmap_pro_item_moved

do_action('roadmap_pro_item_moved', $item_id, $old_status, $new_status);

Fired when item is moved via drag & drop.

roadmap_pro_before_reorder

do_action('roadmap_pro_before_reorder', $items, $new_order);

Fired before items are reordered.

Pro Filter Hooks

Template Filters

roadmap_pro_templates

$templates = apply_filters('roadmap_pro_templates', $templates);

Register custom pro templates.

roadmap_pro_timeline_periods

$periods = apply_filters('roadmap_pro_timeline_periods', $periods);

Modify timeline period options.

roadmap_pro_timeline_item_data

$item_data = apply_filters('roadmap_pro_timeline_item_data', $item_data, $item);

Filter timeline item data.

Analytics Filters

roadmap_pro_analytics_metrics

$metrics = apply_filters('roadmap_pro_analytics_metrics', $metrics);

Add custom analytics metrics.

roadmap_pro_analytics_charts

$charts = apply_filters('roadmap_pro_analytics_charts', $charts);

Register custom chart types.

roadmap_pro_analytics_date_ranges

$ranges = apply_filters('roadmap_pro_analytics_date_ranges', $ranges);

Add custom date range options.

Product Filters

roadmap_pro_product_capabilities

$caps = apply_filters('roadmap_pro_product_capabilities', $caps, $product);

Filter product-specific capabilities.

roadmap_pro_product_settings

$settings = apply_filters('roadmap_pro_product_settings', $settings, $product_id);

Filter product-specific settings.

Pro REST API Extensions

All endpoints use the namespace roadmap/v1 and require appropriate WordPress authentication/nonces.

Analytics Endpoints

Get Analytics Overview

GET /wp-json/roadmap/v1/analytics/overview

Returns total items, votes, comments, active users, popular items, and recent activity.

Response:

{
  "total_items": 45,
  "total_votes": 432,
  "total_comments": 89,
  "active_users": 127,
  "popular_items": [...],
  "recent_activity": [...]
}

Get Analytics Trends

GET /wp-json/roadmap/v1/analytics/trends

Parameters:

• period: Time period (7days, 30days, 90days, 1year)

Response:

{
  "votes_over_time": [...],
  "comments_over_time": [...],
  "items_by_status": [...],
  "items_by_category": [...]
}

Get Popular Items

GET /wp-json/roadmap/v1/analytics/popular-items

Parameters:

• product: Product filter (term ID)
• period: Time period (7days, 30days, 90days, year)

Get Recent Activity

GET /wp-json/roadmap/v1/analytics/recent-activity

Parameters:

• product: Product filter (term ID)
• period: Time period (7days, 30days, 90days, year)

Get Charts Data

GET /wp-json/roadmap/v1/analytics/charts

Returns data formatted for Chart.js: status distribution (doughnut) and votes over time (line).

Timeline Endpoints

Get Timeline Data

GET /wp-json/roadmap/v1/timeline

Parameters:

• product: Product slug
• start_date: Start date (YYYY-MM-DD)
• end_date: End date (YYYY-MM-DD)

Response:

[
  {
    "id": 123,
    "title": "New Feature",
    "start_date": "2024-01-15",
    "end_date": "2024-03-30",
    "progress": 65,
    "status": "in-progress",
    "assignee": {
      "id": 5,
      "name": "John Doe",
      "avatar": "https://..."
    },
    "dependencies": [45, 67]
  }
]

Drag & Drop Endpoint

Reorder Items

POST /wp-json/roadmap/v1/items/reorder

Body:

{
  "item_id": 123,
  "new_status": "in-progress",
  "new_position": 2
}

Permission: Requires edit_posts capability

Filter Presets Endpoints

Get Filter Presets

GET /wp-json/roadmap/v1/filter-presets

Returns user's saved filter configurations.

Save Filter Preset

POST /wp-json/roadmap/v1/filter-presets

Body:

{
  "name": "High Priority Features",
  "filters": {
    "priority": "high",
    "category": "feature",
    "status": "planned"
  }
}

Delete Filter Preset

DELETE /wp-json/roadmap/v1/filter-presets/{id}

Export Endpoint

Export Items

GET /wp-json/roadmap/v1/export

Parameters:

• format: Export format (csv, pdf)
• product: Product slug filter
• status: Status slug filter
• date_from: Start date filter
• date_to: End date filter

Returns CSV download with columns: ID, Title, Description, Status, Category, Priority, Target Date, Votes, Comments, Progress, Assignee.

Product Management

List Products

GET /wp-json/roadmap/v1/products

Returns all products with metadata.

Get Single Product

GET /wp-json/roadmap/v1/products/{id}

Returns product details including item count.

Pro JavaScript API

Timeline API

// Initialize timeline
const timeline = new RoadmapTimeline({
  container: '#roadmap-timeline',
  view: 'quarter', // quarter, month, year
  startDate: '2024-01-01',
  endDate: '2024-12-31',
  onItemClick: (item) => {
    console.log('Timeline item clicked:', item);
  }
});

// Update timeline view
timeline.setView('month');

// Add item to timeline
timeline.addItem({
  id: 123,
  title: 'New Feature',
  start: '2024-03-01',
  end: '2024-04-15',
  status: 'planned'
});

Drag & Drop API

// Initialize drag & drop
const dragDrop = new RoadmapDragDrop({
  container: '.roadmap-board',
  onDrop: async (item, newStatus) => {
    const response = await fetch('/wp-json/roadmap-pro/v1/move', {
      method: 'POST',
      headers: {
        'X-WP-Nonce': roadmapPro.nonce,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        item_id: item.id,
        status: newStatus
      })
    });
    return response.json();
  }
});

// Enable/disable drag & drop
dragDrop.enable();
dragDrop.disable();

Analytics API

// Initialize analytics chart
const chart = new RoadmapChart({
  container: '#analytics-chart',
  type: 'line', // line, bar, pie
  metric: 'votes',
  period: 'month'
});

// Update chart data
chart.update({
  metric: 'progress',
  period: 'week'
});

// Export chart
chart.export('png');

Pro Database Extensions

Additional Tables

wp_roadmap_products

CREATE TABLE wp_roadmap_products (
  id bigint(20) NOT NULL AUTO_INCREMENT,
  name varchar(255) NOT NULL,
  slug varchar(255) NOT NULL,
  description text,
  settings longtext,
  created_at datetime DEFAULT CURRENT_TIMESTAMP,
  updated_at datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  UNIQUE KEY slug (slug)
);

wp_roadmap_analytics

CREATE TABLE wp_roadmap_analytics (
  id bigint(20) NOT NULL AUTO_INCREMENT,
  metric_type varchar(50) NOT NULL,
  metric_value float NOT NULL,
  item_id bigint(20),
  product_id bigint(20),
  date date NOT NULL,
  metadata longtext,
  PRIMARY KEY (id),
  KEY metric_date (metric_type, date),
  KEY item_id (item_id),
  KEY product_id (product_id)
);

Pro Meta Keys

• _roadmap_product_id: Associated product ID
• _roadmap_timeline_start: Timeline start date
• _roadmap_timeline_end: Timeline end date
• _roadmap_dependencies: Item dependencies (JSON)
• _roadmap_custom_fields: Additional custom fields (JSON)
• _roadmap_assignees: Multiple assignees (JSON)
• _roadmap_milestone: Milestone marker
• _roadmap_effort_estimate: Effort estimation value

Pro Template System

Creating Custom Pro Templates

// Register custom template
add_filter('roadmap_pro_templates', function($templates) {
  $templates['gantt'] = array(
    'label' => 'Gantt Chart',
    'file' => plugin_dir_path(__FILE__) . 'templates/gantt.php',
    'scripts' => array('gantt-lib', 'custom-gantt'),
    'styles' => array('gantt-styles'),
    'supports' => array('timeline', 'dependencies', 'milestones')
  );
  return $templates;
});

Template Data Structure

// Available in pro templates
$template_data = array(
  'items' => $roadmap_items,
  'grouped_items' => $items_by_status,
  'timeline_data' => array(
    'start' => $timeline_start,
    'end' => $timeline_end,
    'periods' => $timeline_periods
  ),
  'filters' => $active_filters,
  'product' => $current_product,
  'settings' => $pro_settings
);

Timeline Template Customization

// Modify timeline periods
add_filter('roadmap_pro_timeline_periods', function($periods) {
  $periods['sprint'] = array(
    'label' => '2-Week Sprints',
    'duration' => 14, // days
    'format' => 'Sprint %d'
  );
  return $periods;
});

Pro Features Integration

Multi-Product Implementation

// Get product-specific items
function get_product_roadmap_items($product_slug) {
  $args = array(
    'post_type' => 'roadmap_item',
    'meta_query' => array(
      array(
        'key' => '_roadmap_product_id',
        'value' => get_product_id_by_slug($product_slug),
        'compare' => '='
      )
    )
  );
  return new WP_Query($args);
}

// Switch product context
add_action('init', function() {
  if (isset($_GET['roadmap_product'])) {
    $product = sanitize_text_field($_GET['roadmap_product']);
    apply_filters('roadmap_current_product', $product);
  }
});

Advanced Permissions

// Product-specific capabilities
add_filter('roadmap_pro_product_capabilities', function($caps, $product) {
  if ($product->slug === 'internal') {
    $caps['view'] = 'manage_options'; // Admin only
  }
  return $caps;
}, 10, 2);

// Role-based template access
add_filter('roadmap_pro_template_access', function($allowed, $template, $user) {
  if ($template === 'analytics' && !user_can($user, 'view_roadmap_analytics')) {
    return false;
  }
  return $allowed;
}, 10, 3);

Analytics Integration

// Track custom metric
function track_roadmap_metric($type, $value, $item_id = null) {
  global $wpdb;
  
  $wpdb->insert(
    $wpdb->prefix . 'roadmap_analytics',
    array(
      'metric_type' => $type,
      'metric_value' => $value,
      'item_id' => $item_id,
      'date' => current_time('mysql')
    )
  );
}

// Custom analytics metric
add_filter('roadmap_pro_analytics_metrics', function($metrics) {
  $metrics['custom_engagement'] = array(
    'label' => 'Custom Engagement Score',
    'calculate' => 'calculate_custom_engagement',
    'chart_type' => 'line',
    'color' => '#ff6384'
  );
  return $metrics;
});

Pro Code Examples

Custom Timeline View

// Create custom timeline visualization
class Custom_Timeline_Renderer {
  public function render($items, $settings) {
    $timeline_data = $this->prepare_timeline_data($items);
    
    ob_start();
    ?>
    <div class="custom-timeline">
      <?php foreach ($timeline_data as $period => $period_items): ?>
        <div class="timeline-period" data-period="<?php echo esc_attr($period); ?>">
          <h3><?php echo esc_html($this->format_period($period)); ?></h3>
          <div class="timeline-items">
            <?php foreach ($period_items as $item): ?>
              <?php $this->render_timeline_item($item); ?>
            <?php endforeach; ?>
          </div>
        </div>
      <?php endforeach; ?>
    </div>
    <?php
    return ob_get_clean();
  }
  
  private function prepare_timeline_data($items) {
    // Group items by period
    $grouped = array();
    foreach ($items as $item) {
      $period = $this->get_item_period($item);
      $grouped[$period][] = $item;
    }
    return $grouped;
  }
}

Export Handler

// Custom export format
add_filter('roadmap_pro_export_formats', function($formats) {
  $formats['jira'] = array(
    'label' => 'Jira CSV',
    'handler' => 'export_to_jira_format',
    'mime_type' => 'text/csv',
    'extension' => 'csv'
  );
  return $formats;
});

function export_to_jira_format($items) {
  $csv = array();
  $csv[] = array('Summary', 'Description', 'Issue Type', 'Priority', 'Labels');
  
  foreach ($items as $item) {
    $csv[] = array(
      $item->post_title,
      strip_tags($item->post_content),
      'Story',
      get_post_meta($item->ID, '_roadmap_priority', true),
      implode(',', wp_get_post_terms($item->ID, 'roadmap_category', array('fields' => 'names')))
    );
  }
  
  return generate_csv($csv);
}

Analytics Dashboard Widget

// Add custom analytics widget
add_action('roadmap_pro_analytics_widgets', function() {
  ?>
  <div class="analytics-widget" id="velocity-chart">
    <h3>Development Velocity</h3>
    <canvas id="velocity-canvas"></canvas>
    <script>
      jQuery(document).ready(function($) {
        const ctx = document.getElementById('velocity-canvas').getContext('2d');
        
        // Fetch velocity data
        $.get(roadmapPro.api_url + '/analytics', {
          metric: 'velocity',
          period: 'sprint'
        }, function(data) {
          new Chart(ctx, {
            type: 'line',
            data: {
              labels: data.labels,
              datasets: [{
                label: 'Items Completed',
                data: data.values,
                borderColor: '#4caf50',
                tension: 0.1
              }]
            }
          });
        });
      });
    </script>
  </div>
  <?php
});

Webhook Integration

// Send webhook on status change
add_action('roadmap_pro_item_moved', function($item_id, $old_status, $new_status) {
  $webhooks = get_option('roadmap_pro_webhooks', array());
  
  foreach ($webhooks as $webhook) {
    if (in_array('status_change', $webhook['events'])) {
      wp_remote_post($webhook['url'], array(
        'body' => json_encode(array(
          'event' => 'roadmap.item.status_changed',
          'item_id' => $item_id,
          'old_status' => $old_status,
          'new_status' => $new_status,
          'timestamp' => time()
        )),
        'headers' => array(
          'Content-Type' => 'application/json',
          'X-Roadmap-Signature' => generate_webhook_signature($webhook['secret'])
        )
      ));
    }
  }
}, 10, 3);

Best Practices

Performance Optimization

1. Cache analytics calculations
2. Lazy load timeline items
3. Implement pagination for large datasets
4. Use database indexes effectively

Security Considerations

1. Validate all product slugs
2. Check permissions per product
3. Sanitize import data thoroughly
4. Escape all template output

Code Organization

1. Separate pro features into modules
2. Use dependency injection
3. Follow WordPress coding standards
4. Document pro-specific functions

Support

For pro developer support:

1. Priority support tickets
2. Developer documentation portal
3. Code examples repository
4. Direct developer contact

Remember to test all customizations with both free and pro versions to ensure compatibility.

Updated on: 25/09/2025