PHPackages                             oblik/kirby-link-field - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. oblik/kirby-link-field

ActiveKirby-plugin[Utility & Helpers](/categories/utility)

oblik/kirby-link-field
======================

Kirby 4 field for all types of links.

6.0.2(1y ago)7650.6k↑125%10[18 issues](https://github.com/oblik/kirby-link-field/issues)[5 PRs](https://github.com/oblik/kirby-link-field/pulls)2MITPHPCI passing

Since May 16Pushed 1mo ago6 watchersCompare

[ Source](https://github.com/oblik/kirby-link-field)[ Packagist](https://packagist.org/packages/oblik/kirby-link-field)[ GitHub Sponsors](https://github.com/OblikStudio)[ RSS](/packages/oblik-kirby-link-field/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (3)Versions (31)Used By (2)

**NOTE:** Since Kirby 4, there's a built in [link field](https://getkirby.com/docs/reference/panel/fields/link). Consider using it instead!

kirby-link-field
================

[](#kirby-link-field)

Kirby 4 Field for links of any kind - external, page, file, email, phone. Has settings for text, popup true/false, and hash.

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

[![usage demo](usage.gif)](usage.gif)

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

[![links in structure field](structure.gif)](structure.gif)

Contributing
------------

[](#contributing)

- Read the [CONTRIBUTING.md](https://github.com/OblikStudio/kirby-link-field/blob/master/docs/CONTRIBUTING.md) for details
- Support development by [sponsoring us](https://github.com/sponsors/OblikStudio)

Installation
------------

[](#installation)

With Composer from [oblik/kirby-link-field on packagist](https://packagist.org/packages/oblik/kirby-link-field):

```
composer require oblik/kirby-link-field

```

...or check out [other plugin installation methods](https://getkirby.com/docs/guide/plugins/plugin-setup-basic#the-three-plugin-installation-methods).

Blueprint
---------

[](#blueprint)

Add a field and set its type to `legacyLink`:

```
fields:
  myfield:
    type: legacyLink
    label: Link
```

**Note:** The field type name was changed in version 6.0.1 from `link` to `legacyLink` to prevent a conflict with Kirby 4's built in [link field](https://getkirby.com/docs/reference/panel/fields/link).

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

```
fields:
  myfield:
    type: legacyLink
    label: Link
    linkTypes:
      - page
      - url
```

**Note:** This was changed in version 4.0.0 from `options` to `linkTypes` due to an issue with Kirby's internal logic.

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: legacyLink
    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.link-field' => [
        'linkTypes' => [
            'url',
            'page'
        ],
        'settings' => [
            'popup' => [
                'label' => 'External Link'
            ]
        ]
    ]
];
```

...or:

```
return [
    'oblik.link-field.settings' => false
];
```

### Pages/Files Settings

[](#pagesfiles-settings)

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

```
fields:
  myfield:
    type: legacyLink
    pages:
      query: page.siblings
      image:
        cover: true
    files:
      query: site.files
      text: "{{ file.id }}"
```

Usage
-----

[](#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: page://hMipdcIiFl53yXdC
text: My Text
popup: true
hash: heading-1

```

To get the link object, you should call:

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

### `$link->isEmpty()`

[](#link-isempty)

**Since version 5.0.0**

Returns `true` or `false` depending on whether the link is empty. Note that it returns `true` not only when the field is empty, but whenever a valid URL can't be generated. If you have a broken link, such as:

```
type: page
value: page://broken-uuid

```

…the link would still be considered empty, because no such page exists.

### `$link->isNotEmpty()`

[](#link-isnotempty)

**Since version 5.1.0**

The opposite of `$link->isEmpty()`.

### `$link->url()`

[](#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()`

[](#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])`

[](#link-attrattributes)

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

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

```

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

[](#link-tagattributes)

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

```

  My Text

```

### `$link->title()`

[](#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

[](#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
```

### `$field->toValidLink()`

[](#field-tovalidlink)

**Since version 5.2.0**

It may be cumbersome to use `$field->toLinkObject()`, then always have to check if the link is valid with `$link->isNotEmpty()`:

```