allow custom handlers description and distinct sample files

Author: lekoala

README.md

@@ -64,6 +64,27 @@ This require some custom code on your `ModelAdmin` class that could look like th
 The import handlers only need to implement a `load` method that needs to return a result string
 or a `BulkLoader_Result` object.
 
+These custom handlers can have a custom description and a custom sample file:
+
+```php
+    public static function getImportDescription()
+    {
+        return "This is my custom description";
+    }
+
+    public static function getSampleFileLink()
+    {
+        return ExcelImportExport::createDownloadSampleLink(__CLASS__);
+    }
+
+    public static function getSampleFile()
+    {
+        $data = []; // TODO
+        ExcelImportExport::createSampleFile($data, __CLASS__);
+    }
+
+```
+
 ## Compatibility
 
 Tested with ^5 and up

src/ExcelImportExport.php

@@ -151,6 +151,32 @@ public static function importFieldsForClass($class)
         return array_combine($importedFields, $importedFields);
     }
 
+    public static function createDownloadSampleLink($importer = '')
+    {
+        /** @var \SilverStripe\Admin\ModelAdmin $owner */
+        $owner = Controller::curr();
+        $class = $owner->getModelClass();
+        $downloadSampleLink = $owner->Link(str_replace('\\', '-', $class) . '/downloadsample?importer=' . urlencode($importer));
+        $downloadSample = '<a href="' . $downloadSampleLink . '" class="no-ajax" target="_blank">' . _t(
+            'ExcelImportExport.DownloadSample',
+            'Download sample file'
+        ) . '</a>';
+        return $downloadSample;
+    }
+
+    public static function createSampleFile($data, $fileName)
+    {
+        $ext = self::getDefaultExtension();
+        $fileNameExtension = pathinfo($fileName, PATHINFO_EXTENSION);
+        if (!$fileNameExtension) {
+            $fileName .= ".$ext";
+        }
+        $options = new Options();
+        $options->creator = ExcelImportExport::config()->default_creator;
+        SpreadCompat::output($data, $fileName, $options);
+        exit();
+    }
+
     /**
      * Output a sample file for a class
      *
@@ -190,10 +216,7 @@ public static function sampleFileForClass($class)
             throw new Exception("`sampleImportData` must return an iterable");
         }
 
-        $options = new Options();
-        $options->creator = ExcelImportExport::config()->default_creator;
-        SpreadCompat::output($data, $fileName, $options);
-        exit();
+        self::createSampleFile($data, $fileName);
     }
 
     /**

src/extensions/ModelAdminExcelExtension.php

@@ -80,7 +80,12 @@ public function downloadsample()
     {
         /** @var \SilverStripe\Admin\ModelAdmin $owner */
         $owner = $this->owner;
-        ExcelImportExport::sampleFileForClass($owner->getModelClass());
+        $importer = $owner->getRequest()->getVar('importer');
+        if ($importer && class_exists($importer) && method_exists($importer, 'getSampleFile')) {
+            $importer::getSampleFile();
+        } else {
+            ExcelImportExport::sampleFileForClass($owner->getModelClass());
+        }
     }
 
     /**
@@ -166,17 +171,41 @@ public function updateImportForm(Form $form)
 
         $fields = $form->Fields();
 
-        $downloadSampleLink = $owner->Link(str_replace('\\', '-', $class) . '/downloadsample');
-        $downloadSample = '<a href="' . $downloadSampleLink . '" class="no-ajax" target="_blank">' . _t(
-            'ExcelImportExport.DownloadSample',
-            'Download sample file'
-        ) . '</a>';
+        // We can implement a custom handler
+        $importHandlers = [];
+        $htmlDesc = '';
+        $useDefaultSample = true;
+        if ($modelSNG->hasMethod('listImportHandlers')) {
+            $importHandlers = array_merge([
+                'default' => _t('ExcelImportExport.DefaultHandler', 'Default import handler'),
+            ], $modelSNG->listImportHandlers());
+
+            $supportOnlyUpdate = [];
+            foreach ($importHandlers as $class => $label) {
+                if (!class_exists($class)) {
+                    continue;
+                }
+                if (method_exists($class, 'setOnlyUpdate')) {
+                    $supportOnlyUpdate[] = $class;
+                }
+                if (method_exists($class, 'getImportDescription')) {
+                    $htmlDesc .= '<div class="js-import-desc" data-name="' . $class . '" hidden>' . $class::getImportDescription() . '</div>';
+                }
+                if (method_exists($class, 'getSampleFileLink')) {
+                    $useDefaultSample = false;
+                    $htmlDesc .= '<div class="js-import-desc" data-name="' . $class . '" hidden>' . $class::getSampleFileLink() . '</div>';
+                }
+            }
+        }
 
         /** @var \SilverStripe\Forms\FileField|null $file */
         $file = $fields->dataFieldByName('_CsvFile');
         if ($file) {
             $csvDescription = ExcelImportExport::getValidExtensionsText();
-            $csvDescription .= '. ' . $downloadSample;
+            if ($useDefaultSample) {
+                $downloadSample = ExcelImportExport::createDownloadSampleLink();
+                $csvDescription .= '. ' . $downloadSample;
+            }
             $file->setDescription($csvDescription);
             $file->getValidator()->setAllowedExtensions(ExcelImportExport::getValidExtensions());
         }
@@ -194,30 +223,19 @@ public function updateImportForm(Form $form)
         // We moved the specs into a nice to use download sample button
         $fields->removeByName("SpecFor{$modelName}");
 
-        // We can implement a custom handler
-        $importHandlers = [];
-        if ($modelSNG->hasMethod('listImportHandlers')) {
-            $importHandlers = array_merge([
-                'default' => _t('ExcelImportExport.DefaultHandler', 'Default import handler'),
-            ], $modelSNG->listImportHandlers());
-
-            $supportOnlyUpdate = [];
-            foreach ($importHandlers as $class => $label) {
-                if (class_exists($class) && method_exists($class, 'setOnlyUpdate')) {
-                    $supportOnlyUpdate[] = $class;
-                }
-            }
-
+        if (!empty($importHandlers)) {
             $form->Fields()->push($OnlyUpdateRecords = new CheckboxField("OnlyUpdateRecords", _t('ExcelImportExport.OnlyUpdateRecords', "Only update records")));
             $OnlyUpdateRecords->setAttribute("data-handlers", implode(",", $supportOnlyUpdate));
-        }
-        if (!empty($importHandlers)) {
+
             $form->Fields()->push($ImportHandler = new OptionsetField("ImportHandler", _t('ExcelImportExport.PleaseSelectImportHandler', "Please select the import handler"), $importHandlers));
             // Simply check of this is supported or not for the given handler (if not, disable it)
             $js = <<<JS
-var cb=document.querySelector('#OnlyUpdateRecords');var accepted=cb.dataset.handlers.split(',');var item=([...this.querySelectorAll('input')].filter((input) => input.checked)[0]); cb.disabled=(item && accepted.includes(item.value)) ? '': 'disabled';
+var desc=document.querySelectorAll('.js-import-desc');var cb=document.querySelector('#OnlyUpdateRecords');var accepted=cb.dataset.handlers.split(',');var item=([...this.querySelectorAll('input')].filter((input) => input.checked)[0]); cb.disabled=(item && accepted.includes(item.value)) ? '': 'disabled';desc.forEach((el)=>el.hidden=!item||el.dataset.name!=item.value);;
 JS;
             $ImportHandler->setAttribute("onclick", $js);
+            if ($htmlDesc) {
+                $ImportHandler->setDescription($htmlDesc); // Description is an HTMLFragment
+            }
         }
 
         $actions = $form->Actions();