242 lines
7.3 KiB
Markdown
242 lines
7.3 KiB
Markdown
|
# Kirby Sortable
|
||
|
|
A toolkit for managing subpages in the content area.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
## Table of contents
|
||
|
|
1. [Features](#1-features)
|
||
|
|
3. [Installation](#2-installation)
|
||
|
|
4. [Blueprint](#3-blueprint)
|
||
|
|
5. [Customize](#4-customize)
|
||
|
|
6. [Donate](#5-donate)
|
||
|
|
|
||
|
|
|
||
|
|
## 1 Features
|
||
|
|
This project started as a simple field and has grown into a reliable and extendable plugin.
|
||
|
|
It includes the [`sortable`](#sortable), [`modules`](#modules), [`redirect`](#redirect) and [`options`](#options) field.
|
||
|
|
In addition to the four fields the plugin has its own [registry](#registry).
|
||
|
|
|
||
|
|
### Fields
|
||
|
|
#### `sortable`
|
||
|
|
The core field. It is the base for the `modules` field.
|
||
|
|
Change appereance in the [blueprint](#3-blueprint) or [build your own field](#4-customize) based on this one.
|
||
|
|
|
||
|
|
#### `modules`
|
||
|
|
The `modules` field is an extended `sortable` field. Bundled with the [modules-plugin](https://github.com/getkirby-plugins/modules-plugin) it is a very powerful tool. You can find further informations [here](fields/modules).
|
||
|
|
To disable the field add `c::get('sortable.field.modules', false);` to your `config.php`.
|
||
|
|
|
||
|
|
#### `redirect`
|
||
|
|
Redirect a user to the parent of the currently visited panel page. Useful for pages that act as a container. You can find further informations [here](fields/redirect).
|
||
|
|
To disable the field add `c::get('sortable.field.redirect', false);` to your `config.php`.
|
||
|
|
|
||
|
|
#### `options`
|
||
|
|
This field is used internally by the `sortable` field for the copy and paste functionality.
|
||
|
|
|
||
|
|
### Registry
|
||
|
|
With the registry you are able to customize the visual appearance and modify or add custom functionality.
|
||
|
|
The registry makes it possible to register [layouts](#layout-1), [actions](#action), [variants](#variant-1) and [translations](#translation). Learn more about how to register components in the [customize](#4-customize) section.
|
||
|
|
|
||
|
|
|
||
|
|
## 2 Installation
|
||
|
|
There are several ways to install the plugin.
|
||
|
|
Please make sure you meet the minimum requirements.
|
||
|
|
|
||
|
|
### Requirements
|
||
|
|
- PHP 5.4+
|
||
|
|
- [Kirby](https://getkirby.com/) 2.3+
|
||
|
|
- [Kirby Modules Plugin](https://github.com/getkirby-plugins/modules-plugin) 1.3+
|
||
|
|
when you want to use the `modules` field
|
||
|
|
|
||
|
|
### Git
|
||
|
|
To clone or add the plugin as a submodule you need to cd to the root directory of your Kirby installation and run one of the corresponding command:
|
||
|
|
`$ git clone https://github.com/lukaskleinschmidt/kirby-sortable.git site/plugins/sortable`
|
||
|
|
`$ git submodule add https://github.com/lukaskleinschmidt/kirby-sortable.git site/plugins/sortable`
|
||
|
|
|
||
|
|
### Kirby CLI
|
||
|
|
If you're using the Kirby CLI, you need to cd to the root directory of your Kirby installation and run the following command: `kirby plugin:install lukaskleinschmidt/kirby-sortable`
|
||
|
|
|
||
|
|
### Download
|
||
|
|
You can download the latest version of the plugin [here](https://github.com/lukaskleinschmidt/kirby-sortable/releases/latest).
|
||
|
|
To install the plugin, please put it in the `site/plugins` directory.
|
||
|
|
The plugin folder must be named `sortable`.
|
||
|
|
|
||
|
|
```
|
||
|
|
site/plugins/
|
||
|
|
sortable/
|
||
|
|
sortable.php
|
||
|
|
...
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
## 3 Blueprint
|
||
|
|
After installing the plugin you can use the new field types.
|
||
|
|
This blueprint shows all available options of the `sortable` field.
|
||
|
|
|
||
|
|
```yml
|
||
|
|
fields:
|
||
|
|
title:
|
||
|
|
label: Title
|
||
|
|
type: text
|
||
|
|
|
||
|
|
sortable:
|
||
|
|
label: Sortable
|
||
|
|
type: sortable
|
||
|
|
|
||
|
|
layout: base
|
||
|
|
variant: null
|
||
|
|
|
||
|
|
limit: false
|
||
|
|
|
||
|
|
parent: null
|
||
|
|
prefix: null
|
||
|
|
|
||
|
|
options:
|
||
|
|
limit: false
|
||
|
|
```
|
||
|
|
|
||
|
|
### Options
|
||
|
|
|
||
|
|
#### `layout`
|
||
|
|
Load a registerd layout. The layout defines how a entry is rendered. Learn how to [register your own layout](#layout-1).
|
||
|
|
|
||
|
|
#### `variant`
|
||
|
|
Load a registerd variant. A variant is used to change the naming of the field from page to modules for example. Learn how to [register your own variant](#variant-1).
|
||
|
|
|
||
|
|
#### `limit`
|
||
|
|
Limit he number of visible pages. Example blueprint from the `modules` field.
|
||
|
|
```yml
|
||
|
|
fields:
|
||
|
|
modules:
|
||
|
|
label: Modules
|
||
|
|
type: modules
|
||
|
|
|
||
|
|
# Allow 5 visible modules overall
|
||
|
|
limit: 5
|
||
|
|
|
||
|
|
# Template specific option
|
||
|
|
options:
|
||
|
|
|
||
|
|
# Allow only 3 modules per template (applies to all templates)
|
||
|
|
limit: 3
|
||
|
|
module.gallery:
|
||
|
|
|
||
|
|
# Allow only 1 visible gallery module (overwrites the current limit of 3)
|
||
|
|
limit: 1
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `parent`
|
||
|
|
Uid to use when looking for the container page. If left empty the field will look for subpages in the current page.
|
||
|
|
```yml
|
||
|
|
# home.yml
|
||
|
|
|
||
|
|
fields:
|
||
|
|
events:
|
||
|
|
label: Events
|
||
|
|
type: sortable
|
||
|
|
|
||
|
|
parent: events
|
||
|
|
```
|
||
|
|
```
|
||
|
|
site/content/
|
||
|
|
home/
|
||
|
|
home.txt
|
||
|
|
events/
|
||
|
|
event-1/
|
||
|
|
event.txt
|
||
|
|
event-2/
|
||
|
|
event.txt
|
||
|
|
...
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `prefix`
|
||
|
|
Template prefix to filter available subpages.
|
||
|
|
```yml
|
||
|
|
# home.yml
|
||
|
|
|
||
|
|
fields:
|
||
|
|
events:
|
||
|
|
label: Events
|
||
|
|
type: sortable
|
||
|
|
|
||
|
|
prefix: event.
|
||
|
|
```
|
||
|
|
```
|
||
|
|
site/content/
|
||
|
|
home/
|
||
|
|
home.txt
|
||
|
|
event-1/
|
||
|
|
event.default.txt
|
||
|
|
event-2/
|
||
|
|
event.default.txt
|
||
|
|
subpage/
|
||
|
|
default.txt
|
||
|
|
...
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
## 4 Customize
|
||
|
|
With the registry you are able to customize the visual appearance and modify or add functionality.
|
||
|
|
The registry makes it possible to register layouts, actions, variants and translations.
|
||
|
|
|
||
|
|
```php
|
||
|
|
// site/plugins/sortable-variants/sortable-variants.php
|
||
|
|
|
||
|
|
// Make sure that the sortable plugin is loaded
|
||
|
|
$kirby->plugin('sortable');
|
||
|
|
|
||
|
|
if(!function_exists('sortable')) return;
|
||
|
|
|
||
|
|
$kirby->set('field', 'variants', __DIR__ . DS . 'field');
|
||
|
|
|
||
|
|
$sortable = sortable();
|
||
|
|
$sortable->set('layout', 'variant', __DIR__ . DS . 'layout');
|
||
|
|
$sortable->set('variant', 'variants', __DIR__ . DS . 'variant');
|
||
|
|
$sortable->set('action', '_add', __DIR__ . DS . 'actions' . DS . '_add');
|
||
|
|
$sortable->set('action', '_paste', __DIR__ . DS . 'actions' . DS . '_paste');
|
||
|
|
$sortable->set('action', '_duplicate', __DIR__ . DS . 'actions' . DS . '_duplicate');
|
||
|
|
```
|
||
|
|
|
||
|
|
A plugin can take care of registering all kinds of extensions, which will then be available in the `sortable` field or any field based on that.
|
||
|
|
|
||
|
|
### List of registry extensions
|
||
|
|
These are all possible registry extensions you can register this way:
|
||
|
|
|
||
|
|
#### layout
|
||
|
|
```php
|
||
|
|
// The layout directory must exist and it must have a PHP file with the same name in it
|
||
|
|
sortable()->set('layout', 'mylayout', __DIR__ . DS . 'mylayout');
|
||
|
|
```
|
||
|
|
Have a look at the [base layout](sortable/layouts/base) or the [module layout](sortable/layouts/module).
|
||
|
|
|
||
|
|
#### action
|
||
|
|
```php
|
||
|
|
// The action directory must exist and it must have a PHP file with the same name in it
|
||
|
|
sortable()->set('action', 'myaction', __DIR__ . DS . 'myaction');
|
||
|
|
```
|
||
|
|
Have a look at the [actions](sortable/actions).
|
||
|
|
|
||
|
|
#### variant
|
||
|
|
```php
|
||
|
|
// The variant directory must exist and can have multiple tranlation files
|
||
|
|
sortable()->set('variant', 'myvariant', __DIR__ . DS . 'myvariant');
|
||
|
|
```
|
||
|
|
Have a look at the [modules variant](sortable/variants/modules) or the [sections variant](sortable/variants/sections).
|
||
|
|
|
||
|
|
#### translation
|
||
|
|
```php
|
||
|
|
// The translation file must exist at the given location
|
||
|
|
sortable()->set('translation', 'en', __DIR__ . DS . 'en.php');
|
||
|
|
sortable()->set('translation', 'sv_SE', __DIR__ . DS . 'sv_SE.php');
|
||
|
|
```
|
||
|
|
Have a look at the [translations](sortable/translations).
|
||
|
|
|
||
|
|
### Examples
|
||
|
|
- [kirby-sortable-variants](https://github.com/lukaskleinschmidt/kirby-sortable-variants)
|
||
|
|
- [kirby-sortable-events](https://github.com/lukaskleinschmidt/kirby-sortable-events)
|
||
|
|
|
||
|
|
|
||
|
|
## 5 Donate
|
||
|
|
|
||
|
|
If you enjoy this plugin and want to support me you can [buy me a beer](https://www.paypal.me/lukaskleinschmidt/5eur) :)
|