Custom file previews

[distantnative]

This PR …

• [ ] We should also consider how to best alter the image preview (e.g. also used in sections). Is there a similar way to do this?
• [ ] Audio and video previews suffer from https://github.com/getkirby/kirby/issues/1207
  • I started locally another attempt at HTTP range requests for files but sadly it doesn't seem to work fully. It's hard for me to fully understand the requests Safari mades and if they fail, why or actually succeed. https://github.com/getkirby/kirby/tree/lab/nico/http-range-response

Features

• Enhanced file previews for audio and video files

• Support providing custom file previews https://feedback.getkirby.com/636

Breaking changes

• <k-file-preview> got completely refactored and is now used as boilerplate wrapper for the actual preview components loaded: k-file-default-preview or k-file-image-preview, k-file-audio-preview, k-file-video-preview, ...

Docs

To add custom file previews, plugins can do two things:

• Add/overwrite a k-file-{type of file}-preview component that will be used for all files of that type
• Add a filePreview extension as a Closure. If the Closure returns an array, it is claiming to provide the preview for this specific file. Return a Vue component name and/or additional props

Kirby::plugin('my/plugin', [
  'filePreviews' => [
    function (\Kirby\Cms\File $file) {
      if ($file->extension() === 'pdf') {
        return [
          'component' => 'k-my-pdf-preview',
          'props' => [
            'pages' => 7
           ]
        ];
      }
    }
  ]
]);

Potential cookbook article on how to build a GLB preview: https://github.com/getkirby/sandbox/tree/feature/custom-file-previews/environments/lab/site/plugins/custom-file-preview

Ready?

• [x] In-code documentation (wherever needed)
• [ ] Unit tests for fixed bug/feature
• [ ] Tests and checks all pass

For review team

• [ ] Add lab and/or sandbox examples (wherever helpful) https://github.com/getkirby/sandbox/pull/7
• [ ] Add changes & docs to release notes draft in Notion

[lukasbestle]

Allowing custom previews is certainly a very useful feature.

I'm wondering if basing them on the type is a full solution though. With video, audio and code, one preview for most/all files of that type will work. But with documents it's more difficult. A PDF preview will need to do other things than a Markdown preview or a MS Office preview. And with totally custom file types such as GPX this is even more pronounced.

Quick idea, not sure if feasible: Make this a plugin extension that defines a closure. This closure will get the file object passed and can either return a string with a component name or null if the extension cannot handle the passed file. All registered preview plugins would then be called one after another until one returns a valid component name.

[distantnative]

Maybe even more closures that get looped through here https://github.com/getkirby/kirby/pull/6418/files#diff-f48d01ff6f4c25f3c2e8f1a34251e92010823474044243852b1654a8f6b97497R408 and that then can add required data for their preview as well as overwrite a new component key or so if they want to provide the preview for this kind of file (type/mime/extension/name...).

I still think it make sense by default to go by the type names as well. Allowing us easy to offer different previews for images, audio and videos (and everything else, especially documents as varied as they are, get the default icon preview).

[lukasbestle]

It could be a system like: First check if an extension closure feels responsible, then for a registered component for that type and finally fall back to the default preview.

[distantnative]

Exactly. It wouldn't be hard to implement. I am still hesitating a little bit as it feels quite different to other extensions etc. – asking myself if we're creating a setup that works but we might not be that happy later on.

[lukasbestle]

I think it would still be quite simple. Other projects would probably go for a class interface that needs to be implemented by the extension. But that's too much overhead IMO. So a closure is a simple solution that still adds flexibility and makes it possible for multiple plugins to provide specific previews for specific file types or extensions.

[distantnative]

Probably more a 5.0 thing right now as we should consider the change of k-file-preview probably as larger breaking change.

[nilshoerrmann]

From a plugin developer perspective, it would be great if you'd come up with a general concept that could be transfered to other areas of the panel later on because there are definitely other components that would benefit from a simple system of alternative views.

[bastianallgeier]

Looking a bit closer at this, I was expecting that it would only take care of the part with the pattern background.

If we look at it from a perspective to make it reusable in as many situations as possible, the preview should be super easy to load into the file browser or maybe even some other places later and I think we could only guarantee this if we keep the preview part isolated from the details list.

[distantnative]

I don't see it as something to be reused in other places to be honest. For that we have the simple Panel image method. As e.g. loading audio or videos in list sections wouldn't be a good idea I think.

For me this is about offering a customizable way to provide the best possible detail preview of a file. And I think there it would be quite sad to limit it just to the thumb. E.g. we already see it with the image preview where we want to add the extra focus button in the details. With the video preview we might want to change the proportions of the thumb and details parts. Or someone wants to deliver a preview that doesn't deal with the details section at all. I think all of these are very valuable and limiting it only to the thumb part would be quite sad. And also a part we've already covered with the overwritable image method in the Panel models.

[nilshoerrmann]

We are interested in providing a preview for MBTiles which would benefit from offering a custom preview and custom file information (basically showing information from the tile meta data).