From 661a6c2d847b968e30d712af18931ba09e233a22 Mon Sep 17 00:00:00 2001
From: Mahmoud Zalt <mahmoud.z@msn.com>
Date: Mon, 17 Apr 2017 19:44:23 -0400
Subject: [PATCH] introducing the SubAction component in Porto.

Tried to avoid that for long time, but seems now way to avoid it.
In some situations, where you have large Actions, you need to share some
sequence of Tasks (not only tasks) to avoid duplicate code between
both actions, they should be able to call SubAction
---
 app/Ship/Parents/Actions/Action.php    |  6 ++-
 app/Ship/Parents/Actions/SubAction.php | 13 ++++++
 docs/_docs/D.components/subactions.md  | 55 ++++++++++++++++++++++++++
 3 files changed, 72 insertions(+), 2 deletions(-)
 create mode 100644 app/Ship/Parents/Actions/SubAction.php
 create mode 100644 docs/_docs/D.components/subactions.md

diff --git a/app/Ship/Parents/Actions/Action.php b/app/Ship/Parents/Actions/Action.php
index 98d0538d2..cfcfd5235 100644
--- a/app/Ship/Parents/Actions/Action.php
+++ b/app/Ship/Parents/Actions/Action.php
@@ -11,11 +11,13 @@
  */
 abstract class Action
 {
-
     use CallableTrait;
 
     /**
-     * @var
+     * Set automatically by the controller after calling an Action.
+     * Allows the Action to know which UI invoke it, to modify it's behaviour based on it, when needed.
+     *
+     * @var string
      */
     protected $ui;
 
diff --git a/app/Ship/Parents/Actions/SubAction.php b/app/Ship/Parents/Actions/SubAction.php
new file mode 100644
index 000000000..3ab52897f
--- /dev/null
+++ b/app/Ship/Parents/Actions/SubAction.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace App\Ship\Parents\Actions;
+
+/**
+ * Class Action.
+ *
+ * @author  Mahmoud Zalt <mahmoud@zalt.me>
+ */
+abstract class SubAction extends Action
+{
+
+}
diff --git a/docs/_docs/D.components/subactions.md b/docs/_docs/D.components/subactions.md
new file mode 100644
index 000000000..9d16855ac
--- /dev/null
+++ b/docs/_docs/D.components/subactions.md
@@ -0,0 +1,55 @@
+---
+title: "Sub Actions"
+category: "Components"
+order: 5
+---
+
+### Definition & Principles
+
+Read from the [**Porto SAP Documentation (#SubActions)**](https://github.com/Mahmoudz/Porto#SubActions).
+
+### Rules
+
+- All SubActions MUST extend from `App\Ship\Parents\Actions\SubAction`.
+
+### Folder Structure
+
+```
+ - app
+    - Containers
+        - {container-name}
+            - Actions
+                - ValidateAddressSubAction.php
+                - BuildOrderSubAction.php
+                - ...
+```
+
+### Code Sample
+
+**ValidateAddressSubAction User Action:**
+
+```php
+<?php
+
+namespace App\Containers\Shipment\Actions;
+
+use App\Containers\Recipient\Models\Recipient;
+use App\Containers\Recipient\Tasks\UpdateRecipientTask;
+use App\Containers\Shipment\Tasks\ValidateAddressWithEasyPostTask;
+use App\Containers\Shipment\Tasks\ValidateAddressWithMelissaDataTask;
+use App\Ship\Parents\Actions\SubAction;
+
+class ValidateAddressSubAction extends SubAction
+{
+    public function run(Recipient $recipient)
+    {
+        $hasValidAddress = true;
+
+        $easyPostResponse = $this->call(ValidateAddressWithEasyPostTask::class, [$recipient]);
+
+        ...
+    }
+}
+```
+
+**Every feature available for Actions, is also available in SubActions.**