oblik / kirby-link-field
Kirby 4 field for all types of links.
Fund package maintenance!
OblikStudio
Installs: 44 535
Dependents: 2
Suggesters: 0
Security: 0
Stars: 77
Watchers: 7
Forks: 10
Open Issues: 19
Type:kirby-plugin
Requires
- getkirby/cms: ^4
- getkirby/composer-installer: ^1.1
Requires (Dev)
- phpunit/phpunit: ^9.5
README
NOTE: Since Kirby 4, there's a built in link field. Consider using it instead!
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:
If used inside a structure field, link fields get a nice preview. Links to pages and files get the native page/file preview:
Contributing
- Read the CONTRIBUTING.md for details
- Support development by sponsoring us
Installation
With Composer from oblik/kirby-link-field on packagist:
composer require oblik/kirby-link-field
...or check out other plugin installation methods.
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.
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
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
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()
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()
Since version 5.1.0
The opposite of $link->isEmpty()
.
$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
$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()
:
<?php $link = page()->myLinkField()->toLinkObject(); ?> <?php if ($link->isNotEmpty()) : ?> <a href="<?= $link->href() ?>">Click here!</a> <?php endif ?>
In this case, you can use $field->toValidLink()
:
<?php if ($link = page()->myLinkField()->toValidLink()) : ?> <a href="<?= $link->href() ?>">Click here!</a> <?php endif ?>
The toValidLink()
method returns:
null
if the link is invalid or empty- The link object, when it's a valid, existing link
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: legacyLink
...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
...or:
Myfield:
type: url
value: https://example.com
Support
If you find the plugin useful and would like to receive better support for it, please consider sponsoring us. Thank you! 🙏