README

Adds a Link Object that can be link to a URL, Email, Phone number, an internal Page or File.

Installation

Composer is the recommended way of installing SilverStripe modules.

composer require gorriecoe/silverstripe-link

Requirements

• silverstripe/framework ^4.0
• unclecheese/display-logic ^2.0
• giggsey/libphonenumber-for-php ^8.0

Suggestion

• gorriecoe/silverstripe-linkfield. Silverstripe link opts to separated from linkfield to give the opportunity for developers to choose their own relationship manager such as gridfield. I'm happy to add any other suggested modules to this list.
• gorriecoe/silverstripe-logoutlink

Embed

If you are coming from Linkable and are looking for Embed functionality check out silverstripe-embed

Maintainers

• Gorrie Coe

Usage

<?php

use gorriecoe\Link\Models\Link;

class MyClass extends DataObject
{
    private static $has_one = [
        'Button' => Link::class
    ];

    private static $many_many = [
        'Buttons' => Link::class
    ];

    private static $many_many_extraFields = [
        'Buttons' => [
            'Sort' => 'Int' // Required for all many_many relationships
        ]
    ];
}

Template options

Basic usage

<% loop Links %>
    {$Me}
<% end_loop %>

Define link classes

<% loop Links %>
    {$setClass('button')}
<% end_loop %>

Define a custom template to render the link

<% loop Links %>
    {$renderWith('Link_button')}
<% end_loop %>

Define a custom style. This will apply a css class and render a custom template if it exists. The example below will look for Link_button.ss in the includes directory.

<% loop Links %>
    {$setStyle('button')}
<% end_loop %>

Custom template

<% loop Links %>
    <% if LinkURL %>
        <a href="{$LinkURL}"{$TargetAttr}{$ClassAttr}>
            {$Title}
        </a>
    <% end_if %>
<% end_loop %>

Template variables

$LinkURL

Returns the URL of the link.

$TargetAttr

Returns the html target attribute. target='_blank' or null

$Target

Returns the html target attribute value. _blank or null

$IDAttr

Returns the html id attribute. id='my-custom-id' or null

$IDValue

Returns the html id value.

Refer to Add html id attribute for more information

$ClassAttr

Returns the html class attribute. class='my-custom-id' or null

$Class

Returns the html class value.

Refer to CMS Selectable Style for more information

Linking Modes

Linking mode variables are also available any sitetree link. Refer to Linking Modes for more information

CMS Selectable Style

You can offer CMS users the ability to select from a list of styles, allowing them to choose how their Link should be rendered. To enable this feature, register them in your site config.yml file as below.

gorriecoe\Link\Models\Link:
  styles:
    button: Description of button template # applies button class and looks for Link_button.ss template
    iconbutton: Description of iconbutton template # applies iconbutton class and looks for Link_iconbutton.ss template

Limit allowed Link types

To limit types define them in your site config.yml file as below.

gorriecoe\Link\Models\Link:
  allowed_types:
    - URL
    - SiteTree

Add html id attribute

Link has 3 options for defining html id, automatic, define-able or both.

To apply automatic id's add the following to your config.

gorriecoe\Link\Models\Link:
  extensions:
    - gorriecoe\Link\Extensions\AutomaticMarkupID

To apply input defineable id's add the following to your config.

gorriecoe\Link\Models\Link:
  extensions:
    - gorriecoe\Link\Extensions\DefineableMarkupID

To apply both automatic and define-able add the following to your config, ensuring the order is correct

gorriecoe\Link\Models\Link:
  extensions:
    - gorriecoe\Link\Extensions\AutomaticMarkupID
    - gorriecoe\Link\Extensions\DefineableMarkupID

String template manipulation

Link has a few methods to help manipulate DBString's.

PhoneFriendly

Converts a string to a phone number e.g 0800PIZZAHUT becomes 080074992488.

PHP

$this->obj('Phone')->PhoneFriendly()

Template

{$Phone.PhoneFriendly}

Additional methods are available to modify the output of phone numbers.

{$Phone.PhoneFriendly.E164} = +6480074992488
{$Phone.PhoneFriendly.National} = 80074992488
{$Phone.PhoneFriendly.International} = +64 80074992488
{$Phone.PhoneFriendly.RFC3966} = tel:+64-80074992488

Define the country the user is dialing from

{$Phone.PhoneFriendly.From('GB')}

Define the country the phone belongs to.

{$Phone.PhoneFriendly.To('NZ')}

And define both to and from.

{$Phone.PhoneFriendly.From('GB').To('NZ')} or {$Phone.PhoneFriendly.To('NZ').From('GB')}

For more information check put https://github.com/giggsey/libphonenumber-for-php

LinkFriendly or URLFriendly

Converts a DBString to a url safe string. This can be useful for anchors.

PHP

$this->obj('Title')->LinkFriendly()

Template

{$Title.LinkFriendly}