Linkit Plugin for Craft 3
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
resources/img 1.1.2 Sep 28, 2018
src Update Link.php Oct 16, 2018
.craftplugin Version Bump Apr 24, 2018
.gitignore First commit Mar 4, 2018
CHANGELOG.md Version Bump Oct 23, 2018
LICENSE.md Renamed LinkIt.php to Linkit.php Mar 30, 2018
README.md 1.1.0 Aug 23, 2018
composer.json Version Bump Oct 23, 2018

README.md

Linkit

Linkit plugin for Craft 3

One link field to rule them all... This plugin adds a custom fieldtype which enables support for linking to email addresses, telephone numbers, URL's and Craft element types.

New for Craft 3

  • Link to Users and specify a profile url rule
  • New social links
  • Completely rewritten for Craft 3
  • Easily extendable, create your own custom link types

Requirements

This plugin requires Craft CMS 3.0.0-RC1 or later.

Installation

To install the plugin, follow these steps:

  1. Install with Composer via:

    composer require fruitstudios/linkit
    
  2. In the Control Panel, go to Settings → Plugins and click the “Install” button for Linkit.

Updating from Craft 2

Version 1.0.7 includes migration scripts for Craft 2, just install or update via the plugin store and Linkit will handle everything else.

Backup before installing / updating and note that only native link types (email, url, phone, entry, asset, category and product) can be updated. Settings for custom link types will be overwritten and although content will remain in place, it may cause issues unexpected issues with your templates.

For help on migrating custom link types see the docs and if you run into issues during the update just open a GitHub issue.

Configuring Linkit

Once installed, create a new field and choose the Linkit fieldtype. You'll then have the option of configuring what link type will be available to this field.

The following link types are available:

Basic

  1. Email Address
  2. Telephone Number
  3. URL

Social

  1. Twitter
  2. Facebook
  3. Instagram
  4. Linked In

Elements

  1. Entry
  2. Category
  3. User
  4. Asset
  5. Product

Each link type has additional option to allow further customisation. For example, the User link type allows you to set a default path...

Linkit

You can also customise the dropdown labels that appear on the field.

Linkit

Using Linkit

Template Variables (Basic Use)

Output the custom field to get a ready built html link...

{{ entry.linkItField | raw }}

or in full...

{{ entry.linkItField.link }} or {{ entry.linkItField.getLink() }}

Create a customised html link...

{% set attributes = {
    title: 'Custom Title',
    target: '_self',
    class: 'my-class',
    "data-custom": 'custom-data-attribute'
} %}
{{ entry.linkItField.link(attributes) }}

Template Variables (Advanced Use)

Each Linkit field returns a Linkit model with the following tags...

{{ entry.linkItField.url }} or {{ entry.linkItField.getUrl() }}
{{ entry.linkItField.text }} or {{ entry.linkItField.getText() }}

{{ entry.linkItField.type }}
{{ entry.linkItField.typeHandle }}

{{ entry.linkItField.hasElement }}
{{ entry.linkItField.avialable }} or {{ entry.linkItField.isAvialable() }}

{{ entry.linkItField.target }}
{{ entry.linkItField.targetString }}
{{ entry.linkItField.linkAttributes }}

If your link is an element link you also have access to the following...

{{ entry.linkItField.element }} or {{ entry.linkItField.getElement() }}

or via the specific element types...

{{ entry.linkItField.entry }} or {{ entry.linkItField.getEntry() }}
{{ entry.linkItField.asset }} or {{ entry.linkItField.getAsset() }}
{{ entry.linkItField.category }} or {{ entry.linkItField.getCategory() }}
{{ entry.linkItField.user }} or {{ entry.linkItField.getUser() }}
{{ entry.linkItField.product }} or {{ entry.linkItField.getProduct() }}

Example Usage

If you have created a field called 'linkItField' with a User link type like so...

Linkit

{{ entry.linkItField.link }}

would output <a href="/profile/USERNAME">Visit Profile</a> which is the default user path that is created in the setting and the user would be available at...

{{ entry.linkItField.user }}

A Note On Element Status

To match first party element fieldtypes, Linkit now links to and allows users to select disabled elements when using element link types, we have added a new method to allow you to determine if a link is available (enabled) for the current site, as such the following will return a boolean value

{{ entry.linkItField.avialable }} or {{ entry.linkItField.isAvialable() }}

you can use this to work out if you should display a link

{% if entry.linkItField.available %}
    {{ entry.linkItField.link | raw }}
{% endif %}

You can still access the linked element and any other attributes should you need to access a disabled element

{# So long as it exists the link is always returned irrelevant of status #}
{% set element = entry.linkItField.element %}
{% if element %}
    {{ element.title }} - {{ element.url }}
{% endif %}

Custom Link Types

You can easily create your own link types,

Full documenation is coming soon, for now, take a look at the models folder. Each link type is a seperate model, just extend Link or ElementLink, depending on your needs, and everything will be set up for you.

Hook up the requirements and register custom link types in your plugin (or modules) init()...

<?php

...

use fruitstudios\linkit\Linkit;
use fruitstudios\linkit\events\RegisterLinkTypesEvent;
use fruitstudios\linkit\services\LinkitService;

use developer\plugin\models\CustomType;

...

public function init()
{
    parent::init();

    Event::on(Linkit::class, LinkitService::EVENT_REGISTER_LINKIT_FIELD_TYPES, function (RegisterLinkTypesEvent $event) {
        $event->types[] = new CustomType();
    });

}

If you think they are super useful and you agree we can look to add them to the core plugin for everyone to use.

Brought to you by FRUIT