Kirby 5 – alpha releases

Bring out the big files: Chunked uploads

Kirby 5 supports large Panel uploads. Uploads are no longer restricted by the server's upload_max_filesize limit but instead uploaded in chunks that are pieced back together on the server.

If you want to keep restricting the upload size to some limits, the file blueprint accept maxsize option is your friend.

This way, you can reference existing buttons by name and decide which ones to include and in what order. You can however also define new custom buttons:

buttons:
  - preview
  - settings
  myBytton:
    text: My Button
    link: https://getkirby.com
    theme: positive

The available options are based on the k-view-button component (better docs will follow until the final release).

In the config.php

Similarly to the blueprints, buttons can be defined in your config file. In this case, not for a specific template but in general for the different view types (page, file, site, user, system, ...):

'panel' => [
  'viewButtons' => [
    'site' => [
      'preview',
      'a' => [
        'icon'   => 'heart',
        'text'   => 'Kosmos',
        'theme'  => 'purple-icon',
        'target' => '_blank',
        'link'   => 'https://getkirby.com'
      ],
      'b-dropdown' => [
        'props' => [
          'icon'     => 'info',
          'text'     => 'Info',
          'dropdown' => 'my/dropdown/route'
        ]
      ],
      'c-component' => [
        'component' => 'my-custom-component',
        'props' => [
          'foo' => 'bar'
        ]
      ]
    ]
  ]
]

What you can see above are three different ways to define a custom button:

• The first one directly defines the options. It's a shortcut that assumes these are the props for the k-view-button component.
• In the second example, they are already wrapped inside the props key. But no component is defined, so k-view-button is used as well.
• In the third example, we actually define a custom Vue component that should be used instead, alongside passing props to this component.

In a Panel area

If you do not want to define just one button via the config, but reuse it (or even ship it as part of your plugin), you can add them to the Panel area extension:

Kirby::plugin('custom/buttons', [
  'areas' => [
    'todos' => function () {
      return [
        'buttons' => [
          'todos.add' => function () {
            return [
              'props' => [
                'icon'   => 'add',
                'dialog' => 'todos/create'
              ]
            ];
          }
        ]
      ];
    }
  ]
]);

You have the same options for your return value: full component-props array or just props on top-level. In addition, you can also return directly a Kirby\Panel\Ui\Button\ViewButton object.

File previews: your media at a glance

With Kirby 5, we're opening up the preview part of the Panel's file view to more rich media previews that aren't just images.

It starts with basic previews for video and audio files that now ship as part of the core:

But you can also add custom file previews as plugin extensions to customize the preview for these formats or create previews for other file formats.

Custom file previews consist of two parts:

• a PHP class defining what data is passed to the preview and what files this preview is used for
• a Vue component to render the preview

Custom FieldPreview class

For a custom file preview, you need a new class that extends Kirby\Panel\Ui\FieldPreview. In this example, we're building a custom preview for .glb files that are used to display 3D data:

class GlbFilePreview extends FilePreview
{
    public function __construct(
        public File $file,
        public string $component = 'k-glb-file-preview'
    ) {
    }

    public static function accepts(File $file): bool
    {
        return $file->extension() === 'glb';
    }
}

This is the minimal setup for a custom class. What it does:

• It defines which Vue component to use, in this case k-glb-file-preview which we will create later. If no component is specified, k-default-file-preview will be used.
• Something you must define is the ::accepts($file) method. It is used to determine which preview class is used for a certain file. Kirby will loop through all available preview classes and use the first one that accepts the file.

Register your preview class

To use your custom file preview class, you need to register it as a plugin extension:

Kirby::plugin('your/plugin', [
    'filePreviews' => [
        GlbFilePreview::class
    ]
]);

Vue component

Finally, we need to create the Vue component that is used to render the preview. As above listed, we have named it k-glb-file-preview.

By default, file preview components will receive three default props:

• url to the file
• details array with basic file information (ideally used for <k-file-preview-details>)
• image object with the thumb icon/image also used in sections etc. (we don't use it for this preview)

We also use the <k-file-preview-frame> component as wrapper for our actual 3D model, which adds a pattern background.

panel.plugin("getkirby/custom-file-preview", {
    components: {
        "k-glb-file-preview": {
            template: `
                <figure class="k-default-file-preview k-glb-file-preview">
                    <k-file-preview-frame>
                        <model-viewer :src="url" />
                    </k-file-preview-frame>

                    <k-file-preview-details :details="details" />
                </figure>
            `,
            props: {
                details: Array,
                url: String,
            },
        },
    }
});

The <model-viewer> element is from a library that helps to actually display the GLB file. I won't go into the details how to use it exactly (loading external script etc.). You can try the full custom file view.

• New files.sort permission #1969
• UUIDs are fully lowercased now to avoid issues between filesystems handling casing differently #6566
• <k-tag>: new element and theme props #6569
• <k-tags>: new element, element-tag and theme props #6569
• New <k-tags-field-preview> component #6569
• New <k-view-button> component #6540
• New uploadAsChunks JS helper function #6421
• New Panel\Panel::buttons() method that collects all defined buttons from all Panel areas #6541
• New Panel\Ui namespace with basic Panel\Ui\Component and Panel\Ui\Button classes #6539
  • Each component renders as an array with a component, unique key and props entries
• New Panel\Ui\Buttons\ViewButtons and Panel\Ui\Buttons\ViewButton classes #6542
  • responsible for gathering and transforming view buttons configured in blueprints, config files and/or Panel areas
  • renders them as PHP array definitions that can be handed to the dedicated Vue frontend components
  • Added Panel\Model::model() method
• Backend classes for core view buttons #6545

• Sections: improved title and info wrapping #6447
• Calendar input: first day of the week is chosen based on user language or date.weekday config option (0 for Sunday ... 6 for Saturday) #6635
• Duplicating pages: All UUIDs within the copied page, its files and children that point to an object that got copied as - well will be replaced with the UUID of the copied version. If no copying files, any UUID pointing to a file within the copied page gets removed. #6567

• Fixed thumb issues resulting from EXIF orientation entry #2695
• Kirby is better at removing failed file uploads from the server tmp directory #2476
• Canceling the file upload dialog now also cancels ongoing uploads #6421
• <k-header>: fixed wrapping with many buttons in narrow screens #6544

• Model hooks for actions: multiple hooks don't overwrite each others' changes to the model #6460 #2828

• Kirby requires the following browser versions to use the Panel (other browser requirements remain unchanged)
  • Safari 16+
  • Mobile Safari 16+
  • Android Browser 126+
  • Chrome for Android 126+
• If file sorting was previously disabled via the files.update permission, the new file.sort permission has to be configured accordingly. #6589
• Panel uploads can exceed the upload_max_filesize limit #6421
  • If you want to restrict the upload size, please use the file blueprint accept maxsize option
• Increased PHP type hinting: when you're extending core classes, you might have to add the same type hints to your code as added to our core classes.
• Image\Dimensions::forImage() now receives an Image\Image object #6591
• Image\Exif::read() is now a static method that receives an absolute path to a file #6591
• Thumb driver autoOrient option has been removed and now is always applied #6591

• Model action before hooks: rules get applied after the hook runs
• <k-file-preview> got fully refactored. If you were replacing or extending it, your code likely will break. Check out the new custom file preview feature if you want to provide previews for specific files. #6578
• Calendar dropdown input will show Sunday now as first day of the week (depending on the user's language). If you want to enforce Monday as first day of the week, you can set the date.weekday option to 1. #6635
• All methods in *Rules classes are now marked to return void instead of a boolean #6660
• Users without a role in their credentials file will now receive the default role (if exists), not the visitor role anymore #6656
• Site::changes is now a new method to track changes across the site. The changes field is used as a storage for those changes and has thus become a reserved field for Kirby.
• All methods in *Rules classes are now marked to return void instead of a boolean #6660

• <k-bubble>, <k-bubbles> and <k-bubbles-field-preview>. Use <k-tag>, <k-tags> and <k-tag-field-preview> instead. #6569

• Exception classes: passing $arg array will be removed in a future version. Use named arguments. #6618

• New Kirby\Api\Upload class to handle file uploads via the REST API #6421

• Refactor LanguageRules #6659
• Exception classes support named arguments #6618
• Improve code style Collection::sort() #6626

• Vite: Make dev server by default https://sandbox.test instead of http://sandbox.test #6522
• Turn panel JS modules fully reactive #6529
• The ::setUpSingleLanguage and ::setUpMultiLanguage helper test methods in global TestCase class. #6561