README

Kirby 3 Field for links of any kind - external, page, file, email, phone. Has settings for text, popup true/false, and hash. Original plugin is this, created by Thomas Günther.

The plugin uses the native Kirby fields for pages, files, url, email, and tel:

If used inside a structure field, link fields get a nice preview. Links to pages and files get the native page/file preview:

Installation

With Composer:

composer require oblik/kirby-link-field

...or check out other plugin installation methods.

Blueprint

Add a field and set its type to link:

fields:
  myfield:
    type: link
    label: Link

To define what link types you want, use options. Possible values are url, page, file, email, and tel:

fields:
  myfield:
    type: link
    label: Link
    options:
      - page
      - url

By default, you can also specify link text, popup true/false, and hash. You can disable those options or change their appearance by using the settings value:

fields:
  myfield:
    type: link
    label: Link
    settings:
      popup:
        width: 1/3
        label: External Link
        help: Open link in a new tab?
      text:
        width: 2/3
      hash: false

To disable settings altogether, set:

settings: false

You could also apply such settings globally:

config/config.php

return [
    'oblik.linkField' => [
        'options' => [
            'url',
            'page'
        ],
        'settings' => [
            'popup' => [
                'label' => 'External Link'
            ]
        ]
    ]
];

...or:

return [
    'oblik.linkField.settings' => false
];

Pages/Files Settings

You could specify settings for the pages/files field. For example:

fields:
  myfield:
    type: link
    pages:
      query: page.siblings
      image:
        cover: true
    files:
      query: site.files
      text: '{{ file.id }}'

Usage

To render the links, use the provided toLinkObject() method. It returns an instance of the Link class.

Let's say you have a field with the following values:

Myfield: 

type: page
value: home
text: My Text
popup: true
hash: heading-1

$link = $page->myfield()->toLinkObject();

`$link->url()`

Returns the link URL, including the hash:

http://localhost/home#heading-1

Note: For email and tel links, the value is null since they're not actual links.

`$link->href()`

Returns link href:

http://localhost/home#heading-1

If the link type is email or tel, it has mailto: or tel: accordingly.

Note: This is automatically called when you try to convert the class to string, meaning that:

echo $page->myfield()->toLinkObject();

...is the same as:

echo $page->myfield()->toLinkObject()->href();

`$link->attr([$attributes])`

Returns the link attributes, merged with the optional $attributes:

href="http://localhost/home#heading-1" rel="noopener noreferrer" target="_blank"

`$link->tag([$attributes])`

Returns a full <a> tag with merged attributes from the optional $attributes:

<a href="http://localhost/home#heading-1" rel="noopener noreferrer" target="_blank">My Text</a>

`$link->title()`

Returns either the link text, page title, file title, filename, or finally the value. Used to generate the link text for the tag() method.

Retrieving Properties

You can get the properties of a link by invoking them as a method:

echo $link->type();     // page
echo $link->value();    // home
echo $link->text();     // My Text
echo $link->popup();    // true
echo $link->hash();     // heading-1

Migrating From URL Fields

If you've previously used a URL field:

fields:
  myfield:
    type: url

...you could simply change it to:

fields:
  myfield:
    type: link

...and it'll work. Also, the toLinkObject() method can handle both link formats in your TXT files. It's the same if you have:

Myfield: https://example.com