Skip to content

Kirby 3.7.3

Helpers

The Panel bundles a few functions that help you with common tasks.

Available helpers

How to access helpers

The Panel exposes all shared helpers via this.$helper:

// example in the Vue component of a custom field

panel.plugin("your/pad-display-field", {
  fields: {
    "pad-display": {
      // …
      computed: {
        paddedValue() {
          return this.$helper.pad(this.value);
        }
      }
      // …
    }
  }
});

Reference

this.$helper.clipboard

Helpers to read from and write to the clipboard.

Example

this.$helper.clipboard.read(ClipboardEvent);
this.$helper.clipboard.read(value);

this.$helper.clipboard.write(value, ClipboardEvent);

this.$helper.color

Turns a string into a valid CSS color making use of the Panel's custom CSS properties.

Example

this.$helper.color("#444");
this.$helper.color("purple-400");
this.$helper.color("pattern");

this.$helper.debounce

Parameters

Name Description
fn Function to be debounced
delay Delay in miliseconds

Example

debounce(function (query) {
  this.search(query);
}, 200);

this.$helper.embed

Helps to generate proper YouTube or Vimeo embed URLs.

Parameters

Name Description
url URL to transform into valid embed URL
doNotTrack If URL should try to enforce non-tracking (default: false)

Example

this.$helper.embed.video(youtubeOrVimeoUrl);
this.$helper.embed.youtube(youtubeUrl);
this.$helper.embed.vimeo(vimeoUrl);

this.$helper.isComponent

Checks if string refers to an existing Vue component.

Example

this.$helper.isComponent("my-mysterious-component");

this.$helper.isUploadEvent

Checks if a javascript event is really an upload event.

Example

YourVueComponent.vue
<template>
  <div @drop="onDrop" />
</template>

<script>
export default {
  methods: {
    onDrop(event) {
      if (this.$helper.isUploadEvent(event) === true) {
        // …
      }
    }
  }
}

this.$helper.keyboard

Collection of helpers corresponding to keyboard events

Example

// returns meta key name depending on operating system, e.g. "cmd"
this.$helper.keyboard.metaKey();

this.$helper.object

Collection of helpers for JavaScript objects:

clone

Shorthand helper for cloning an object

let array = ["homer, "simpson"];
let cloned = this.$helper.clone(array);

isEmpty

Since 3.7.0

Checks if a value of any type is empty

this.$helper.object.isEmpty(undefined) // true
this.$helper.object.isEmpty(null) // true
this.$helper.object.isEmpty("") // true
this.$helper.object.isEmpty([]) // true
this.$helper.object.isEmpty({}) // true

merge

Merges two objects

this.$helper.object.merge(object1, object2);

this.$helper.ratio

Receive a padding percentage for a specified image ratio.

Parameters

Name Description
ratio e.g. 1/2 (default: 3/2)

Example

return this.$helper.ratio("1/2");
// result: "50%"

this.$helper.sort

Natural sort algorithm with unicode support

Example

return this.$helper.sort(valueA, valueB);

this.$helper.string

Helper that offers a couple of methods:

camelToKebab
return this.$helper.string.camelToKebab("myFavoriteSong");
// result: "my-favorite-song"
escapeHTML
return this.$helper.string.escapeHTML("<script>");
// result: "&lt;script&gt;"
hasEmoji
return this.$helper.string.hasEmoji("hello");
// result: false

return this.$helper.string.hasEmoji("😎");
// result: true
lcfirst
return this.$helper.string.lcfirst("Hello");
// result: "hello"

pad

Adds 0 to the left of the value

Name Description
value Value to be padded
length Length of the returned string (default: 2)
let money = 9;
return this.$helper.pad(money, 4);
// result: "0009"
random

Returns a random alpha-numeric string of specified length.

return this.$helper.string.random(8);

slug

Transform a string to a valid slug according to a specified ruleset.

Name Description
string String to be transformed
rules Array of transformation rulesets (objects themselves)
allowed String of allowed characters
return this.$helper.slug("Was für ein Spaß", [
  {
    ü: "ue",
  },
  {
    ß: "sz",
  },
]);
// result: "was-fuer-ein-spasz"
stripHTML
return this.$helper.string.ucfirst("<p>Hello</p>");
// result: "Hello"
template

Replaces placeholers in a string with provided values

return this.$helper.string.template("Hello, { name }!", { name: "Homer" });
// result: "Hello, Homer!"
ucfirst
return this.$helper.string.ucfirst("hello");
// result: "Hello"
ucwords
return this.$helper.string.ucwords("hello my dear");
// result: "Hello My Dear"

this.$helper.upload

Helper to upload a file.

Parameters

Name Description
file File object
params Options object (see defaults below)
// available params and their default
const defaults = {
  url: "/",
  field: "file",
  method: "POST",
  accept: "text",
  attributes: {},
  complete: function() {},
  error: function() {},
  success: function() {},
  progress: function() {}
};