pstaender / kirby-uri-field
Kirby 3 uri field which can be assigned also assigned to a page or a file.
Installs: 1 067
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 4
Forks: 0
Open Issues: 0
Type:kirby-plugin
Requires
- getkirby/cms: ^3.7
- getkirby/composer-installer: ^1.1
Requires (Dev)
- oblik/kirby-tester: ^1.2
- phpunit/phpunit: ^9.0
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
...or:
Myfield:
type: url
value: https://example.com