195

Product support

Get help in the plugin support forum.

Categories

The purpose of the action link is to interact with frontend users and prompt them to take actions. It can be used for a simple one-click action or a start of a more complex one.

Demo

The use case for the demo is a simple birthday invitation.

Frontend login: demofe / demofe
Backend login: demobe / demobe

Use cases

Some example use cases might be:

  • turn on/off features in user settings
  • apply to event
  • confirm or deny attendance
  • general yes/no/maybe choice
  • visit a subpage

and many more.

Feature overview

The plugin provides the following features.

  • API for creating and using action links
  • A component for handling action links
  • Backend lists for created models
  • Optional translate support using RainLab.Translate plugin

Support

Please use the plugin support forum section if you have any problem using the plugin, feature requests or questions.

Action links used in email - Birthday invitation

TOC

  • Handling Action Links
  • Creating Action Links
  • Using created Action Links
  • Basic Example Code

Handling Action Links

Before you can create an action link you need to create at least one handling page. The page URL will be the static part of the action link's URL. You can create as many pages as you wish. The handling page needs at least one Action Link Handler component. When creating an action link you will need to specify the page and the component that will handle it.

1. Create a handling page

Create a page with the URL of your choice and the required URL parameter named key. Page layout is not needed.

Note: If you have the RainLab.Translate plugin installed you can also translate the URL.

2. Add the handler component

Add the Action Link Handler component to the page. Modify the component properties to your needs. You do not need to render the component in the Markup section.

Component properties
  • successPage - page name to redirect after successful action handling
  • errorPage - page name to redirect after unsuccessful action handling
  • loginPage - can be empty. If selected, authentication is required befere action handling
  • flash - enable or disable flash messages after redirect
  • forceDelete - soft or force delete links after action handling

Important: Include the following code in the page layout for flash messages to work.

{% flash %}
    <p data-control="flash-message" data-interval="5" class="{{ type }}">
        {{ message }}
    </p>
{% endflash %}

Note: Default success and error messages can be overriden.

3. Register the handler callback

In the Code section, in onInit function register a callback that will handle links in a specific context. A context is basically a group of links.

function onInit()
{
    // The context here is 'birthday-invitation'
    \RoboCode\ActionLinks\Classes\ActionLinkHandler::handleContext('birthday-invitation', function ($actionLink) {
       //Do something useful here
    });
}

Or you can be more general and register a callback for all contexts.

function onInit()
{
    \RoboCode\ActionLinks\Classes\ActionLinkHandler::handleContext('*', function ($actionLink) {
        // Check the link context
        if ($actionLink->context->key == 'birthday-invitation') {
            // ...
        }
    });
}

Generating Action Links

A basic action link needs a context and a handling page base filename. The handleBy method must allways be last. Other methods are optional and their order can be random.

/**
* @param string $context I.e. 'birthday-invitation'
* @param string $page Handling page base filename (without the .htm)
*/

$link = ActionLink::createInContext($context)
        ->handleBy($page);

If you have more than one actionLinkHandler component on a handle page you must also specify the component alias that will handle the link.

$link = ActionLink::createInContext($context)
        ->handleBy($page, $componentAlias);

You can create a link for a registered user.

$link = ActionLink::createInContext($context)
        -> ...
        ->forUser($user)
        -> ...
        ->handleBy($page, $component);

Or for a guest user.

$link = ActionLink::createInContext($context)
        -> ...
        ->forGuestUser('john.doe@example.com')
        -> ...
        ->handleBy($page, $component);

Maybe you need some additional parameters in the handle callback.

$link = ActionLink::createInContext($context)
        -> ...
        ->withParam('foo', bar)
        ->withParam('x', 'y')
        -> ...
        ->handleBy($page, $component);

You can set the expiration date. After the date, the link will become expired. User will be redirected to the error page chosen in the component's properties.

//Pass a DateTime object
$expiresOn = new \DateTime('first day of December 2020');

//Or an instance of Carbon
$expiresOn = Carbon::now()->addDay();

//Or a string (uses Carbon::parse)
$expiresOn = 'first day of December 2020';

$link = ActionLink::createInContext($context)
        -> ...
        ->expiresOn($expiresOn)
        -> ...
        ->handleBy($page);

Or use the Carbon addition API.

//Carbon addition
$addition = '10 minutes'; // (10 seconds, 10 hours, etc)

$link = ActionLink::createInContext($context)
        -> ...
        ->expiresIn($addition)
        -> ...
        ->handleBy($page);

Note: RainLab.Translate plugin needs to be installed for all the translation examples. Language code pi is a fictional pirate language.

A link can have a text.

$link = ActionLink::createInContext($context)
        -> ...
        ->withText('Click Here')
        -> ...
        ->handleBy($page);

//translated text
$link = ActionLink::createInContext($context)
        -> ...
        ->withText('Click Here', 'en')
        ->withText('Arrr! Click Here', 'pi')
        -> ...
        ->handleBy($page);

And it can have a success message.

$link = ActionLink::createInContext($context)
        -> ...
        ->withSuccessMessage('A cool message!')
        -> ...
        ->handleBy($page);

//translated success message
$link = ActionLink::createInContext($context)
        -> ...
        ->withSuccessMessage('Success!', 'en')
        ->withSuccessMessage('Arrr! Success!', 'pi')
        -> ...
        ->handleBy($page);

Creating variants

If you need a link that with multiple choices, like yes and no, you can use variants. Variants function like radio buttons. Only one can be chosen by the user per action link.

$link = ActionLink::createInContext($context)
        -> ...
        ->withVariant('yes')
        ->withVariant('no')
        -> ...
        ->handleBy($page);

Variants can have a text.

$link = ActionLink::createInContext($context)
        -> ...
        ->withVariant('yes', 'Yes, please!')
        ->withVariant('no', 'No, thank you!')
        -> ...
        ->handleBy($page);

A callback can be used if you want to translate the variants.

$link = ActionLink::createInContext($context)
        ->withVariant('yes', function ($variant) {
            $variant
                -> ...
                ->withText('Yes, please!', 'en')
                ->withText('Aye!', 'pi');
        })
        ->withVariant('no', function ($variant) {
            $variant
                -> ...
                ->withText('No, thank you!', 'en')
                ->withText('No, thank ye!', 'pi');
        })
        ->handleBy($page);

You can also set a success message for a specific variant.

$link = ActionLink::createInContext($context)
        ->withVariant('yes', function ($variant) {
            $variant
                -> ...
                ->withSuccessMessage('Success for yes!', 'en')
                ->withSuccessMessage('Arrr! Success fer aye!', 'pi');
        })
        ->withVariant('no', function ($variant) {
            $variant
                -> ...
                ->withSuccessMessage('Success for no!', 'en')
                ->withSuccessMessage('Arrr! Success fer no', 'pi');
        })
        ->handleBy($page);

Using created action links

After the action link is created you can get tha data you need with provided getters.

Getting the action link URL.

$link->getUrl();

//translated URL
$link->getUrl('pi');

//relative URL
$link->getRelativeUrl();

//translated relative URL
$link->getRelativeUrl('pi');

Getting the params.

$link->getParam('foo');

Getting the text.

$link->getText();

//translated text
$link->getUrl('pi');

Getting the success message.

$link->getSuccessMessage();

//translated success message
$link->getSuccessMessage('pi');

Using created variants

Getting the action link URL for a variant.

$link->getVariantUrl('yes');

//translated variant URL
$link->getVariantUrl('yes', 'pi');

//relative variant URL
$link->getRelativeVariantUrl();

//translated relative variant URL
$link->getRelativeVariantUrl('pi');

Getting the variant text.

$link->getVariantText('yes');

//translated variant text
$link->getVariantText('yes', 'pi');

Getting the variant success message.

$link->getVariantSuccessMessage('yes');

//translated variant success message
$link->getVariantSuccessMessage('yes', 'pi');

Basic example code

This is an example page that will create an action link. For this example we will name it 'linkexample.htm'.

title = "Link example"
url = "/link-example"
layout = "default"
is_hidden = 0
==
<?php
function onStart()
{
    $this['link'] = \RoboCode\ActionLinks\Models\ActionLink::createInContext('context')
        ->withText('Link Example')
        ->withSuccessMessage('Success Message Example')
        ->handleBy('handlerexample');

    $this['link_id'] = \Session::get('link_id');
}
?>
==
<div class="container">
    <br>
    <div>
        <a class="btn btn-primary" href="{{link.getUrl()}}">{{link.getText()}}</a>
    </div>
    <br>
    {% if link_id %}
        <div>
            Last used link id: {{link_id}}
        </div>
    {% endif %}
</div>

This is an example hander page that will handle the link. For this example we will name it 'handlerexample.htm'.

title = "Handler Example"
url = "/handler-example/:key"
is_hidden = 0

[actionLinkHandler]
successPage = "linkexample"
errorPage = "linkexample"
flash = 1
==
<?php
function onInit()
{
    \RoboCode\ActionLinks\Classes\ActionLinkHandler::handleContext('*', function ($actionLink) {
        //Do something more useful her
        \Session::flash('link_id', $actionLink->id);
    });
}
?>
==
1.0.5

Minor updates.

Jan 22, 2020

1.0.4

Minor updates.

Jan 06, 2020

1.0.3

Optional localization (RainLab.Translate).

Jan 05, 2020

1.0.2

Created table robocode_actionlinks_links.

Dec 19, 2019

1.0.1

Initialize plugin.

Dec 19, 2019