Defining Actions

Lamotivo actions allow you to perform custom tasks on one or more Eloquent models.

Once an action has been attached to a resource definition, you may initiate it from the resource's index or details screens.

Overview

Lamotivo actions may be generated using the lm:action Artisan command. By default, all actions are placed in the app/Lm/Actions directory:

php artisan lm:action SendCoupon

You may generate a destructive action by passing the --destructive option:

php artisan lm:action ResetAccount --destructive

This will change the color of the action's confirm button to red.

To learn how to define Lamotivo actions, let's look at an example. In this example, we'll define an action that sends an email message to a user or group of users:

<?php

namespace App\Lm\Actions;

use Illuminate\Http\Request;
use Illuminate\Support\Collection;

use Anyspin\Lamotivo\Actions\Action;
use Anyspin\Lamotivo\Actions\ActionFields;
use Anyspin\Lamotivo\Actions\DestructiveAction;

class SendCoupon extends Action
{

  /**
   * Perform the action on the given models.
   *
   * @param  \Anyspin\Lamotivo\Fields\ActionFields  $fields
   * @param  \Illuminate\Support\Collection  $models
   * @return mixed
   */
  public function handle(ActionFields $fields, Collection $models)
  {
    foreach ($models as $model)
    {
      $model->sendCoupon();
    }
    return Action::success('Action is performed');
  }

  /**
   * Get the fields available on the action.
   *
   * @return array
   */
  public function fields()
  {
    return [];
  }
}

The most important method of an action is the handle method. The handle method receives the values for any fields attached to the action, as well as a collection of selected models. The handle method always receives a Collection of models, even if the action is only being performed against a single model.

Within the handle method, you may perform whatever tasks are necessary to complete the action.

Action Fields

Sometimes you may wish to gather additional information before dispatching an action. For this reason, Lamotivo allows you to attach supported fields directly to an action. When the action is initiated, Lamotivo will prompt the user to provide input for the fields.

To add a field to an action, add the field to the array of fields returned by the action's fields method:

use Anyspin\Lamotivo\Fields\Text;

/**
 * Get the fields available on the action.
 *
 * @return array
 */
public function fields()
{
  return [
    Text::make('type'),
  ];
}

Finally, within your action's handle method, you may access your fields using dynamic accessors on the provided ActionFields instance:

/**
 * Perform the action on the given models.
 *
 * @param  \Anyspin\Lamotivo\Fields\ActionFields  $fields
 * @param  \Illuminate\Support\Collection  $models
 * @return mixed
 */
public function handle(ActionFields $fields, Collection $models)
{
  foreach ($models as $model)
  {
    $model->sendCoupon($fields->type);
  }
}

Action Responses

Typically, when an action is executed, a generic "success" messages is displayed. However, you are free to customize this response using a variety of methods on the Action class.

To display a custom success message, you may return the result of the Action::message method from your handle method:

/**
 * Perform the action on the given models.
 *
 * @param  \Anyspin\Lamotivo\Fields\ActionFields  $fields
 * @param  \Illuminate\Support\Collection  $models
 * @return mixed
 */
public function handle(ActionFields $fields, Collection $models)
{
    // ...

    return Action::message('Done!');
}

To return a red danger message, you may use the Action::danger method:

return Action::danger('Got an error!');

Redirect Responses

To redirect the user to an entirely new location after the action is executed, you may use the Action::redirect method:

return Action::redirect('/lm/customers');

To redirect the user to an external URL in new tab use Action::away method:

return Action::away('https://example.com');

Download Responses

To initiate a file download after the action is executed, you may use the Action::download method. The download method accepts the URL of the file to be downloaded as its first argument, and the desired name of the file as its second argument:

return Action::download($url);

Also you may use Action::downloadAsFile to download data from a string:

return Action::downloadAsFile('... some CSV data ...', 'export.csv');

Registering Actions

Once you have defined an action, you are ready to attach it to a resource. Each resource contains an actions method. To attach an action to a resource, you should simply add it to the array of actions returned by this method:

/**
 * Get the actions available for the resource.
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
public function actions(Request $request)
{
    return [
      new Actions\SendCoupon,
    ];
}