Plotly Chart Editor Laravel Package

Getting Started

1. Installation:

   composer require uneca/plotly-chart-editor
   

   Load Plotly.js (via CDN or npm) and include these Blade directives in your layout:

   @plotlyChartEditorStyles
   @plotlyChartEditorScripts
   @livewireStyles
   @livewireScripts
   

2. First Use Case: Embed the editor in a Blade view with minimal props:

   <livewire:plotly-editor
       :data-sources="$rawDataset"
       :trace-types="['bar', 'line']"
   />
   

   Where $rawDataset is an associative array of column names and values (e.g., ['Country' => ['Ghana', 'Kenya'], 'Population' => [34, 55]]).

3. Quick Preview: Wrap the component in a flex container for full-page layout:

   <div class="h-screen flex flex-col">
       <livewire:plotly-editor :data-sources="$rawDataset" />
   </div>
   

Implementation Patterns

1. Data Flow

• Server → Client: Pass raw data (dataSources), initial traces (data), and layout (layout) as props.

• Client → Server: Use sync-mode to control when changes are sent:

  • manual: Requires user click on "Save" (default).
  • auto: Debounced sync (~500ms) after mutations.
  • hybrid: Auto-sync + explicit "Save" button.

  Example with hybrid mode:

  <livewire:plotly-editor
      :data-sources="$rawDataset"
      :sync-mode="'hybrid'"
      @chart-synced="saveChart"
  />
  

2. Persisting Changes

Option A: Livewire Wrapping (Recommended for Laravel Apps) Wrap the editor in a parent Livewire component to handle persistence:

// ParentComponent.php
#[On('chart-synced')]
public function saveChart(array $data, array $layout): void {
    $this->chart->update(['traces' => $data, 'layout' => $layout]);
}

<livewire:parent-component :chart="$chart" />

Option B: Event Listeners Listen to the ChartSynced Laravel event:

// EventServiceProvider.php
protected $listen = [
    \Uneca\PlotlyChartEditor\Events\ChartSynced::class => [
        \App\Listeners\SaveChart::class,
    ],
];

3. Dynamic Trace Types

Enable/disable trace types via the trace-types prop:

<livewire:plotly-editor
    :trace-types="['scatter', 'bar', 'pie']"
    :preload-schema="true"  <!-- Loads schema for all enabled types -->
/>

4. Theming

Override default styles by publishing assets:

php artisan vendor:publish --tag="plotly-chart-editor-assets"

Modify resources/css/plotly-chart-editor.css to adjust --plotly-editor-* theme variables.

5. Validation

Validate incoming chart data in controllers:

use Uneca\PlotlyChartEditor\Rules\ValidChartConfig;

$request->validate([
    'chart' => ['required', new ValidChartConfig],
]);

Gotchas and Tips

Pitfalls

1. Data Mismatch Warnings:

   • If dataSources columns have unequal lengths, the editor shows a non-blocking warning. Ensure all columns are the same length.

2. Plotly.js Dependency:

   • The package does not bundle Plotly.js. You must load it via CDN or npm before the package scripts:

     <script src="https://cdn.plot.ly/plotly-3.5.0.min.js"></script>
     

3. Sync Mode Confusion:

   • auto mode syncs debounced changes but hides the "Save" button. Use hybrid if you need both auto-sync and explicit saves.

4. Alpine Store Direct Access:

   • Avoid directly modifying Alpine.store('chartBuilder') outside the component’s methods. Use the provided store methods (e.g., addTrace()).

5. Trace Type Profiles:

   • Custom trace types require publishing the config:

     php artisan vendor:publish --tag="plotly-chart-editor-config"
     

   • Edit config/plotly-chart-editor.php to add new profiles.

Debugging Tips

1. Check Sync Events:

   • Listen for plotly-chart-editor:synced in browser console:

     window.addEventListener('plotly-chart-editor:synced', (e) => {
         console.log('Synced data:', e.detail);
     });
     

2. Inspect Alpine Store:

   • Temporarily add a debug button to dump the store:

     <button x-on:click="console.log(Alpine.store('chartBuilder'))">
         Debug Store
     </button>
     

3. Validate DataSources:

   • Ensure dataSources is an associative array with consistent column lengths:

     $dataSources = [
         'xAxis' => [1, 2, 3],
         'yAxis' => [10, 20, 30], // Must match length of 'xAxis'
     ];
     

Performance Tips

1. Disable Auto-Sync for Large Datasets:

   • Use sync-mode="manual" to reduce debounced syncs:

     <livewire:plotly-editor :sync-mode="'manual'" />
     

2. Preload Schema:

   • Set :preload-schema="false" if you only use a subset of trace types to reduce initial load time.

3. Disable Unused Features:

   • Hide the export/data viewer buttons if unused:

     <livewire:plotly-editor
         :show-export="false"
         :show-data-viewer="false"
     />
     

Extension Points

1. Custom Trace Types:

   • Add new trace profiles in config/plotly-chart-editor.php:

     'profiles' => [
         'my-custom-type' => [
             'groups' => [
                 'data' => ['x', 'y', 'text'],
                 'style' => ['color', 'opacity'],
             ],
         ],
     ],
     

2. Override Translations:

   • Publish translations and modify resources/lang/en/plotly-chart-editor.php.

3. Alpine Store Extensions:

   • Extend the store by adding methods to resources/js/plotly-chart-editor.js:

     Alpine.store('chartBuilder', () => ({
         // Existing methods...
         customMethod() {
             // Your logic
         },
     }));
     

4. Validation Rules:

   • Extend ValidChartConfig by copying the rule class and overriding passes():

     class CustomValidChartConfig extends ValidChartConfig {
         public function passes($attribute, $value) {
             // Custom logic
             return parent::passes($attribute, $value);
         }
     }