Feature/improve tutorials

demos/index.php

@@ -2,6 +2,28 @@
 
 include_once __DIR__ . '/init.php';
 
+/*
+$tut_array = [
+    ['id'=>'intro', 'name'=>'Agile UI Intro', 'description'=>'Take a quick stroll through some of the amazing features of Agile Toolkit.'],
+    ['id'=> 'actions', 'name'=>'New in 2.0: Actions', 'description'=>'Version 2.0 introduced support for universal user actions. Easy to add and supported by all Views.'],
+];
+$db = new \atk4\data\Persistence_Static($tut_array);
+$db->app = $app;
+$tutorials = new \atk4\data\Model($db, ['read_only'=>true]);
+$tutorials->addAction('Watch', function ($m) {
+    return $m->app->jsRedirect(['tutorial-'.$m->id, 'layout'=>'Centered']);
+});
+
+$app->add([
+    'Header',
+    'Welcome to Agile Toolkit!',
+    'size'     => 1,
+    'subHeader'=> 'Below are some tutorials to walk you through core concepts',
+]);
+$deck = $app->add(['CardDeck']);
+$deck->setModel($tutorials, ['description']);
+*/
+
 if (!$app->stickyget('begin')) {
     \atk4\ui\Header::addTo($app)->set('Welcome to Agile Toolkit Demo!!');
 
@@ -17,7 +39,7 @@
     $t->addParagraph('In this version of Agile Toolkit we introduce "User Actions"!');
 
     \atk4\ui\Button::addTo($app, ['Learn about User Actions', 'huge basic primary fluid', 'iconRight' => 'right arrow'])
-        ->link(['tutorial_actions', 'layout' => 'Centered', 'begin' => true]);
+        ->link(['tutorial-actions', 'layout' => 'Centered', 'begin' => true]);
 
     $app->callExit();
 }
@@ -231,40 +253,7 @@ public function init()
 });
 
 $wizard->addFinish(function ($page) use ($wizard) {
-    $t = \atk4\ui\Text::addTo($page);
-    $t->addParagraph(
-        <<< 'EOF'
-Agile Toolkit base package includes:
-EOF
-    );
-
-    $t->addHTML(
-        <<< 'HTML'
-<ul>
-<li>Over 40 ready-to-use and nicely styled UI components</li>
-<li>Over 10 ways to build interraction</li>
-<li>Over 10 configurable field types, relations, aggregation and much more</li>
-<li>Over 5 SQL and some NoSQL vendors fully supported</li>
-</ul>
-
-HTML
-    );
-
-    $gl = \atk4\ui\GridLayout::addTo($page, [null, 'stackable divided', 'columns'=>4]);
-    \atk4\ui\Button::addTo($gl, ['Explore UI components', 'primary basic fluid', 'iconRight'=>'right arrow'], ['r1c1'])
-        ->link('https://github.com/atk4/ui/#bundled-and-planned-components');
-    \atk4\ui\Button::addTo($gl, ['Try out interactive features', 'primary basic fluid', 'iconRight'=>'right arrow'], ['r1c2'])
-        ->link(['loader', 'begin'=>false, 'layout'=>false]);
-    \atk4\ui\Button::addTo($gl, ['Dive into Agile Data', 'primary basic fluid', 'iconRight'=>'right arrow'], ['r1c3'])
-        ->link('https://git.io/ad');
-    \atk4\ui\Button::addTo($gl, ['More ATK Add-ons', 'primary basic fluid', 'iconRight'=>'right arrow'], ['r1c4'])
-        ->link('https://github.com/atk4/ui/#add-ons-and-integrations');
-
+    PromotionText::addTo($page);
     \atk4\ui\Button::addTo($wizard, ['Exit demo', 'primary', 'icon'=>'left arrow'], ['Left'])
         ->link(['begin'=>false, 'layout'=>false]);
-
-    \atk4\ui\View::addTo($page, ['ui'=>'divider']);
-
-    \atk4\ui\Message::addTo($page, ['Cool fact!', 'info', 'icon'=>'book'])->text
-        ->addParagraph('This entire demo is coded in Agile Toolkit and takes up less than 300 lines of very simple code code!');
 });

demos/init.php

@@ -15,14 +15,16 @@ class Demo extends \atk4\ui\Columns
     public $right;
     public static $isInitialized = false;
     public $highlightDefaultStyle = 'dark';
+    public $left_width = 8;
+    public $right_width = 8;
 
     public function init()
     {
         parent::init();
         $this->addClass('celled');
 
-        $this->left = $this->addColumn();
-        $this->right = $this->addColumn();
+        $this->left = $this->addColumn($this->left_width);
+        $this->right = $this->addColumn($this->right_width);
     }
 
     public function setCode($code, $lang = 'php')
@@ -45,6 +47,51 @@ public function highLightCode()
     }
 }
 
+class PromotionText extends \atk4\ui\View
+{
+    public function init()
+    {
+        parent::init();
+
+        $t = \atk4\ui\Text::addTo($this);
+        $t->addParagraph(
+            <<< 'EOF'
+Agile Toolkit base package includes:
+EOF
+        );
+
+        $t->addHTML(
+            <<< 'HTML'
+<ul>
+<li>Over 40 ready-to-use and nicely styled UI components</li>
+<li>Over 10 ways to build interraction</li>
+<li>Over 10 configurable field types, relations, aggregation and much more</li>
+<li>Over 5 SQL and some NoSQL vendors fully supported</li>
+</ul>
+
+HTML
+        );
+
+        $gl = \atk4\ui\GridLayout::addTo($this, [null, 'stackable divided', 'columns'=>4]);
+        \atk4\ui\Button::addTo($gl, ['Explore UI components', 'primary basic fluid', 'iconRight'=>'right arrow'], ['r1c1'])
+            ->link('https://github.com/atk4/ui/#bundled-and-planned-components');
+        \atk4\ui\Button::addTo($gl, ['Try out interactive features', 'primary basic fluid', 'iconRight'=>'right arrow'], ['r1c2'])
+            ->link(['loader', 'begin'=>false, 'layout'=>false]);
+        \atk4\ui\Button::addTo($gl, ['Dive into Agile Data', 'primary basic fluid', 'iconRight'=>'right arrow'], ['r1c3'])
+            ->link('https://git.io/ad');
+        \atk4\ui\Button::addTo($gl, ['More ATK Add-ons', 'primary basic fluid', 'iconRight'=>'right arrow'], ['r1c4'])
+            ->link('https://github.com/atk4/ui/#add-ons-and-integrations');
+
+
+        \atk4\ui\View::addTo($this, ['ui'=>'divider']);
+
+        \atk4\ui\Message::addTo($this, ['Cool fact!', 'info', 'icon'=>'book'])->text
+            ->addParagraph('This entire demo is coded in Agile Toolkit and takes up less than 300 lines of very simple code code!');
+    }
+}
+
+
+
 $app = new \atk4\ui\App([
     'call_exit'        => isset($_GET['APP_CALL_EXIT']) && $_GET['APP_CALL_EXIT'] == 0 ? false : true,
     'catch_exceptions' => isset($_GET['APP_CATCH_EXCEPTIONS']) && $_GET['APP_CATCH_EXCEPTIONS'] == 0 ? false : true,

demos/loader.php

@@ -1,6 +1,7 @@
 <?php
 
 require_once __DIR__ . '/init.php';
+require_once '../tests/ViewTester.php';
 
 \atk4\ui\Button::addTo($app, ['Loader Examples - Page 2', 'small right floated basic blue', 'iconRight' => 'right arrow'])
     ->link(['loader2']);

demos/tutorial-actions.php

@@ -0,0 +1,213 @@
+<?php
+
+require 'init.php';
+require 'database.php';
+
+/** @var \atk4\ui\View $wizard */
+$wizard = $app->add('Wizard');
+$app->stickyGet($wizard->name);
+
+$wizard->addStep('Define User Action', function ($page) {
+    /** @var \atk4\ui\Text $t */
+
+    \atk4\ui\Header::addTo($page, ['What are Actions?']);
+
+    $t = $page->add('Text');
+    $t->addParagraph(
+        <<< 'EOF'
+Since the early version ATK UI was about building generic UI capable of automatically read information about 
+model Fields and visualising them correctly. Version 2.0 introduces support for "Actions" which can be declared
+in Data layer and can use generic UI for visualising and triggering. Models of Agile Data has always supported 3
+basic actions: "save" (for new and existing records) and "delete". Historically any other interaction required
+tinkering with UI layer. Now ATK implements a generic support for arbitrary actions and then re-implements
+"save", "delete" and "add" on top.
+EOF
+    );
+
+    $t->addParagraph(
+        <<< 'EOF'
+This enables developer to easily add more actions in the Data layers and have the rest of ATK recognise
+and respect those actions. Actions can be added into the model just like you are adding fields:
+EOF
+    );
+
+    $page->add(new Demo())->setCode(
+        <<<'CODE'
+$country = new Country($app->app->db);
+
+$country->addAction('send_message');
+CODE
+    );
+
+    $t = $page->add('Text');
+    $t->addParagraph(
+        <<< 'EOF'
+Once defied - actions will be visualised in the Form, Grid, CRUD and CardDeck. Additionally add-ons will recognise
+your actions - for example 'Login' add-on introduces ACL system capable of enabling/disabling fields or actions
+on per-user basis.
+EOF
+    );
+
+    $t->addParagraph(
+        <<< 'EOF'
+Any actions you define will automatically appear in the UI. This is consistent with your field definitions. You can
+also "disable" or mark actions as "system". When action is executed, the response will appear to the user as a 
+toast message, but this can also be customised.
+EOF
+    );
+
+    $page->add(new Demo())->setCode(
+        <<<'CODE'
+
+$country = new Country($app->app->db);
+
+$country->addAction('send_message', function() { 
+    return 'sent'; 
+});
+$country->tryLoadAny();
+
+$card = $app->add('Card');
+$card->setModel($country, ['iso']);
+$card->addClickAction($country->getAction('send_message'));
+
+CODE
+    );
+});
+
+$wizard->addStep('UI Integration', function ($page) {
+    /** @var \atk4\ui\Text $t */
+    $t = $page->add('Text');
+    $t->addParagraph(
+        <<< 'EOF'
+Agile UI introduces a new set of views called "Action Executors". Their job is to recognise all that meta-information
+that you have specified for the action and requesting it from the user. "edit" action is defined for models by default
+and you can trigger it on button-click with a very simple code:
+EOF
+    );
+
+    $page->add(new Demo())->setCode(
+        <<<'CODE'
+$country = new Country($app->app->db);
+$country->loadAny();
+
+$app->add(['Button', 'Edit some country'])
+    ->on('click', $country->getAction('edit'));
+CODE
+    );
+
+    $t = $page->add('Text');
+    $t->addParagraph(
+        <<< 'EOF'
+It is not only the button, but any view can have "Action" passed as a second step of the on() call. Here the action
+is executed when you click on "World" menu item:
+EOF
+    );
+
+    $page->add(new Demo())->setCode(
+        <<<'CODE'
+$country = new Country($app->app->db);
+$country->loadAny();
+
+$menu = $app->add('Menu');
+$menu->addItem('Hello');
+$menu->addItem('World', $country->getAction('edit'));
+CODE
+    );
+});
+
+$wizard->addStep('Arguments', function ($page) {
+    $t = $page->add('Text');
+    $t->addParagraph(
+        <<< 'EOF'
+Next demo defines an action that requires arguments. You can specify action when the action is invoked, but if not
+defined - user will be asked to supply an argument. Action will automatically validate argument types and it uses
+same type system as fields.
+EOF
+    );
+
+    $page->add(new Demo())->setCode(
+        <<<'CODE'
+$model = new \atk4\data\Model($app->db, 'test');
+$model->addAction('greet', [
+    'scope' => \atk4\data\UserAction\Generic::NO_RECORDS,
+    'args'=> [
+        'age'=>[
+            'type'=>'integer', 
+            'required' => true
+        ]
+    ], 
+    'callback'=>function ($m, $age) {
+        return 'Age is '.$age;
+    }
+]);
+
+$app->add(new \atk4\ui\FormField\Line([
+    // TODO - how to specify watermark here?
+    'action' => $model->getAction('greet'),
+]));
+
+$app->add(['ui'=>'divider']);
+
+$app->add(['Button', 'Greet without Age argument'])
+    ->on('click', $model->getAction('greet'));
+CODE
+    );
+});
+
+/*
+$wizard->addStep('More Ways', function ($page) {
+    $page->add(new Demo(['left_width'=>5, 'right_width'=>11]))->setCode(
+        <<<'CODE'
+$m = new Stat($app->db);
+$m->addAction('mail', [
+    'fields'      => ['currency_field'],
+    'scope'       => \atk4\data\UserAction\Generic::SINGLE_RECORD,
+    'callback'    => function() { return 'testing'; },
+    'description' => 'Email testing',
+]);
+$app->add('CardDeck')
+    ->setModel(
+        $m,
+        ['description']
+    );
+CODE
+    );
+});
+*/
+
+
+
+$wizard->addStep('CRUD integration', function ($page) {
+    $t = $page->add('Text');
+    $t->addParagraph(
+        <<< 'EOF'
+Compared to 1.x versions CRUD implementation has became much more lightweight, however you retain all the same
+functionality and more. Next example shows how you can disable action (add) entirely, or on per-row basis (delete)
+and how you could add your own action with a custom trigger button and even a preview.
+EOF
+    );
+
+
+    $page->add(new Demo())->setCode(
+        <<<'CODE'
+$country = new Country($app->app->db);
+$country->getAction('add')->enabled = false;
+$country->getAction('delete')->enabled = function() { return rand(1,2)>1; };
+$country->addAction('mail', [
+    'scope'       => \atk4\data\UserAction\Generic::SINGLE_RECORD,
+    'preview'    => function($m) { return 'here is email preview for '.$m['name']; },
+    'callback'    => function($m) { return 'email sent to '.$m['name']; },
+    'description' => 'Email testing',
+    'ui'       => ['icon'=>'mail', 'button'=>[null, 'icon'=>'green mail']],
+]);
+$crud = $app->add(['CRUD', 'ipp'=>5]);
+$crud->setModel($country, ['name','iso']);
+CODE
+    );
+});
+
+$wizard->addFinish(function ($page) use ($wizard) {
+    PromotionText::addTo($page);
+    \atk4\ui\Button::addTo($wizard, ['Exit demo', 'primary', 'icon'=>'left arrow'], ['Left'])
+        ->link(['begin'=>false, 'layout'=>false]);
+});